Migrating to the linked API

Topics covered in this chapter:

Prior to Xpress 9.4, variables and constraints in the Python API were global objects that could be shared among several different problems at the same time. As a consequence, the attributes of variable and constraint objects could not be used to inspect or modify the optimization problem held in the solver after being added to it:

import xpress as xp
x = xp.var(ub=1)
p1 = xp.problem(x)
x.ub = 10           # Does not modify problem p1
p2 = xp.problem(x)
# Upper bound of x is 1 in p1 and 10 in p2

Xpress 9.4 introduces a new way to create variables and constraints that are associated with a single problem. These variables and constraints are called linked objects, to distinguish them from the unlinked objects that were used in previous releases. The attributes of linked objects are synchronized with the optimization problem:

import xpress as xp
p = xp.problem()
x = p.addVariable(ub=1)
x.ub = 10   # Problem p is updated with the new upper bound

Unlinked variables and constraints are deprecated and will be removed in a future release.

Creating linked variables

Linked variables are created using problem.addVariable:

import xpress as xp
p = xp.problem()
x = p.addVariable(name='x', lb=0, ub=5, vartype=xp.integer)

addVariable takes exactly the same arguments as the deprecated xpress.var constructor, so migrating code that uses unlinked variables is simple:

import xpress as xp

# Before (unlinked)
p = xp.problem()              # Create problem
x = xp.var(name=...)          # Create unlinked variable
p.addVariable(x)              # Add variable to problem

# After (linked)
p = xp.problem()              # Create problem
x = p.addVariable(name=...)   # Create linked variable within the problem

Note that the addVariable function was previously used to add existing unlinked variables to a problem. This is no longer necessary. The calls to xpress.var(var_attributes...) and problem.addVariable(myvar) should be replaced with a single call to problem.addVariable(var_attributes...).

Several linked variables can be created at once using problem.addVariables:

import xpress as xp
p = xp.problem(x)
x = p.addVariables(10)  # Returns a NumPy array of 10 linked variables

addVariables takes exactly the same arguments as the deprecated xpress.vars function, so migrating code that uses unlinked variables is again simple:

import xpress as xp

# Before (unlinked)
p = xp.problem()        # Create problem
x = xp.vars(10)         # Create 10 unlinked variables
p.addVariable(x)        # Add variables to problem

# After (linked)
p = xp.problem()        # Create problem
x = p.addVariables(10)  # Create 10 linked variables within the problem

Creating linked constraints

Linked constraints are created using the same syntax as unlinked constraints: using an inequality operator or by explicitly calling the xpress.constraint constructor. As in previous releases, constraints must be explicitly added to the problem by calling problem.addConstraint. The attributes of linked constraints are synchronized with the problem:

import xpress as xp
p = xp.problem()
x, y = p.addVariables(2, vartype=xp.binary)
c = (x + y <= 1)
p.addConstraint(c)
c.rhs = 2     #  Problem p is updated with the new right-hand side

A constraint involving linked variables can only be added to the problem which owns those variables.

Creating linked SOS constraints

Linked special ordered set (SOS) constraints are created using problem.addSOS:

import xpress as xp
p = xp.problem()
x, y = p.addVariables(2)
s = p.addSOS([x, y], [1, 2])  # Create SOS1 constraint with given weights

addSOS takes exactly the same arguments as the deprecated xpress.sos constructor, so migrating code that uses unlinked SOS constraints is simple:

import xpress as xp

# Before (unlinked)
p = xp.problem()              # Create problem
x, y = xp.vars(2)             # Create unlinked variables
p.addVariable(x, y)           # Add variables
s = xp.sos([x, y], [1, 2])    # Create unlinked SOS1 constraint
p.addSOS(s)                   # Add SOS to problem

# After (linked)
p = xp.problem()              # Create problem
x, y = p.addVariables(2)      # Create linked variables
s = p.addSOS([x, y], [1, 2])  # Create linked SOS1 constraint within the problem

Note that the addSOS function was previously used to add existing unlinked SOS constraints to a problem. This is no longer necessary. The calls to xpress.sos(sos_attributes...) and problem.addSOS(mysos) should be replaced with a single call to problem.addSOS(sos_attributes...).

Creating linked problems

When working with unlinked objects, the variables, constraints and objective could be provided as problem constructor arguments:

import xpress as xp
x, y = xp.vars(2)
p = xp.problem(x, y, x + y <= 1, 2 * x)

When working with linked objects, the problem must be created first, before the variables and constraints. Only the optional name argument may be provided in the constructor. When migrating code that uses unlinked objects, it may be necessary to move the call to the problem constructor earlier in your code, and to add explicit calls to problem.addConstraint and problem.setObjective.

import xpress as xp
p = xp.problem('myprob')
x, y = p.addVariables(2)
p.addConstraint(x + y <= 1)
p.setObjective(2 * x)

Other API functions

The following functions can create either linked or unlinked objects, depending on the context: problem.addrows, problem.addcols, problem.read, problem.loadproblem. If the problem already contains unlinked objects, these functions will continue to create unlinked objects. If not, the default behaviour is now to create linked objects. The previous behaviour of creating unlinked objects can be achieved by passing the argument unlinked=True:

import xpress as xp
p = xp.problem()
p.readprob('myprob.mps', unlinked=True)   # Creates unlinked objects

Summary

The following usages are deprecated and will be removed in a future release:

xpress.var

Replace these calls with problem.addVariable

xpress.vars

Replace these calls with problem.addVariables

xpress.sos

Replace these calls with problem.addSOS

problem.addVariable(var1, var2, ...)

Remove these calls

problem.addSOS(sos1, sos2, ...)

Remove these calls

xpress.problem(vars, constraints, objective)

Remove constructor arguments and add explicit calls to problem.addConstraint and problem.setObjective