ILOG AMPL CPLEX User Manual

ILOG AMPL CPLEX System

Version 11.0

User’s Guide

Standard (Command-line) Version

Including CPLEX Directives

January 2008

COPYRIGHT NOTICE

Copyright © 1987-2007, by ILOG S.A. and ILOG, Inc. All rights reserved.

General Use Restrictions

This document and the software described in this document are the property of ILOG and
are protected as ILOG trade secrets. They are furnished under a license or nondisclosure
agreement, and may be used or copied only within the terms of such license or nondisclosure
agreement.

No part of this work may be reproduced or disseminated in any form or by any means,
without the prior written permission of ILOG S.A, or ILOG, Inc.

Trademarks

ILOG, the ILOG design, CPLEX, and all other logos and product and service names of
ILOG are registered trademarks or trademarks of ILOG in France, the U.S. and/or other
countries.

All other company and product names are trademarks or registered trademarks of their
respective holders.

Java and all Java-based marks are either trademarks or registered trademarks of Sun
Microsystems, Inc. in the United States and other countries.

Microsoft, Windows, and Windows NT are either trademarks or registered trademarks of
Microsoft Corporation in the United States and other countries.

document version 11.0

CO N T E N T S

Table of Contents

Chapter 1 Welcome to AMPL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

Using this Guide. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9

Installing AMPL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10

Requirements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10

Unix Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10

Windows Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .11

AMPL and Parallel CPLEX. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .11

Licensing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .11

Usage Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12

Installed Files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13

Chapter 2 Using AMPL. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

Running AMPL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

Using a Text Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

Running AMPL in Batch Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16

Chapter 3 AMPL-Solver Interaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

Choosing a Solver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .19

Specifying Solver Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .20

Initial Variable Values and Solvers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .21

Problem and Solution Files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .21

ILOG AMPL CPLEX SYSTEM 11.0 — USER’ S GUIDE 3

Saving temporary files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .22

Creating Auxiliary Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .23

Running Solvers Outside AMPL. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .24

Using MPS File Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .24

Temporary Files Directory. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .25

Chapter 4 Customizing AMPL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

Command Line Switches. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .27

Persistent Option Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .28

Chapter 5 Using CPLEX with AMPL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

Problems Handled by CPLEX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .31

Piecewise-linear Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .32

Quadratic Programs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .32

Quadratic Constraints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .33

Specifying CPLEX Directives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .34

Directives for Handling Infeasible Problems. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .35

Directive for Tuning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .36

Chapter 6 Using CPLEX for Continuous Optimization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

CPLEX Algorithms for Continuous Optimization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .39

Directives for Problem and Algorithm Selection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .40

Directives for Preprocessing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

Directives for Controlling the Simplex Algorithm. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

Directives for Controlling the Barrier Algorithm. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .49

Directives for Improving Stability. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .51

Directives for Starting and Stopping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .52

Directives for Controlling Output. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54

Chapter 7 Using CPLEX for Integer Programming . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57

CPLEX Mixed Integer Algorithm. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .57

Directives for Preprocessing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59

Directives for Algorithmic Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .62

4 ILOG AMPL CPLEX SYSTEM 11.0 — USER’ S GUIDE

Directives for Relaxing Optimality . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70

Directives for Halting and Resuming the Search . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .72

Directives to Manage the Solution Pool. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .72

Directives for Controlling Output. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74

Common Difficulties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .74

Running Out of Memory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .74

Failure To Prove Optimality . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .75

Difficult MIP Subproblems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .76

Chapter 8 Defined Suffixes for CPLEX. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77

Algorithmic Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .77

Sensitivity Ranging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .80

Diagnosing Infeasibilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .81

Direction of Unboundedness . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .83

Chapter 9 CPLEX Status Codes in AMPL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85

Solve Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .85

Basis Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .89

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93

ILOG AMPL CPLEX SYSTEM 11.0 — USER’ S GUIDE 5

6 ILOG AMPL CPLEX SYSTEM 11.0 — USER’ S GUIDE

TA B L E S

List of Tables

3.1 Auxiliary Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

4.1 AMPL Option Names for Command Line Switches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

6.1 Settings for the dependency Directive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

6.2 Settings for the advance Directive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

6.3 Settings for the pgradient Directive. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

6.4 Dual Pricing Indicator dgradient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

7.1 Values of the AMPL Option send_statuses. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61

7.2 Settings for the mipemphasis Directive. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63

7.3 Settings for the mipcrossover Directive. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65

7.4 Settings for the round Directive. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69

7.5 Settings for the startalgorithm Directive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69

8.1 Settings for the lazy Directive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79

9.1 Interpretation of Numeric Result Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86

9.2 Solve Codes and Termination Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86

A.1 CPLEX Synonyms. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91

ILOG AMPL CPLEX SYSTEM 11.0 — USER’ S GUIDE 7

8 ILOG AMPL CPLEX SYSTEM 11.0 — USER’ S GUIDE

CH A P T E R

1

Welcome to AMPL

Welcome to the AMPL Modeling System—a comprehensive, powerful, algebraic modeling
language for problems in linear, nonlinear, and integer programming. AMPL is based upon
modern modeling principles and utilizes an advanced architecture providing flexibility most
other modeling systems lack. AMPL has been proven in commercial applications, and is
successfully used in demanding model applications around the world.

AMPL helps you create models with maximum productivity. By using AMPL's natural
algebraic notation, even a very large, complex model can often be stated in a concise (often
less than one page), understandable form. As its models are easy to understand, debug, and
modify, AMPL also makes maintaining models easy.

Using this Guide

This brief guide describes starting up AMPL, reading a model and supplying data, and
solving (optimizing) the model using CPLEX. Chapters 2-4 cover issues such as using
command-line options and environment variables and using AMPL on different operating
systems. Later chapters provide a detailed description of CPLEX directives.

This Guide does not teach you the AMPL language. To learn and effectively use the features
of the AMPL language, you should have a copy of the book AMPL: A Modeling Language
for Mathematical Programming, 2nd. edition by Robert Fourer, David M. Gay and Brian W.
Kernighan (copyright 2003, publisher Thomson Brooks/Cole, ISBN number 0-534-38809-

ILOG AMPL CPLEX SYSTEM 11.0 — USER’ S GUIDE 9

Installing AMPL

4.). This book includes a tutorial on AMPL and optimization modeling; models for many
"classical" problems such as production, transportation, blending, and scheduling;
discussions of modeling concepts such as linear, nonlinear and piecewise-linear models,
integer linear models, and columnwise formulations; and a reference section.

Additional information can be found at the AMPL website at: www.ampl.com.

AMPL is continuously undergoing development, and while we strive to keep users updated
on language features and capabilities, the official reference to the language is the AMPL
book, which is naturally revised less frequently.

Please read these instructions in their entirety before beginning the installation. Remember
that most distributions will operate properly only on the specific platform and operating
system version for which they were intended. If you upgrade your operating system you may
need to obtain a new distribution.

All AMPL installations include

cplexamp (cplexamp.exe on Windows), the CPLEX

solver for AMPL. This combined distribution is known as the AMPL/CPLEX system.

Note that
However, most AMPL installations will include the use of

cplexamp may not be licensed for a few users with unsupported solvers.

cplexamp.

Requirements

AMPL may be installed and run on many different hardware and software configurations. A
table of the currently-supported configurations is available at:

http://www.ilog.com/products/cplex/product/platforms.cfm.

Unix Installation

On Unix systems, AMPL is installed into the current working directory. We recommend that
you perform the installation in an empty directory. After installation, make sure the
executable files have read and execute privileges turned on for all users and accounts that
will use AMPL.

CD-ROM

The ILOG CD contains the AMPL/CPLEX system for several different platforms. First,
read the file

INFO_UNX.TXT. The section titled, "AMPL CPLEX System" contains

information to help you locate the distribution for your platform. Note that the files listed in
this section contain the entire AMPL/CPLEX System, not just the AMPL language
processor. After you have located the files, read the CD booklet for instructions on
extracting the distribution.

10 ILOG AMPL CPLEX SYSTEM 11.0 — USER’ S GUIDE

FTP

Execute:

gzip-dc < /path/ampl.tgz | tar xf -

where /path is the full path name into which ampl.tgz was downloaded.

Windows Installation

On Windows systems AMPL is installed into a directory which you can specify during the
installation (the default location is

C:\AMPL).

CD-ROM

The ILOG CD contains the AMPL/CPLEX system for several different platforms. Follow
the instructions in the CD booklet and in the setup program menus to set up the distribution.

FTP

After downloading the files, execute the downloaded

.EXE file from the Run dialog or in an

MS-DOS window. Follow the instructions presented by the setup program. To access the
Run dialog box on Windows, click on the Start button and select Run…

AMPL and Parallel CPLEX

If you have purchased AMPL and Parallel CPLEX, follow the above instructions for the
appropriate media. You will use the same programs to run in serial or parallel mode.

Licensing

ILOG License Manager (ILM) access keys are needed for both AMPL and CPLEX. If you
have already activated a license for the CPLEX Suite on this machine, you only need to
activate an AMPL license to use the AMPL CPLEX System.

Updating an Existing License

If you are upgrading from a previous version of CPLEX, please refer to the ILM license
update procedures (provided separately) or contact ILOG Sales Administration. You should
skip any installation steps that would establish a new license.

New Installation

If you are installing CPLEX or AMPL for the first time, you will receive an ILOG License
Manager (ILM) manual and a license key that enables the use of AMPL and/or CPLEX.
Follow the instructions in that manual for details on how to install the license key.

ILOG AMPL CPLEX SYSTEM 11.0 — USER’ S GUIDE 11

Usage Notes

The CPLEX solver for AMPL is named

cplexamp (cplexamp.exe on Windows). This

version of AMPL will use this solver by default. Older versions of the CPLEX solver for
AMPL were simply named

cplex (cplex.exe on Windows). Some users of that version

may have specified the solver in their model or run files like this:

option solver cplex;

If you have models containing settings like this, you will encounter errors (or the old version
of the solver might be invoked). There are two ways to fix this. Ideally, you should change
these lines to:

option solver cplexamp;

If that is not practical, you can copy the file
must remember to copy it again the next time you upgrade

cplexamp to cplex. If you do the latter, you

cplexamp.

12 ILOG AMPL CPLEX SYSTEM 11.0 — USER’ S GUIDE

Installed Files

Unix systems

ampl AMPL

cplexamp The CPLEX solver for AMPL

amplcplex100userguide.pdf User’s manual for AMPL/CPLEX

examples Directory of examples (see

README.TXT The notes on using CPLEX with AMPL provided by

AMPL Optimization LLC

Examples

below)

Windows Systems

ampl.exe AMPL

amplcplex100userguide.pdf User’s manual for AMPL/CPLEX

ampltabl.dll Table handlers

cplex100.dll CPLEX DLL used by cplexamp.exe

cplexamp.exe

examples Directory of examples (see

exhelp32.exe Utility program invoked by AMPL for DOS shells

README.TXT The notes on using CPLEX with AMPL provided by

The CPLEX solver for AMPL

Examples

AMPL Optimization LLC

below)

Examples

/models Sample AMPL models - Most of these correspond to

examples in the AMPL book. More information on some
of the examples is provided in the readme file in this
directory.

/looping Advanced sample AMPL models - A description of each

is provided in the readme file in this directory.

/industries
/industries/finance
/industries/logistic
/industries/product
/industries/purchase
/industries/schedule

More samples - The industries directory is sub­divided into industry-specific subdirectories. The models
have been brought together from a variety of sources.
Together, they provide a palette of AMPL models that
you may use as a starting point for your projects.

ILOG AMPL CPLEX SYSTEM 11.0 — USER’ S GUIDE 13

14 ILOG AMPL CPLEX SYSTEM 11.0 — USER’ S GUIDE

CH A P T E R

2

Using AMPL

Running AMPL

If you have added the AMPL installation directory to the search path, you can run AMPL
from any directory. Otherwise, run AMPL by moving to the
at the shell prompt.

At the
described in Section A.14 of the book AMPL: A Modeling Language for Mathematical
Programming, 2nd. edition. To end the session, type

Using a Text Editor

Generally, you will edit your model and data (both expressed using AMPL language
statements) in a text editor, and type commands at the
data, solve a problem, and inspect the results. Although you could type in the statements of a
model at the
AMPL commands to edit the statements you have previously entered. Microsoft Windows
users (on PCs) and XWindows users (on Unix systems) should open separate windows for
editing files and running AMPL.

ILOG AMPL CPLEX SYSTEM 11.0 — USER’ S GUIDE 15

AMPL directory and typing ampl

ampl: prompt, you can type any AMPL language statement, or any of the commands

quit; at the ampl: prompt.

ampl: prompt to load your model and

ampl: prompt, AMPL does not include a built-in text editor, so you cannot use

If you cannot open multiple windows on your desktop, you can use AMPL's shell command
to invoke an editor from within AMPL. You can use any editor that saves files in ASCII
format. Windows command-line (DOS) users can use edit or notepad and Unix users vi or
emacs. If you are using edit under DOS, for instance, you can type:

ampl: shell 'edit steel.dat';

Use editor menus and commands to edit your file, then save it and exit the editor. At the

ampl: prompt you can type new AMPL commands, such as:

ampl: reset data;
ampl: data steel.dat;

Note that editing a file in a text editor does not affect your AMPL session until you
explicitly reload the edited file, as shown above.

Running AMPL in Batch Mode

If you have previously developed a model and its data, and would like to solve it and display
the results automatically, you can create a file containing the commands you would like
AMPL to execute, and specify that file at the command line when you run AMPL. For
example, you might create a file called

model steel.mod;
data steel.dat;
option solver cplexamp;
solve;
display Make >steel.ans;

steel.run, containing the commands:

Note that this assumes that

steel.run is in the same directory as the model and data files,

and that AMPL can be found on the path.

You can then run AMPL as follows:

C:\> ampl steel.run

A more flexible approach, which is a commonly followed convention among AMPL users,
is to put just the AMPL commands (the last three lines in the example above) in a file with
the

*.run extension. You can then type:

C:\> ampl steel.mod steel.dat steel.run

which accomplishes the same thing as:

C:\> ampl
ampl: include steel.mod;
ampl: include steel.dat;
ampl: include steel.run;
ampl: quit;
C:\>

16 ILOG AMPL CPLEX SYSTEM 11.0 — USER’ S GUIDE

If you intend to load several files and solve a problem, but you want to type a few interactive
commands in the middle of the process, type the character
processes the files on the command line from left to right; when it encounters the
displays the

ampl: prompt and accepts commands until you type end;. For example, you

– in place of a filename. AMPL

– symbol it

could type:

C:\> ampl steel.mod steel.dat - steel.run
ampl: let avail := 50;
ampl: end;

This will solve the problem as before, but with the parameter
(the value specified in

steel.dat). To start AMPL, load a model and data file, and wait for

your interactive commands, type:

C:\> ampl steel.mod steel.dat -

avail set to 50 instead of 40

ILOG AMPL CPLEX SYSTEM 11.0 — USER’ S GUIDE 17

18 ILOG AMPL CPLEX SYSTEM 11.0 — USER’ S GUIDE

CH A P T E R

3

AMPL-Solver Interaction

Choosing a Solver

AMPL's solver interface supports linear, nonlinear, and mixed integer models with no built­in size limitations. This interface is rich enough to support many of the features used by
advanced solvers to improve performance and solution accuracy, such as piecewise-linear
constructs, representation of network problems, and automatic differentiation of nonlinear
functions. To take advantage of these features, solvers must be written to utilize AMPL's
interface. ILOG provides no support for the usage of AMPL with solvers not distributed by
ILOG.

You choose a solver for a particular problem by giving its executable filename in the AMPL

option solver command. For example, to use the (AMPL-compatible) CPLEX solver,

type:

ampl: option solver cplexamp;

Most solvers have algorithmic options, such as CPLEX with its Mixed Integer and Barrier
options. In these cases, you give the solver executable name to AMPL (for example, with

option solver cplexamp); the solver will determine, from the problem characteristics

as passed by AMPL (for example, a quadratic objective or integer variables) as well as
solver options you specify, which algorithmic options will be used.

ILOG AMPL CPLEX SYSTEM 11.0 — USER’ S GUIDE 19

Specifying Solver Options

You can specify option settings for a particular solver through the AMPL option
command. (CPLEX-specific directives are described later in this document.) Since all
solvers provide default settings for their options, this is necessary only when your problem
requires certain nondefault settings in order to solve, or when certain settings yield improved
performance or solution accuracy.

To specify solver options, enter

option

where

solver_

solver is replaced by the name of the solver you are using. This approach allows

options 'settings';

you to set up different options for each solver you use and to switch among them by simply
choosing the appropriate solver with the

ampl: option cplex_options 'relax scale=1';

Solver options consist of an identifier alone, or an identifier followed by an

option solver command. For example:

= sign and a

value. Some solvers treat uppercase and lowercase versions of an option identifier as
equivalent, while others are sensitive to case, so that

RELAX is not the same as relax, for

example.

Solver option settings can easily become long enough to stretch over more than one line. In
such cases you can either continue a single quoted string by placing a

\ character at the end

of each line, as in:

ampl: option cplex_options 'crash=0 dual \
ampl? feasibility=1.0e-8 scale=1 \
ampl? lpiterlim=100';

Or you can write a series of individually quoted strings, which will be concatenated
automatically by AMPL, as in:

ampl: option cplex_options 'crash=0 dual'
ampl? ' feasibility=1.0e-8 scale=1'
ampl? ' lpiterlim=100';

If you use the latter approach, be sure to include spaces at the beginning or end of the
individual strings, so that the identifiers will be separated by spaces when all of the strings
are concatenated.

20 ILOG AMPL CPLEX SYSTEM 11.0 — USER’ S GUIDE

Often you will want to add solver options to the set you are currently using. If you simply
type a command such as

option solver_options 'new options'; however, you will

overwrite the existing option settings. To avoid this problem, you can use AMPL's
notation for options: the symbol

option_name. To add an optimality tolerance to the CPLEX options in the above example,

you would write:

ampl: option cplex_options $cplex_options
ampl? ' optimality=1.0e-8';

Initial Variable Values and Solvers

Some optimizers (including most nonlinear solvers but excluding simplex-based linear
solvers) make use of initial values for the decision variables as a starting point in their search
for an optimal solution. A good choice of initial values can greatly speed up the solution
process in some cases. Moreover, in nonlinear models with multiple local optima, the
optimal solution reported by the solver may depend on the initial values for the variables.

AMPL passes initial values for decision variables, and dual values if available, to the solver.
You can set initial values using the

When you solve a problem two times in a row, the final values from the first solver
invocation become the initial values for the second solver invocation (unless you override
this behavior with statements in your AMPL model). In nonlinear models with multiple
local optima, this can cause some solvers to report a different solution on the second
invocation.

$

$option_name is replaced by the current value of

:= syntax in the var declaration of your AMPL model.

Simplex-based solvers typically discard initial values. However, they can use basis status
information, if available. Basis statuses can be set either within AMPL or by a previous
optimization. Information on interpreting and setting variable statuses is provided in
Chapter 9, CPLEX Status Codes in AMPL.

Problem and Solution Files

When you type solve; AMPL processes your model and data to create a temporary
problem file, such as
the solver program, which is responsible for creating a solution file such as
AMPL reads the solution file and makes the solution values available through the variable,
constraint, and objective names you have declared in your AMPL model. Unless you specify
otherwise, AMPL then deletes the temporary problem and solution files.

ILOG AMPL CPLEX SYSTEM 11.0 — USER’ S GUIDE 21

steel.nl, which will be read by the solver. It then loads and executes

steel.sol.

You can display the solution information, for example the values of the decision variables
and constraints, in your AMPL session with commands such as
you have just solved a problem created from

ampl: display Make, Time;

steel.mod and steel.dat, you could type:

display. For example, if

To save this output in a file, you can use redirection:

ampl: display Make, Time > mysol.txt;

Note that when you simply mention the name of a constraint in a display statement, AMPL
will display the dual value (shadow price) of that constraint, not its left-hand side value. You
can use the AMPL suffix notation to display the left-hand side value, as described in the
book AMPL: A Modeling Language for Mathematical Programming, 2nd. edition.

Saving temporary files

AMPL deletes the temporary problem (

*.nl) and solution (*.sol) files after a solver is

finished, so no permanent record of the solution is kept unless you save the output yourself
(for example, using display with redirection as illustrated above). To override the deletion of
temporary files, you can use the AMPL

C:\> ampl
ampl: model steel.mod; data steel.dat;
ampl: write bsteel;
ampl: solve;
CPLEX 11.0.0: optimal solution; objective 192000
2 iterations (0 in phase I)
ampl: quit;

The first letter,

b, in the filename portion of the write command is interpreted specially,

write command. For example:

as explained below. If you now display the files in the current directory with a command
such as

steel.sol.

To later view the solution values, you would use the

C:\> ampl
ampl: model steel.mod; data steel.dat;
ampl: solution steel.sol;
CPLEX 11.0.0: optimal solution; objective 192000
2 iterations (0 in phase I)
ampl: display Make;
Make [*] :=
bands 6000
coils 1400
;
ampl: quit;

dir steel.*, you will find the problem file steel.nl and the solution file

solution command. For example:

You must include the model and data statements, as shown above, so that AMPL knows the
definitions of symbolic names like
from

steel.sol, without running a solver.

Make. But solution then retrieves the earlier results

22 ILOG AMPL CPLEX SYSTEM 11.0 — USER’ S GUIDE

if you use
uses a compact and efficient binary format for the problem and solution files. If you use

b as the first character of the filename portion of the write command, AMPL

g

instead, AMPL writes the files in an ASCII format that may be easier to transmit
electronically over systems like the Internet. In technical support and consulting situations,
ILOG may ask you to send a file using this format. If you use
in MPS format, and the filename ends in

mps (for example, steel.mps). This is described

m, AMPL writes the problem

further in Using MPS File Format on page 24.

Creating Auxiliary Files

AMPL can create certain human- and program-readable auxiliary files that help relate the
various set, variable, constraint, and objective names used in your AMPL model to the
column and row indices that are written to the problem file and seen by the solver. This is
particularly valuable when the AMPL presolve phase actually eliminates variables and
constraints before the problem is sent to the solver.

To create the auxiliary files, you set the AMPL option auxfiles to a string of letters denoting
the combination of auxiliary files you would like produced, and then use the write command
to create and save the auxiliary files along with the problem (

*.nl) file. For example, the

command:

ampl: option auxfiles 'cr';

will cause the

write command to create auxiliary files containing the names of the

variables (columns) and constraints (rows) as sent to the solver. The table below shows the
types of auxiliary files that can be created and the letter you use to request them via the
AMPL option auxfiles.

Table 3.1 Auxiliary Files

Letter Extension Description

a .adj adjustment to objective, for example, to compensate for fixed

variables eliminated by presolve

c .col AMPL names of the variables (columns) sent to the solver

f .fix names of variables fixed by presolve, and the values to which they

are fixed

r .row AMPL names of the constraints (rows) sent to the solver

s .slc names of “slack” constraints eliminated by presolve because they

can never be binding

u .unv names of variables dropped by presolve because they are never

used in the problem instance

ILOG AMPL CPLEX SYSTEM 11.0 — USER’ S GUIDE 23

Running Solvers Outside AMPL

With the write and solution commands, you can arrange to execute your solver outside
the AMPL session. You might want to do this if you receive an
from your solver (not from AMPL itself): When the solver is invoked from within AMPL, a
fair amount of memory is already used for the AMPL Modeling System program code and
for data structures created by AMPL for its own use in memory. If you execute the solver
alone, it can use all available memory.

To run your solver separately, first use AMPL to create a problem file:

C:\> ampl
ampl: model steel.mod; data steel.dat;
ampl: write bsteel;
ampl: quit;

Then run your solver with a command like the one below (for CPLEX):

out of memory message

C:\> cplexamp steel -AMPL

In this example, the first argument
the AMPL
problem from AMPL. This may optionally be followed by any solver options you need for
the problem, using the same syntax used with the
omitting the outer quotes, for example
successfully to completion, it will write a solution file;
then restart AMPL and read in the results with the solution command, as outlined earlier:

C:\> ampl
ampl: model steel.mod; data steel.dat;
ampl: solution steel.sol;

Using MPS File Format

MPS file format, originally developed decades ago for IBM's Mathematical Programming
System, is a widely recognized format for linear and integer programming problems.
Although it is a standard supported by many solvers and modeling systems (including
AMPL), MPS file format is neither compact nor easy to read and understand; AMPL's
binary file format is a much more efficient way for modeling systems and solvers to
communicate. Also, MPS file format cannot be used for nonlinear problems, and not all
MPS-compatible solvers support exactly the same format, particularly for mixed integer
problems.

solver_options

steel matches the filename (after the initial letter b) in

write command. The -AMPL argument tells the solver that it is receiving a

option

crash=1 relax. Assuming that the solver runs

solver_

steel.sol in this case. You can

options command but

24 ILOG AMPL CPLEX SYSTEM 11.0 — USER’ S GUIDE

AMPL does have the ability to translate a model into MPS file format, as outlined below.
With this feature, you may be able to solve AMPL models with a solver that reads its
problem input in MPS file format. If you choose to use this feature, you will find AMPL's
ability to produce auxiliary files very useful, since these files can be used to relate the MPS
file format information to the sets, variables, constraints, and objectives defined in the
AMPL model. However, you will not be able to bring the solution—variable values, dual
values, and so on—back into AMPL; further work with the solution must be performed
outside of AMPL.

To translate your model into MPS file format, use the
with

m as the first letter of the filename. To illustrate, the command shown below creates a

file named

ampl: write msteel;

steel.mps:

In most cases, you will need to run your solver separately to obtain the solution.

Note that the MPS format does not provide a way to distinguish between objective
maximization and minimization. However, CPLEX assumes that the objective is to be
minimized. (There is no standardization on this issue; other solvers may assume
maximization.) Thus, it is incumbent upon the user of the MPS format to ensure that the
objective sense in the AMPL model corresponds to the solver's interpretation.

Temporary Files Directory

If the TMPDIR option is not set, AMPL writes the problem and solution files and other
temporary files to the current directory. You can give a specific location for the temporary
files by setting option TMPDIR to a valid path. On a PC, you might use:

ampl: option TMPDIR 'D:\temp';

On a Unix machine, a typical choice would be:

ampl: option TMPDIR '/tmp';

write command as outlined above

ILOG AMPL CPLEX SYSTEM 11.0 — USER’ S GUIDE 25

26 ILOG AMPL CPLEX SYSTEM 11.0 — USER’ S GUIDE

CH A P T E R

4

Customizing AMPL

Command Line Switches

Certain AMPL options normally set with the option command during an AMPL session
can also be set when AMPL is first invoked. This is done using a command line switch
consisting of a hyphen and a single letter, followed in some cases by a numeric or string
value. You will find these switches most useful when you have one or more model, data, or
run file that you want AMPL to process using different option settings at different times,
without actually editing the files themselves.

The table below summarizes the command line switches and their equivalent names when
set with the AMPL option command:

Table 4.1 AMPL Option Names for Command Line Switches

Switch AMPL Option Description

-C

n

n

-e

ILOG AMPL CPLEX SYSTEM 11.0 — USER’ S GUIDE 27

Cautions

eexit

nn

nn

= 0: suppress caution messages

n

= 1: report caution messages (default)

n

= 2: treat cautions as errors

> 0: abandon command after n errors

n

< 0: abort AMPL after |n| errors

n

= 0: report any number of errors

Switch AMPL Option Description

-f funcwarn 1 do not treat unavailable functions of constant
arguments as variable

-P presolve 0 turn off AMPL’s presolve phase

-S substout 1 use “defining” equations to eliminate variables

-L linelim 1 fully eliminate variables with linear “defining”
equations, so model is recognized as linear

-T gentimes 1 show time to generate each model component

-t times 1 show time taken in each model translation phase

str

-o

-s randseed ‘’ use current time for random number seed

-s

n

-v version display the AMPL software version number

If you type ampl -? at the shell prompt, AMPL will display a summary list of all the
command line switches. On some Unix shells,
use

"-?" with double quotation marks.

Persistent Option Settings

If you have many option settings or other commands that you would like performed each
time AMPL starts, you may create a text file containing these commands (in AMPL
language syntax). Then set the environment variable name
this text file. For example, on a Windows PC, you should type:

C:\> set OPTIONS_IN=c:\amplinit.txt

If you are using a C shell on a Unix machine you would type something like:

% setenv OPTIONS_IN ~ijr/amplinit.txt

outopt

str

randseed

set problem file format (b, g, m) and stub name;
to display more possibilities use -o?

n

use n for random number seed

? is a special character, so you may need to

OPTIONS_IN to the pathname of

AMPL reads the file referred to by

OPTIONS_IN and executes any commands therein before

it reads any other files mentioned on the command line or prompts for any interactive
commands.

28 ILOG AMPL CPLEX SYSTEM 11.0 — USER’ S GUIDE

If you want AMPL to preserve all of your option settings from one session to the next, you
can cause AMPL to write the options into a text file named by setting the AMPL option

OPTIONS_INOUT:

ampl: option OPTIONS_INOUT 'c:\amplopt.txt';

Before exiting, AMPL writes a series of option commands to the file named by

OPTIONS_INOUT which, when read, will set all of the options to the values they had at the

end of the session. To use this text file, set the corresponding environment variable to the
same filename:

C:\> set OPTIONS_INOUT=c:\amplopt.txt

After you do this, AMPL will read and execute the commands in

amplopt.txt when it

starts up. When you end a session, AMPL will write the current option settings - including
any changes you have made during the session - into this file, so that they will be preserved
for use in your next session.

If both the
referred to by

OPTIONS_INOUT.

OPTIONS_IN and OPTIONS_INOUT environment variables are defined, the file

OPTIONS_IN will be processed first, then the file referred to by

ILOG AMPL CPLEX SYSTEM 11.0 — USER’ S GUIDE 29

30 ILOG AMPL CPLEX SYSTEM 11.0 — USER’ S GUIDE