Decision Optimization model input and output data file formats

Model input and output data file formats

Last updated: Oct 09, 2024

With your Decision Optimization model, you can use the following input and output data identifiers and extension combinations.

This table shows the supported file type combinations for Decision Optimization in Watson Machine Learning:

Model type	Input file type	Output file type	Comments
`cplex`	`.lp` `.mps` `.sav` `.feasibility` `.prm` `.jar` for Java™ models	`.xml` `.json` The name of the output file must be solution	The output format can be specified by using the API. Files of type `.lp`, `.mps`, and `.sav` can be compressed by using `gzip` or `bzip2`, and uploaded as, for example, `.lp.gz` or `.sav.bz2`. The schemas for the CPLEX formats for solutions, conflicts, and feasibility files are available for you to download in the cplex_xsds.zip archive from the Decision Optimization github.
`cpo`	`.cpo` `.jar` for Java models	`.xml` `.json` The name of the output file must be solution	The output format can be specified by using the solve parameter. For the native file format for CPO models, see: CP Optimizer file format syntax.
`opl`	`.mod` `.dat` `.oplproject` `.xls` `.json` `.csv` `.jar` for Java models	`.xml` `.json` `.txt` `.csv` `.xls`	The output format is consistent with the input type but can be specified by using the solve parameter if needed. To take advantage of data connectors, use the `.csv` format. Only models that are defined with tuple sets can be deployed; other OPL structures are not supported. To read and write input and output in OPL, see OPL models.
`docplex`	`.py` `.` (input data)	Any output file type that is specified in the model.	Any format can be used in your Python code, but to take advantage of data connectors, use the `.csv` format. To read and write input and output in Python, use the commands `get_input_stream("filename")` and `get_output_stream("filename")`. See DOcplex API sum example

Data identifier restrictions

A file name has the following restrictions:

Is limited to 255 characters
Can include only ASCII characters
Cannot include the characters /\?%*:|"<>, the space character, or the null character
Cannot include _ as the first character

OPL data formats

The OPL model declares the tuples, decision variables, objective function, and constraints of the optimization problem by using the keywords tuple, dvar, minimize (or maximize) and subject to. The following example shows an extract of an OPL model :

tuple parameters {
	int maxTrucks;
	int maxVolume;
}
parameters Parameters = ...;

tuple location {
  key string name;
}
{location} Hubs = ...;

tuple spoke {
  key string name;
  int     minDepTime;
  int     maxArrTime;
};
{spoke} Spokes = ...;

dvar int+ TruckOnRoute[Routes][TruckTypeIds] in 0..Parameters.maxTrucks;

[...]

minimize TotalCost;

subject to {
	[...]
}

OPL input data

The input data can be populated from an external data source. The input data for OPL models can be provided in one of these formats:

.dat file
JSON document
Microsoft Excel workbook (.xls for Excel 2003 or .xlsx for Excel 2007), .csv files

.dat file

All OPL data structures are supported. For example,

{Parameters = <100, 5000>;

Hubs = { <"G">, <"H"> };

Spokes = { <"A", 360, 1080>, <"B", 400, 1150> };

JSON document or Microsoft Excel workbook

You can use only tuples and tuple sets as inputs in the OPL model.

Supported types for tuple fields are int, float or string.

To map the input values to your OPL model, you must follow these rules:

The OPL element must have the same name as the JSON property or Excel worksheet.
A tuple set can be populated by a JSON property array or a worksheet.
A tuple element can be populated by a JSON property object, or with a single row Excel sheet.

The limitation on inputs is to facilitate integration with data sources. For example, SQL data sources can be accessed and data-streamed with a minimum of effort; NoSQL data sources can be accessed and data can be transformed automatically to tables. If necessary, the optimization model developer can reformulate the data to populate other data structures during the optimization, but this manipulation must not affect the input or output data.

JSON example

JSON format can be used for OPL model integration so that it is easier to generate input data and to parse the results.

{
  "Parameters": {
    "maxTrucks": 100,
    "maxVolume": 5000
  },
  "Hubs": [
    {  "name": "G"  },
    {  "name": "H"  }
  ],
  "Spokes": [
    { "name": "A",
      "minDepTime": 360,
      "maxArrTime": 1080 },
    { "name": "B",
      "minDepTime": 400,
      "maxArrTime": 1150  },
   . . .
}

Excel file

You can use an Excel file instead of using a .dat file. This option is different from IBM ILOG CPLEX Optimization Studio where the Excel file must be specified as an external source in the .dat file. In Decision Optimization the Excel file must be included with the model and cannot be called from a .dat file.

OPL output data

If your output is a text file, then the objective function, and values of the decision variables are provided in an unstructured format.

If your output format is JSON, .csv or Excel, then you must define what you want to export back to the client in the post-processing block. Post-processing is all the code that follows the subject to section in the .mod file. Thus to define JSON, .csv or Excel output, you must declare tuple or tuple sets in the post-processing.

If you do not declare output elements in the post-processing block of the .mod file, no output data is generated.

In the following example, the output file will contain the value of Result and NbTrucksOnRouteRes and the objective function because these elements are defined in the post-processing.

subject to {
   [...]
}

tuple result {
  float totalCost;
}
result Result;

execute {
     Result.objValue = cplex.getObjValue();
}

tuple nbTrucksOnRouteRes {
  key string	spoke;
  key string	hub;
  key string	truckType;
  int			nbTruck;
}
{nbTrucksOnRouteRes} NbTrucksOnRouteRes =
  {<r.spoke, r.hub, t, TruckOnRoute[r][t]> | r in Routes, t in TruckTypeIds :
                                                              TruckOnRoute[r][t] > 0};