AMPL#

group AMPL

An AMPL translator.

An AMPL struct can be used to do the following tasks:

Run AMPL code. See AMPL_Eval().
Read models and data from files. See AMPL_Read() and AMPL_ReadData().
Solve optimization problems constructed from model and data (see AMPL_Solve()).
Access lists of available entities of an optimization problem. See AMPL_GetVariables(), AMPL_GetObjectives(), AMPL_GetConstraints(), AMPL_GetSets() and AMPL_GetParameters().

AMPL stores one or more problems which may consume substantial amount of memory. The AMPL struct has a deallocator AMPL_Free() which automaticallly closes the underlying AMPL interpreter.

Consistency is not maintained automatically. Any command issued to the translator through AMPL_Eval() and similar functions do not invalidate all entities, and any further access to any entity will require a new call to the entity.

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 the error handler which can be set and get via AMPL_GetErrorHandler() and AMPL_SetErrorHandler().
Generic errors coming from misusing the API, which are detected in C, are returned by any function as the AMPL_ERRORINFO pointer.

All invocations of AMPL API functions returning an AMPL_ERRORINFO pointer must be wrapped using the AMPL_CALL() macro in order to detect and print error messages. For example:

AMPL_CALL(AMPL_Eval(...));

The output of every user interaction with the underlying translator is handled implementing using an output handler. The (only) function is called at each block of output from the translator. The current output handler can be accessed and set via AMPL_GetOutputHandler() and AMPL_SetOutputHandler().

Typedefs

typedef struct Ampl AMPL#: An AMPL translator.

Functions

AMPL_ERRORINFO *AMPL_Create(AMPL **ampl)#

Allocates the AMPL struct with the default environment.

Parameters:

ampl – Pointer to the pointer of the AMPL struct.

Returns:

Pointer to the AMPL_ERRORINFO struct.

AMPL_ERRORINFO *AMPL_CreateWithEnv(AMPL **ampl, AMPL_ENVIRONMENT *env)#

Allocates the AMPL struct 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:

ampl – Pointer to the pointer of the AMPL struct.
env – Pointer to the AMPL environment struct.

Returns:

Pointer to the AMPL_ERRORINFO struct.

void AMPL_Free(AMPL **ampl)#

Frees the AMPL struct.

Parameters:

ampl – Pointer to the pointer of the AMPL struct.

AMPL_ERRORINFO *AMPL_Eval(AMPL *ampl, const char *statement)#

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 output of interpreting the statements is passed to the current output handler (see AMPL_GetOutputHandler() and AMPL_SetOutputHandler()).

By default, errors and warnings are reported as return value are printed on stderr using the macro AMPL_CALL(). This behavior can be changed reassigning an error handler using AMPL_SetErrorHandler.

Parameters:

ampl – Pointer to the AMPL struct.
statement – A collection of AMPL statements and declarations to be passed to the interpreter.

Returns:

Pointer to the AMPL_ERRORINFO struct.

AMPL_ERRORINFO *AMPL_EvalAsync(AMPL *ampl, const char *statement, RunnablePtr function, void *cb)#

Interpret the given AMPL statement asynchronously.

Returns AMPL_RUNTIME_ERROR if the underlying ampl interpreter is not running.

Parameters:

ampl – Pointer to the AMPL struct.
statement – A collection of AMPL statements and declarations to be passed to the interpreter.
function – Callback pointer.
cb – Callback data.

Returns:

Pointer to the AMPL_ERRORINFO struct.

AMPL_ERRORINFO *AMPL_SolveAsync(AMPL *ampl, RunnablePtr function, void *cb)#

Solve the current model asynchronously.

Parameters:

ampl – Pointer to the AMPL struct.
function – Callback pointer.
cb – Callback data.

Returns:

Pointer to the AMPL_ERRORINFO struct.

AMPL_ERRORINFO *AMPL_ReadAsync(AMPL *ampl, const char *filename, RunnablePtr function, void *cb)#

Interprets the specified file asynchronously, interpreting it as a model or a script 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).

Parameters:

ampl – Pointer to the AMPL struct.
filename – Path to the file (Relative to the current working directory or absolute).
function – Callback pointer.
cb – Callback data.

Returns:

Pointer to the AMPL_ERRORINFO struct.

AMPL_ERRORINFO *AMPL_ReadDataAsync(AMPL *ampl, const char *filename, RunnablePtr function, void *cb)#

Interprets the specified data file asynchronously.

When interpreting is over, the specified callback is called. The file is interpreted as data. 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:

ampl – Pointer to the AMPL struct.
filename – Full path to the file.
function – Callback pointer.
cb – Callback data.

Returns:

Pointer to the AMPL_ERRORINFO struct.

AMPL_ERRORINFO *AMPL_Reset(AMPL *ampl)#

Clears all entities in the underlying AMPL interpreter, clears all maps and invalidates all entities.

Parameters:

ampl – Pointer to the AMPL struct.

Returns:

Pointer to the AMPL_ERRORINFO struct.

AMPL_ERRORINFO *AMPL_ResetData(AMPL *ampl)#

Clears all data.

Parameters:

ampl – Pointer to the AMPL struct.

Returns:

Pointer to the AMPL_ERRORINFO struct.

AMPL_ERRORINFO *AMPL_Close(AMPL *ampl)#

Stops the underlying engine, and release all any further attempt to execute optimization commands without restarting it will return an error.

Parameters:

ampl – Pointer to the AMPL struct.

Returns:

Pointer to the AMPL_ERRORINFO struct.

AMPL_ERRORINFO *AMPL_IsRunning(AMPL *ampl, bool *running)#

Returns true if the underlying engine is running.

Parameters:

ampl – Pointer to the AMPL struct.
running – Pointer to boolean running.

Returns:

Pointer to the AMPL_ERRORINFO struct.

AMPL_ERRORINFO *AMPL_IsBusy(AMPL *ampl, bool *busy)#

Returns true if the underlying engine is doing an async operation.

Parameters:

ampl – Pointer to the AMPL struct.
busy – Pointer to boolean busy.

Returns:

Pointer to the AMPL_ERRORINFO struct.

AMPL_ERRORINFO *AMPL_Solve(AMPL *ampl, const char *problem, const char *solver)#

Solve the current model.

Parameters:

ampl – Pointer to the AMPL struct.
problem – Name of the problem to solve as a string.
solver – Name of the solver to use as a string.

Returns:

Pointer to the AMPL_ERRORINFO struct.

AMPL_ERRORINFO *AMPL_Interrupt(AMPL *ampl)#

Interrupts the underlying engine.

Parameters:

ampl – Pointer to the AMPL struct.

Returns:

Pointer to the AMPL_ERRORINFO struct.

AMPL_ERRORINFO *AMPL_Snapshot(AMPL *ampl, const char *fileName, bool model, bool data, bool options, char **output)#

Take a snapshot of the AMPL session.

Parameters:

ampl – Pointer to the AMPL struct.
fileName – The file where to write the snapshot to.
model – Include model if set to not 0.
data – Include data if set to not 0.
options – Include options if set to not 0.
output – Pointer to the snapshot string.

Returns:

Pointer to the AMPL_ERRORINFO struct.

AMPL_ERRORINFO *AMPL_ExportModel(AMPL *ampl, const char *fileName, char **output)#

Write the declarations that were made in the current AMPL struct to a file.

Parameters:

ampl – Pointer to the AMPL struct.
fileName – The file where to write the declarations to.
output – Pointer to the exported model string.

Returns:

Pointer to the AMPL_ERRORINFO struct.

AMPL_ERRORINFO *AMPL_ExportData(AMPL *ampl, const char *fileName, char **output)#

Write all data loaded in the current instance to a file.

Parameters:

ampl – Pointer to the AMPL struct.
fileName – The file where to write the data to.
output – Pointer to the exported data string.

Returns:

Pointer to the AMPL_ERRORINFO struct.

AMPL_ERRORINFO *AMPL_Cd(AMPL *ampl, char **output)#

Get the current working directory from the underlying interpreter (see https://en.wikipedia.org/wiki/Working_directory).

Parameters:

ampl – Pointer to the AMPL struct.
output – Current working directory.

Returns:

Pointer to the AMPL_ERRORINFO struct.

AMPL_ERRORINFO *AMPL_Cd2(AMPL *ampl, const char *path, char **output)#

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

Parameters:

ampl – Pointer to the AMPL struct.
path – New working directory or null (to display the working directory).
output – Current working directory.

Returns:

Pointer to the AMPL_ERRORINFO struct.

AMPL_ERRORINFO *AMPL_GetCurrentObjective(AMPL *ampl, char **currentObjective)#

Get the name of the currently active objective (see the objective command).

Parameters:

ampl – Pointer to the AMPL struct.
currentObjective – Current objective or empty string if no objective has been declared.

Returns:

Pointer to the AMPL_ERRORINFO struct.

AMPL_ERRORINFO *AMPL_SetOption(AMPL *ampl, const char *name, const char *value)#

Set an AMPL option to a specified value.

Parameters:

ampl – Pointer to the AMPL struct.
name – Name of the option to be set (alphanumeric without spaces).
value – String representing the value the option must be set to.

Returns:

Pointer to the AMPL_ERRORINFO struct.

AMPL_ERRORINFO *AMPL_GetOption(AMPL *ampl, const char *name, bool *exists, char **value)#

Get the current value of the specified option.

If the option does not exist, the parameter exists will be set to false.

Parameters:

ampl – Pointer to the AMPL struct.
name – Option name (alphanumeric)
exists – True if the option exists, false otherwise.
value – Pointer to the value of the option as a string.

Returns:

Pointer to the AMPL_ERRORINFO struct.

AMPL_ERRORINFO *AMPL_GetIntOption(AMPL *ampl, const char *name, bool *exists, int *value)#

Get the current value of the specified integer option.

If the option does not exist, the parameter exists will be set to false.

Parameters:

ampl – Pointer to the AMPL struct.
name – Option name (alphanumeric).
exists – True if the option exists, false otherwise.
value – Pointer to the value of the option as an integer.

Returns:

Pointer to the AMPL_ERRORINFO struct.

AMPL_ERRORINFO *AMPL_GetDblOption(AMPL *ampl, const char *name, bool *exists, double *value)#

Get the current value of the specified double option.

If the option does not exist, the parameter exists will be set to false.

Parameters:

ampl – Pointer to the AMPL struct.
name – Option name (alphanumeric).
exists – True if the option exists, false otherwise.
value – Pointer to the value of the option as an double.

Returns:

Pointer to the AMPL_ERRORINFO struct.

AMPL_ERRORINFO *AMPL_SetDblOption(AMPL *ampl, const char *name, double value)#

Set an AMPL double option to a specified value.

Parameters:

ampl – Pointer to the AMPL struct.
name – Name of the double option to be set (alphanumeric without spaces).
value – Double representing the value the option must be set to.

Returns:

Pointer to the AMPL_ERRORINFO struct.

AMPL_ERRORINFO *AMPL_SetIntOption(AMPL *ampl, const char *name, int value)#

Set an AMPL integer option to a specified value.

Parameters:

ampl – Pointer to the AMPL struct.
name – Name of the double option to be set (alphanumeric without spaces).
value – Integer representing the value the option must be set to.

Returns:

Pointer to the AMPL_ERRORINFO struct.

AMPL_ERRORINFO *AMPL_GetBoolOption(AMPL *ampl, const char *name, bool *exists, bool *value)#

Get the current value of the specified boolean option.

If the option does not exist, the parameter exists will be set to false.

Parameters:

ampl – Pointer to the AMPL struct.
name – Option name (alphanumeric).
exists – True if the option exists, false otherwise.
value – Pointer to the value of the option as a boolean.

Returns:

Pointer to the AMPL_ERRORINFO struct.

AMPL_ERRORINFO *AMPL_SetBoolOption(AMPL *ampl, const char *name, bool value)#

Set an AMPL boolean option to a specified value.

Parameters:

ampl – Pointer to the AMPL struct.
name – Name of the boolean option to be set (alphanumeric without spaces).
value – Boolean representing the value the option must be set to.

Returns:

Pointer to the AMPL_ERRORINFO struct.

AMPL_ERRORINFO *AMPL_Read(AMPL *ampl, const char *fileName)#

Interprets the specified file (script or model or mixed).

Parameters:

ampl – Pointer to the AMPL struct.
fileName – Full path to the file.

Returns:

Pointer to the AMPL_ERRORINFO struct.

AMPL_ERRORINFO *AMPL_ReadData(AMPL *ampl, const char *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). After reading the file, the interpreter is put back to “model” mode.

Parameters:

ampl – Pointer to the AMPL struct.
fileName – Full path to the file.

Returns:

Pointer to the AMPL_ERRORINFO struct.

AMPL_ERRORINFO *AMPL_GetData(AMPL *ampl, const char *const *displayStatements, size_t n, AMPL_DATAFRAME **output)#

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 displayStatements 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:

ampl – Pointer to the AMPL struct.
displayStatements – The display statements to be fetched.
n – Number of displayStatements.
output – DataFrame capturing the output of the display command it tabular form.

Returns:

Pointer to the AMPL_ERRORINFO struct.

AMPL_ERRORINFO *AMPL_SetData(AMPL *ampl, AMPL_DATAFRAME *df, const char *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:

ampl – Pointer to the AMPL struct.
df – The dataframe containing the data to be assigned.
setName – The name of the set to which the indices values of the DataFrame are to be assigned.

Returns:

Pointer to the AMPL_ERRORINFO struct.

AMPL_ERRORINFO *AMPL_ToString(AMPL *ampl, char **output)#

Get a string describing the AMPL interpreter.

Output points 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).

Parameters:

ampl – Pointer to the AMPL struct.
output – Pointer to the value of the version as a string.

Returns:

Pointer to the AMPL_ERRORINFO struct.

AMPL_ERRORINFO *AMPL_ReadTable(AMPL *ampl, const char *tableName)#

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

read table tableName;

Parameters:

ampl – Pointer to the AMPL struct.
tableName – Name of the table to be read.

Returns:

Pointer to the AMPL_ERRORINFO struct.

AMPL_ERRORINFO *AMPL_WriteTable(AMPL *ampl, const char *tableName)#

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

write table tableName;

Parameters:

ampl – Pointer to the AMPL struct.
tableName – Name of the table to be written.

Returns:

Pointer to the AMPL_ERRORINFO struct.

AMPL_ERRORINFO *AMPL_Write(AMPL *ampl, const char *filename, const char *auxfiles)#

Write model instances.

Equivalent to

option auxfiles auxfiles;
write filename;

Parameters:

ampl – Pointer to the AMPL struct.
filename – The name of the file to write; the first letter indicates which filetype to write (see the output of ampl -o?).
auxfiles – The auxiliary files to write. Most notably, ‘cr’ instructs AMPL to write out column and row names respectively.

Returns:

Pointer to the AMPL_ERRORINFO struct.

AMPL_ERRORINFO *AMPL_GetValue(AMPL *ampl, const char *scalarExpression, AMPL_VARIANT **v)#

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

Parameters:

ampl – Pointer to the AMPL struct.
scalarExpression – An AMPL expression which evaluates to a scalar value.
v – Pointer to the value of the expression.

Returns:

Pointer to the AMPL_ERRORINFO struct.

AMPL_ERRORINFO *AMPL_GetBuiltInParameter(AMPL *ampl, AMPL_BUILTINPARAMETER builtinparam, AMPL_VARIANT **v)#

Get the value of a built-in parameter from the underlying AMPL interpreter, as a double or a string (AMPL_VARIANT).

Parameters:

ampl – Pointer to the AMPL struct.
builtinparameter – Built-in parameter.
v – Pointer to the value of the expression.

Returns:

Pointer to the AMPL_ERRORINFO struct.

AMPL_ERRORINFO *AMPL_GetValueString(AMPL *ampl, const char *scalarExpression, char **value)#

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

Parameters:

ampl – Pointer to the AMPL struct.
scalarExpression – An AMPL expression which evaluates to a scalar value.
value – Pointer to the value of the expression.

Returns:

Pointer to the AMPL_ERRORINFO struct.

AMPL_ERRORINFO *AMPL_GetValueNumeric(AMPL *ampl, const char *scalarExpression, double *value)#

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

Parameters:

ampl – Pointer to the AMPL struct.
scalarExpression – An AMPL expression which evaluates to a scalar value.
value – Pointer to the value of the expression.

Returns:

Pointer to the AMPL_ERRORINFO struct.

AMPL_ERRORINFO *AMPL_GetOutput(AMPL *ampl, const char *amplstatement, char **output)#

Equivalent to AMPL_Eval() but points the output as a string.

Parameters:

ampl – Pointer to the AMPL struct.
amplstatement – An AMPL statement to be evaluated.
output – Pointer to the value of the option as a string.

Returns:

Pointer to the AMPL_ERRORINFO struct.

AMPL_ERRORINFO *AMPL_CallVisualisationCommandOnNames(AMPL *ampl, const char *command, const char *const *args, size_t nargs)#

Call a visualisation command on names.

Parameters:

ampl – Pointer to the AMPL struct.
command – An AMPL command
args – Arguments as strings.
nargs – Number of arguments.

Returns:

Pointer to the AMPL_ERRORINFO struct.

AMPL_ERRORINFO *AMPL_SetOutputHandler(AMPL *ampl, AMPL_OutputHandlerCb callback, void *usrdata)#

Set output handler Callback.

Parameters:

ampl – Pointer to the AMPL struct.
callback – Output Handler Callback.
usrdata – User data.

Returns:

Pointer to the AMPL_ERRORINFO struct.

AMPL_ERRORINFO *AMPL_SetErrorHandler(AMPL *ampl, ErrorHandlerCbPtr callback, void *usrdata)#

Set error handler Callback.

Parameters:

ampl – Pointer to the AMPL struct.
callback – Output Handler Callback.
usrdata – User data.

Returns:

Pointer to the AMPL_ERRORINFO struct.

AMPL_ERRORINFO *AMPL_GetOutputHandler(AMPL *ampl, void **usrdata)#

Get output handler user data.

Parameters:

ampl – Pointer to the AMPL struct.
usrdata – Pointer to the user data.

Returns:

Pointer to the AMPL_ERRORINFO struct.

AMPL_ERRORINFO *AMPL_GetErrorHandler(AMPL *ampl, void **usrdata)#

Get error handler user data.

Parameters:

ampl – Pointer to the AMPL struct.
usrdata – Pointer to the user data.

Returns:

Pointer to the AMPL_ERRORINFO struct.

AMPL_ERRORINFO *AMPL_GetVariables(AMPL *ampl, size_t *size, char ***names)#

Get all the variables declared.

Parameters:

ampl – Pointer to the AMPL struct.
size – Pointer to the number of variables.
names – Pointer to the array of strings representing all declared variables.

Returns:

Pointer to the AMPL_ERRORINFO struct.

AMPL_ERRORINFO *AMPL_GetConstraints(AMPL *ampl, size_t *size, char ***names)#

Get all the constraints declared.

Parameters:

ampl – Pointer to the AMPL struct.
size – Pointer to the number of constraints.
names – Pointer to the array of strings representing all declared constraints.

Returns:

Pointer to the AMPL_ERRORINFO struct.

AMPL_ERRORINFO *AMPL_GetParameters(AMPL *ampl, size_t *size, char ***names)#

Get all the parameters declared.

Parameters:

ampl – Pointer to the AMPL struct.
size – Pointer to the number of parameters.
names – Pointer to the array of strings representing all declared parameters.

Returns:

Pointer to the AMPL_ERRORINFO struct.

AMPL_ERRORINFO *AMPL_GetObjectives(AMPL *ampl, size_t *size, char ***names)#

Get all the objectives declared.

Parameters:

ampl – Pointer to the AMPL struct.
size – Pointer to the number of objectives.
names – Pointer to the array of strings representing all declared objectives.

Returns:

Pointer to the AMPL_ERRORINFO struct.

AMPL_ERRORINFO *AMPL_GetSets(AMPL *ampl, size_t *size, char ***names)#

Get all the sets declared.

Parameters:

ampl – Pointer to the AMPL struct.
size – Pointer to the number of sets.
names – Pointer to the array of strings representing all declared sets.

Returns:

Pointer to the AMPL_ERRORINFO struct.

AMPL_ERRORINFO *AMPL_GetProblems(AMPL *ampl, size_t *size, char ***names)#

Get all the problems declared.

Parameters:

ampl – Pointer to the AMPL struct.
size – Pointer to the number of problems.
names – Pointer to the array of strings representing all declared problems.

Returns:

Pointer to the AMPL_ERRORINFO struct.