The following documentation is preliminary. More detailed documentation,
with examples, is available through the AMPL World Wide Web sites
http://www.iems.nwu.edu/ampl/ampl.html
http://netlib.att.com/netlib/att/cs/home/ampl/ampl.html
and will eventually be available in printed form.
------------
SHOW COMMAND
------------
The "show" command has several forms:
show;
or
show >filename;
lists all model entities.
show name;
or
show name >filename;
shows name's declaration if it has one, or else lists model
entities of the kind indicated by the first letters of name:
ch... ==> checks c... ==> constraints
e... ==> environments f... ==> functions
o... ==> objectives pr... ==> problems
p... ==> parameters s... ==> sets
v... ==> variables
---------------
FLOW OF CONTROL
---------------
Several new commands permit conditional execution of and
looping over lists of AMPL commands:
if lexpr then cmd
if lexpr then cmd else cmd # else matches nearest available if
for opt_name indexing cmd # dummies from indexing may appear in cmd
repeat opt_name opt_while { cmds } opt_while ;
break opt_name ;
continue opt_name ;
cmd is either a single command (ending with ;) or { cmds } .
cmds is a sequence of 0 or more commands .
lexpr is a logical expression.
opt_name is an optional loop name (which must be an unbound
before the syntactic start of the loop), which goes out of
scope after syntactic end of the loop.
opt_while clauses are optional. If not null, opt_while
has the form
while lexpr
or
until lexpr
If the optional loop name is not specified, break and continue
apply to the immediately enclosing loop; otherwise they apply
to the named loop; break terminates the loop, and continue
causes its next iteration to begin (if permitted by the
optional initial and final opt_while clauses of a repeat loop,
or by the indexing of a for loop).
Loops and if-then-else structures are treasured up until syntactically
complete. Because else clauses are optional, AMPL must look ahead one
token to check for their presence. At the outermost level, one must
thus issue a null command (just a semicolon) or some other command or
declaration to execute an outermost else-less "if ... then stmt".
(In this regard, end-of-file implies an implicit null statement.)
New options prompt3 and prompt4 control prompting within the new
flow-of-control commands.
As a convenience, semicolons that precede right braces may be elided,
as may the semicolon at the end of a repeat loop whose opt_while is
null. (Whether such elisions will be documented as "official" AMPL
syntax is undecided.)
-------------
INPUT CHANGES
-------------
Both "model filename" and "data filename" are now treated as commands.
AMPL returns to model mode at the end of the file unless the file ends
in the middle of data.
When a "data" command or the (hitherto undocumented) "commands" command
appears within a compound command (i.e., the body of a loop or the then
or else part of an if command, or simply in a sequence of commands
enclosed in braces), it is now executed when the flow of control reaches
it, instead of when the compound command is being read. In this case,
if it does not specify a file, AMPL reads commands or data from the
current input file until it encounters either an "end" command or
the end of the current file. New option insertprompt (default '<%d>'),
if nonnull, specifies an insert-prompt (in which %d is the current
insert level, i.e., nesting of "data" and "commands" commands
specifying files and appearing within a compound command) that
immediately precedes the usual prompt for input from stdin.
Commands read by "include" or "model" are at insert-level 0. Two
variants of the "break" command work with the "commands" command:
break commands;
break all;
terminate, respectively, the current "commands" command or all "commands"
commands, if any, and otherwise act as a "quit" command.
------------
READ COMMAND
------------
The new "read" command has syntax similar to the print command, except
that only simple or subscripted params, variables, and constraints
(dual values) can be read. Optional input redirections are specified
by < filename or < 'quoted_file_name' (before the read command's
terminating semicolon). If no redirection is specified, values are read
from the current input stream. To read from stdin, specify <- .
Examples (reading from the current input steam):
param p;
read p;
4.2
display p;
param ps symbolic;
read ps;
'some funny text\
with a newline'
display ps;
param q{1..3};
read{i in 1..3} q[i];
1.1 2.2
3.3 display q;
param i;
param j;
param A{1..10,1..10};
param n;
read n,{1..n}(i,j,A[i,j]);
3
2 4 2.4
3 5 3.5
4 7 4.7
display A;
----------------
SINGLE-STEP MODE
----------------
As a (perhaps preliminary) scheme to help debug loops and complicated
scripts,
option single_step n;
where n is a positive integer, specifies that if the insert level
is at most n, AMPL should behave as though "commands -;" were inserted
before each command: it should read commands from stdin until "end" or
eof (control-D on Unix systems, control-Z under MS-DOS). Some special
commands may appear in this mode:
command meaning
step execute the next command
skip skip the next command
next if the next command is an if-then-else
or looping command, execute the entire
compound command before stopping again
(unless the compound command itself
specifies "commands -;")
cont execute until the end of the end of all
currently nested compound commands at the
current insert level
-------------------------------
NAMED PROBLEMS AND ENVIRONMENTS
-------------------------------
The new "problem" declaration/command has three functions:
declaring a new problem, making a previously declared problem
current, and printing the name of the current problem (in the form
of a problem command establishing the current problem).
problem name optional_indexing optional_environ : itemlist ;
declares a new problem and specifies the variables, constraints, and
objectives that are in it. Other variables appearing in the specified
constraints and objectives are fixed (but can be unfixed by the
"unfix" command). The new problem becomes the current problem.
"Current" is always a synonym for the current problem.
Initially the current problem is "Initial". The "itemlist" in a
problem declaration is a comma-separated list of possibly subscripted
names of variables, constraints, and objectives, each optionally
preceded by an indexing, as in {i in A} foo[i]. More generally,
nested indexings similar to those allowed in function calls may be
specified, as in
{i in A} (foo[i], goo[i], {(i,j) in B} zoo[i,j])
The command
problem name;
makes name (a previously declared problem) current. And
problem;
or
problem >filename;
prints the current problem name (as "problem name;"). Drop/restore
and fix/unfix commands apply only to the current problem. Variable
values, like params, are global; just the fixed/unfixed status of a
variable depends on the problem. Similarly, the drop/restore status
of a constraint depends on the problem (as do reduced costs). The
current problem does not restrict the "let" command.
When a problem is declared, it can optionally specify an environment
associated with the problem: the optional_environ phrase has the form
environ envname
to specify that the problem's initial environment is envname.
Otherwise a new environment with the same name as the problem is
created, and it inherits the then current environment (set of option
values). In option commands, unadorned (conventional) option names
refer to options in the current environment, and the notation
envname.opname refers to $opname in environment envname.
The new declaration
environ envname optional_indexing;
declares a environment envname (or a set of environments, subscripted
by the indexing if specified). If there is no indexing, envname
becomes the current environment for the current problem.
The new command
environ optional_indexing envname := envname1;
where envname and envname1 are optionally subscripted environment names,
copies environment envname1 to envname.
Starting with version 19951027, problems (including the current one)
are adjusted when their indexing expressions change, except that
previous explicit drop, restore, fix, and unfix commands remain in
effect. The new "reset problem" command cancels this treatment of
previous explicit drop, restore, fix, and unfix commands, and brings
the problem to its declared drop/fix state. This command has the
forms
reset problem; # applies to the current problem
reset problem foo;
reset problem goo[subscripting];
If the latter forms mention the current problem, they have the same
effect as the first form. For now, at least, "reset problem"
does not affect the problem's environment.
-------
STRINGS
-------
Strings passed to functions used to be quoted if they would need to be
quoted in a data section. Now they are not quoted: they are stripped
of surrounding quotes and the \ before a newline. This affects the
print command. For example,
print 'a b';
now prints
a b
rather than
'a b'
The printf command now recognizes two new formats: %q prints with
data-section quoting rules (omit quotes if omitting them is allowed in a
data section); %Q always quotes strings.
Expressions may involve the new concatenation operator &, which has
precedence below all arithmetic operators and performs string
concatenation. It accepts numeric operands and converts them to
full-precision decimal strings (as though by printf format "%.g", which
is equivalent to "%.0g": recall that in AMPL, these formats give full
precision, rather than behaving like "%.1g"). For example,
print 'abc' & 1 + 2;
gives
abc3
Contexts (other than alias strings in declarations) that previously
required literal strings now also accept an expression in parentheses.
Thus
print 1/7 >('abc' & 1 + 2);
prints 0.14285714285714285 on file "abc3".
Expressions in commands may involve operands of the form $value
(a $ followed by an environment name) and $environ.value (where
environ is the possibly subscripted and previously declared name of
an environment). $values may not be used in declarations.
Several new builtin functions work with strings:
num('12.34') = 12.34 # convert string to number
num('12.34x') = error # complain if stripping leading and
# trailing white space doesn't yield
# a valid decimal number
num0('12.34x') = 12.34 # strip leading white space, and
# interpret as much as possible as
# a number, but never complain
ichar('A') = 65 # Unicode value of the first character
# in its argument string
char(65) = 'A' # inverse of ichar
length('abcd') = 4 # length of string
substr('abcdef',3,2) = 'cd' # substring
substr('abcdef',3) = 'cdef' # substring
sprintf("stuff %.2f blah %g Blah %.g", 13/3, 2/7, 3/11)
= 'stuff 4.33 blah 0.285714 Blah 0.2727272727272727'
# general formatted conversion to string
match('abcde','cd') = 3 # starting position of arg2 in arg1
match('abcde','xy') = 0 # or 0 if not found; arg2 can be a general
# regular expression
sub('abcdecd','cd','XYZ') = 'abXYZecd'
# substitute arg3 for the first occurrence
# of arg2 in arg1
gsub('abcdecd','cd','XYZ') = 'abXYZeXYZ'
# substitute arg3 for all occurrences of
# of arg2 in arg1
arity('S') = arity of S if S is a set; else 0
# for use with _SETS, as in
# display{s in _SETS} arith(s);
indexarity('foo') = arity of foo's index set if foo has been
# declared to be something indexed, or 0
# if foo has been declared as something
# that is not indexed, or -1 if foo has
# not been declared.
ctime() = ctime(time()) = current time, a string formatted as in
# 'Sat Jul 27 23:37:43 1996'
# time() = current time in seconds (numeric)
# from a system-dependent origin, shown by
# ctime(0) (often 1 January 1970 GMT).
There is no implicit conversion of strings to numbers, but the new
builtin functions num(string) and num0(string) perform explicit
conversions. Both ignore leading and trailing white space; num
complains if what remains is not a valid number, whereas num0 just
converts as much as it can (returning 0 if it sees no digits).
The expressions
'abc' & x+3
and
'abc' & sprintf("%.g",x+3)
yield the same strings, and
setof{i in 1..3} 'ABC' & i
yields
{'ABC1', 'ABC2', 'ABC3'}.
The match, sub, and gsub functions accept strings representing regular
expressions as their second arguments. Such expressions are as in
plan 9. They are similar to the regular expressions recognized by the
Unix editors ed and sed, except that parentheses as operators must not
be escaped, and, in addition to * for 0 or more occurrences of the
preceding item, + means 1 or more occurrences, and ? means 0 or 1
occurrence. The replacement patterns (third arguments) for sub and
gsub are like those for ed and sed: & stands for the whole matched
string, as does \0, and \1, \2, ... \9 stand for the string matched
by the first, second, ..., ninth parenthesized expression in the
pattern.
------------
CALL COMMAND
------------
The new "call" command directly invokes a user-defined function for
its side effects: rather than, e.g., saying "print foo(1,2,3);" or
"let Dummy := foo(1,2,3);" to force foo(1,2,3) to be called, you can
now say "call foo(1,2,3);". Syntax:
call [indexing] function [(arglist)];
----------
CD COMMAND
----------
The new "cd" command reports or changes the current working directory.
With no argument, it reports the current directory; given a directory
argument (a string expression in which quotes can be omitted as for
file names), the "cd" command tries to change to that directory. It
always reports the current directory that results from its execution.
This printing may be directed to a file with the usual file redirection
notation.
--------------
EXPAND COMMAND
--------------
The new "expand" command prints generated constraints and objectives:
expand [indexing] itemlist [>filename];
The itemlist can assume the same forms allowed in problem declarations.
If it is empty, all non-dropped constraints and objectives are expanded.
The variant
solexpand [indexing] itemlist [>filename];
shows how constraints and objectives appear to the solver. It omits
constraints and variables eliminated by presolve unless they are
explicitly specified in the itemlist.
Both the "expand" and "solexpand" commands permit variables to appear
in the itemlist; for each, the commands show the linear coefficients
of the variable in the relevant (non-dropped and, for solexpand,
not eliminated by presolve) constraints and objectives, and indicates
" + nonlinear" when the variable also participates nonlinearly in a
constraint or objective.
The new options expand_precision and expand_round control printing of
numbers by expand. By default they are currently printed to 6
significant figures (option expand_precision 6).
------------
NEW SYNONYMS
------------
The following act as params and are automatically updated:
_nvars = number of variables in current model
_ncons = number of constraints in " "
_nobjs = number of objectives in " "
_varname{1.._nvars} = names of variables in current model
_conname{1.._ncons} = " " " " " "
_objname{1.._nobjs} = " " " " " "
The following are synonyms for current model entities:
_var{1.._nvars} = synonyms for variables in current model
_con{1.._ncons} = " " constraints " " "
_obj{1.._nobjs} = " " objectives " " "
These synonyms can be used in display and other commands. They
present the modeler's view (before presolve). Similarly automatically
updated entities with _ changed to _s (i.e., _snvars, _svarnames,
_svar, etc.) give the solver's view, i.e., the view after presolve.
The following "system" params are available only in "_s" form
(solver's view):
_snbvars = number of binary variables used linearly
_snivars = number of general integer variables used linearly
_snnlcons = number of nonlinear constraints
_snnlobjs = number of nonlinear objectives
_snzcons = number of nonzeros in the constraint Jacobian matrix
_snzobjs = number of nonzeros in objective gradients
The following "system" sets are automatically updated:
_PARS = set of all declared param names
_SETS = " " " " set "
_VARS = " " " " variable "
_CONS = " " " " constraint names
_OBJS = " " " " objective "
_PROBS = " " " " problem "
_ENVS = " " " " environment "
_FUNCS = " " " " (user-defined) functions
_AVAILFUNCS = " " " user-defined functions that have been
linked (statically or dynamically) with AMPL and thus
can be declared and evaluated in the AMPL session.
(Other user-defined functions may be declared and used
in constraints and objectives, but AMPL will not be able
to evaluate them. It can, however, pass them by name to
solvers that know how to use them.)
These sets may appear in commands, such as display and print.
They may not appear in declarations.
------------------------------------------------------
ADJUSTING DECLARATIONS: XREF, DELETE, PURGE, REDECLARE
------------------------------------------------------
The new "xref" command shows entities that depend directly or indirectly
on specified entities. Syntax:
xref itemlist optional_redirection;
The new command
delete foo;
deletes foo, restoring any previous meaning foo had, provided no other
entities depend on foo, i.e., if "xref foo;" reports no dependents.
Variant
delete check n;
deletes the n-th check (n = 1, 2, ...).
The new command
purge foo;
deletes foo and all its (direct or indirect) dependents.
A declaration may now be prefixed by "redeclare", which causes it to
replace any existing declaration of the specified entity with the given
one, provided either that the entity has no dependents, or that the new
declaration does not change the character of the entity (its kind, such
as set or param, and its number of subscripts). Redeclarations that
would cause circular dependencies are rejected. To redeclare the n-th
check, start with
redeclare check n
----------------
MISC. EXTENSIONS
----------------
The new reserved word "all" may be used in "drop all;", "fix all;",
"restore all;", and "unfix all;".
"objective;" or "objective >filename;" prints commands establishing the
current drop status of objectives. In particular, if one had previously
said "objective foo[3];", "objective;" would print "objective foo[3];".
Similarly, "drop;" or "drop >filename;" or "restore;" or
"restore > filename;" prints commands establishing the current drop stat
of the constraints and objectives, and "fix;" or "fix >filename;" or
"unfix;" or "unfix >filename;" prints commands establishing the current
"fix" state of the variables. In these contexts, "drop" and "restore"
are interchangeable, as are "fix" and "unfix".
New variant of close command: "close;" closes all files opened by
input or output redirections.
The new symbolic system parameter solve_message is assigned the message
shown (when not suppressed by "option solver_msg 0;") by the solve
and solution commands. One can assign solve_message with "let", but
may not delete or redeclare it.
If $solver_auxfiles (for "solve" commands, or $auxfiles for "write"
commands) contains capital letters and the current problem is
nonlinear (with binary and integer variables counted as nonlinearities),
they are treated as the corresponding lower-case letters. Capital
letters have no effect on linear problems. The default $minos_auxfiles
is now RF rather than rf, causing .row and .fix files to be written only
for nonlinear problems.
In solve and write commands, .fix files no longer show the values of
variables fixed by presolve unless 'v' appears in $solver_auxfiles
(or $auxfiles, as appropriate). (The main recent use of .fix files
is to supply names of defined variables for printing error messages.)
The following have been added to the reserved-word list: Current, Initial,
all, dotname, environ, inout, option, out. Other new names mentioned
above may be declared to be something else. Deleting their
declaration restores their former meanings. The new reserved words
"inout" and "out" are for use in forthcoming extensions.
_pid is a predefined param that gives the process ID of the AMPL process
(a number unique among processes running on the system).
-----------
NEW OPTIONS
-----------
abs_boundtol, rel_boundtol, and show_boundtol (all default 0) are
meant to help deduce correct dual values for constraints
eliminated by presolve when the solver uses an interior-point
algorithm and returns a solution with no bounds strictly
holding. All three new options have default value 0, which
gives the previous behavior. Suppose for some variable x that
the solver sees the bounds lb <= x <= ub. The lower-bound
constraint lb <= x is considered active (during reconstruction
of dual values) if
x <= lb
or (x - lb < ub - x
and x - lb <= max($abs_boundtol,
|lb|*$rel_boundtol)),
and similarly for the simple upper-bound constraint (x <= ub).
Thus negative values of $abs_boundtol and $rel_boundtol behave
like 0. The condition x - lb < ub - x ensures that x is closer
to lb than half-way between lb and ub, ensuring that AMPL picks
the more appropriate bound no matter how large $abs_boundtol
and $rel_boundtol are.
bad_subscripts (default 3): ampl now discards invalid subscripts
(read in a data section or assigned by "let"), and the
accompanying error message now shows at most $bad_subscripts
invalid subscripts per entity (when there is more than one
bad subscript).
cmdprompt1 (default '%s ampl: '): primary prompt, i.e., prompt for
new command within flow-of-control commands; %s
is replaced by a string suggesting the context.
cmdprompt2 (default '%s ampl? '): secondary prompt, i.e., prompt for
incomplete command within flow-of-control commands; %s
is replaced by a string suggesting the context.
constraint_drop_tol (default 0), introduced to deal with subtle
presolve bug apparently caused by roundoff error: with
$presolve > 1 and $var_bounds == 1 (the defaults), constraint
bounds were very occasionally relaxed due to bounds only
conveyed for $var_bounds > 1; this could increase the size of
the feasible region, possibly making the problem unbounded.
(Only known example: test problem MAROS from netlib's lp/data.)
The fix involves keeping two sets of constraint bounds and
switching between them based on $var_bounds. The constraint
bounds for $var_bounds == 1 are only relaxed if roundoff poses
no danger or the deduced bounds on the constraint body are
sharper than the declared bounds by at least
$constraint_drop_tol. (The default $constraint_drop_tol value 0
causes both sets of constraint bounds to be the same and gives
the same behavior as before this change.) New constraint dot
values: constraint.lbs1, .ubs1, lbs2, .ubs2 = versions of .lbs,
.ubs corresponding to $var_bounds <= 1 or > 1, respectively.
Constraint.lbs, .ubs still reflect the bounds sent to the
solver.
dataprompt1 (default 'ampl data: '): prompt given in data mode when
AMPL is ready to read a new statement or a command that returns
AMPL to model mode.
dataprompt2 (default 'ampl data? '): prompt given in data mode within a
statement. To make prompts appear as they do in the AMPL book,
issue the command
option dataprompt1 $prompt1, dataprompt2 $prompt2;
expand_precision (default 6) and
expand_round (default '') control printing precision in the "expand"
command.
format_range_errmsg, if not '', replaces %i, %d, %o, %u, %x, or %X in
printf commands or sprintf invocations in which the number to be
converted is outside the appropriate range of integers.
If $format_range_errmsg has its default value of '', an error
message appears and the command is aborted.
insertprompt (default '<%d>') used when executing a "commands" or "data"
command within a compound command when the "commands" or "data"
command does not specify a file.
log_file (default ''): if $log_file is not '', then all lines
read from stdin or written to stdout or stderr are copied
to file $log_file.
nl_permute (default 3) tells whether to permute constraints and variables as
described in "Hooking Your Solver to AMPL". The value, mod 4, tells
what to permute:
0 nothing
1 just constraints
2 just variables
3 both constraints and variables
Note that some solvers, such as cplex, minos, and osl, require the
permutations.
presolve_fixeps (default 0) and
presolve_fixepsmax (default 0): if presolve finds or deduces lower and
upper bounds on a variable that differ by at most $presolve_fixeps,
it fixes the variable at the average of the bound values. When
changes below $presolve_fixepsmax to $presolve_fixeps would affect
presolve, the $show_stats output reports these changes. Presolve
now behaves as though $presolve_eps were max($presolve_eps,
$presolve_fixeps): when $presolve_eps < $presolve_fixeps,
variable bounds declared or deduced to be within $presolve_fixeps
of each other in absolute value result in the variable being fixed
at the average of the bounds.
presolve_inteps (default 1e-6): tolerance for rounding updated bounds
on integer variables to integer values during presolve:
if x.dlb and x.dub denote the new deduced lower
and upper bounds on x, then for $presolve_inteps < 1,
x.dlb := ceil(x.dlb - $presolve_inteps) and
x.dub := floor(x.dub + $presolve_inteps).
For $presolve_inteps >= 1,
x.dlb := floor(x.dlb) and x.dub := ceil(x.dub).
presolve_intepsmax (default 1e-5): the message
"Setting $presolve_inteps >= nnn might help" is suppressed if
nnn > $presolve_intepsmax.
presolve_warnings (default 5) limits the number of warning messages
printed during presolve; subsequent warning messages are
suppressed, and the number of suppressed warnings (if positive)
is reported at the end of presolve. When
$presolve_warnings < |$eexit|
(as is true by default), a subsequent "Ignoring solve command
because presolve finds no feasible solution possible" may now
appear even when presolve finds at least |$eexit| causes for
infeasibility.
rel_boundtol: see abs_boundtol above.
relax_integrality (default 0):
option relax_integrality 1;
causes "integer" and "binary" attributes of variables to be
ignored (in solve and write commands).
show_boundtol (default 0) works similarly to $show_stats, except
that it delivers its messages when it is on (nonzero) and
another dual-value computation occurs or (like $show_stats)
when it is set to 1. It reports changes to $abs_boundtol and
$rel_boundtol that would change the outcome of the dual
computation, and is silent if the values of $abs_boundtol and
$rel_boundtol do not matter. [$show_boundtol was called
$show_boundstats prior to 20 Dec. 1993.]
single_step (default 0): if positive, use single-step mode as long
the insert level (see "INPUT CHANGES" above) is at most
$single_step.
solver_msg (default 1): if set to 1, the solution message normally
printed by the solve and solution commands is suppressed.
It is still assigned to param solve_message.