D. The OPF format


The Optimization Problem Format (OPF) is an alternative to LP and MPS files for specifying optimization problems. It is row-oriented, inspired by the CPLEX LP format.

Apart from containing objective, constraints, bounds etc. it may contain complete or partial solutions, comments and extra information relevant for solving the problem. It is designed to be easily read and modified by hand and to be forward compatible with possible future extensions.

D.1. Intended use

The OPF file format is meant to replace several other files:

D.2. The file format

The format uses tags to structure data. A simple example with the basic sections may look like this:

[comment]
  This is a comment. You may write almost anything here...
[/comment]

# This is a single-line comment. 

[objective min 'myobj']
  x + 3 y + x^2 + 3 y^2 + z + 1 
[/objective]

[constraints]
  [con 'con01'] 4 <= x + y  [/con]
[/constraints]

[bounds]
  [b] -10 <= x,y <= 10  [/b]

  [cone quad] x,y,z [/cone]
[/bounds]

A scope is opened by a tag of the form [tag] and closed by a tag of the form [/tag]. An opening tag may accept a list of unnamed and named arguments, for examples

 [tag value] tag with one unnamed argument [/tag]
 [tag arg=value] tag with one named argument in quotes [/tag]

Unnamed arguments are identified by their order, while named arguments may appear in any order, but never before an unnamed argument. The value can be a quoted, single-quoted or double-quoted text string, i.e.

 [tag 'value']     single-quoted value [/tag]
 [tag arg='value'] single-quoted value [/tag]
 [tag "value"]     double-quoted value [/tag]
 [tag arg="value"] double-quoted value [/tag]

D.2.1. Sections

The recognized tags are

  • [comment] A comment section. This can contain almost any text: Between single quotes (') or double quotes (") any text may appear. Outside quotes the markup characters ([ and ]) must be prefixed by backslashes. Both single and double quotes may appear alone or inside a pair of quotes if it is prefixed by a backslash.
  • [objective] The objective function: This accepts one or two parameters, where the first one (in the above example `min') is either min or max (regardless of case) and defines the objective sense, and the second one (above `myobj'), if present, is the objective name. The section may contain linear and quadratic expressions.

    If several objectives are specified, all but the last are ignored.

  • [constraints] This does not directly contain any data, but may contain the subsection `con' defining a linear constraint.

    [con] defines a single constraint; if an argument is present ([con NAME]) this is used as the name of the constraint, otherwise it is given a null-name. The section contains a constraint definition written as linear and quadratic expressions with a lower bound, an upper bound, with both or with an equality. Examples:

    [constraints]
      [con 'con1'] 0 <= x + y       [/con]
      [con 'con2'] 0 >= x + y       [/con]
      [con 'con3'] 0 <= x + y <= 10 [/con]
      [con 'con4']      x + y  = 10 [/con]
    [/constraints]
    

    Constraint names are unique. If a constraint is apecified which has the same name as a previously defined constraint, the new constraint replaces the existing one.

  • [bounds] This does not directly contain any data, but may contain the subsections `b' (linear bounds on variables) and `cone' (quadratic cone).

    • [b]. Bound definition on one or several variables separated by comma (`,'). An upper or lower bound on a variable replaces any earlier defined bound on that variable. If only one bound (upper or lower) is given only this bound is replaced. This means that upper and lower bounds can be specified separately. So the OPF bound definition:

            [b]  x,y >= -10  [/b]
            [b]  x,y <= 10   [/b] 
          

      results in the bound

      \begin{math}\nonumber{}-10\leq{}x,y\leq{}10.\end{math} (D.2.1)
    • [cone]. Currently, the supported cones are the quadratic cone and the rotated quadratic cone (see section 5.4). A conic constraint is defined as a set of variables which belongs to a single unique cone.

      A quadratic cone of n variables [[MathCmd 976]] defines a constraint of the form

      \begin{displaymath}\nonumber{}x_{1}^{2}>\sum ^{n}_{{i=2}}x_{i}^{2.}\end{displaymath}

      A rotated quadratic cone of n variables [[MathCmd 976]] defines a constraint of the form

      \begin{displaymath}\nonumber{}x_{1}x_{2}>\sum ^{n}_{{i=3}}x_{i}^{2.}\end{displaymath}

    A [bounds]-section example:

    [bounds]
      [b]  0 <= x,y <= 10  [/b] # ranged bound
      [b] 10 >= x,y >=  0  [/b] # ranged bound
      [b]  0 <= x,y <= inf [/b] # using inf
      [b]       x,y free   [/b] # free variables
      # Let (x,y,z,w) belong to the cone K
      [cone quad]  x,y,z,w  [/cone] # quadratic cone
      [cone rquad] x,y,z,w  [/cone] # rotated quadratic cone
    [/bounds]
    

    By default all variables are free.

  • [variables] This defines an ordering of variables as they should appear in the problem. This is simply a space-separated list of variable names.
  • [integer] This contains a space-separated list of variables and defines the constraint that the listed variables must be integer values.
  • [hints] This may contain only non-essential data; for example estimates of the number of variables, constraints and non-zeros. Placed before all other sections containing data this may reduce the time spent reading the file.

    In the hints section, any subsection which is not recognized by MOSEK is simply ignored. In this section a hint in a subsection is defined as follows:

      [hint ITEM] value [/hint]
    

    where ITEM may be replaced by numvar (number of variables), numcon (number of linear/quadratic constraints), numanz (number if linear non-zeros in constraints) and numqnz (number of quadratic non-zeros in constraints).

  • [solutions] This section can contain a number of full or partial solutions to a problem, each inside a [solution]-section. The syntax is

    [solution SOLTYPE status=STATUS]...[/solution]
    

    where SOLTYPE is one of the strings

    • `interior', a non-basic solution,
    • `basic', a basic solution,
    • `integer', an integer solution,

    and STATUS is one of the strings

    • `UNKNOWN',
    • `OPTIMAL',
    • `INTEGER_OPTIMAL',
    • `PRIM_FEAS',
    • `DUAL_FEAS',
    • `PRIM_AND_DUAL_FEAS',
    • `NEAR_OPTIMAL',
    • `NEAR_PRIM_FEAS',
    • `NEAR_DUAL_FEAS',
    • `NEAR_PRIM_AND_DUAL_FEAS',
    • `PRIM_INFEAS_CER',
    • `DUAL_INFEAS_CER',
    • `NEAR_PRIM_INFEAS_CER',
    • `NEAR_DUAL_INFEAS_CER',
    • `NEAR_INTEGER_OPTIMAL'.

    Most of these values are irrelevant for input solutions; when constructing a solution for simplex hot-start or an initial solution for a mixed integer problem the safe setting is UNKNOWN.

    A [solution]-section contains [con] and [var] sections. Each [con] and [var] section defines solution values for a single variable or constraint, each value written as

    KEYWORD=value
    

    where KEYWORD defines a solution item and value defines its value. Allowed keywords are as follows:

    • sk. The status of the item, where the value is one of the following strings:

      • LOW, the item is on its lower bound.
      • UPR, the item is on its upper bound.
      • FIX, it is a fixed item.
      • BAS, the item is in the basis.
      • SUPBAS, the item is super basic.
      • UNK, the status is unknown.
      • INF, the item is outside its bounds (infeasible).
    • lvl Defines the level of the item.
    • sl Defines the level of the variable associated with its lower bound.
    • su Defines the level of the variable associated with its upper bound.
    • sn Defines the level of the variable associated with its cone.
    • y Defines the level of the corresponding dual variable (for constraints only).

    A [var] section should always contain the items sk and lvl, and optionally sl, su and sn.

    A [con] section should always contain sk and lvl, and optionally sl, su and y.

    An example of a solution section

    [solution basic status=UNKNOWN]
        [var x0] sk=LOW    lvl=5.0      [/var]
        [var x1] sk=UPR    lvl=10.0     [/var]
        [var x2] sk=SUPBAS lvl=2.0  sl=1.5 su=0.0 [/var]
    
        [con c0] sk=LOW    lvl=3.0 y=0.0 [/con]
        [con c0] sk=UPR    lvl=0.0 y=5.0 [/con]
    [/solution]
    
  • [vendor] This contains solver/vendor specific data. It accepts one argument, which is a vendor ID – for MOSEK the ID is simply mosek – and the section contains the subsection parameters defining solver parameters. When reading a vendor section, any unknown vendor can be safely ignored. This is described later.

Comments using the `#' may appear anywhere in the file. Between the `#' and the following line-break any text may be written, including markup characters.

D.2.2. Numbers

Numbers, when used for parameter values or coefficients, are written in the usual way by the printf function. That is, they may be prefixed by a sign (+ or -) and may contain an integer part, decimal part and an exponent. The decimal point is always `.' (a dot). Some examples are

 1
 1.0
  .0
 1.
 1e10
 1e+10
 1e-10

Some invalid examples are

 e10   # invalid, must contain either integer or decimal part
 .     # invalid
 .e10  # invalid

More formally, the following standard regular expression describes numbers as used:

[+|-]?([0-9]+[.][0-9]*|[.][0-9]+)([eE][+|-]?[0-9]+)?

D.2.3. Names

Variable names, constraint names and objective name may contain arbitrary characters, which in some cases must be enclosed by quotes (single or double) that in turn must be preceded by a backslash. Unquoted names must begin with a letter (a-z or A-Z) and contain only the following characters: the letters a-z and A-Z, the digits 0-9, braces ({ and }) and underscore (_).

Some examples of legal names:

 an_unqouted_name
 another_name{123}
 'single qouted name'
 "double qouted name"
 "name with \"qoute\" in it"
 "name with []s in it"

D.3. Parameters section

In the vendor section solver parameters are defined inside the parameters subsection. Each parameter is written as

  [p PARAMETER_NAME] value [/p]

where PARAMETER_NAME is replaced by a MOSEK parameter name, usually of the form MSK_IPAR_..., MSK_DPAR_... or MSK_SPAR_..., and the value is replaced by the value of that parameter; both integer values and named values may be used. Some simple examples are:

[vendor mosek]
  [parameters]
    [p MSK_IPAR_OPF_MAX_TERMS_PER_LINE] 10     [/p]
    [p MSK_IPAR_OPF_WRITE_PARAMETERS]   MSK_ON [/p]
    [p MSK_DPAR_DATA_TOL_BOUND_INF]     1.0e18 [/p]
  [/parameters]
[/vendor]

D.4. Writing OPF files from MOSEK

The function Task.writedata can be used to produce an OPF file from a task.

To write an OPF file set the parameter mosek.iparam.write_data_format to mosek.dataformat.op as this ensures that OPF format is used. Then modify the following parameters to define what the file should contain:

D.5. Examples

This section contains a set of small examples written in OPF and describing how to formulate linear, quadratic and conic problems.

D.5.1. Linear example lo1.opf

Consider the example:

\begin{math}\nonumber{}\begin{array}{lccccc}\nonumber{}\mbox{minimize} & -10x_{1} &  & -9x_{2}, &  & \\\nonumber{}\mbox{subject to} & 7/10x_{1} & + & 1x_{2} & \leq{} & 630,\\\nonumber{} & 1/2x_{1} & + & 5/6x_{2} & \leq{} & 600,\\\nonumber{} & 1x_{1} & + & 2/3x_{2} & \leq{} & 708,\\\nonumber{} & 1/10x_{1} & + & 1/4x_{2} & \leq{} & 135,\\\nonumber{} & x_{1}, &  & x_{2} & \geq{} & 0.\end{array}\end{math} (D.5.1)

In the OPF format the example is displayed as shown below:

[comment] Example lo1.mps converted to OPF. [/comment] [hints] # Give a hint about the size of the different elements in the problem. # These need only be estimates, but in this case they are exact. [hint NUMVAR] 2 [/hint] [hint NUMCON] 4 [/hint] [hint NUMANZ] 8 [/hint] [/hints] [variables] # All variables that will appear in the problem x1 x2 [/variables] [objective minimize 'obj'] - 10 x1 - 9 x2 [/objective] [constraints] [con 'c1'] 0.7 x1 + x2 <= 630 [/con] [con 'c2'] 0.5 x1 + 0.8333333333 x2 <= 600 [/con] [con 'c3'] x1 + 0.66666667 x2 <= 708 [/con] [con 'c4'] 0.1 x1 + 0.25 x2 <= 135 [/con] [/constraints] [bounds] # By default all variables are free. The following line will # change this to all variables being nonnegative. [b] 0 <= * [/b] [/bounds]

D.5.2. Quadratic example qo1.opf

An example of a quadratic optimization problem is

\begin{math}\nonumber{}\begin{array}{lcccl}\nonumber{}\mbox{minimize} &  &  & x_{1}^{2}+0.1x_{2}^{2}+x_{3}^{2}-x_{1}x_{3}-x_{2} & \\\nonumber{}\mbox{subject to} & 1 & \leq{} & x_{1}+x_{2}+x_{3}, & \\\nonumber{} &  &  & x\geq{}0. &\end{array}\end{math} (D.5.2)

This can be formulated in opf as shown below.

[comment] Example qo1.mps converted to OPF. [/comment] [hints] [hint NUMVAR] 3 [/hint] [hint NUMCON] 1 [/hint] [hint NUMANZ] 3 [/hint] [/hints] [variables] x1 x2 x3 [/variables] [objective minimize 'obj'] # The quadratic terms are often multiplied by 1/2, # but this is not required. - x2 + 0.5 ( 2 x1 ^ 2 - 2 x3 * x1 + 0.2 x2 ^ 2 + 2 x3 ^ 2 ) [/objective] [constraints] [con 'c1'] 1 <= x1 + x2 + x3 [/con] [/constraints] [bounds] [b] 0 <= * [/b] [/bounds]

D.5.3. Conic quadratic example cqo1.opf

Consider the example:

\begin{math}\nonumber{}\begin{array}{lccl}\nonumber{}\mbox{minimize} & 1x_{1}+2x_{2} &  & \\\nonumber{}\mbox{subject to} & 2x_{3}+4x_{4} & = & 5,\\\nonumber{} & x_{5}^{2} & \leq{} & 2x_{1}x_{3},\\\nonumber{} & x_{6}^{2} & \leq{} & 2x_{2}x_{4},\\\nonumber{} & x_{5} & = & 1,\\\nonumber{} & x_{6} & = & 1,\\\nonumber{} & x\geq{}0. &  &\end{array}\end{math} (D.5.3)

Please note that the type of the cones is defined by the parameter to [cone ...]; the content of the cone-section is the names of variables that belong to the cone.

[comment] Example cqo1.mps converted to OPF. [/comment] [hints] [hint NUMVAR] 6 [/hint] [hint NUMCON] 1 [/hint] [hint NUMANZ] 2 [/hint] [/hints] [variables] x1 x2 x3 x4 x5 x6 [/variables] [objective minimize 'obj'] x1 + 2 x2 [/objective] [constraints] [con 'c1'] 2 x3 + 4 x4 = 5 [/con] [/constraints] [bounds] # We let all variables default to the positive orthant [b] 0 <= * [/b] # ... and change those that differ from the default. [b] x5,x6 = 1 [/b] # We define two rotated quadratic cones # k1: 2 x1 * x3 >= x5^2 [cone rquad 'k1'] x1, x3, x5 [/cone] # k2: 2 x2 * x4 >= x6^2 [cone rquad 'k2'] x2, x4, x6 [/cone] [/bounds]

D.5.4. Mixed integer example milo1.opf

Consider the mixed integer problem:

\begin{math}\nonumber{}\begin{array}{lccl}\nonumber{}\mbox{maximize} & x_{0}+0.64x_{1} &  & \\\nonumber{}\mbox{subject to} & 50x_{0}+31x_{1} & \leq{} & 250,\\\nonumber{} & 3x_{0}-2x_{1} & \geq{} & -4,\\\nonumber{} & x_{0},x_{1}\geq{}0 &  & \mbox{and integer}\end{array}\end{math} (D.5.4)

This can be implemented in OPF with:

[comment] Written by MOSEK version 5.0.0.7 Date 20-11-06 Time 14:42:24 [/comment] [hints] [hint NUMVAR] 2 [/hint] [hint NUMCON] 2 [/hint] [hint NUMANZ] 4 [/hint] [/hints] [variables disallow_new_variables] x1 x2 [/variables] [objective maximize 'obj'] x1 + 6.4e-1 x2 [/objective] [constraints] [con 'c1'] 5e+1 x1 + 3.1e+1 x2 <= 2.5e+2 [/con] [con 'c2'] -4 <= 3 x1 - 2 x2 [/con] [/constraints] [bounds] [b] 0 <= * [/b] [/bounds] [integer] x1 x2 [/integer]
Wed Oct 21 21:17:32 2015