README file for the AMPL-PCx interface

Installation
------------

To use PCx from the AMPL environment, the executable 'pcx' should be
placed in the same directory as the AMPL executable.  For some
platforms, this executable is already available; otherwise it may be
built from the source code.  The installation procedure depends on
whether or not 'pcx' needs to be built or not:

1) Installation using a precompiled executable:

   o Uncompress the file 'pcx.gz'

   o Either move the file to the same place as AMPL, or make sure that 
     you invoke AMPL in the directory where you have placed the downloaded
     file.

2) Installation from the source code:

   o Obtain the solver interface code for AMPL from netlib:
     ftp://netlib.bell-labs.com/netlib/ampl/index.html
     For a complete tar file of the solver interface code, see
     ftp://netlib.bell-labs.com/netlib/ampl/solvers.tar

   o Install the solver interface code as directed, producing the file
     'amplsolver.a'. (SJW adds on 12/24/01: This is not necessarily a 
     trivial step. After unpacking all the source code into a directory
     "solvers", look for the Unix makefile called "makefile.u". It contains
     comments on how to modify the make for different architectures. For
     Sun Solaris machines, no modification should be necessary: typing 
     "make -f makefile.u" should produce the desired file "amplsolver.a".
     For Linux machines, it's usually necessary to add "-DNON_STDIO" to 
     "CFLAGS" to avoid  getting an error message during  compilation
     of "stderr.c". Then type "make -f makefile.u" as before.)
   
   o Download `amplpcx.tar.gz' and move it into the same directory as
     `amplsolver.a'.  Uncompressing the file will create a new
     subdirectory 'PCx'.

   o Enter the newly created subdirectory, edit the makefile as needed
     and type `make'.

   o Either move the file to the same place as AMPL, or make sure that 
     you invoke AMPL in the directory where you have placed the downloaded
     file.

Usage
-----

To set PCx as the solver in AMPL, type

   options solver pcx

from the `ampl:' prompt.

To change the default parameters that PCx uses, set the variable
`pcx_options'.  This variable should be a string (enclosed in single
quotes) of the following form:

   'param1=value1 param2=value2 ... paramN=valueN'

Note that there should be no spaces between the name of the parameter,
the equal sign, and the value.  The options available are the same
ones as those listed in the PCx User Guide, except that the parameter
names should be lowercase.  For example:

options pcx_options 'iterationlimit=50 max preprocess=no stepfactor=0.8'

A few of the options will be read but will have no effect because they
have no meaning when PCx is called from within AMPL.  These options
are:

   boundname
   inputdirectory
   objectivename
   rangename
   rhsname

Tasks such as selecting which objective to use, etc. can already be
done within AMPL, for example, the AMPL command `objective'.

Troubleshooting
---------------

If the interface doesn't work at all, (i.e. when you type in 'solve'
nothing happens) make sure that either

1) The file 'pcx' is in the same directory as your AMPL installation or
2) You invoke AMPL while in the directory containing 'pcx'.

Questions and comments concerning the AMPL-PCx interface should be
directed to brixius@cs.uiowa.edu.

----------------------------------------------------------------------
Nathan Brixius 7/31/98.

Revised: Stephen J. Wright 12/24/01.