Function structure#

AMPL C API Documentation

Overview#

The AMPL C API allows programs to interact with the AMPL interpreter, access input and output, and manipulate mathematical optimization models. All API functions start with the prefix AMPL_.

The main object in the API is the AMPL struct. One instance of this struct represents an execution of the AMPL translator. You must create it before interacting with the API. The AMPL struct lets you send AMPL commands, inspect and modify models, retrieve results, and control execution.

Since the AMPL struct manages important resources, you should explicitly close it with AMPL_Close() when you are done.

AMPL Struct#

The AMPL struct wraps the AMPL execution engine. You create it using AMPL_Create() or AMPL_CreateWithEnv(). All model creation and modification happens through this struct by sending AMPL statements. You can also access the current model state through entity-related functions.

API functions for AMPL fall into four categories:

Direct interaction with AMPL
Model interrogation
Commands and options
Output and error handling

Direct Interaction with AMPL#

AMPL_Eval() - executes an AMPL statement
AMPL_Read() - reads and executes a model or script file
AMPL_ReadData() - reads and executes a data file

Model Interrogation#

Enumerating Entities:

AMPL_GetVariables() - get all variables
AMPL_GetConstraints() - get all constraints
AMPL_GetObjectives() - get all objectives
AMPL_GetSets() - get all sets
AMPL_GetParameters() - get all parameters

Accessing Known Entities: If you know an entity’s AMPL name, you can access it directly. After you obtain an entity, you can inspect or modify it, and read or assign data. Accessing an entity communicates with the AMPL engine only when needed.

Entities become invalid if:

A dependent entity is modified, or
A generic AMPL command is executed

The API automatically refreshes invalid entities, but this can be costly. Prefer API functions over raw AMPL commands to avoid unnecessary invalidation.

Commands and Options#

Some common AMPL commands have direct API functions:

AMPL_Solve() – solves the model
Snapshot and export functions
Table read/write functions

AMPL options can be accessed and modified using:

AMPL_GetOption() / AMPL_SetOption()
AMPL_GetBoolOption() / AMPL_SetBoolOption() for boolean options

Use dedicated API functions whenever possible instead of AMPL_Eval().

Output and Error Handling#

Output:

Output is handled by a callback of type AMPL_OutputHandlerCb.
Use AMPL_GetOutputHandler() and AMPL_SetOutputHandler() to read or replace it.
By default, output is printed to the console.

Errors:

Translator errors (e.g., syntax errors) are handled by an error callback set with AMPL_GetErrorHandler() and AMPL_SetErrorHandler().
API-level errors (e.g., invalid arguments) are returned by functions directly.
Use AMPL_CALL() to wrap API calls that return AMPL_ERRORINFO for proper error checking.

Model Entities#

Entities represent the core model components: variables, constraints, objectives, parameters, and sets. They allow programs to access model state and assign some data.

Two base abstractions exist: AMPL_ENTITY and AMPL_INSTANCE.

An AMPL_INSTANCE represents a single indexed instance of an entity (e.g., a variable at a specific index).
Derived types include AMPL_VARIABLEINSTANCE, AMPL_CONSTRAINTINSTANCE, AMPL_OBJECTIVEINSTANCE, AMPL_SETINSTANCE.
Parameters are represented directly as values (numbers or strings).

Entities expose methods appropriate to their type, for example:

Constraints: drop, restore, dual values
Variables: fix, unfix, assign values

Access to Instances and Values#

Use AMPL_EntityGetValues() or iterators to access instances.
Individual instance access is slower because it checks validity and syncs with the interpreter.
For bulk access, use AMPL_DATAFRAME for better performance.

Scalar entities mirror instance-level methods for easier access.

DataFrames and Bulk Access#

AMPL_DATAFRAME allows efficient bulk access to data:

Assign or retrieve multiple entity values at once
Decouples data handling from AMPL
Works with AMPL_SetData() and AMPL_EntityGetValues()