A Package Adding Automatic Differentiation to Snopt

Argonne National Lab oratory

South Cass Avenue

Argonne IL

ANLMCSTM

Users Guide for SnadiOpt A Package Adding

Automatic Dierentiation to Snopt

E Michael Gertz

Mathematics and Computer Science Division

Argonne National Lab oratory

Argonne Illinois

Philip E Gil l and Julia Muetherig

Department of Mathematics

University of California San Diego

La Jolla California

Mathematics and Computer Science Division

Technical Memorandum No

January

gertzmcsanlgov pgillucsdedu jmuethucsdedu

httpwwwmcsanlgovgertz httpwwwscicompucsdedupeg httpwwwscicompucsdedujulia

This work was supp orted by the Mathematical Information and Computational Sciences Division

subprogram of the Oce of Advanced Scientic Computing Research US Department of Energy under

Contract WEng and by National Science Foundation Grant CCR

Argonne National Lab oratory with facilities in the states of Illinois and Idaho is owned

by the United States Government and op erated by The University of Chicago under the

provisions of a contract with the Department of Energy

DISCLAIMER

This rep ort was prepared as an accountofwork sp onsored by an agency of the United

States Government Neither the United States Government nor any agency thereof nor The

University of Chicago nor anyoftheiremployees or ocers makes anywarranty express

or implied or assumes any legal liability or resp onsibility for the accuracy completeness or

usefulness of any information apparatus pro duct or pro cess disclosed or represents that its

use would not infringe privatelyowned rights Reference herein to any sp ecic commercial

pro duct pro cess or service by trade name trademark manufacturer or otherwise do es not

necessarily constitute or imply its endorsement recommendation or favoring by the United

States Governmentorany agency thereof The views and opinions of do cument authors

expressed herein do not necessarily state or reect those of the United States Government

or any agency thereof Argonne National Lab oratory or The University of Chicago ii

Contents

Abstract

Intro duction

Problem Types

Why Automatic Dierentiation

ADIFOR

Who Should Use This Package

How to Read This Manual

Basic Usage

Additional Resources

Automatic Dierentiation

UserSupplied Subroutines

The Function Denition Routine

The Initialization Routine

An Example Problem

Invoking SnadiOpt

Lo cating Executables and Libraries

Basic Usage

Files Generated by snadioptpl

Merging Changes

AdvancedUsage

Summary of All Options

Building the Executable

Typical Usage

Sub ordinate Makeles

Useful makefile Targets

Useful makefile Variables

Dense ADIFOR

References

Index iii

Users Guide for SnadiOpt A Package Adding

Automatic Dierentiation to Snopt

E Michael Gertz Philip E Gil l and Julia Muetherig

Abstract

SnadiOpt is a package that supp orts the use of the automatic dierentiatio n package

ADIFOR with the optimization package Snopt

Snopt is a generalpurp ose system for solving optimization problems with many

variables and constraints It minimizes a linear or nonlinear function sub ject to b ounds

on the variables and sparse linear or nonlinear constraints It is suitable for largescale

linear and quadratic programming and for linearly constrained optimization as well as

for general nonlinear programs

The metho d used by Snopt requires the rst derivatives of the ob jective and con

straint functions to b e available The SnadiOpt package allows users to avoid the time

consuming and errorprone pro cess of evaluating and co ding these derivatives Given

Fortran co de for evaluating only the values of the ob jective and constraints SnadiOpt

automatically generates the co de for evaluating the derivatives and builds the relevant

Snopt input les and sparse data structures

Keywords Largescale nonlinear programming constrained optimization SQP

metho ds automatic dierentiati on Fortran software

Users Guide for SnadiOpt

Intro duction

This is the users guide for SnadiOpt a package that adds the automatic dierentiation

capability to the nonlinear optimization package Snopt SnadiOpt uses the sourceto

source automatic dierentiation package ADIFOR to p erform the dierentiation

Problem Typ es

Snopt is a collection of Fortran subroutines for solving a nonlinear programming problem

assumed to b e stated in the following form

NP min or max F x

obj

sub ject to l x u L F x U

where u U l andL are constantvectors of upp er and lower b ounds F xisavector of

smo oth linear and nonlinear problem functions and F x denotes the comp onentof F to

obj

b e minimized or maximized

Note that upp er and lower b ounds are sp ecied for all variables and constraints This

form allows full generality in sp ecifying various typ es of constraint Sp ecial values are used

to indicate absent b ounds l or u for appropriate j Free variables and free

j j

constraints free rows are ones that have b oth b ounds innite Similarlyxedvariables

have l u and equality constraints have L U

j j j j

The metho d used by Snopt requires that the elements J xF x x of the Jaco

ij i j

bian matrix of rst derivatives b e known at any p oint x In practice it is often inconvenient

or imp ossible to co de the derivatives and so Snopt allows the user to co de as manyderiva

tives as is convenient Snopt then estimates unknown derivatives by nite dierences by

making a call to F for eachvariable x whose partial derivatives need to b e estimated

However nite dierences reduce the reliability of the optimization algorithm and can b e

exp ensive if there are many suchvariables x TheSnadiOpt package allows the user to avoid

the timeconsuming and errorprone pro cess of evaluating and co ding derivatives without

the need for Snopt to compute nite dierences

Often an element J is constant which implies that variable x o ccurs only linearly

ij j

in the problem function F x If a signicantnumb er of these constant elements are zero

then J is known as a sparse matrix and Snopt uses a sparse matrix format to store only

the nonzero elements of J SnadiOpt automatically identies constant and zero Jacobian

elements by using a scheme that evaluates the Jacobian at a number of points close to

the starting p oint see Section Given Fortran co de for evaluating only F x SnadiOpt

automatically generates co de for evaluating J and builds the relevant Snopt input les and

sparse data structures

Why Automatic Dierentiation

Writing co de for the derivatives of F x is dicult time consuming and error prone es

p ecially when problems involvemanyvariables and constraints Automatic dierentiation

AD to ols in this case ADIFOR quickly provide correct and numerically accurate

derivative functions from the co de used to evaluate the ob jective and constraint functions

Prior to the wide availability of AD software and ADbased mo deling languages nu

merical dierentiation was the only alternativetoproviding derivative co de Unfortunately

numerical dierentiation is an inherently unstable pro cess that causes b oth theoretical and

practical diculties for nonlinear solvers Numerical dierentiation places a severe theo

retical limit on the accuracy of the solution that may b e computed by an algorithm see

eg Chapter In practice co de that uses numerical dierentiation tends to need

Introduction

more iterations to nd a solution than do es co de that uses exact derivatives Furthermore

co de that uses numerical dierentiation is typically less robust and will fail to nd solutions

for problems that mighthave b een solved if analytic derivatives were supplied Notwith

standing these diculties numerical dierentiation was often used to avoid the high cost of

handco ding the exact derivatives

With mo dern AD to ols derivativecodemay b e quickly obtained leading to a signicant

increase in user pro ductivityeven on simple problems Moreover functions can nowbe

dierentiated that were once considered to o complex to b e co ded by hand An example

is a function dened in terms of the output from an ordinary dierential equation solver

ADIFOR has b een successfully applied to such functions

Automatic dierentiation allows users to develop mo dels quickly This increase in pro

ductivity makes optimization software a much more useful to ol for scientists who often wish

to exp eriment with dierent ob jective functions and dierent sets of constraints

ADIFOR

ADIFOR is a robust mature automatic dierentiation to ol develop ed through a collab ora

tive pro ject b etween the Mathematics and Computer Science Division at Argonne National

Lab oratory and the Center for ResearchonParallel Computation at Rice University The

package is a sourcetosource translator for functions written in Fortran It is widely

available and runs on many p opular platforms Moreover the source co de for the ADI

FOR libraries but not the translator is provided making it p ossible to compile and run

ADIFORgenerated co de on most platforms

ADIFOR implements the forward mo de for automatic dierentiation although it do es

make some use of the reverse mo de internally As a practical matter this means that

ADIFORgenerated co de will tend to run most quickly if the number of variables is not

much larger than the numb er of constraints

Who Should Use This Package

It is usually wise to try automatic dierentiation b efore attempting to co de derivatives by

hand Some users may b e more comfortable using mo deling languages with an automatic

dierentiation capability see eg AMPL and GAMS SnadiOpt is intended for those

who prefer to co de in Fortranorneedtomake use of existing Fortran software Suchusers

should nd that this package can provide derivativecodequickly and eciently

Programmers who typically write in C or Fortran mightlike to consider developing

their mo dels in Fortran so that they may use this package to obtain derivatives A C

programmer should b e able to learn enough Fortran to formulate simple to mo derately

complicated mo dels within a few hours C has many features that Fortran do es not but it

is exactly those features that can make the automatic dierentiation of C co de problematic

How to Read This Manual

Section summarizes the four steps needed to dene and solve an optimization mo del

using SnadiOpt and Snopt Section describ es the main features of the SnadiOpt package and

provides some background on the mechanics of automatic dierentiation this section may

b e omitted on rst reading Section describ es the subroutines that must b e provided by

users to dene their mo del Section descib es the invo cation of the Perl script snadioptpl

that automatically generates all input les for ADIFOR This discussion includes detailed

information on the various les generated by SnadiOpt see Section Finally Section

discusses the use of the Make utility to automatically dierentiate the problem les and build an executable le ready for execution

Users Guide for SnadiOpt

Basic Usage

In the simplest case the SnadiOpt package can b e used to solve problem NP in four steps

Step Construct a le probf containing Fortran subroutines usrini and usrfun see Sec

tion Subroutine usrini initializes all data asso ciated with the mo del including

the b ounds l u L and U and the comp onentof F that denes the ob jective function

Subroutine usrfun denes the values of the problem functions F at a given value of

xAFortran main program is not required However subroutine usrini must dene

the lengths of all arrays used to dene the mo del

Step Invoke the Perl script snadioptpl to generate the input les needed by the automatic

dierentiation package ADIFOR The syntax of the call is

snadioptpl o prob probf

The symbol is the shell prompt and is not to b e typ ed This generates a number

of auxiliary les with the prex prob see Section

Step Build the executable le for the mo del prob This step uses ADIFOR to generate the

dierentiated subroutines needed for Snopt compiles them and links them with the

Snopt libraries All these tasks are p erformed by using the Make utility where the

makefile is one of the les automatically generated by snadioptpl see Section

To start the build pro cess typ e

makeprob

Step Solve the optimization problem bytyping

prob

Any output from the run will b e written to the les dened in the subroutine usrini

Additional Resources

All users should read the Snopt users guide which details the many user options available

in Snopt that maybesetby providing a sp ecs le The users guide describ es the algorithm

and its output and answers many questions ab out the p erformance of the optimizer on a

particular mo del

SnadiOpt tries to insulate the user from the details of invoking ADIFOR but users may

wish to read the ADIFOR users guide In particular while ADIFOR is very robust it is

p ossible to write Fortran co de that fo ols ADIFOR and the manual will explain howtoavoid

this pitfall

For general information on optimization we recommend that users explore the NEOS

guide on the Web httpwwwmcsanlgovotcGuideindexhtml

More information ab out automatic dierentiation in general and ADIFOR in particular

may b e found on the Argonne National Lab oratory automatic dierentiation Web page

httpwwwmcsanlgovautodiff

Users with complicated functions for which the automatically dierentiated co de app ears

to b e unacceptably slow can often accelerate their co de by refactoring it Several technical

rep orts on the automatic dierentiation page describ e how to do this

The authors of this package also maintain Web pages Philip Gills page has links to

published pap ers and technical rep orts on Snopt Michael Gertz maintains a Web page at

Argonne National Lab oratory

httpscicompucsdedupeg

httpwwwmcsanlgovgertz

Automatic Dierentiation

Automatic dierentiation is the pro cess of pro ducing co de that evaluates the derivatives

of a function from co de that evaluates the function itself It is closely related to symb olic

dierentiation but diers from it in imp ortantways Symb olic dierentiation takes the

mathematical expression for a function and pro duces another expression that represents the

derivative of that function Unlike symb olic dierentiation packages automatic dierentia

tion packages

understand programming concepts such as lo ops branches and subroutines and

use intermediate quantities and the chain rule to avoid p otentially exp onential growth

in the size of the resulting co de

ADIFOR is a sourcetosource translator it takes as its input a function expressed as

a Fortran subroutine and generates Fortran co de that computes the derivatives of the

n m

dep endentvariables with resp ect to the indep endentvariables Supp ose F IR IR is a

function and

subroutine func xnFm

integer m n

double precision xn Fm

is a Fortran subroutine that will compute the value of F at anygiven xLetJ xF x

b e the Jacobian of F ADIFOR will pro duce co de that computes J xS for any n p matrix

S with p nThus if S I ADIFOR will compute the Jacobian itself

In many optimization mo dels certain terms that o ccur in F will b e linear and will result

in constant elements in J x SnadiOpt do es not require that these elements o ccur in a

particular part of J x but for the sake of discussion let us assume that J x has the

following structure

N L

J x

L L

where the elements of L L andL are constant and the elements of N mayor

may not b e constant but all rows and columns of N contain at least one nonconstant

element Any Jacobian may b e transformed to a matrix with this structure by p ermuting

the constraints rows and variables columns Snopt is designed to exploit the constant

elements in J For instance the constraints corresp onding to L L are linear and

Snopt will maintain feasibility with resp ect to the linear constraints Because the ADIFOR

generated co de computes J xS SnadiOpt is able to cho ose an S in a manner that avoids

the need to reassign L L and L every time J is required

Snopt is designed to solve problems with sparse derivatives These are problems for

which many of the elements of J x are identically zero SnadiOpt determines the sparsity

pattern for the Jacobian and identies the constant elements automaticallyTomakethis

determination SnadiOpt computes the value of J xattwo random p erturbations of a user

supplied initial p oint x If an element of the Jacobian is the same at b oth p oints then

it is taken to b e constant If it is zero at b oth p oints it is taken to b e identically zero

The random p oints are not chosen close together so the heuristic will correctly classify the

Jacobian elements in the vast ma jority of cases Snopt validates the computed derivatives

linearity pattern and sparsity pattern at the p oint x by comparing the supplied values

to values computed using numerical dierentiation This additional test at a third p oint

makes it unlikely that an incorrect sparsity or linearity pattern will b e used

Of course it is p ossible to fo ol this heuristic SnadiOpt cannot deal well with functions

for which the sparsity pattern or linearity pattern in a relatively large region around x is

Users Guide for SnadiOpt

not representative of the sparsity or linearity pattern of the function as a whole Computing

a sparsity pattern for such a function would require signicant additional user intervention

Because we are uncertain of the demand to minimize such functions wehave opted for the

simpler user interface Wewelcome examples of realword optimization mo dels that fall into

this category

Once SnadiOpt has computed the sparsity and linearity pattern and the appropriate S to

minimize recomputation of the derivatives of linear elements it calls Snopt as a blackb ox

optimization routine This means that it presents the optimization data to Snopt in the

same format as a handwritten routine for computing the derivatives Users have full access

to all the options and features of Snopt and can link the resulting co de with their own co de

sub ject of course to any licensing restrictions

UserSupplied Subroutines

In order to use SnadiOpt the user must provide the following Fortran routines

usrfun x Denes the functions F x

usrini x Denes the actual dimension of the problem and initializes all data needed

by Snopt The workspace for SnadiOpt is also assigned here

The user routines usrfun and usrini have xed parameter lists but mayhaveany conve

nient name The names of the parameters may also b e chosen by the user

The Function Denition Routine

The user must provide a subroutine that calculates the vector F of ob jective and constraint

functions at a given p oint x

subroutine usrfun Status mode x n F neF

cu lencu iu leniu ru lenru

integer Status mode neF n

double precision FneF xn

integer lencu leniu lenru

character culencu

integer iuleniu

double precision rulenru

On entry

Status indicates the rst and last call to usrfun

If Status there is nothing sp ecial ab out the currentcalltousrfun

If Status Snopt is calling the subroutine for the rst time Some data may

need to b e input or computed and saved

If Status Snopt is calling the subroutine for the last time The user maywish

to p erform some additional computation using the nal solution

If the nonlinear functions are exp ensivetoevaluate it may b e desirable to do

nothing on the last call by including a statement of the form

if Status ge return at the start of the subroutine

UserSupplied Subroutines

xn contains the p oint at which the problem functions are to b e evaluated

culencu iuleniu rulenru are character integer and real scratcharrays These

arrays maybeusedtostoreany information that needs to b e saved b etween calls

to usrfun

On exit

FneF holds the values of the ob jective and constraint functions computed at x The

ob jectiveiscomponent FObjRow as dened in usrini

mode is used to communicate b etween Snopt and the user If the user is unwilling or

unable to evaluate the function at the current p ointthen mode should b e set to

Snopt will try to provide an alternativepointatwhichtoevaluate the function

If for some reason the user wishes to terminate solution of the current problem

mode should b e set to a negativevalue other than

culencu iuleniu rulenru are character integer and double precision arrays in

which the user may store information b etween calls to usrfun

The Initialization Routine

Subroutine usrini is used to initialize quantities asso ciated with the problem It is called

once b efore Snopt

subroutine usrini ObjAdd ObjRow Prob

x xlow xupp xstate Names

Fmul Flow Fupp Fstate FNames

iSpecs iPrint iSumm iErr

cu iu ru

cw iw rw

Each argument is fully describ ed b elow Many of the arguments are arrays eg x is the

vector containing an initial guess at the solution However we emphasize that the lengths

of the array arguments do not appear in the argument list The user must declare all arrays

to b e of xed length at the head of the subroutine usrini These declarations are used by

the Perl script snadioptpl to automatically construct a main program that calls Snopt

with appropriately dimensioned arrays For example a typical denition of the variables at

the head of usrini is as follows

integer n neF

integer nName nFnames

integer lencw leniw lenrw lencu leniu lenru

parameter lencw leniw lenrw

parameter lencu leniu lenru

parameter n neF

parameter nName nFnames

character NamesnName FNamesnFnames

double precision xn xlown xuppn

double precision FlowneF FuppneF FmulneF

integer xstaten FstateneF

integer iuleniu iwleniw

double precision rulenru rwlenrw

character culencu cwlencw

Users Guide for SnadiOpt

The names of the arguments for usrini are unimp ortant but the position of each argument

is signicant For example if the user prefers to call the vector of variables varsand

declares the fourth argumentofusrini to b e

parameter maxvars

double precision varsmaxvars

then snadioptpl will parse this declaration and include

parameter n

double precision xn

in the automatically generated calling routine SnadiOpt can recognize Fortran style param

eters and numb ers but cannot read more complicated expressions For instance declaring

Fmul as double precision Fmuln will denitely confuse it

Below we describ e each of the arguments of usriniInmany cases these arguments

are assigned a default value in the automatically generated calling program If the user

wishes to use the default value of an argument then it should not b e altered in usrini

The symbol denotes the value of the Snopt optional parameter Infinite bound which

has default value

Parameters

ObjAdd is a double precision constant that is added to the ob jective function for printing

purp oses ObjAdd do es not aect the minimizer found

Default value ObjAdd

ObjRow is an integer dening the comp onentofF x to b e used as the ob jective function

F x If ObjRow thenSnopt nds a p oint x that satises the constraints

obj

l x u and L F x U

Default value ObjRow

Prob is an eightcharacter name for this mo del

Default value The name of the executable truncated to eightcharacters

x is a double precision arraycontaining the p oint at which Snopt will start searching

for a minimizer

Default value xj

xlow xupp are double precision arrays containing the lower and upp er b ounds l and u

suchthatl x u By default xlow and xupp are assumed to b e innite ie

the value of x is not restricted

Default values xlowj xuppj

xstate denes the initial state for eachvariable x One mayset xstatej xj

for all j n All variables will b e eligible for the initial basis

Less triviallytosay that the optimal value of variable j will probably b e equal to

one of its b ounds set xstatej andxj xlowj orxstatej and

xj xuppj as appropriate

Default value xstatej

Names is a character arrayofsymb olic names for the comp onents of x Each name may

haveuptoeightcharacters If the user do es not wish to supply symb olic names for

the variables Names should b e declared to b e b e an array of length one

UserSupplied Subroutines

Fmul is a double precision array of estimates of the dual variables for the constraints

L F x U Dual variables are sometimes known as Lagrange multipliers or

shadow prices FmulObjRow corresp onds to the ob jective and is ignored

Default value Fmulj

Flow Fupp are double precision arrays containing the lower and upp er b ounds L and U

suchthatL F x U The comp onents FlowObjRow and FuppObjRow

corresp onding to the ob jective is ignored For an equality constraint of the form

F x cset Flowj Fuppj c

Default values Flowj and Fuppj

FNames isacharacter arrayofsymb olic names for the constraints Eachnamemay consist of

up to eightcharacters If the user do es not wish to supply names for the constraints

FNames should b e declared to b e an array of length one

iSpecs is an op en readable Fortran le descriptor p ointing to an options or sp ecs le

See the Snopt users guide to discover which options are available If one cho oses

not to use an options le iSpecs should b e set to zero

Default value iSpecs

iPrint is a Fortran le descriptor p ointing to a le that will b e overwritten with the results

of this run of Snopt If one do es not wish to save the output to a le iPrint should

b e set to zero

Default value iPrint

iSumm a Fortran le descriptor p ointing to a le that will b e overwritten with summary

information from this run of SnoptTypically iSumm is either set to which will

cause the summary output to b e printed on the terminal or set to which disables

the printing of summary information

Default value iSumm

iErr a Fortran le descriptor p ointing to a le that will b e overwritten with diagnostic

information from this run of Snopt Set iErr to zero to disable printing of diagnostic

information

Default value iErr

cu iu ru are character integer and double precision arrays in which the user maystore

information b etween calls to usrfun

cw iw rw are character integer and double precision workspace arrays used by Snopt

These arrays must b e declared suciently large for Snopt to solve the optimization

problem

An Example Problem

Here we give examples of subroutines usrini and usrfun for the following four variable

problem

minimize x x x x x

sub ject to x x

x x x

x x

Users Guide for SnadiOpt

In the format of problem NP wehave L F x U where

x x x x x

C C B C B B

x x

C C B C B B

U F L

C C B C B B

A A A

x x x

The ob jective function has b een assigned to the rst comp onentofF which means that

ObjRow The ob jective comp onent is not constrained by Snopt so there are innite

upp er and lower b ounds on F Acomponent with innite upp er and lower b ounds is

obj

known as a free row of the problem Snopt automatically provides these innite b ounds

on the ob jectiverow and so it is unnecessary to provide them unless later the user plans

to set ObjRow to make Snopt nd a feasible p oint for the constraints

The upp er and lower b ounds on the variables are given by l x u where

C C B C B B

u x l

C C B C B B

A A A

Our version of subroutine usrini p erforms four tasks i it denes the length of the variable

dimensioned arrays used by Snopt and SnadiOpt ii it op ens the print le and summary

le iii it initializes the arrayofvariables and iv it denes the upp er and lower b ounds

on x and F

subroutine usrini ObjAdd ObjRow Prob

x xlow xupp xstate Names

Fmul Flow Fupp Fstate FNames

iSpecs iPrint iSumm iErr

cu iu ru cw iw rw

implicit none

integer n neF nName nFnames ObjRow

lencw leniw lenrw lencu leniu lenru

parameter lencw leniw lenrw

parameter lencu leniu lenru

parameter n neF

parameter nName nFnames

integer iSpecs iPrint iSumm iErr xstaten

FstateneF iuleniu iwleniw

double precision ObjAdd xn xlown xuppn FlowneF

FuppneF FmulneF rulenru rwlenrw

character Prob NamesnName FNamesnFnames

culencu cwlencw

usrini defines input data for the problem discussed in the

SnadiOpt Users Guide

integer i

character lfile

double precision plInfy

parameter plInfy d

Initial x

UserSupplied Subroutines

x d

xlow d

Impose bounds on the constraint rows

Flow d

Flow d Equality constraint

Fupp d

Flow d Equality constraint

Fupp d

iSpecs

iPrint

lfile probspc

open iSpecs filelfile statusOLD err

lfile probout

open iPrint filelfile statusUNKNOWN err

return

writeiErr Error while opening file lfile

format a x a

end subroutine usrini

Note that default initial values are used for the variables Prob Fmul xstate Fstateand

ObjAdd Similarly only those b ounds not equal to their default innite values are assigned

The subroutine usrfun denes the values of the vector F x

subroutine usrfun Status mode

neF n x F

cu lencu iu leniu ru lenru

cw lencw iw leniw rw lenrw

implicit none

integer Status mode neF n lencu leniu lenru

lencw leniw lenrw iuleniu iwleniw

double precision FneF xn rulenru rwlenrw

character culencu cwlencw

Usrfun computes the objective and constraint functions for the

problem featured in the SnadiOpt users guide

integer Obj

Obj The objective row

FObj dx x x x dx

Users Guide for SnadiOpt

Constraint functions

F dx dx

F x x x

end subroutine usrfun

Invoking SnadiOpt

The usersupplied routines must b e run through ADIFOR and then compiled and linked into

a complete program b efore Snopt maybeinvoked There are two steps in the pro cess of

building this complete program First the user invokes the script snadioptpl to scan the

usersupplied routines and pro duce the comp onents that are needed to build a complete

executable notably the main program itself Second the user invokes a version of the

program make to p erform the build

Users will typically call snadioptpl only once Most changes made to a mo del can b e

incorp orated into the executable by simply typing make By design snadioptpl generates

a relatively straightforward set of comp onents that may b e mo died at will In some cases

particularly if the sizes of the arrays dened in usrini change it maybeconvenient to call

snadioptpl again rather than mo difying multiple les Wehave incorp orated a feature

into snadioptpl to simplify this pro cess See Section for more information

Lo cating Executables and Libraries

Before one can use SnadiOpt the package must of course b e installed on the users machine

Installation instructions are provided with the SnadiOpt distribution Because the installa

tion pro cess dep ends on the machine typ e and the source of the distribution installation

instructions will not b e rep eated here A few words however are in order

The SnadiOpt package consists of a program named snadioptpl some data les needed

by snadioptpl and co de libraries that must b e combined linked with usersupplied co de

to pro duce a problem executable Ideally these comp onents will b e installed in an appropri

ate systemdep endent lo cation On Unix systems for instance the default lo cation is the

usrlocal directory structure If the SnadiOpt package is lo cated in some appropriate

system lo cation then typing

snadioptpl help

will provide summary help information ab out using the snadioptpl program If this

is the case then the rest of this section may b e skipp ed If the system cannot nd the

snadioptpl program then the user will need to tell the system where to nd it The

following instructions are for versions of the Unix op erating system

First one should ask the individual who installed SnadiOpt where the snadioptpl

program is lo cated If it is not in a systemdep endent lo cation it will normally b e found in

the bin sub directory of the Snopt distribution The cd command may b e used to change

the working directory to the directory containing snadioptpl The command used to set

the PATH environmentvariable dep ends on which shell is b eing used For bash or kshthe

appropriate command is

PATHPATHPWD

but for csh or tcsh the command setenv PATH PATHPWD

Invoking SnadiOpt

must b e used Virtually all users will b e using a shell that resp onds to one of these two

commands It is safe to try these commands if one is unsure which shell is b eing used

Once the PATH environmentvariable has b een set the system will b e able to nd

snadioptpl One can then generate and compile problem executables The executa

bles may not however run While this would seem to b e undesirable b ehavior there is

actually a reason for it Mo dern op erating systems supp ort the concept of dynamically

linked libraries Such libraries are not copied into an executable but rather are loaded into

memory when a program is run With suchascheme several executables may share one

library SnadiOpt uses dynamically linked libraries whenever p ossible

Because dynamically linked libraries must b e loaded at runtime the op erating system

must know where to lo cate these libraries The simplest scheme is to place the libraries in

a systemdep endent lo cation If one had to set the PATH environmentvariable to tell the

system where to nd the snadioptpl program then it is likely that one will need to tell

the system where to nd the SnadiOpt libraries as well To do so one should rst change

the working directory to the directory containing the SnadiOpt libraries These libraries will

usually b e lo cated in the lib sub directory of the Snopt distribution and will havenames

similar to libsnddioptso and libsnsdioptso If the user is using bash or kshthe

command

LDLIBRARYPATHLDLIBRARYPATHPWD

export LDLIBRARYPATH

should b e executed Those using csh or tcshmust determine whether LD LIBRARY PATH

has already b een set If the command

printenv LDLIBRARYPATH

prints nothing then the variable has not b een set and

setenv LDLIBRARYPATH PWD

will set it appropriately Otherwise typing

setenv LDLIBRARYPATH LDLIBRARYPATHPWD

will add the current directory to the existing LD LIBRARY PATH

Let us make a few nal notes ab out this pro cess These days it is common for a user

to havemultiple command windows op en It is a frequent mistake to think that setting

the PATH variable or anyvariable in one window sets its value in all windows Setting

avariable in one command window do es not aect the other command windows in any

way It is usually p ossible to alter certain initialization les to set the values of PATH and

LIBRARY PATH in every command window automatically at login It is not p ossible for LD

us to describ e this pro cess b ecause it is very system dep endent One should ask a system

administrator how to do this

Basic Usage

Supp ose a user has placed all the co de needed to dene a certain problem including the

required subroutines usrfun and usrini in a le named probf The command

snadioptpl o prob probf

will generate the les that are needed to build an executable named prob that solves the

users optimization mo del

To actually build the executable invokethe GNU version of the program make On many

systems GNU make is installed as make or gmake and so typing

Users Guide for SnadiOpt

make

gmake

should build a program named prob that may b e executed from the command line

Files Generated by snadioptpl

In this section we briey describ e the les generated by snadioptpl itself Other temp o

rary les may b e generated by the compiler and ADIFOR A b eginning user should not need

to know ab out the generated les in order to use this package Therefore this section may

b e skipp ed on a rst reading

This section lists the les generated for a problem named prob The script snadioptpl

uses prob as the prex for most of the les generated for this problem If the user had

invoked the command

snadioptpl o prob probf

then prob will b e the prex of the generated les In general the o option determines

the prex of the generated les If the option is omitted then unnamed will b e the prex

used

GNUmakefile This is the only generated le that is not prexed by the name of the

problem The GNUmakefile is meant to b e shared by all problems in a given directory it

contains general information ab out building and managing problem executables

Users maywishtomodifyGNUmakefile to customize the build pro cess For instance

GNUmakefile might b e mo died to tell the compiler to generate ob ject co de suitable for use

with a debugger The snadioptpl program will not overwrite an existing GNUmakefile

unless it is called with the refreshmakefile option Therefore it is safe to mo dify this

prob submake prob submakeorig prob submakebak The le prob submake contains

the commands for building the program including the commands for calling ADIFOR The

le should contain the complete dep endency information for the program and should b e

capable of rebuilding the program when comp onents are mo died

It is sometimes necessary to mo dify prob submake The le prob submakeorig contains

the original version of this le as generated by snadioptpl This allows the user to

compare the mo died version of prob submake with the original le

If snadioptpl detects an existing le named prob submake it will save this le as

prob submakebak The user may then reapply anychanges made to prob submake to

the newly generated le Many times these changes can b e merged automaticallySee

Section for more information

mainf prob mainforig prob mainfbak The le prob mainf contains the prob

Fortran main program that calls Snopt with the users data and problem denition func

tions It also p erforms some necessary b o okkeeping and initialization and is resp onsible for

allo cating the arrays that the user requests in the usrini subroutine

Users may wish to mo dify prob mainfFor instance a user might wish to output the

results from Snopt in a particular format and so might place the commands for doing so in

mainf The le prob mainforig contains the version of prob mainf generated prob

Invoking SnadiOpt

by the last call to snadioptpl This allows the user to compare the mo died prob mainf

with the original le

If snadioptpl detects an existing le named prob mainf it will savethatleas

prob mainfbak b efore pro ceeding All changes that the user had made to the existing

prob mainf are saved in that backup le and the user may reapply these changes to

the newly generated le Many times these changes can b e merged automaticallySee

Section for more information

probadf The le probadf contains the ADIFOR script for dierentiating the mo dels

functions See the ADIFOR users guide for more information It is unlikely that a user will

need to mo dify this le

prob admainf ADIFOR requires a complete compilable program in order to dierentiate

a function called from that program The le prob admainf contains a phony program

that calls usrfunWeknow of no reason for users to mo dify this le

prob sparse dispatchf prob dense dispatchf These les call library routines sup

p orting the use of ADIFOR with Snopt The existence of these les is an artifact of the

Fortran language not having syntax for storing a reference to a subroutine Weknowofno

reason for users to mo dify these les

probcmp The le usercmp is not generated by snadioptpl but rather is created as

an intermediate le in the build pro cess It contains a list of Fortran les that are to b e

senttoADIFOR One should not not mo dify this le one should mo dify the AD SOURCE and

AD OTHER FILES variables in the le prob submake

Merging Changes

Users need to call snadioptpl only once The comp onents that it creates may then b e

mo died at will and the executable rebuilt using makeHowever on some o ccasions it may

b e useful to call snadioptpl again particularly when

the sizes of the arrays in usrini havechanged The array sizes in prob mainf and

p ossibly probadf must also b e mo died The program snadioptpl will up date

these quantities automatically

the names of the parameters of usrfun havechanged The user must either call

snadioptpl again or edit probadf to up date the names of the indep endentvariables

IVARS and the names of the dep endentvariables AD DVARS AD

the names of Fortran source les are mo died or new source les are added Users

will need to up date prob submake or call snadioptpl again

It is not uncommon however for users to wanttomodifyprob submake to customize

the build pro cess or mo dify prob mainf to p erform some action on the results of snopt

Normallywhen snadioptpl is called it overwrites these les saving copies of the existing

les as prob mainfbak and prob submakebak Users may then reapply the changes they

had made to the old prob mainf and prob submake to the newly generated les

There are however Unix utilities that are able to merge changes b etween versions au

tomaticallyThesnadioptpl merge option provides an interface to these to ols Simply

call snadioptpl with the arguments snadioptpl merge o prob probf

Users Guide for SnadiOpt

The merge is based only on the comparison of blo cks of text It do es not pretend to

understand the meaning of the co de However it is eective remarkably often In case the

merge is ineective the les that snadioptpl would have pro duced without the merge

option may b e found in prob submakeorig and prob mainforig

Rarely there will b e conicts that make it imp ossible to complete the merge In these

cases lines of the form

probsubmakebak

lines from probsubmakebak

lines from probsubmakeorig

probsubmakeorig

will b e inserted in the les and these sections must b e edited by hand

The merge option uses the standard Unix utilities diff and ed Merging is not sup

p orted on platforms on which these programs are not available We dont supp ort automatic

merging of the other generated les Merging requires that the les prob mainforig and

prob submakeorig generated by the last call to snadioptpl b e present in the current