AMPL Programs

Introduction

An AMPL program is a sequence of instruction statements (or simply statements) written according to the rules of the AMPL language. The language is designed for the implementation of mathematical optimization programs, so most of the statements of the language are for declaring, initializing, manipulating, using or displaying model entities. Model entities are the basic building blocks used to implement an optimization model: parameters, variables, constraints, and so on.

The following AMPL program has two statements, each ended with a ;.

param a = 1; display a;

The first one declares a parameter called a and assigns it the value 1. The second one displays the value of a in the terminal.

Statement Types and Program Structure

We can divide the AMPL statements into three main types:

  1. Declaration statements: define model entities that will be used in the program.
  2. Assignment statements: assign values to model entities.
  3. Command statements: perform some action that may or may not use model entities.

A typical AMPL program will be structured in such a way that all the declaration statements will come first, followed by all the assignment statements and, finally, all the command statements.

Single File Program

A simple AMPL program can be fully contained in a single file with three sections, as such:

# Declaration statements model; param a; param b; # Assignment statements data; param a = 1; param b = 2; # Command statements commands; display a + b;

The lines starting with # are comments, which don't do anything. They are there just to help us visualizing the program structure. The statements model, data and commands indicate to the AMPL processor how the next statements should be interpreted. After seeing a model statement, the processor expects to see only declarations of model entities or command statements. After a data statement, the processor expects to see only assignment statements. And finally, after a commands statement, the processor expects to see only command or declaration statements.

NOTE: By default, the AMPL processor expects to see only declaration and command statements, so the instructions model and commands are usually not required. However, it is always necessary to indicate when a data section begins using the data statement. Otherwise, the processor will try to read the assignments as declarations, resulting in an error.

Note that model and commands can be used interchangeably, but in order to make our code more readable, it's a good practice to use one that best describes the code section that follows.

A single file program can be executed using the following terminal command line:

> ampl input_file.md
TIP: At PIFOP, we can also run single file programs at NEOS using neos -m input_file.md. Click here to learn more.

Multiple Files Program

More often than not, AMPL programmers will put each of the three mentioned program sections into separate files, as such:

# Model file param a; param b; # Data file param a = 1; param b = 2; # Commands file model "model.mod"; data "data.dat"; display a + b;

In this arrangement, the commands file is the entry point of our program. The model and data statements are used to read the model file (called "model.mod") and the data file (called "data.dat"). It is as if these commands replaced the lines in which the statements appear with the contents of the other files, such that the resulting program is exactly the same as the single file program example. The advantage of spliting the program into files like this is that optimization projects that alternate between different data sets and formulations become more manageable.

A multiple file program like the above is executed by calling the AMPL processor using the commands file as main input:

> ampl commands.run