Reference

This section contains the reference to all the classes and functions of the C++ API.

Generic

class ampls::AMPLModel

Store an in-memory representation of an AMPL model, which can be constructed by loading it from an NL file using the loadModel function available in a solver driver (i.e.

CPLEXDrv::loadModel(), GurobiDrv::loadModel() or XPRESSDrv::loadModel()). It also contains two-way mappings between solver column and row numbers and AMPL entity names.

Subclassed by ampls::AMPLMPModel

Public Functions

inline std::string getFileName()

Get the name of the NL file from which the model has been loaded from.

std::map<int, std::string> getVarMapInverse()

Get the map from variable index in the solver interface to AMPL variable instance name.

std::map<int, std::string> getConMapInverse()

Get the map from constraint index in the solver interface to AMPL variable instance name.

inline std::map<std::string, int> getVarMap()

Get the map from variable name to index in the solver interface.

inline std::map<std::string, int> getConMap()

Get the map from constraint name to index in the solver interface.

std::map<std::string, int> getVarMapFiltered(const char *beginWith)

Return the variable map filtered by the variable name, to avoid getting the whole (possibly large) map.

Parameters

beginWith – Prefix to be matched

std::map<std::string, int> getConMapFiltered(const char *beginWith)

Return the constraint map filtered by the constraint name, to avoid getting the whole (possibly large) map.

Parameters

beginWith – Prefix to be matched

inline virtual int setCallback(GenericCallback *callback)

Set a generic callback to be called during optimization.

This function is automatically dispatched when (and only when) assigning an ampls::GenericCallback, as it needs a special treatment to automatically create the solver-specific wrapper

Parameters

callback – The generic callback to be set

inline int setCallback(impl::BaseCallback *callback)

Set callback to be called during optimization.

Parameters

callback – The callback to be set

std::vector<double> getSolutionVector()

Get all the variables of the current problem.

inline std::vector<double> getDualVector()

Get all the dual values of the current problem.

inline virtual int getNumVars()

Get the number of variables.

inline virtual int getNumCons()

Get the number of constraints.

inline virtual Status::SolStatus getStatus()

Get the solution status P(generic)

inline virtual void optimize()

Start the optimization process.

inline virtual void writeSol()

Write the solution file to the defualt location (filename.sol in the original directory)

inline virtual void writeSol(const char *solFileName)

Write the solution file to a specific file.

Parameters

solFileName – Path of the solution file to write

inline virtual int getSolution(int first, int length, double *sol)

Get “length” variables of the current problem in an array, starting at the specified position.

Parameters

• first – Index of the first variable to return

• length – Number of variables to return

• sol – Array to store the values

inline virtual double getObj()

Get the current objective value.

inline virtual std::string error(int code)

Get the error message corresponding to the code.

inline virtual void enableLazyConstraints()

Enable adding lazy constraints via callbacks (to be called only once), call before calling AMPLModel::optimize() if planning to add lazy constraints via callbacks.

void printModelVars(bool onlyNonZero)

Utility function: prints all variables to screen.

inline virtual void setAMPLParameter(SolverParams::SolverParameters param, int value)

Set an integer parameter (solver control) using ampls generic aliases.

Parameters

• param – The parameter to be set

• value – The integer value to set

inline virtual void setAMPLParameter(SolverParams::SolverParameters params, double value)

Set an double parameter (solver control) using ampls generic aliases.

Parameters

• param – The parameter to be set

• value – The double value to set

inline virtual int getAMPLIntParameter(SolverParams::SolverParameters params)

Get the value of an integer parameter (solver control) using ampls generic aliases.

Parameters

param – The parameter to get

inline virtual double getAMPLDoubleParameter(SolverParams::SolverParameters param)

Get the value of a double parameter (solver control) using ampls generic aliases.

Parameters

param – The parameter to get

inline virtual std::vector<Option> getOptions()

Get a list of the options supported by the solver, as seen from the -= output of the solver driver.

Note that these options are the ones found in the list of the corresponding solver driver options at: https://dev.ampl.com/solvers/index.html

Returns

A vector of option descriptions

inline virtual void setOption(const char *name, int value)

Set a solver driver option to the specified value.

See getOptions() for a list of supported options. Note that some options (most notably the converter options, with prefixes acc: and cvt:) cannot be specified after the model has been loaded. Such options should be specified when loading/importing the model (AMPLModel::load or AMPLAPIInterface::exportModel<T>()). When in doubt, specify all options at loading time.

inline virtual int getIntOption(const char *name)

Get the current value of the option ‘name’.

See getOptions() for a list of supported options.

inline virtual double getDoubleOption(const char *name)

Get the current value of the option ‘name’.

See getOptions() for a list of supported options.

inline virtual std::string getStringOption(const char *name)

Get the current value of the option ‘name’. See getOptions() for a list of supported options.

inline virtual void refresh()

Refresh the underlying solver driver, useful in case solver options that involve reading suffixes have been changed with the AMPLModel::setOption set of functions

Public Static Functions

template<class T>
static inline T load(const char *nlfile, const char **options = nullptr)

Load a model from an NL file

Template Parameters

T – Concrete class (e.g. CPLEXModel, GurobiModel, …) to create

Parameters

• nlfile – NL file path

• options – NULL terminated array of startup options

Returns

class ampls::GenericCallback : public ampls::impl::BaseCallback

Base abstract class for generic callbacks, inherit from this class to implement a generic callback.

Provides all mapping between solver-specific and generic values. To implement a callback, you should implement the run() method and set it via AMPLModel::setCallback() before starting the solution process via AMPLModel::optimize(). Depending on where in the solution process the callback is called from, you can obtain various information about the progress of the optimization and can modify the behaviour of the solver.

Public Functions

inline virtual int getSolution(int len, double *sol)

Get the current solution vector

inline virtual std::vector<double> getSolutionVector()

Get the current solution vector.

inline virtual std::vector<double> getValueArray(Value::CBValue v)

Get a (generic) array.

inline virtual double getObj()

Get the current objective value.

inline virtual int getWhere()

Get an iteger representing where in the solution process the callback has been called.

NOTE: this is expressed using the solver’s own (not generic) values

inline virtual Where::CBWhere getAMPLWhere()

Get where in the solution process the callback has been called (generic)

inline virtual const char *getWhereString()

Get a textual representation of the current solver status.

inline virtual const char *getMessage()

Get the message that was being printed (if where == msg)

inline virtual Variant getValue(Value::CBValue v)

Get a value from the solver.

virtual int run() = 0

Function to override, called periodically by the optimizer.

std::map<std::string, int> &getVarMap()

Get the map AMPLEntityName -> SolverVarIndex.

std::map<int, std::string> &getVarMapInverse()

Get the map SolverVarIndex -> AMPLEntityName.

inline ampls::Constraint addCut(std::vector<std::string> vars, const double *coeffs, CutDirection::Direction direction, double rhs)

Add a user cut using AMPL variables names.

Parameters

• vars – Vector of AMPL variable names

• coeffs – Vector of cut coefficients

• direction – Direction of the constraint ampls::CBDirection::Direction

• rhs – Right hand side value

inline ampls::Constraint addLazy(std::vector<std::string> vars, const double *coeffs, CutDirection::Direction direction, double rhs)

Add a lazy constraint using AMPL variables names.

Parameters

• vars – Vector of AMPL variable names

• coeffs – Vector of cut coefficients

• direction – Direction of the constraint ampls::CBDirection::Direction

• rhs – Right hand side value

inline ampls::Constraint addCutIndices(int nvars, const int *vars, const double *coeffs, CutDirection::Direction direction, double rhs)

Add a user cut using solver indics.

Parameters

• nvars – Number of variables in the cut (length of *vars)

• vars – Vector of variable indices (in the solvers representation)

• coeffs – Vector of cut coefficients

• direction – Direction of the constraint ampls::CBDirection::Direction

• rhs – Right hand side value

inline ampls::Constraint addLazyIndices(int nvars, const int *vars, const double *coeffs, CutDirection::Direction direction, double rhs)

Add a lazy constraint using solver indics.

Parameters

• nvars – Number of variables in the cut (length of *vars)

• vars – Vector of variable indices (in the solvers representation)

• coeffs – Vector of cut coefficients

• direction – Direction of the constraint ampls::CBDirection::Direction

• rhs – Right hand side value

enum ampls::Where::CBWhere

These values (generic) identify where in the solution process a callback has been called; to get this generic value call GenericCallback::getAMPLType().

Not all solvers “where” are mapped to these values; in case the callback is called with a not-mapped “where” parameter, refer to the solver-specific functionality.

Values:

enumerator MSG

When the solver wants to print a message, obtain it via GenericCallback::getMessage.

enumerator PRESOLVE

Presolve phase.

enumerator LPSOLVE

Executing simplex.

enumerator MIPNODE

Exploring a MIP node.

enumerator MIPSOL

Found a new MIP solution.

enumerator MIP

Executing MIP algorithm.

enumerator NOTMAPPED

Not mapped, refer to the specific user documentation.

enum ampls::Value::CBValue

Which values (generic) to get in a callback; just a subset of all the value types are mapped here.

In case a not mapped value is required, refer to the solver-specific API.

Values:

enumerator OBJ

Objective value.

enumerator PRE_DELCOLS

Presolve: number of deleted columns.

enumerator PRE_DELROWS

Presolve: number of deleted rows.

enumerator PRE_COEFFCHANGED

Presolve: number of coefficients changed.

enumerator ITERATIONS

Number of algorithm iterations.

enumerator RUNTIME

Time since solution start.

enumerator MIP_NODES

Number of MIP nodes.

enumerator MIP_RELATIVEGAP

Current relative MIP gap.

enumerator MIP_OBJBOUND

Current best bound on objective.

enumerator MIP_SOL_RELAXED

enumerator N_ROWS

enumerator N_COLS

Gurobi

class ampls::GurobiModel : public ampls::AMPLMPModel

Encapsulates all the instance level information for a gurobi model, namely the GRBmodel object and the relative MP library.

It can not be created any other way than by reading an nl file, and any assignment moves actual ownership. At the end of its life, it deletes the GRBmodel and the MP structures.

Public Functions

inline virtual void enableLazyConstraints()

Enable adding lazy constraints via callbacks (to be called only once), call before calling AMPLModel::optimize() if planning to add lazy constraints via callbacks.

inline virtual Status::SolStatus getStatus()

Get the solution status P(generic)

inline virtual int getNumVars()

Get the number of variables.

inline virtual int getNumCons()

Get the number of constraints.

inline virtual double getObj()

Get the current objective value.

inline virtual int getSolution(int first, int length, double *sol)

Get “length” variables of the current problem in an array, starting at the specified position.

Parameters

• first – Index of the first variable to return

• length – Number of variables to return

• sol – Array to store the values

virtual std::string error(int code)

Get the error message corresponding to the code.

int getIntAttr(const char *name)

Get an integer model attribute (using gurobi C library name)

double getDoubleAttr(const char *name)

Get a double model attribute (using gurobi C library name)

int getIntAttrArray(const char *name, int first, int length, int *arr)

Get an integer array model attribute (using gurobi C library name)

int getDoubleAttrArray(const char *name, int first, int length, double *arr)

Get a double array model attribute (using gurobi C library name)

inline int getIntParam(const char *name)

Get an integer parameter (using gurobi C library name)

inline double getDoubleParam(const char *name)

Get a double parameter (using gurobi C library name)

inline char *getStringParam(const char *name)

Get a textual parameter (using gurobi C library name)

inline void setParam(const char *name, int value)

Set an integer parameter (using gurobi C library name)

inline void setParam(const char *name, double value)

Set a double parameter (using gurobi C library name)

inline void setParam(const char *name, const char *value)

Set a textual parameter (using gurobi C library name)

inline GRBmodel *getGRBmodel()

Get the pointer to the native C GRBmodel structure.

inline GRBenv *getGRBenv()

Get the pointer to the native C GRBenv structure.

inline virtual void setAMPLParameter(SolverParams::SolverParameters param, int value)

Set an integer parameter using ampls aliases.

inline virtual void setAMPLParameter(SolverParams::SolverParameters param, double value)

Set a double parameter using ampls aliases.

inline virtual int getAMPLIntParameter(SolverParams::SolverParameters param)

Get an integer parameter using ampls aliases.

inline virtual double getAMPLDoubleParameter(SolverParams::SolverParameters params)

Get a double parameter using ampls aliases.

inline virtual int getAMPLIntAttribute(SolverAttributes::Attribs attrib)

Get an integer attribute using ampls aliases.

inline virtual double getAMPLDoubleAttribute(SolverAttributes::Attribs attrib)

Get a double attribute using ampls aliases.

std::vector<double> getSolutionVector()

Get all the variables of the current problem.

inline virtual std::vector<Option> getOptions()

Get a list of the options supported by the solver, as seen from the -= output of the solver driver.

Note that these options are the ones found in the list of the corresponding solver driver options at: https://dev.ampl.com/solvers/index.html

Returns

A vector of option descriptions

virtual void setOption(const char *name, int value)

Set a solver driver option to the specified value.

See getOptions() for a list of supported options.

virtual void setOption(const char *name, double value)

Set an option to the specified value.

See getOptions() for a list of supported options.

virtual void setOption(const char *name, const char *value)

Set an option to the specified value. See getOptions() for a list of supported options.

inline virtual int getIntOption(const char *name)

Get the current value of the option ‘name’.

See getOptions() for a list of supported options.

inline virtual double getDoubleOption(const char *name)

Get the current value of the option ‘name’.

See getOptions() for a list of supported options.

inline virtual std::string getStringOption(const char *name)

Get the current value of the option ‘name’. See getOptions() for a list of supported options.

inline virtual void refresh()

Refresh the underlying model (especially useful if modifying with setOption() functionalities that need suffixes to be read from the NL file

inline virtual void optimize()

Solve using the underlying MP solver driver functionality

inline std::string getFileName()

Get the name of the NL file from which the model has been loaded from.

std::map<int, std::string> getVarMapInverse()

Get the map from variable index in the solver interface to AMPL variable instance name.

std::map<int, std::string> getConMapInverse()

Get the map from constraint index in the solver interface to AMPL variable instance name.

inline std::map<std::string, int> getVarMap()

Get the map from variable name to index in the solver interface.

inline std::map<std::string, int> getConMap()

Get the map from constraint name to index in the solver interface.

std::map<std::string, int> getVarMapFiltered(const char *beginWith)

Return the variable map filtered by the variable name, to avoid getting the whole (possibly large) map.

Parameters

beginWith – Prefix to be matched

std::map<std::string, int> getConMapFiltered(const char *beginWith)

Return the constraint map filtered by the constraint name, to avoid getting the whole (possibly large) map.

Parameters

beginWith – Prefix to be matched

inline virtual int setCallback(GenericCallback *callback)

Set a generic callback to be called during optimization.

This function is automatically dispatched when (and only when) assigning an ampls::GenericCallback, as it needs a special treatment to automatically create the solver-specific wrapper

Parameters

callback – The generic callback to be set

inline int setCallback(impl::BaseCallback *callback)

Set callback to be called during optimization.

Parameters

callback – The callback to be set

inline std::vector<double> getDualVector()

Get all the dual values of the current problem.

inline virtual void writeSol()

Write the solution file to the defualt location (filename.sol in the original directory)

inline virtual void writeSol(const char *solFileName)

Write the solution file to a specific file.

Parameters

solFileName – Path of the solution file to write

void printModelVars(bool onlyNonZero)

Utility function: prints all variables to screen.

Public Static Functions

template<class T>
static inline T load(const char *nlfile, const char **options = nullptr)

Load a model from an NL file

Template Parameters

T – Concrete class (e.g. CPLEXModel, GurobiModel, …) to create

Parameters

• nlfile – NL file path

• options – NULL terminated array of startup options

Returns

class ampls::GurobiCallback : public ampls::impl::BaseCallback

Base class for Gurobi callbacks, inherit from this to declare a callback to be called at various stages of the solution process.

Provides all mapping between solver-specific and generic values. To implement a callback, you should implement the run() method and set it via AMPLModel::setCallback() before starting the solution process via AMPLModel::optimize(). Depending on where the callback is called from, you can obtain various information about the progress of the optimization and can modify the behaviour of the solver.

Public Functions

virtual int run() = 0

Function to override, called periodically by the optimizer.

virtual const char *getWhereString()

Get a string description of where the callback was called from.

virtual const char *getMessage()

To get the gurobi log message.

virtual int getSolution(int len, double *sol)

Get the current solution.

virtual double getObj()

Get the current objective value.

inline void *getCBData()

Get CBdata, useful for calling gurobi c library functions.

GRBmodel *getGRBModel()

• Get the underlying gurobi model pointer

void terminate()

Terminate the solution.

inline int getInt(int what)

Get an integer attribute (using gurobi C library enumeration to specify what)

inline double getDouble(int what)

Get a double attribute (using gurobi C library enumeration to specify what)

inline std::vector<double> getDoubleArray(int what)

Get a double array attribute (using gurobi C library enumeration to specify what)

inline double setSolution(double *x)

Set the current solution.

inline virtual Where::CBWhere getAMPLWhere()

Get where in the solution process the callback has been called (generic)

Variant get(int what)

Get a value (using gurobi C library enumeration to specify what)

inline virtual std::vector<double> getValueArray(Value::CBValue v)

Get a (generic) array.

std::map<std::string, int> &getVarMap()

Get the map AMPLEntityName -> SolverVarIndex.

std::map<int, std::string> &getVarMapInverse()

Get the map SolverVarIndex -> AMPLEntityName.

inline ampls::Constraint addCut(std::vector<std::string> vars, const double *coeffs, CutDirection::Direction direction, double rhs)

Add a user cut using AMPL variables names.

Parameters

• vars – Vector of AMPL variable names

• coeffs – Vector of cut coefficients

• direction – Direction of the constraint ampls::CBDirection::Direction

• rhs – Right hand side value

inline ampls::Constraint addLazy(std::vector<std::string> vars, const double *coeffs, CutDirection::Direction direction, double rhs)

Add a lazy constraint using AMPL variables names.

Parameters

• vars – Vector of AMPL variable names

• coeffs – Vector of cut coefficients

• direction – Direction of the constraint ampls::CBDirection::Direction

• rhs – Right hand side value

inline ampls::Constraint addCutIndices(int nvars, const int *vars, const double *coeffs, CutDirection::Direction direction, double rhs)

Add a user cut using solver indics.

Parameters

• nvars – Number of variables in the cut (length of *vars)

• vars – Vector of variable indices (in the solvers representation)

• coeffs – Vector of cut coefficients

• direction – Direction of the constraint ampls::CBDirection::Direction

• rhs – Right hand side value

inline ampls::Constraint addLazyIndices(int nvars, const int *vars, const double *coeffs, CutDirection::Direction direction, double rhs)

Add a lazy constraint using solver indics.

Parameters

• nvars – Number of variables in the cut (length of *vars)

• vars – Vector of variable indices (in the solvers representation)

• coeffs – Vector of cut coefficients

• direction – Direction of the constraint ampls::CBDirection::Direction

• rhs – Right hand side value

virtual std::vector<double> getSolutionVector()

Get the current solution vector.

inline virtual int getWhere()

Get an iteger representing where in the solution process the callback has been called.

NOTE: this is expressed using the solver’s own (not generic) values

inline virtual Variant getValue(Value::CBValue v)

Get a (generic) value.

class ampls::GurobiDrv : public ampls::impl::SolverDriver<GurobiModel>

Encapsulates the main environment of the gurobi driver.

Public Functions

inline GurobiModel loadModel(const char *modelName, const char **options = nullptr)

Load a model from an NL file.

Mappings between solver row and column numbers and AMPL names are available only if the row and col files have been generated as well, by means of the ampl option option auxfiles cr; before writing the NL file.

CPLEX

class ampls::CPLEXModel : public ampls::AMPLMPModel

Encapsulates all the instance level information for a CPLEX model, namely the CPLEX object, the relative ASL and all the locals of the driver up to the moment in which optimize would be called.

It can not be created any other way than by reading an nl file, and any assignment moves actual ownership. At the end of its life, it deletes the relative structures.

Public Functions

inline virtual Status::SolStatus getStatus()

Get the solution status P(generic)

virtual void optimize()

Solve using the underlying MP solver driver functionality

inline virtual int getNumVars()

Get the number of variables.

inline virtual int getNumCons()

Get the number of constraints.

inline virtual double getObj()

Get the current objective value.

inline virtual int getSolution(int first, int length, double *sol)

Get “length” variables of the current problem in an array, starting at the specified position.

Parameters

• first – Index of the first variable to return

• length – Number of variables to return

• sol – Array to store the values

virtual std::string error(int code)

Get the error message corresponding to the code.

inline virtual int setCallback(GenericCallback *callback)

Set a generic callback to be called during optimization.

This function is automatically dispatched when (and only when) assigning an ampls::GenericCallback, as it needs a special treatment to automatically create the solver-specific wrapper

Parameters

callback – The generic callback to be set

inline CPXLPptr getCPXLP()

Get the pointer to the native CPLEX LP model object.

inline CPXENVptr getCPXENV()

Get the pointer to the native CPLEX environment object.

inline void setParam(int CPXPARAM, int value)

Set an integer CPLEX control parameter.

inline void setParam(int CPXPARAM, double value)

Set a double CPLEX control parameter.

inline int getIntParam(int CPXPARAM)

Get an integer CPLEX control parameter.

inline double getDoubleParam(int CPXPARAM)

Get a double CPLEX control parameter.

inline virtual int getAMPLIntParameter(SolverParams::SolverParameters param)

Get an integer parameter using ampls aliases.

inline virtual double getAMPLDoubleParameter(SolverParams::SolverParameters param)

Get a double parameter using ampls aliases.

inline virtual void setAMPLParameter(SolverParams::SolverParameters param, int value)

Set an integer parameter using ampls aliases.

inline virtual void setAMPLParameter(SolverParams::SolverParameters param, double value)

Set a double parameter using ampls aliases.

inline virtual int getAMPLIntAttribute(SolverAttributes::Attribs attrib)

Get an integer attribute using ampls aliases.

inline virtual double getAMPLDoubleAttribute(SolverAttributes::Attribs attrib)

Get a double attribute using ampls aliases.

inline virtual std::vector<Option> getOptions()

Get a list of the options supported by the solver, as seen from the -= output of the solver driver.

Note that these options are the ones found in the list of the corresponding solver driver options at: https://dev.ampl.com/solvers/index.html

Returns

A vector of option descriptions

virtual void setOption(const char *name, int value)

Set a solver driver option to the specified value.

See getOptions() for a list of supported options.

virtual void setOption(const char *name, double value)

Set an option to the specified value.

See getOptions() for a list of supported options.

virtual void setOption(const char *name, const char *value)

Set an option to the specified value. See getOptions() for a list of supported options.

inline virtual int getIntOption(const char *name)

Get the current value of the option ‘name’.

See getOptions() for a list of supported options.

inline virtual double getDoubleOption(const char *name)

Get the current value of the option ‘name’.

See getOptions() for a list of supported options.

inline virtual std::string getStringOption(const char *name)

Get the current value of the option ‘name’. See getOptions() for a list of supported options.

inline virtual void refresh()

Refresh the underlying model (especially useful if modifying with setOption() functionalities that need suffixes to be read from the NL file

inline std::string getFileName()

Get the name of the NL file from which the model has been loaded from.

std::map<int, std::string> getVarMapInverse()

Get the map from variable index in the solver interface to AMPL variable instance name.

std::map<int, std::string> getConMapInverse()

Get the map from constraint index in the solver interface to AMPL variable instance name.

inline std::map<std::string, int> getVarMap()

Get the map from variable name to index in the solver interface.

inline std::map<std::string, int> getConMap()

Get the map from constraint name to index in the solver interface.

std::map<std::string, int> getVarMapFiltered(const char *beginWith)

Return the variable map filtered by the variable name, to avoid getting the whole (possibly large) map.

Parameters

beginWith – Prefix to be matched

std::map<std::string, int> getConMapFiltered(const char *beginWith)

Return the constraint map filtered by the constraint name, to avoid getting the whole (possibly large) map.

Parameters

beginWith – Prefix to be matched

std::vector<double> getSolutionVector()

Get all the variables of the current problem.

inline std::vector<double> getDualVector()

Get all the dual values of the current problem.

inline virtual void writeSol()

Write the solution file to the defualt location (filename.sol in the original directory)

inline virtual void writeSol(const char *solFileName)

Write the solution file to a specific file.

Parameters

solFileName – Path of the solution file to write

inline virtual void enableLazyConstraints()

Enable adding lazy constraints via callbacks (to be called only once), call before calling AMPLModel::optimize() if planning to add lazy constraints via callbacks.

void printModelVars(bool onlyNonZero)

Utility function: prints all variables to screen.

Public Static Functions

template<class T>
static inline T load(const char *nlfile, const char **options = nullptr)

Load a model from an NL file

Template Parameters

T – Concrete class (e.g. CPLEXModel, GurobiModel, …) to create

Parameters

• nlfile – NL file path

• options – NULL terminated array of startup options

Returns

class ampls::CPLEXCallback : public ampls::impl::BaseCallback

Base class for CPLEX callbacks, inherit from this to declare a callback to be called at various stages of the solution process.

Provides all mapping between solver-specific and generic values. To implement a callback, you should implement the run() method and set it via AMPLModel::setCallback() before starting the solution process via AMPLModel::optimize(). Depending on where the callback is called from, you can obtain various information about the progress of the optimization and can modify the behaviour of the solver.

Public Functions

int getMaxThreads()

CPLEX specific.

Usable only after linking the callback to a model using AMPLModel::setCallback. Returns the number of cores in the system or the value of the options threads, if present in the model

inline void enableThreadsSupport(int nthreads = 0)

Enable threads support for this callback.

Maximum supported threads = ncores if nthreads==0, else nthreads

inline int getWhere(int threadid = 0)

Get CPLEX callback context id

inline virtual int run()

Override to implement generic (or single threaded) callback

inline virtual int run(int threadid)

Override to implement multi-threaded callback (CPLEX-specific)

std::map<std::string, int> &getVarMap()

Get the map AMPLEntityName -> SolverVarIndex.

std::map<int, std::string> &getVarMapInverse()

Get the map SolverVarIndex -> AMPLEntityName.

inline ampls::Constraint addCut(std::vector<std::string> vars, const double *coeffs, CutDirection::Direction direction, double rhs)

Add a user cut using AMPL variables names.

Parameters

• vars – Vector of AMPL variable names

• coeffs – Vector of cut coefficients

• direction – Direction of the constraint ampls::CBDirection::Direction

• rhs – Right hand side value

inline ampls::Constraint addLazy(std::vector<std::string> vars, const double *coeffs, CutDirection::Direction direction, double rhs)

Add a lazy constraint using AMPL variables names.

Parameters

• vars – Vector of AMPL variable names

• coeffs – Vector of cut coefficients

• direction – Direction of the constraint ampls::CBDirection::Direction

• rhs – Right hand side value

inline ampls::Constraint addCutIndices(int nvars, const int *vars, const double *coeffs, CutDirection::Direction direction, double rhs)

Add a user cut using solver indics.

Parameters

• nvars – Number of variables in the cut (length of *vars)

• vars – Vector of variable indices (in the solvers representation)

• coeffs – Vector of cut coefficients

• direction – Direction of the constraint ampls::CBDirection::Direction

• rhs – Right hand side value

inline ampls::Constraint addLazyIndices(int nvars, const int *vars, const double *coeffs, CutDirection::Direction direction, double rhs)

Add a lazy constraint using solver indics.

Parameters

• nvars – Number of variables in the cut (length of *vars)

• vars – Vector of variable indices (in the solvers representation)

• coeffs – Vector of cut coefficients

• direction – Direction of the constraint ampls::CBDirection::Direction

• rhs – Right hand side value

virtual std::vector<double> getSolutionVector()

Get the current solution vector.

inline virtual int getWhere()

Get an iteger representing where in the solution process the callback has been called.

NOTE: this is expressed using the solver’s own (not generic) values

inline virtual Variant getValue(Value::CBValue v)

Get a (generic) value.

class ampls::CPLEXDrv : public ampls::impl::SolverDriver<CPLEXModel>

Encapsulates the main environment of the CPLEX driver; without modifications, a static CPLEXENV is created in the AMPL driver, and it would be fairly easy to lose track of it; this way, it is deleted in the destructor.

Public Functions

inline CPLEXModel loadModel(const char *modelName, const char **options = nullptr)

Load a model from an NL file.

Mappings between solver row and column numbers and AMPL names are available only if the row and col files have been generated as well, by means of the ampl option option auxfiles cr; before writing the NL file.

XPRESS

class ampls::XPRESSModel : public ampls::AMPLMPModel

Encapsulates all the instance level information for a CPLEX model, namely the CPLEX object, the relative ASL and all the locals of the driver up to the moment in which optimize would be called.

It can not be created any other way than by reading an nl file, and any assignment moves actual ownership. At the end of its life, it deletes the relative structures.

Public Functions

inline virtual Status::SolStatus getStatus()

Get the solution status P(generic)

inline virtual int getNumVars()

Get the number of variables.

inline virtual int getNumCons()

Get the number of constraints.

inline virtual double getObj()

Get the current objective value.

inline virtual int getSolution(int first, int length, double *sol)

Get “length” variables of the current problem in an array, starting at the specified position.

Parameters

• first – Index of the first variable to return

• length – Number of variables to return

• sol – Array to store the values

inline virtual std::string error(int code)

Get the error message corresponding to the code.

inline XPRSprob getXPRSprob()

Get a pointer to the underlying XPRESSprob object.

inline virtual void optimize()

Solve the problem.

inline int getIntAttr(int what)

Get an integer attribute identified by XPRESS native enum.

inline double getDoubleAttr(int what)

Get a double attribute identified by XPRESS native enum.

inline bool isMIP()

Return true if the problem is MIP.

inline void setParam(int XPRSParam, int value)

Set an integer XPRESS control parameter.

inline void setParam(int XPRSParam, double value)

Set a double XPRESS control parameter.

inline int getIntParam(int XPRSParam)

Get an integer XPRESS control parameter.

inline double getDoubleParam(int XPRSParam)

Get a double XPRESS control parameter.

inline virtual void enableLazyConstraints()

Enable adding lazy constraints via callbacks (to be called only once), call before calling AMPLModel::optimize() if planning to add lazy constraints via callbacks.

inline virtual void setAMPLParameter(SolverParams::SolverParameters param, int value)

Set an integer parameter using ampls aliases.

inline virtual void setAMPLParameter(SolverParams::SolverParameters param, double value)

Set a double parameter using ampls aliases.

inline virtual int getAMPLIntParameter(SolverParams::SolverParameters params)

Get an integer parameter using ampls aliases.

inline virtual double getAMPLDoubleParameter(SolverParams::SolverParameters params)

Get a double parameter using ampls aliases.

inline virtual int getAMPLIntAttribute(SolverAttributes::Attribs attrib)

Get an integer attribute using ampls aliases.

inline virtual double getAMPLDoubleAttribute(SolverAttributes::Attribs attrib)

Get a double attribute using ampls aliases.

inline virtual std::vector<Option> getOptions()

Get a list of the options supported by the solver, as seen from the -= output of the solver driver.

Note that these options are the ones found in the list of the corresponding solver driver options at: https://dev.ampl.com/solvers/index.html

Returns

A vector of option descriptions

virtual void setOption(const char *name, int value)

Set a solver driver option to the specified value.

See getOptions() for a list of supported options.

virtual void setOption(const char *name, double value)

Set an option to the specified value.

See getOptions() for a list of supported options.

virtual void setOption(const char *name, const char *value)

Set an option to the specified value. See getOptions() for a list of supported options.

inline virtual int getIntOption(const char *name)

Get the current value of the option ‘name’.

See getOptions() for a list of supported options.

inline virtual double getDoubleOption(const char *name)

Get the current value of the option ‘name’.

See getOptions() for a list of supported options.

inline virtual std::string getStringOption(const char *name)

Get the current value of the option ‘name’. See getOptions() for a list of supported options.

inline virtual void refresh()

Refresh the underlying model (especially useful if modifying with setOption() functionalities that need suffixes to be read from the NL file

inline std::string getFileName()

Get the name of the NL file from which the model has been loaded from.

std::map<int, std::string> getVarMapInverse()

Get the map from variable index in the solver interface to AMPL variable instance name.

std::map<int, std::string> getConMapInverse()

Get the map from constraint index in the solver interface to AMPL variable instance name.

inline std::map<std::string, int> getVarMap()

Get the map from variable name to index in the solver interface.

inline std::map<std::string, int> getConMap()

Get the map from constraint name to index in the solver interface.

std::map<std::string, int> getVarMapFiltered(const char *beginWith)

Return the variable map filtered by the variable name, to avoid getting the whole (possibly large) map.

Parameters

beginWith – Prefix to be matched

std::map<std::string, int> getConMapFiltered(const char *beginWith)

Return the constraint map filtered by the constraint name, to avoid getting the whole (possibly large) map.

Parameters

beginWith – Prefix to be matched

inline virtual int setCallback(GenericCallback *callback)

Set a generic callback to be called during optimization.

This function is automatically dispatched when (and only when) assigning an ampls::GenericCallback, as it needs a special treatment to automatically create the solver-specific wrapper

Parameters

callback – The generic callback to be set

inline int setCallback(impl::BaseCallback *callback)

Set callback to be called during optimization.

Parameters

callback – The callback to be set

std::vector<double> getSolutionVector()

Get all the variables of the current problem.

inline std::vector<double> getDualVector()

Get all the dual values of the current problem.

inline virtual void writeSol()

Write the solution file to the defualt location (filename.sol in the original directory)

inline virtual void writeSol(const char *solFileName)

Write the solution file to a specific file.

Parameters

solFileName – Path of the solution file to write

void printModelVars(bool onlyNonZero)

Utility function: prints all variables to screen.

Public Static Functions

template<class T>
static inline T load(const char *nlfile, const char **options = nullptr)

Load a model from an NL file

Template Parameters

T – Concrete class (e.g. CPLEXModel, GurobiModel, …) to create

Parameters

• nlfile – NL file path

• options – NULL terminated array of startup options

Returns

class ampls::XPRESSCallback : public ampls::impl::BaseCallback

Base class for XPRESS callbacks, inherit from this to declare a callback to be called at various stages of the solution process.

Provides all mapping between solver-specific and generic values. To implement a callback, you should implement the run() method and set it via AMPLModel::setCallback() before starting the solution process via AMPLModel::optimize(). Depending on where the callback is called from, you can obtain various information about the progress of the optimization and can modify the behaviour of the solver.

Public Functions

virtual int run() = 0

Function to override, called periodically by the optimizer.

virtual std::vector<double> getSolutionVector()

Get the current solution vector.

virtual int getSolution(int len, double *sol)

Get the current solution.

inline virtual double getObj()

Get the current objective value.

virtual const char *getWhereString()

Get a textual representation of where in the solution process the callback has been called.

NOTE: this is expressed using the solver’s own (not generic) values

virtual const char *getMessage()

Get the message from the solver (available only for specific values of getWhere)

inline virtual Where::CBWhere getAMPLWhere()

Get where in the solution process the callback has been called (generic)

Variant get(int what)

Get an attribute variant.

inline int getInt(int what)

Get an integer attribute.

inline double getDouble(int what)

Get a double attribute.

inline XPRSprob getXPRSprob()

Get the underlying XPRSprob structure.

virtual std::vector<double> getValueArray(Value::CBValue v)

Get a (generic) array.

std::map<std::string, int> &getVarMap()

Get the map AMPLEntityName -> SolverVarIndex.

std::map<int, std::string> &getVarMapInverse()

Get the map SolverVarIndex -> AMPLEntityName.

inline ampls::Constraint addCut(std::vector<std::string> vars, const double *coeffs, CutDirection::Direction direction, double rhs)

Add a user cut using AMPL variables names.

Parameters

• vars – Vector of AMPL variable names

• coeffs – Vector of cut coefficients

• direction – Direction of the constraint ampls::CBDirection::Direction

• rhs – Right hand side value

inline ampls::Constraint addLazy(std::vector<std::string> vars, const double *coeffs, CutDirection::Direction direction, double rhs)

Add a lazy constraint using AMPL variables names.

Parameters

• vars – Vector of AMPL variable names

• coeffs – Vector of cut coefficients

• direction – Direction of the constraint ampls::CBDirection::Direction

• rhs – Right hand side value

inline ampls::Constraint addCutIndices(int nvars, const int *vars, const double *coeffs, CutDirection::Direction direction, double rhs)

Add a user cut using solver indics.

Parameters

• nvars – Number of variables in the cut (length of *vars)

• vars – Vector of variable indices (in the solvers representation)

• coeffs – Vector of cut coefficients

• direction – Direction of the constraint ampls::CBDirection::Direction

• rhs – Right hand side value

inline ampls::Constraint addLazyIndices(int nvars, const int *vars, const double *coeffs, CutDirection::Direction direction, double rhs)

Add a lazy constraint using solver indics.

Parameters

• nvars – Number of variables in the cut (length of *vars)

• vars – Vector of variable indices (in the solvers representation)

• coeffs – Vector of cut coefficients

• direction – Direction of the constraint ampls::CBDirection::Direction

• rhs – Right hand side value

inline virtual int getWhere()

Get an iteger representing where in the solution process the callback has been called.

NOTE: this is expressed using the solver’s own (not generic) values

inline virtual Variant getValue(Value::CBValue v)

Get a (generic) value.

class ampls::XPRESSDrv : public ampls::impl::SolverDriver<XPRESSModel>

Encapsulates the main environment of the xpress driver; the environment is then associated with the model being instantiated and deleted with it.

Public Functions

inline XPRESSModel loadModel(const char *modelName, const char **options = nullptr)

Load a model from an NL file.

Mappings between solver row and column numbers and AMPL names are available only if the row and col files have been generated as well, by means of the ampl option option auxfiles cr; before writing the NL file.

previous

Generic Examples

next

AMPLS-API changelog