AMPL#

class AMPL#

The AMPL object is central to the MATLAB API for AMPL. All usage of the API starts from the creation of an AMPL object. It represent an underlying interpreter, and can be used to issue commands and to gain access to the created entities.

eval#

classmethod AMPL.eval(amplstring)#

Syntax

eval(amplstring)

Description

eval(amplstring) interprets the string given as an argument through the underlying AMPL interpeter. It accepts only AMPL statements and the output of the interpreter is displayed on the MATLAB console.

Input Arguments

amplstring A sequence of AMPL statements

Example

Create a variable x and a simple objective function in the underlying AMPL object, and use its functionalities to show the equational form of the objective function.

ampl.eval('var x {1..3} >= 0; minimize o: sum {j in 1..3} x[j];');
ampl.eval('expand o;');

The object output stores now the output of the interpreter when subject to those statements. To display it in MATLAB, simply execute:

>> output =
minimize o:
   x[1] + x[2] + x[3];

read#

classmethod AMPL.read(filename)#

Syntax

read(filename)

Description

read(filename) reads the file specified by its parameter as a model file. The output coming from the interpreter will be printed on the console. Equivalent to the AMPL statement model filename;.

Input Arguments

filename A path to an AMPL file. Can be absolute or relative to the AMPL’s current working directory (as given by AMPL.cd).

Example

Reads a model file called test.mod placed in the subdirectory “/models” of the current working directory.

ampl.read('models/test.mod');

readData#

classmethod AMPL.readData(filename)#

Syntax

o = readData(filename)

Description

o = readData(filename) reads the file specified by its parameter as a data file. Equivalent to the AMPL statement data filename;.

Input Arguments

filename A path to an AMPL data file (.dat). Can be absolute or relative to the AMPL’s current working directory (as given by AMPL.cd).

Example

Reads a model file called test.mod placed in the subdirectory “/models” of the current working directory and a data file called dataset1.dat in the current directory.

ampl.read('models/test.mod');
o = ampl.readData('dataset1.dat')

solve#

classmethod AMPL.solve()#

Syntax

solve()

Description

solve starts the solution process, on the current model instance and with the current options. It is equivalent to issuing eval('solve;');.

Example

Create a simple model and solve it:

ampl.eval('var x;');
ampl.eval('maximize z: x;');
ampl.eval('subject to c: x<=5;');
ampl.solve();
o = ampl.getObjective('z');
v = o.value

This will give:

>> v = 5

getValue#

classmethod AMPL.getValue(scalarExpression)#

Syntax

v = getValue(scalarExpression)

Description

v = getValue(scalarExpression) Get a (single) value corresponding to the evaluation of the given expression in the underlying AMPL interpreter.

Input Arguments

scalarExpression A string representing an AMPL expression which evaluates to a single value.

Output Arguments

v A number or a string containing the value of the AMPL expression

Example 1: Get value of a scalar variable

Get the value of a scalar variable in a very compact way:

ampl.eval('var x := 3;')
v = ampl.getValue('x')

gives:

v =
3

getData#

classmethod AMPL.getData(displayExpressions)#

Syntax

df = getData(displayExpressions)

Description

df = getData(displayExpression) Get the data corresponding to the display statements in a DataFrame. The statements can be AMPL expressions or entities. It captures the equivalent of the command: display ds1, ..., dsn; where ds1, ..., dsn are the strings passed to the function. 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.

Input Arguments

displayExpression A list of strings representing the display expression(s) to be fetched into the DataFrame.

Output Arguments

df A DataFrame containig the values returned by the display expression

Example 1

Get values of an AMPL expression into a dataframe

ampl.eval('var x{i in 1..100} := i;);
df = ampl.getData('{i in 1..100 : x[i] >= 98} x[i]')

gives:

df =

index0  |  x[i]
98.0    |  98.0
99.0    |  99.0
100.0   |  100.0

Example 2

Fetch multiple values in the same dataframe

ampl.eval('var x{i in 1..2, j in 3..4} := i+10*j;');
ampl.eval('var y{i in 2..4, j in 4..5} := i*j;');
df = ampl.getData('x', 'y')

will give:

df =
index0  index1  |  x     y
0     3.0     |  31.0
0     4.0     |  41.0
0     3.0     |  32.0
0     4.0     |  42.0  8.0
0     5.0     |        10.0
0     4.0     |        12.0
0     5.0     |        15.0
0     4.0     |        16.0
0     5.0     |        20.0

setData#

classmethod AMPL.setData(dataframe, assignSets)#

Syntax

setData(dataframe)

setData(dataframe, setName)

Description

setData(dataframe) ` assigns the data in the dataframe to the AMPL entities with the corresponding names

setData(dataframe, setName) assigns the data in the dataframe to the AMPL entities with the corresponding names (and the indexing columns to the specified set)

Input Arguments

dataframe A DataFrame with columns which names correspond to entities currently defined in the underlying AMPL interpreter.

setName The name of the set to which the indices values of the DataFrame are to be assigned. Note that at most one set can be assigned at the same time as the parameters (for DataFrame with multiple indexing columns)

Example 1

Create DataFrame with one indexing column and arbitrary column names, populate it and set the values into the parameters

d = DataFrame(1, {'PROD', 'price', 'cost'});
d.addRow('shirts', 10, 5);
d.addRow('skirts', 8,  6);
ampl.eval('set PROD; param price{PROD}; param cost{PROD};')
ampl.setData(d, 'PROD');
% now the AMPL parameters price and cost, as well as the set PROD are assigned the listed values

Example 2

Create a DataFrame object inferring the table structure from the AMPL entities. It is mandatory for sets to be listed first. Do not assign the set values to AMPL (it is not supported for multiple sets at once).

ampl.eval('set PROD; set COLOUR; param price{PROD, COLOUR};');
ampl.eval('data; set PROD := shirts skirts; set COLOUR := red blue; model;');
PROD = ampl.getSet('PROD');
COLOUR = ampl.getSet('COLOUR');
price = ampl.getParameter('price');
d = DataFrame([PROD, COLOUR, price]);

d.addRow({'shirts', 'red', 5});
d.addRow({'shirts', 'blue',  4.5});
d.addRow({'skirts', 'blue',  5.5});

ampl.setData(d);
% now the AMPL parameter cost will have the assigned value
price.display

will give:

ans =

price :=
shirts blue   4.5
shirts red    5
skirts blue   5.5

cd#

classmethod AMPL.cd()#

Syntax

workingdir = cd

cd(directory)

Description

cd changes or displays the current working directory of the underlying AMPL interpreter.

Input Arguments

directory the directory to change to

Output Arguments

workingdir: The current working directory of the underlying AMPL interpreter. Can be different from MATLAB’s current directory.

Example

Display the current working directory and then change it to be the same as MATLAB’s.

workingdir = ampl.cd % display AMPL's current working directory
ampl.cd(pwd)         % changes AMPL working directory to MATLAB's (and displays it)

This will give:

workingdir =
d:\

ans =
D:\Development\AMPLApi\git\distribution\target\distribution-0.1-bin\matlab

close#

classmethod AMPL.close()#

Syntax

close

Description

close stops the underlying AMPL process and releases all the resources it uses.

Example

Close all resources:

ampl.close
ampl.isRunning

This will give:

ans =
      0

getConstraints#

classmethod AMPL.getConstraints()#

Syntax

names = getConstraints

Description

names = getConstraints gets the EntityList of constraints currently defined. Once a reference to the list is obtained, is automatically kept in sync with the AMPL interpreter.

Example

Get the list of constraints defined in a model:

ampl.eval('var x{1..3}; c{i in 1..2}: x[i] <= i; c2: x[3] <= 10;');
names = ampl.getConstraints()

This will give:

names =

List of defined constraints:
c2
c

To prove that is kept in sync, executing:

ampl.eval('c3: x[1]<=0;')
names

Will then give:

names =

List of defined constraints:
c2
c
c3

getVariables#

classmethod AMPL.getVariables()#

Syntax

names = getVariables

Description

names = getVariables gets the EntityList of variables currently defined. Once a reference to the list is obtained, is automatically kept in sync with the AMPL interpreter.

Example

Get the list of variables defined in a model:

ampl.eval('var x{1..3}; var y;');
names = ampl.getVariables()

This will give:

names =

List of defined variables:
x
y

To prove that is kept in sync, executing:

ampl.eval('var x;')
names

Will then give:

names =

List of defined constraints:
x
y
z

getObjectives#

classmethod AMPL.getObjectives()#

Syntax

names = getObjectives

Description

names = getObjectives gets the EntityList of objectives currently defined. Once a reference to the list is obtained, is automatically kept in sync with the AMPL interpreter.

Example

Get the list of objectives defined in a model:

ampl.eval('var x{1..3} <= 4; maximize obj: sum{i in 1..3} x[i];');
names = ampl.getObjectives()
ampl.eval('maximize newobj: sum{i in 1..3} x[i]/i;');
names
ampl.eval('delete obj;');
names

will give:

names =
List of defined objectives:
   obj

names =
List of defined objectives:
   newobj
   obj

names =
List of defined objectives:
   newobj

getParameters#

classmethod AMPL.getParameters()#

Syntax

names = getParameters

Description

names = getParameters gets the EntityList of parameters currently defined. Once a reference to the list is obtained, is automatically kept in sync with the AMPL interpreter.

Example

Get the list of parameters defined in a model:

ampl.eval('param a; param b symbolic;');
names = ampl.getParameters();
names

will give:

names =
 List of defined parameters:
   b
   a

getSets#

classmethod AMPL.getSets()#

Syntax

names = getSets

Description

a reference to the list is obtained, is automatically kept in sync with the AMPL interpreter.

Example

Get the list of sets defined in a model:

ampl.eval('set A; set B{A};');
names = ampl.getSets();
names

will give:

names =
 List of defined sets:
   B
   A

getEntity#

classmethod AMPL.getEntity(name)#

Syntax

entity = getEntity(name)

cons = getConstraint(name)

var = getVariable(name)

set = getSet(name)

param = getParameter(name)

obj = getObjective(name)

Description

getEntity is the generic version of all the specialised functions below, and gets any AMPL entity which has the specified name.

getConstraint gets the constraint entity corresponding to the specified name,

getVariable gets the variable entity corresponding to the specified name,

getParameter gets the parameter entity corresponding to the specified name,

getSet gets the set entity corresponding to the specified name and

getObjective gets the objective entity corresponding to the specified name.

Output Arguments

entity: The Entity corresponding to the name, its type is resolved dynamically by MATLAB
var: The Variable corresponding to the name
set: The Set set corresponding to the name
param: The Parameter corresponding to the name
obj: The Objective corresponding to the name
cons: The Constraint corresponding to the name

Example

Declare a model and gain programmatic access to various entities:

ampl.eval('param a := 5; set A = 1..3; var x{A} >= 0;');
ampl.eval('maximize z: sum{i in A} x[i]; c{i in A}: x[i] <= a;');
a = ampl.getParameter('a');
A = ampl.getSet('A');
x = ampl.getVariable('x');
z = ampl.getObjective('z');
c = ampl.getConstraint('c');
ampl.display(a)
ampl.display(A)
ampl.display(x)
ampl.display(z)
ampl.display(c)

This will give:

ans =
   a = 5

ans =
   set A := 1 2 3;

ans =
   x [*] :=
   1  0
   2  0
   3  0
   ;

ans =
   z = 0

ans =
   c [*] :=
   1  0
   2  0
   3  0
   ;

getConstraint#

classmethod AMPL.getConstraint(name)#

See AMPL.getEntity .

getObjective#

classmethod AMPL.getObjective(name)#

See AMPL.getEntity.

getParameter#

classmethod AMPL.getParameter(name)#

See AMPL.getEntity.

getSet#

classmethod AMPL.getSet(name)#

See AMPL.getEntity.

getVariable#

classmethod AMPL.getVariable(name)#

See AMPL.getEntity.

isRunning#

classmethod AMPL.isRunning()#

Syntax

b = isRunning

Description

b = isRunning returns 1 if the underlying AMPL intepreter is running and ready to accepts commands.

Output Arguments

b: 1 if the underlying engine is running, 0 otherwise (if the engine had been stopped with AMPL.close or if it had not been started due to other problems.

Example

Start AMPL and check if it is running

ampl = initAMPL;
b = isRunning

gives:

>> b =
   1

reset#

classmethod AMPL.reset()#

Syntax

b = reset

Description

reset resets the underlying AMPL interpreter. Equivalent to the AMPL statement reset;.

Example

Start AMPL and check if it is running

ampl.eval('var x;');
ampl.reset;
ampl.eval('var x{1..3};')

does not give an error because the variable x has been deleted from AMPL by the reset command.

display#

classmethod AMPL.display(displayExpressions)#

Syntax

display(displayExpression)

display(displayExpressions)

Description

display(displayExpression) Prints on screen the result of calling the AMPL display command on the display expression.

display(displayExpressions) Prints on screen the result of calling the AMPL display command on a series of expressions.

Input Arguments

displayExpression A string containing the display expression to be displayed

displayExpressions A list of display expression(s) to be displayed

Example 1

Prints the values of an AMPL expression: and of two expressions.

ampl.eval('var x{i in 1..100} := i;');
ampl.display('{i in 1..100 : x[i] >= 98} x[i]');
ampl.display('{i in 95..98} i', '{i in 1..100 : x[i] >= 98} x[i]');

gives:

:      i    x[i]    :=
  95      .
  96      .
  97      .
  98      98
    .     99
   .    100
;

show#

classmethod AMPL.show(showExpressions)#

Syntax

show(entity)

show(entities)

Description

The AMPL show command fetches the declaration of an entity. It can be used on single entities or list of entities

show(entity) Prints on screen the result of calling the AMPL show command on the specified entity

show(entities) Prints on screen the result of calling the AMPL show command on a series of entities.

Input Arguments

entity An AMPL entity

entities A list of AMPL entities

Example 1

Prints the declaration of an AMPL expression and an entity

ampl.eval('var x{i in 1..100}; maximize z: sum{i in 1..100} x[i];');
x = ampl.getVariable('x');
z = ampl.getObjective('z');
ampl.show(x, z);

gives:

var x{i in 1 .. 100}
maximize z: sum{i in 1 .. 100} x[i];

expand#

classmethod AMPL.expand(expandExpressions)#

Syntax

expand(entity)

expand(entities)

Description

The AMPL expand command expands an entity, visualizing all its instances. It can be used on single entities or list of entities

expand(entity) Prints on screen the result of calling the AMPL expand command on the specified entity.

expand(entities) Prints on screen the result of calling the AMPL expand command on all the entieis.

Input Arguments

entity An AMPL entity

entities A list of AMPL entities

Example 1

Expands the entities in this model:

ampl.eval('var x{i in 1..3}; maximize z: sum{i in 1..3} x[i];');
x = ampl.getVariable('x');
z = ampl.getObjective('z');
ampl.expand(x, z);

gives:

Coefficients of x[1]:
   z  1
Coefficients of x[2]:
   z  1
Coefficients of x[3]:
   z  1
maximize z:
   x[1] + x[2] + x[3];

getOption#

classmethod AMPL.getOption(name)#

Syntax

stringvalue = getOption(name)

intvalue = getIntOption(name)

dblvalue = getDblOption(name)

boolvalue = getBoolOption(name)

Description

getOption, getIntOption, getDblOption, getBoolOption get values of the specified options in the underlying AMPL interpreter, casted to the specified data structure.

Output Arguments

stringvalue: The value of the specified option as a string
intvalue: The value of the specified option as an integer
dblvalue: The value of the specified option as a floating point nubmer
boolvalue: The value of the specified option as a boolean (mapped in MATLAB to an integer, 0 if true, 1 otherwise)

Example

Shows the version of the underlying AMPL interpreter, the current random seed and the current relax_integrality status.

version = ampl.getOption('version')                % Get the value of option version
eps = ampl.getDblOption('display_eps')             % Get the value of display_eps
randseed = ampl.getIntOption('randseed')           % Get the value of randseed
relaxed = ampl.getBoolOption('relax_integrality')  % Get the value of relax_integrality

This will give:

version =
   AMPL OptiRisk Version 20130625 (MS VC++ 10.0, 64-bit)
eps =
   0
randseed =
   1
relaxed =
   0

setOption#

classmethod AMPL.setOption(optionname)#

Syntax

setOption(optionname, stringvalue)

setDblOption(optionname, numericvalue)

setIntOption(optionname, integervalue)

setBoolOption(optionname, booleanvalue)

Description

setOption(optionname, stringvalue) Set the value of the specified option to the specified string

setDblOption(optionname, value) Set the value of the specified option to the specified value

setIntOption(optionname, value) Set the value of the specified option to the specified integer value

setBoolOption(optionname, boolvalue) Set the value of the specified option to the specified boolean value

Input Arguments

optionname The name of the option to be set

stringvalue The string to set the option’s value to

value The number to set the option’s value to

boolvalue The boolean value (true or false) to set the option’s value to. MATLAB maps 0 to false and 1 to true

Example

Get and set values of various options

ampl.getDblOption('presolve')
ampl.setDblOption('presolve', 0);
ampl.getDblOption('presolve')
ampl.setBoolOption('presolve', true);
ampl.getBoolOption('presolve')
ampl.setOption('mystringoption', 'mystringvalue');
ampl.getOption('mystringoption')

gives:

ans =
  10

ans =
   0

ans =
   1

ans =
   mystringvalue

initializeEvents#

classmethod AMPL.initializeEvents()#

Description

initializeEvents() enables output redirection for the current session.: After this functions is called, the event AMPL.Output will be fired every time the interpreter outputs something on screen. See AMPLOutput. Note that the java library must be statically added to classpath for this to work (see https://uk.mathworks.com/help/matlab/matlab_external/jar-file-classes.html?s_tid=gn_loc_drop)

Example

Redirect AMPL output

ampl = AMPL;
ampl.initializeEvents;
addlistener(ampl, 'Output', @(h,e)disp(e.msg));

At this point, every AMPL output will be redirected to the anonymous function (disp(e.msg))

Output#

AMPL.Output#

Description

After initialization with AMPL.initializeEvents, this event is fired whenever the underlying AMPL interpreter prints somethig on screen.