AMPL¶

class AMPL¶

An AMPL translator.

An object of this class can be used to do the following tasks:

Run AMPL code. See eval.
Read models and data from files. See read, and readData.
Solve optimization problems constructed from model and data (see solve).
Access single Elements of an optimization problem. See getVariable, getConstraint, getObjective, getSet, and getParameter.
Access lists of available entities of an optimization problem. See getVariables, getConstraints, getObjectives, getSets, and getParameters.

Error handling is two-faced:

Errors coming from the underlying AMPL translator (e.g. syntax errors and warnings obtained calling the eval method) are handled by an error handler which can be set and get via setErrorHandler and getErrorHandler.
Generic errors coming from misusing the API, which are detected in R, are thrown as exceptions.

The default implementation of the error handler prints errors and warnings to the console.

The output of every user interaction with the underlying translator is handled implementing an output handler function. The current output handler can be accessed and set via getOutputHandler and setOutputHandler.

AMPL()¶

Default constructor.

Raises: Error – If no valid AMPL license has been found or if the translator cannot be started for any other reason.

AMPL(environment)¶

Constructor: creates a new AMPL instance with the specified environment. This allows the user to specify the location of the AMPL binaries to be used and to modify the environment variables in which the AMPL interpreter will run.

Parameters: env (Environment) – The AMPL environment.
Raises: Error – If no valid AMPL license has been found or if the translator cannot be started for any other reason.

AMPL.toString()¶

Get a string describing the object. Returns the version of the API and either the version of the interpreter or the message “AMPL is not running” if the interpreter is not running (e.g. due to unexpected internal error or to a call AMPL::close)

Returns: A string that represents this object.

AMPL.cd(path=NULL)¶

Change or display the current working directory (see https://en.wikipedia.org/wiki/Working_directory).

Parameters: path (str or NULL) – New working directory or null (to display the working directory).
Returns: The current working directory.

AMPL.setOption(name, value)¶

Set an AMPL option to a specified value.

Parameters

name (str) – Name of the option to be set (alphanumeric without spaces).
value – string/number/boolean representing the value the option must be set to.

Raises

Error – If the option name is not valid.

AMPL.getOption(name)¶

Get the current value of the specified option. If the option does not exist, returns NA.

Parameters: name (str) – Option name (alphanumeric)
Returns: Value of the option as a string or NA.
Raises: Error – If the option name is not valid.

AMPL.getDblOption(name)¶

Get the current value of the specified double option. If the option does not exist, returns NA.

Parameters: name (str) – Option name (alphanumeric)
Returns: Value of the option as numeric or NA.
Raises: Error – If the option name is not valid, or if the value could not be casted.

AMPL.getIntOption(name)¶

Get the current value of the specified integer option. If the option does not exist, returns NA.

Parameters: name (str) – Option name (alphanumeric)
Returns: Value of the option as numeric or NA.
Raises: Error – If the option name is not valid, or if the value could not be casted.

AMPL.getBoolOption(name)¶

Get the current value of the specified boolean option. If the option does not exist, returns NA.

Parameters: name (str) – Option name (alphanumeric)
Returns: Value of the option as boolean or NA.
Raises: Error – If the option name is not valid, or if the value could not be casted.

AMPL.read(fileName)¶

Interprets the specified file (script or model or mixed). As a side effect, it invalidates all entities (as the passed file can contain any arbitrary command); the lists of entities will be re-populated lazily (at first access)

Parameters: fileName (str) – Full path to the file.
Raises: Error – In case the file does not exist.

AMPL.readData(fileName)¶

Interprets the specified file as an AMPL data file. As a side effect, it invalidates all entities (as the passed file can contain any arbitrary command); the lists of entities will be re-populated lazily (at first access). After reading the file, the interpreter is put back to “model” mode.

Parameters: filName (str) – Full path to the file.
Raises: Error – In case the file does not exist.

AMPL.readTable(tableName)¶

Read the table corresponding to the specified name, equivalent to the AMPL statement:

read table tableName;

Parameters: tableName (string) – Name of the table to be read.

AMPL.writeTable(tableName)¶

Write the table corresponding to the specified name, equivalent to the AMPL statement:

write table tableName;

Parameters: tableName (string) – Name of the table to be written.

AMPL.eval(amplstatements)¶

Parses AMPL code and evaluates it as a possibly empty sequence of AMPL declarations and statements.

As a side effect, it invalidates all entities (as the passed statements can contain any arbitrary command); the lists of entities will be re-populated lazily (at first access)

The output of interpreting the statements is passed to the current output handler (see getOutputHandler and setOutputHandler).

By default, errors and warnings are printed to stdout. This behavior can be changed reassigning an error handler using setErrorHandler.

Parameters: amplstatements (str) – A collection of AMPL statements and declarations to be passed to the interpreter.
Raises: Error – if the input is not a complete AMPL statement (e.g. if it does not end with semicolon) or if the underlying interpreter is not running

AMPL.reset()¶: Clears all entities in the underlying AMPL interpreter, clears all maps and invalidates all entities.

AMPL.close()¶: Stops the underlying engine, and release all any further attempt to execute optimisation commands without restarting it will throw an exception.

AMPL.isRunning()¶: Returns TRUE if the underlying engine is running.

AMPL.solve()¶

Solve the current model.

Raises: Error – If the underlying interpreter is not running.

AMPL.getData(statements)¶

Get the data corresponding to the display statements. The statements can be AMPL expressions, or entities. It captures the equivalent of the command:

display ds1, ..., dsn;

where ds1, ..., dsn are the statements with which the function is called.

As only one DataFrame is returned, the operation will fail if the results of the display statements cannot be indexed over the same set. As a result, any attempt to get data from more than one set, or to get data for multiple parameters with a different number of indexing sets will fail.

Parameters: statements (list) – The display statements to be fetched.
Returns: DataFrame capturing the output of the display command in tabular form.
Return type: DataFrame
Raises: Error – if the AMPL visualization command does not succeed for one of the reasons listed above.

AMPL.getValue(scalarExpression)¶

Get a scalar value from the underlying AMPL interpreter, as a double or a string.

Parameters: scalarExpression (string) – An AMPL expression which evaluates to a scalar value.
Returns: The value of the expression.

AMPL.getOutput(amplstatements)¶

Equivalent to eval but returns the output as a string.

Parameters: amplstatements (str) – A collection of AMPL statements and declarations to be passed to the interpreter.
Raises: Error – if the input is not a complete AMPL statement (e.g. if it does not end with semicolon) or if the underlying interpreter is not running
Returns: A string with the output.

AMPL.setData(df, numberOfIndexColumns, setName)¶

Assign the data in the dataframe to the AMPL entities with the names corresponding to the column names. If setName is NULL, only the parameters value will be assigned.

Parameters

df (DataFrame) – The dataframe containing the data to be assigned.
numberOfIndexColumns (integer) – Number of index columns.
setName (string) – The name of the set to which the indices values of the DataFrame are to be assigned.

Raises

Error – If the data assignment procedure was not successful.

AMPL.getVariable(name)¶

Get the variable with the corresponding name.

Parameters: name (str) – Name of the variable to be found.
Returns: Variable object.
Return type: Variable
Raises: Error – If the specified variable does not exist.

AMPL.getConstraint(name)¶

Get the constraint with the corresponding name.

Parameters: name (str) – Name of the constraint to be found.
Returns: Constraint object.
Return type: Variable
Raises: Error – If the specified constraint does not exist.

AMPL.getObjective(name)¶

Get the objective with the corresponding name.

Parameters: name (str) – Name of the objective to be found.
Returns: Objective object.
Return type: Objective
Raises: Error – If the specified objective does not exist.

AMPL.getSet(name)¶

Get the set with the corresponding name.

Parameters: name (str) – Name of the set to be found.
Returns: Set object.
Return type: Set
Raises: Error – If the specified set does not exist.

AMPL.getParameter(name)¶

Get the parameter with the corresponding name.

Parameters: name (str) – Name of the parameter to be found.
Returns: Parameter object.
Return type: Parameter
Raises: Error – If the specified parameter does not exist.

AMPL.getVariables()¶

Get all the variables declared.

Returns: List of Variable objects.

AMPL.getConstraints()¶

Get all the constraints declared.

Returns: List of Constraint objects.

AMPL.getObjectives()¶

Get all the objectives declared.

Returns: List of Objective objects.

AMPL.getSets()¶

Get all the sets declared.

Returns: List of Set objects.

AMPL.getParameters()¶

Get all the parameters declared.

Returns: List of Parameter objects.

AMPL.exportModel(modfile)¶

Create a .mod file with the model that has been loaded.

Parameters: modfile (str) – Path to the file (Relative to the current working directory or absolute).

AMPL.exportData(datfile)¶

Create a .dat file with the data that has been loaded.

Parameters: datfile (str) – Path to the file (Relative to the current working directory or absolute).

AMPL.setOutputHandler(outputhandler)¶

Sets a new output handler.

Parameters: outputhandler (function) – The function handling the AMPL output derived from interpreting user commands.

AMPL.getOutputHandler()¶

Get the current output handler.

Returns: The current output handler.
Return type: function
Raises: Error – If no output handler was set.

AMPL.setErrorHandler(errorhandler)¶

Sets a new error handler. The error handler receives a list with: - $type: type (warning or error); - $filename: name of the file where the error was detected; - $line: the row where the error is located; - $offset: the offset where the error is located; - $message: the error message.

Parameters: errorhandler (function) – The function handling AMPL errors and warnings.

AMPL.getErrorHandler()¶

Get the current error handler.

Returns: The current error handler.
Return type: function
Raises: Error – If no error handler was set.

R API Reference

Environment