Draft Writeup of August 13, 1996

REPORTING AND DISPLAY

A variety of miscellaneous new options provide additional information, or regulate the information that AMPL displays.


Solver return messages

AMPL's solver interfaces are set up to display a brief summary of their status when they are done:
	ampl: model diet.mod;
	ampl: data diet2.dat;
	ampl: solve;

	MINOS 5.5: infeasible problem.
	9 iterations
If you are running a script that executes solve frequently, these solver return messages can add up to a lot of output. You can turn them off by changing the new AMPL option solver_msg from its default value of 1 to 0.

A new built-in symbolic parameter, solve_message, always contains the most recent solver return message -- even when display of the message has been turned off. You can display this parameter to verify its value:

	ampl: display solve_message;

	solve_message = 'MINOS 5.5: infeasible problem.\
	9 iterations'
Because solve_message is a symbolic parameter, its value has the form of a character string. It is most useful in AMPL scripts, where you can use AMPL's character-string functions to test the message for indications of optimality and other outcomes.

As an example, the following script for the diet problem builds a table of objective and dual values at steadily decreasing settings of parameter n_max["NA"]. The match function is used to test whether "infeasible" appears in the solver return message. When it does, a warning is displayed, the for loop is aborted, and the completed table is shown:

	model diet.mod;
	data diet2a.dat;

	set NA;
	param NA_obj {NA};
	param NA_dual {NA};

	let NA := n_max["NA"] .. n_max["NA"] - 10000 by -500;

	option solver_msg 0;

	for {a in NA} {
	   let n_max["NA"] := a;
	   solve;

	   if match (solve_message, "infeasible") > 0 then {
	      printf "--- infeasible at %d ---\n\n", a;
	      break;
	      }

	   let NA_obj[a] := total_cost;
	   let NA_dual[a] := diet["NA"].dual;
	   }

	display NA_obj, NA_dual;
Here are the results of running the script, from file diet.run:
	ampl: commands diet.run;

	--- infeasible at 48000 ---

	:       NA_obj      NA_dual      :=
	48500   122.663   -0.00306905
	49000   121.128   -0.00306905
	49500   119.594   -0.00306905
	50000   118.059   -0.00306905
	;
Since return messages vary somewhat from one solver to the next, the appropriate test in such a script is somewhat solver-dependent. More sophisticated and solver-independent ways of checking the return condition are planned for future versions of AMPL, but this simple approach should be adequate in many cases.


Time and memory listings

By changing the show_stats option from its default of 0 to any nonzero value, you request summary statistics on the size of the optimization problem that AMPL generates:

	ampl: option show_stats 1;

	ampl: model prod.mod;
	ampl: data prod13.dat;
	ampl: solve;

	Presolve eliminates 82 constraints and 14 variables.
	Adjusted problem:
	871 variables, all linear
	647 constraints, all linear; 2736 nonzeros
	1 linear objective; 702 nonzeros.

	MINOS 5.4: optimal solution found.
	532 iterations, objective 2359313.555
	ampl: 
Several other options can give you more detailed information about AMPL's resource requirements.

By changing the times option from its default of 0 to any nonzero value, you request a summary of the AMPL translator's time and memory requirements:

	ampl: option times 1;

	ampl: model prod.mod;
	ampl: data prod13.dat;

	#                               incremental     total
	#phase          seconds         memory          memory
	#parse          0.116667        213000          213000
	#data read      0               20480           233480
	#parse          0               0               233480

	ampl: solve;

	#data read      0.05            36864           270344
	#compile        0.0333333       0               270344
	#genmod         0.35            159744          430088
	#collect        0.05            126976          557064
	#presolve       0.266667        118784          675848
	#output         0.316667        8192            684040

	MINOS 5.4: optimal solution found.
	532 iterations, objective 2359313.555

	#Total          1.18333

	ampl: 
The major phases of translation are listed at the left. The "seconds" column gives each phase's execution time in seconds. The "incremental memory" and "total memory" columns give the additional memory that each phase allocated, and the cumulative memory allocated by each phase and all previous ones. This information is mainly useful for benchmarking AMPL's performance.

By similarly changing the gentimes option from its default of 0 to any nonzero value, you can get a more detailed summary of the resources that AMPL's genmod phase consumes in generating a model instance:

	ampl: option gentimes 1;

	ampl: model prod.mod;
	ampl: data prod13.dat;
	ampl: solve;

	##genmod times:
	##seq      seconds    cum. sec.    mem. inc.  name
	##  3            0            0            0  prd
	##  4            0            0            0  pt
	##  5            0            0            0  pc
	##  6            0            0            0  first
	##  7            0            0            0  last
	##  8            0            0            0  time
	##  9            0            0            0  cs
	## 10            0            0            0  sl
	## 11    0.0166667    0.0166667            0  rtr
	## 12            0    0.0166667            0  otr
	## 13            0    0.0166667            0  iw
	## 14            0    0.0166667            0  dpp
	## 15            0    0.0166667            0  ol
	## 16            0    0.0166667            0  cmin
	## 17            0    0.0166667            0  cmax
	## 18            0    0.0166667            0  hc
	## 19            0    0.0166667            0  lc
	## 20            0    0.0166667            0  dem
	## 21            0    0.0166667            0  pro
	## 22            0    0.0166667            0  rir
	## 23            0    0.0166667            0  pir
	## 24            0    0.0166667            0  life
	## 25            0    0.0166667            0  cri
	## 26            0    0.0166667            0  crs
	## 27    0.0166667    0.0333333            0  iinv
	## 28         0.05    0.0833333         4096  iil
	## 29    0.0333333     0.116667            0  minv
	## 30            0     0.116667            0  Crews
	## 32            0     0.116667            0  Hire
	## 34            0     0.116667            0  Layoff
	## 36            0     0.116667         8192  Rprd
	## 38            0     0.116667         4096  Oprd
	## 40    0.0166667     0.133333        16384  Inv
	## 42            0     0.133333            0  Short
	## 44    0.0666667          0.2        65536  cost
	## 46    0.0166667     0.216667            0  rlim
	## 48            0     0.216667            0  olim
	## 50            0     0.216667            0  empl0
	## 52            0     0.216667            0  empl
	## 54            0     0.216667            0  emplbnd
	## 56    0.0166667     0.233333            0  dreq1
	## 58         0.05     0.283333        28672  dreq
	## 60    0.0333333     0.316667            0  ireq
	## 62            0     0.316667            0  izero
	## 64            0     0.316667        28672  ilim1
	## 66    0.0333333         0.35         4096  ilim

	MINOS 5.4: optimal solution found.
	532 iterations, objective 2359313.555
	ampl: 
The right-hand column gives the names of model components processed by the genmod phase. The "seconds" column gives AMPL's processing times for the components, and the "cum. sec." column keeps a running total. The "mem. inc." column indicates the additional memory, if any, that AMPL allocated while processing individual model components.

When AMPL appears to "hang" or takes much more time than expected, the gentimes display can help you to associate the difficulty with a particular model component. Typically, some parameter, variable or constraint has been indexed over a set far larger than what was intended or anticipated, with the result that an excessive amount of time and memory is required.

If you change the model or data and solve again, additional lines of the gentimes display will appear:

	ampl: let {p in prd, t in first..last+1} 
	ampl?    dem[p,t] := dem[p,t] * 1.05;
	ampl: solve;

	##genmod times:
	##seq      seconds    cum. sec.    mem. inc.  name
	## 20            0            0            0  dem
	## 28    0.0666667    0.0666667            0  iil
	## 29    0.0166667    0.0833333            0  minv
	## 56            0    0.0833333            0  dreq1
	## 58    0.0666667         0.15         4096  dreq
	## 60         0.05          0.2            0  ireq

	MINOS 5.4: optimal solution found.
	366 iterations, objective 2483123.471
	ampl: 
Here we see that a change to the parameter dem necessitated changes to only five other model components: the parameters iil and minv that are defined in terms of dem, and the constraints dreq1, dreq and ireq that use these parameters. AMPL keeps a representation of your model in memory throughout a session, and regenerates only the affected components when you solve after a change.

The timings shown above apply only to the AMPL translator, not to the solver. Many solvers have a directive for requesting a breakdown of the solve time, as in this example:

	ampl: option solver cplex;
	ampl: option cplex_options 'timing 1';

	ampl: model prod.mod;
	ampl: data prod13.dat;

	ampl: solve;
	CPLEX 2.1: timing 1

	Times (seconds):
	Input =  0.283333
	Solve =  4.95
	Output = 0.0166667

	CPLEX 2.1: optimal solution; objective 2359313.555
	473 iterations (230 in phase I)
	ampl: 
Information on requesting and interpreting these timings is provided in the documentation of AMPL's links to individual solvers.


Output logs

The log_file option instructs AMPL to save subsequent commands and responses to a file. The option's value is a string that is interpreted as a filename; thus you might say
	ampl: option log_file 'MULTI.TMP';
when running under MS-DOS, or
	ampl: option log_file '/tmp/multi';
under Unix. The log file receives all AMPL statements and the output that they produce, with a few exceptions described below. Setting log_file to the empty string,
	ampl: option log_file '';
turns off writing to the file; the empty string is the default value for this option.

When AMPL reads from an input file by means of a model, data or include command, the statements from that file are not copied to the log file -- although any output resulting from those statements does get logged. In typical situations, this arrangement prevents your model and data files from being echoed to your log file. To request that AMPL echo the contents of input files, change the option log_model (for input in model mode) or log_data (for input in data mode) from its default value of 0 to some nonzero value.

When you invoke a solver, AMPL logs at least a few lines summarizing the objective value, solution status and work required. Through certain solver-specific directives, you can typically request additional solver output such as logs of iterations or branch-and-bound nodes. Many solvers automatically send all of their output to AMPL's log file, but this compatibility is not universal. If a solver's output does not appear in your log file, you should consult the supplementary documentation for that solver's AMPL link; possibly that solver accepts nonstandard directives for diverting its output to files.

[[note on -v command-line options]]


Limits on messages

By specifying option eexit n, where n is some integer, you determine how AMPL handles error messages. If n is not zero, any AMPL statement is terminated after it has produced abs(n) error messages; a negative value causes only the one statement to be terminated, while a positive value results in termination of the entire AMPL session. The effect of this option is most often seen in the use of model statements,

	ampl: option eexit -3;
	ampl: model multemp1.mod;

	multemp1.mod, line 2 (offset 22):
	        syntax error
	context:   >>> set  <<< DEST;   # destinations

	multemp1.mod, line 6 (offset 149):
	        DEST is not defined
	context:  param demand  >>> {DEST, <<< PROD} >= 0;

	multemp1.mod, line 9 (offset 272):
	        DEST is not defined
	context:   sum {i in ORIG} supply[i,p] 
                        = sum {j in  >>> DEST} <<<  demand[j,p];

	Bailing out after 3 warnings.
	ampl: 
and data statements:

	stretto% ampl
	ampl: option eexit 3;

	ampl: model multemp2.mod;
	ampl: data multemp2.dat;

	multemp2.dat, line 9 (offset 262):
	        expected :=
	context:              plate    200    300    300  >>> ; <<< 

	multemp2.dat, line 11 (offset 271):
	        demad is not a param (or var or constraint)
	context:  param  >>> demad <<<  (tr):

	multemp2.dat, line 17 (offset 508):
	        1 item(s) missing in last line of table, 
	          which starts with "defalt"
	context:  param limit defalt 625  >>> ; <<< 

	Bailing out after 3 warnings.
	stretto% 
The default value for eexit is -10. Setting it to 0 causes all error messages to be displayed.

The eexit setting also applies to infeasibility warnings produced by AMPL's presolve phase after you type solve. The number of these warnings is simultaneously limited by the value of option presolve_warnings, which is typically set to a smaller value:

	ampl: option presolve_warnings 3;

	ampl: model multemp3.mod;
	ampl: data multemp3.dat;

	ampl: solve;
	presolve: constraint Demand[LAF,plate] cannot hold:
	        body >= 250 cannot be <= 75; difference = 175
	presolve: constraint Demand[LAF,coils] cannot hold:
	        body >= 500 cannot be <= 75; difference = 425
	presolve: constraint Demand[LAF,bands] cannot hold:
	        body >= 250 cannot be <= 75; difference = 175

	52 presolve messages suppressed.
	Infeasible solution determined by presolve.

	ampl: 
The default value for presolve_warnings is 5.

An AMPL data statement may specify values that correspond to illegal combinations of indices, due to any of a number of mistakes such as incorrect index sets in the model, indices in the wrong order, misuse of (tr), and typing errors. Similar errors may be caused by let statements that change the membership of index sets. In the following example, there are three set members typed incorrectly in the data table for parameter supply:

	set ORIG := GARY CLEV PITT ;
	set PROD := bands coils plate ;

	param supply (tr):  GARY   Clev    PIT :=
	            bands    400    700    800
	            coils    800   1600   1800
	            plates   200    300    300 ;
As a result, the table specifies invalid combinations of indices for seven data values. AMPL catches these errors after solve is typed. The number of invalid combinations actually displayed is determined from the value of the option bad_subscripts:

	ampl: option bad_subscripts 2;

	ampl: model multemp4.mod;
	ampl: data multemp4.dat;
	ampl: solve;

	Error executing "solve" command:
	error processing param supply:
	        7 invalid subscripts discarded:
	        supply[Clev,bands]
	        supply[PIT,bands]
	        and 5 more.
The default value for bad_subscripts is 3.


Prompts

AMPL has three pairs of prompts whose appearance you can change through option settings. The default settings are:

	option cmdprompt1 '%s ampl: ';
	option cmdprompt2 '%s ampl? ';
	option dataprompt1 'ampl data: ';
	option dataprompt2 'ampl data? ';
	option prompt1 'ampl: ';
	option prompt2 'ampl? ';
The values of prompt1 and prompt2 are what you usually see: prompt1 appears when a new statement is expected, and prompt2 when you begin a new line in the middle of a statement.

In data mode, the values of dataprompt1 and dataprompt2 are used instead. When a new line is begun in the middle of an if, for or repeat statement, the values of cmdprompt1 and cmdprompt2 are used, with %s replaced by the appropriate command name; for example:

	ampl: for {t in time} {

	for{...} { ? ampl: if t <= 6
	for{...} { ? ampl?   then let cmin[t] := 3;
	if ... then {...} ? ampl: else let cmin[t] := 4;

	for{...} { ? ampl: };
	ampl:
Since data tables and the if, for and repeat statements are most conveniently read from files rather than typed at the command line, the alternative prompts are rare in normal use.



Comments or questions?
Write to info@ampl.com or use our comment form.

Return to the AMPL update page.

Return to the AMPL home page.


LAST MODIFIED 13 AUGUST 1996 BY 4er.