Model input and output data file formats (Decision Optimization)

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`	`.xml` `.json` The name of the output file must be solution	The output format can be specified using the API. Files of type `.lp`, `.mps`, and `.sav` can be compressed 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`	`.xml` `.json` The name of the output file must be solution	The output format can be specified 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`	`.xml` `.json` `.txt` `.csv` `.xls`	The output format is consistent with the input type but can be specified using the solve parameter if needed. To take advantage of data connectors use the `.csv` format. To read and write input and output in OPL, see OPL models.
docplex	`.py` `.` (input data)	Any output file type, 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 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 only use 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 a single row Excel sheet.

The limitation on inputs is to facilitate integration with data sources: 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 on the fly 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 is different to 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 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 following the subject to section in the .mod file. For that, you must declare tuple or tuple sets in the post processing.

If you do not declare output element 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};