Controls and Attributes

Topics covered in this chapter:

A control is a parameter that can influence the performance and behavior of the Xpress Optimizer. For example, the MIP gap, the feasibility tolerance, or the type of root LP algorithms are controls that can be set. Controls can both be read from and written to an optimization problem.

An attribute is a feature of an optimization problem, such as the number of rows and columns or the number of quadratic elements of the objective function. They are read-only parameters in that they can only be modified, for example, by functions for adding constraints or variables, or functions for setting and modifying the objective function.

Both controls and attributes are of three types: integer, floating point, or string. The Xpress Python interface allows for setting and retrieving the value of all controls of an optimization problem, as well as getting the value of all of a problem's attributes.

This reference manual does not describe the meaning of controls and attributes in the Xpress Optimizer; for a detailed description of each, please refer to the Optimizer's reference manual.

Following Python's philosophy, one can set and obtain multiple controls/attributes with one function call. In other words, one can set either (i) a single control and its value; or (ii) a Python dictionary coupling a list of control names and their respective value. Similarly, with one function call one can obtain (i) the value of a single attribute or control by specifying it as a parameter; or (ii) a dictionary associating names to values for each of a list of controls or attributes given as an argument. See the examples below for more information.

Controls

Use problem.setControl to set the value of one or more controls. Its synopsis is as follows:

setControl(ctrl, value)
setControl({ctrl1: value1, ctrl2: value2, ..., ctrlk: valuek})

The first form is for setting the value of the control ctrl to value. The second form is for setting ctrl1 to value1, ctrl2 to value2, ..., and ctrlk to valuek.

A list of all controls can be found on the Xpress Optimizer's reference manual. The control parameters to be passed in setControl are lower-case strings or upper-case strings (mixed lower- and upper-case will return an error), although in this manual we will only use lower-case:

p.setControl('miprelstop', 1e-9)
p.setControl({'miprelstop': 1e-3, 'feastol': 1e-6})

Alternatively, the control(s) to be changed can be identified by numeric id.

Use the method getControl to retrieve the value of one or more controls. Its synopsis is one of the following:

getControl(ctrl)
getControl([ctrl1, ctrl2, ..., ctrlk])
getControl(ctrl1, ctrl2, ..., ctrlk)
getControl()

The first form is for obtaining the value of the control ctrl. The output will be the value of the control. The second and third forms are for retrieving ctrl1 , ctrl2 , ..., and ctrlk. Whether the controls are declared in a list or a tuple does not matter. The result will be a dictionary coupling each control with its value. The last form is to obtain all controls; the result is a dictionary coupling all controls with their respective value.

Similar to problem.setControl, the control parameters to be passed in getControl are lower-case or upper-case strings. For a problem p the call will be as follows:

mrs = p.getControl('miprelstop')
someattr = p.getControl('miprelstop', 'feastol')

Alternatively, controls can be specified by their numeric id. In that case a returned dictionary will have that id as key for the requested control.

Examples

import xpress as xp

p = xp.problem()

p.setControl({'miprelstop': 1e-5, 'feastol': 1e-4})
p.setControl('miprelstop', 1e-5)

print(p.getControl('miprelstop') )           # print the current value of miprelstop
print(p.getControl('maxtime', 'feastol'))    # print a dictionary with the current
                                             # value of miprelstop and feastol
print(p.getControl(['presolve', 'miplog']))  # Same output
print(p.getControl())                        # print a dictionary with ALL control

# Initialize a dictionary with two controls and their value. Then
# change their value conditionally and set their new (possibly
# changed) value.

myctrl = p.getControl(['miprelstop', 'feastol'])

if (myctrl['miprelstop'] <= 1e-4):
    myctrl['miprelstop']  = 1e-3
    myctrl['feastol']     = 1e-3
else:
    myctrl['feastol']     = 1e-4

p.setControl(myctrl)

Attributes

Use the method getAttrib to retrieve the value of one or more attributes. Its synopsis is one of the following:

getAttrib(attr)
getAttrib([attr1, attr2, ..., attrk])
getAttrib(attr1, attr2, ..., attrk)
getAttrib()

The first form is for obtaining the value of the attribute attr. The output will be the value of the attribute. The second and third forms are for retrieving attr1 , attr2 , ..., and attrk. Whether the attributes are declared in a list or a tuple does not matter. The result will be a dictionary coupling each attribute with its value. The last form is to obtain all attributes; the result is a dictionary coupling all attributes with their respective value.

A list of all attributes can be found on the Xpress Optimizer's reference manual. As for controls, the attribute parameters to be passed in getAttrib are lower-case or upper-case strings (mixed lower- and upper-case strings are, similar to controls, forbidden). For a problem p the call will be as follows:

nrows = p.getAttrib('rows')
problemsize = p.getAttrib('rows', 'cols')

Alternatively, attributes can be specified by their numeric id. In that case a returned dictionary will have that id as key for the requested attribute.

Examples

import xpress as xp

p = xp.problem()

p.read("example.lp")

print("The problem has",
    p.getAttrib('rows'), "rows and",
    p.getAttrib('cols'), "columns")

# Obtain dictionary with two entries: the number of rows and
# columns of the problem read

print(p.getAttrib(['rows', 'cols']))

# produce a Python dictionary with all attributes of problem m, and
# hence of LP file example.lp

attributes = p.getAttrib()

Accessing controls and attributes as object members

An alternative, more "prompt-friendly" way to get controls and attributes is through their direct access in a problem or, in the case of controls, the Xpress module itself.

The Xpress module has an object, called controls, containing all controls of the Optimizer. Upon importing the Xpress module, these controls are initialized at their default value. The user can obtain their value at any point and can also set their value; this new value will be inherited by all problems created after the modification. They can be read and written as follows:

xpress.controls.<controlname>
xpress.controls.<controlname> = <new value>

For example, the object xpress.controls.miprelstop contains the value of the control miprelstop. Controls can be read (and, for example, printed) and set as follows:

import xpress as xp
print(xp.controls.heuremphasis)
xp.controls.feastol = 1e-4 # Set new default to 1e-4

These "global" controls are maintained throughout while the Xpress module is loaded. Note that the controls object of the Xpress module does not refer to any specific problem. All controls have default values that are determined by the Optimizer's library, except for the control xslp_postsolve that is set to 1, as opposed to its default value of 0 in the Xpress Optimizer's library.

In addition, every problem has a controls object that stores the controls related to the problem itself. This is the object the functions getControl and setControl refer to. Similar to the Xpress module's controls object, all members of a problem's object can be read and written. For a problem p, the following shows how to read and write a problem's control:

p.controls.<controlname>
p.controls.<controlname> = <new value>

A problem's controls are independent of the global controls object of the Xpress module. However, when a new problem is created its controls are copied from the current values in the global object. Note that after creating a new problem, changing the members in xpress.controls does not affect the problem's controls. The following examples should clarify this:

import xpress as xp

# create a new problem whose MIPRELSTOP is ten times smaller
# than the default value

p1 = xp.problem("problem1")
p1.controls.miprelstop = 0.1 * xp.controls.miprelstop
p1.controls.feastol = 1e-5
p1.read("example1.lp")

xp.controls.miprelstop = 1e-8 # Set new default

# The new problem will have a MIPRELSTOP of 1e-8

p2 = xp.problem("problem2")
p2.read("example2.lp")

# The next problem has a less restrictive feasibility tolerance
# (i.e. 1e-6) than problem 2

p2v = xp.problem("problem2 variant")
p2v.read("example2.lp")
p2v.controls.feastol = 100 * p2.controls.feastol

p1.optimize()
p2.optimize()

# solve "example2.lp" with a less restrictive
# feasibility tolerance
p2v.optimize()

Attributes can be handled similar as above through a member of the class problem, called attributes, with two exceptions: first, there is no "global" attribute object, as a set of attributes only makes sense when associated with a problem; second, an attribute cannot be set.

Once a problem p has been created (or read from a file), its attributes are available as p.attribute.attribute_name. The example in the previous section can be modified as follows:

import xpress as xp
p = xp.problem()
p.read("example.lp")
print("The problem has",
    p.attributes.rows, "rows and",
    p.attributes.cols, "columns")

When using the Python prompt in creating problems with the Xpress module, the name of controls and attributes can be auto-completed by pressing TAB (note: this only works in Python 3.4 and subsequent versions). For instance,

>>> import xpress
>>> p = xp.problem()
>>> p.read("example.lp")
>>> p.attributes.n<TAB>
p.attributes.namelength  p.attributes.nodedepth   p.attributes.nodes  p.attributes.numiis
>>> p.attributes.nodedepth
0
>>> p.attributes.ma<TAB>
p.attributes.matrixname          p.attributes.maxabsdualinfeas
p.attributes.maxabsprimalinfeas  p.attributes.maxprobnamelength
p.attributes.maxreldualinfeas    p.attributes.maxrelprimalinfeas
>>> p.attributes.matrixname
'noname'
>>> xp.controls.o<TAB>
xp.controls.oldnames             xp.controls.omniformat
xp.controls.optimalitytol        xp.controls.optimalitytoltarget
xp.controls.outputlog            xp.controls.outputmask
xp.controls.outputtol
>>> xp.controls.omniformat
0