Draft Writeup of April 24, 1996

EXAMINING MODELS AND DATA

Two new commands let you more easily review an AMPL model from the command line. The show command displays the names of model components and the definitions of individual components. The xref command lists all components that depend on a given component. The expand command exhibits selected objectives and constraints that AMPL has generated from a model and data, or analogous information for variables. The output from any of these commands may be redirected to a file, buy adding > filename at the end.

To make a listing or a test that applies to all variables, constraints, or objectives, AMPL now also offers "generic" names for these components. New built-in sets and functions let AMPL also access additional information about model components, such as their names and dimensions.


The show command: displaying model components

By itself, this command lists the names of all components of the current model:

	ampl: model multmip3.mod;
	ampl: show;

	parameters:  demand  fcost  limit  maxserve  minload  supply  vcost

	sets:   DEST   ORIG   PROD

	variables:   Trans   Use

	constraints:   Demand   Max_Serve   Min_Ship   Multi   Supply

	objective:   total_cost

	checks: one, called check 1.
This display may be restricted to components of one or more types:

	ampl: show vars;

	variables:   Trans   Use

	ampl: show obj, constr;

	objective:   total_cost

	constraints:   Demand   Max_Serve   Min_Ship   Multi   Supply
The show command can also display the declarations of individual components, saving you the trouble of looking them up in the model file:

	ampl: show total_cost;  

	minimize total_cost: sum{i in ORIG, j in DEST, p in PROD} 
	vcost[i,j,p]*Trans[i,j,p] + sum{i in ORIG, j in DEST} 
	fcost[i,j]*Use[i,j];

	ampl: show vcost, fcost, Trans;

	param vcost{ORIG, DEST, PROD}  >= 0;
	param fcost{ORIG, DEST}  >= 0;
	var Trans{ORIG, DEST, PROD}  >= 0;
If an item following show is the name of a component in the current model, the declaration of that component is displayed. Otherwise, the item is interpreted as a component type according to its first letter or two:
	c   constraints
	ch  checks
	e   environments
	f   functions
	o   objectives
	p   parameters
	pr  problems
	s   sets
	v   variables
Displayed declarations may differ in inessential ways from their appearance in your model file, due to transformations that AMPL performs when the model is parsed and translated.

Since the check statements in a model do not have names, AMPL numbers them in the order that they appear. Thus to see the third check statement you would type

	ampl: show check 1;

	check{p in PROD} : sum{i in ORIG} supply[i,p] == sum{j in DEST} 
	demand[j,p];
By itself, show checks indicates the number of check statements in the model.  


The xref command: displaying model dependencies

The xref command lists all model components that depend on a specified component, either directly (by referring to it) or indirectly (by referring to its dependents). If more than one component is given, the dependents are listed separately for each. Here is an example from
multmip3.mod:
	ampl: xref demand, Trans;

	# 2 entities depend on demand:
	check 1
	Demand

	# 5 entities depend on Trans:
	total_cost
	Supply
	Demand
	Multi
	Min_Ship
In general, the form of the command is
	xref component-list ;
where component-list is a comma-separated or space-separated list of any combination of set, parameter, variable, objective and constraint names.


The expand command: displaying model instances

In checking a model and its data for correctness, you may want to look at some of the specific constraints that AMPL is generating. The expand command displays all constraints in a given indexed collection,
   ampl: model multmip3.mod;
   ampl: data multmip3.dat;

   ampl: expand Max_Serve;

   s.t. Max_Serve['GARY']:
           Use['GARY','FRA'] + Use['GARY','DET'] + Use['GARY','LAN'] + 
           Use['GARY','WIN'] + Use['GARY','STL'] + Use['GARY','FRE'] + 
           Use['GARY','LAF'] <= 5;

   s.t. Max_Serve['CLEV']:
           Use['CLEV','FRA'] + Use['CLEV','DET'] + Use['CLEV','LAN'] + 
           Use['CLEV','WIN'] + Use['CLEV','STL'] + Use['CLEV','FRE'] + 
           Use['CLEV','LAF'] <= 5;

   s.t. Max_Serve['PITT']:
           Use['PITT','FRA'] + Use['PITT','DET'] + Use['PITT','LAN'] + 
           Use['PITT','WIN'] + Use['PITT','STL'] + Use['PITT','FRE'] + 
           Use['PITT','LAF'] <= 5;
or specific constraints that you identify:
   ampl: expand {i in ORIG} Min_Ship[i,'DET'];

   s.t. Min_Ship['GARY','DET']:
           Trans['GARY','DET','bands'] + Trans['GARY','DET','coils'] + 
           Trans['GARY','DET','plate'] - 375*Use['GARY','DET'] >= 0;

   s.t. Min_Ship['CLEV','DET']:
           Trans['CLEV','DET','bands'] + Trans['CLEV','DET','coils'] + 
           Trans['CLEV','DET','plate'] - 375*Use['CLEV','DET'] >= 0;

   s.t. Min_Ship['PITT','DET']:
           Trans['PITT','DET','bands'] + Trans['PITT','DET','coils'] + 
           Trans['PITT','DET','plate'] - 375*Use['PITT','DET'] >= 0;

   ampl: expand Multi['CLEV','DET'];

   s.t. Multi['CLEV','DET']:
           Trans['CLEV','DET','bands'] + Trans['CLEV','DET','coils'] + 
           Trans['CLEV','DET','plate'] - 625*Use['CLEV','DET'] <= 0;
The ordering of terms in an expanded constraint does not necessarily correspond to the order of the symbolic terms in the constraint's declaration.

Objectives may be expanded in the same way.

When expand is applied to a variable, it lists all of the nonzero coefficients of that variable in the linear terms of objectives and constraints:

	ampl: expand {i in ORIG} Use[i,'DET'];

	Coefficients of Use['GARY','DET']:
	        Max_Serve['GARY']          1
	        Multi['GARY','DET']     -625
	        Min_Ship['GARY','DET']  -375
	        total_cost              1200

	Coefficients of Use['CLEV','DET']:
	        Max_Serve['CLEV']          1
	        Multi['CLEV','DET']     -625
	        Min_Ship['CLEV','DET']  -375
	        total_cost              1000

	Coefficients of Use['PITT','DET']:
	        Max_Serve['PITT']          1
	        Multi['PITT','DET']     -625
	        Min_Ship['PITT','DET']  -375
	        total_cost              1200
In a future implementation, expand will also display nonlinear terms in which the variable appears, and the values of bounds and initial values that have appeared in the variable's declaration. In the case of defined variables (Section 13.2), the defining expression will be expanded, too.

To produce an expansion of all variables, objectives and constraints in a model, you can simply type expand without any arguments. Since a single expand command can produce a very long listing, you may want to redirect its output to a file by placing > filename at the end.

The formatting of numbers in the expanded output is governed by the options expand_precision and expand_round, which work the same as the display command's display_precision and display_round (Section 10.5).

The output of expand reflects the "modeler's view" of the problem; it is based on the model and data as they were initially read and translated. AMPL's presolve phase (Section 10.2) may make significant simplifications to the problem before it is sent to the solver, however. To see the expansion of the "solver's view" of the problem following presolve, use the keyword solexpand in place of expand.


Generic synonyms for variables, constraints and objectives

Occasionally it is useful to make a listing or a test that applies to all variables, constraints, or objectives. For this purpose, AMPL provides automatically updated parameters that hold the numbers of variables, constraints, and objectives in the currently generated problem instance:
	_nvars   number of variables in the current problem
	_ncons   number of constraints in current problem
	_nobjs   number of objectives in current problem
Correspondingly indexed parameters contain the AMPL names of all the components:
	_varname{1.._nvars}   names of variables in the current problem
	_conname{1.._ncons}   names of constraints in the current problem
	_objname{1.._nobjs}   names of objectives in the current problem
Finally, the following synomyms for the components are made available:
	_var{1.._nvars}   synonyms for variables in the current problem
	_con{1.._ncons}   synonyms for constraints in the current problem
	_obj{1.._nobjs}   synonyms for objectives in the current problem
These synonyms let you refer to components "generically" by number, rather than by the usual indexed names. Using the variables as an example, _var[5] refers to the 5th variable in the problem, _var[5].ub to its upper bound, _var[5].rc to its reduced cost, and so forth, while _varname[5] is a string giving the variable's true AMPL name.

Generic names are useful for tabulating properties of all variables, where the variables have been defined in several different var declarations:

	ampl: model net3.mod
	ampl: data net3.dat

	ampl: solve;
	MINOS 5.4: optimal solution found.
	3 iterations, objective 1819

	ampl: display {j in 1.._nvars} 
	ampl?   (_varname[j],_var[j],_var[j].ub,_var[j].rc);

	:        _varname[j]      _var[j] _var[j].ub    _var[j].rc  :=
	1   "PD_Ship['NE']"          250      250      -0.5
	2   "PD_Ship['SE']"          200      250      -1.11022e-16
	3   "DW_Ship['NE','BOS']"     90       90       0
	4   "DW_Ship['NE','EWR']"    100      100      -1.1
	5   "DW_Ship['NE','BWI']"     60      100       0
	6   "DW_Ship['SE','EWR']"     20      100       2.22045e-16
	7   "DW_Ship['SE','BWI']"     60      100       2.22045e-16
	8   "DW_Ship['SE','ATL']"     70       70       0
	9   "DW_Ship['SE','MCO']"     50       50       0
	;
Another use is to list all variables having some property, such as being positive in the optimal solution:
	ampl: display {j in 1.._nvars:  
	ampl?   _var[j] < _var[j].ub - 0.00001} _varname[j];

	_varname[j] [*] :=
	2  "PD_Ship['SE']"
	5  "DW_Ship['NE','BWI']"
	6  "DW_Ship['SE','EWR']"
	7  "DW_Ship['SE','BWI']"
	;
The same comments apply to constraints and objectives. More precise formatting of this information can be obtained by using the printf command (Sections 10.6, A.13.1) instead of display.

As in the case of the expand command, these parameters and generic synonyms reflect the "modeler's view" of the problem; their values are determined from the model and data as they were initially read and translated. AMPL's presolve phase (Section 10.2) may make significant simplifications to the problem before it is sent to the solver, however. To work with parameters and generic synonyms that reflect the "solver's view" of the problem following presolve, replace _ by _s in the names given above; for example in the case of variables, use _snvars, _svarname and _svar.


Summary model information

The following sets are automatically updated to contain the names of model components declared so far:
Set: Contains names of all declared:
_SETS sets
_PARS parameters
_VARS variables
_OBJS objectives
_CONS constraints
_FUNCS user-defined functions
_PROBS problems
_ENVS environments
Two new functions, arity(s) and indexarity(s), provide additional information about the component whose name is given by the character string s:
arity(s)

the dimension of s, or number of components in each member of s, provided s is a set; otherwise 0

indexarity(s)

the dimension of the set over which s is indexed, or 0 if s is not indexed over a set, or -1 if s has not been declared

Used together, these features can provide a summary of model components and their dimensions:
	ampl: display {i in _SETS} arity(i);
	arity(i) [*] :=
	DEST  1
	ORIG  1
	PROD  1
	;

	ampl: display {i in _VARS} indexarity(i);
	indexarity(i) [*] :=
	Trans  3
	  Use  2
	;



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 30 JULY 1998 BY 4er.