% $Id: commandl.tex 207 2011-12-18 18:11:16Z jsibert $
%
% Author: David Fournier
% Copyright (c) 2008 Regents of the University of California
%

\ADM\ has a number of options that can be invoked at the command line.
A list of current options can be displayed by typing the name of the application followed by \texttt{-?}. 

\medskip

You will see a display like:
\XX{command line arguments}{\fontindexentry{tt}{-ind NAME}}
\XX{command line arguments}{only estimate parameters}
\begin{code}
 AD Model Builder Copyright (c) 2008 Regents of the University of California
 USAGE--kalman options
 where an option consists of -option_tag followed by arguments if necessary
 -ainp NAME      change default ascii input parameter file name to NAME
 -binp NAME      change default binary input parameter file name to NAME
 -est            only do the parameter estimation
 -ind NAME       change default input data file name to NAME
 -lmn N          use limited memory quasi newton -- keep N steps
 -lprof          perform profile likelihood calculations
 -prsave         save the independent variables from the profile calculations
 -maxph N        increase the maximum phase number to N
 -mcdiag         use diagonal covariance matrix for mcmc with diagonal values 1
 -mcmc [N]       perform markov chain monte carlo with N simulations
 -mcmult N       multiplier N for mcmc default
 -mcr            resume previous mcmc
 -mcrb N         modify the covariance matrix to reduce extremely high correlation      
 -mcnoscale      don't rescale step size for mcmc depending on acceptance rate
 -mcgrope N      use probing strategy for mcmc with factor N
 -mcseed N       seed for random number generator for markov chain monte carlo
 -mccale N       rescale step size for first N evaluations
 -mcsave N       save the parameters for every N'th simulation
 -mceval         Go through the saved mcmc values from a previous mcsave
 -mcpin NAME      Read the starting values for MCMC from the file NAME
 -crit N         set gradient magnitude convergence criterion to N
 -iprint N       print out function minimizer report every N iterations
 -maxfn N        set maximum number of function eval's to N
 -rs             if function minimizer can't make progress rescale and try again
 -nox            don't show vector and gradient values in function minimizer screen
                 report
 -phase N        start minimization in phase N
 -simplex        use simplex algorithm for minimization (new test version)
 -sdonly         do delta method for std dev estimates without redoing hessian
 -ams N          set arrmblsize to n (ARRAY_MEMBLOCK_SIZE) 
 -cbs N          set CMPDIF_BUFFER_SIZE TO N 
 -mno N          set the maximum number of independent variables to N
 -gbs N          set GRADSTACK_BUFFER_SIZE TO N 
 -mdl N          set the maximum number of dvariables to N
 -? or -help     this message
\end{code}
The version of \ADM\ is printed. This can be useful to determine
the version with which the application was compiled.

\XX{command line arguments}{setting the maximum number of dvariables@\texttt{dvariables}}
\XX{command line arguments}{\fontindexentry{tt}{-mno N}}
\XX{command line arguments}{\fontindexentry{tt}{-mdl N}}
\XX{command line arguments}{\fontindexentry{tt}{-ind NAME}}
\XX{command line arguments}{changing the input data file name}
\begin{lstlisting}
-aind NAME 
\end{lstlisting}
\afterlistingthing{By default, the program named \texttt{xxxx(.exe)} tries to read in its data
from the file \texttt{xxxx.dat}. This option changes the data file to \texttt{NAME}.}

\XX{command line arguments}{\fontindexentry{tt}{-ainp NAME}}
\XX{command line arguments}{changing the input data file name}
\begin{lstlisting}
-ainp NAME 
\end{lstlisting}
\afterlistingthing{This option changes to NAME the file from which the initial parameter estimates
are read. The program expects the parameters to
be in \textsc{ascii} format, with comment lines beginning with \texttt{\#}.}

When a program is running, it produces parameter estimates in \textsc{ascii}
format, in files named \texttt{xxxx.p01},$\ldots$, \texttt{xxxx.par}.
These files are in the proper format to be input back into the model
and permit restarts at any phase of the minimization.

\XX{command line arguments}{\fontindexentry{tt}{-binp NAME}}
\XX{command line arguments}{changing the input data file name}
\begin{lstlisting}
-binp NAME 
\end{lstlisting}
\afterlistingthing{This option changes to NAME the file from which the initial parameter estimates
are read. The program expects the parameters to
be in  binary format.}

When a program is running, it produces parameter estimates in binary
format in files named \texttt{xxxx.b01},$\ldots$, \texttt{xxxx.bar}.
These files are in the proper format to be input back into the model
and permit restarts at any phase of the minimization.

Both \textsc{ascii} and binary forms of the parameter files are supplied, because
they have different advantages and disadvantages. \textsc{ascii} files can be
easily examined and edited. Binary files supply parameter values 
to the limit of machine precision in a compact format.

\XX{command line arguments}{\fontindexentry{tt}{-lmn}}
\XX{command line arguments}{limited memory Newton}
\begin{lstlisting}
-lmn N
\end{lstlisting}
\afterlistingthing{The limited memory Newton minimization option reduces the amount
of memory necessary for holding the approximate Hessian inverse.
It is of use particularly in problems with a large number of
parameters (typically, $> 1000$). For many problems, it is not as efficient
per function evaluation as is the default quasi-Newton method, although
this is not always the case. \texttt{N} is the number of pass steps of information
kept for the quasi-Newton update. Typically, a value in the range~5--20
is good.}

\XX{command line arguments}{\fontindexentry{tt}{-likeprof}}
\XX{command line arguments}{likelihood profiles}
\begin{lstlisting}
-lprof     
\end{lstlisting} 
\afterlistingthing{This option turns on the profile likelihood calculations. 
A variable for which profile likelihood calculations are performed
must have been declared with the \texttt{likeprof\_number} in the
\textsc{tpl} file.}

\XX{command line arguments}{\fontindexentry{tt}{-prsave}}
\begin{lstlisting}
-prsave     
\end{lstlisting} 
\afterlistingthing{This option causes the values of the independent variables 
for the profile likelihood points to be saved in a file named
\texttt{xxx.pvl}, where \texttt{xxx} is the name of the variable
being profiled. These values can be used later for starting
the \textsc{mcmc} analysis at different values, which is useful for
testing the mixing of the chain with respect to that parameter.}

\XX{command line arguments}{\fontindexentry{tt}{-maxph N}}
\XX{command line arguments}{set maximum phase of minimization}
\begin{lstlisting}
-maxph N     
\end{lstlisting} 
\afterlistingthing{You may want to add extra phases to the minimization---usually
because the standard set of phases has not converged. This will
set the number of phases to~\texttt{N}.}

\XX{command line arguments}{\fontindexentry{tt}{-mcmc}}
\XX{command line arguments}{Markov Chain Monte Carlo}
\begin{lstlisting}
-mcmc [N]    
\end{lstlisting} 
\afterlistingthing{This option turns on the the calculation of the Markov chain Monte Carlo
routine. By default, the model will recalculate the approximate Hessian,
so you may want to use the \texttt{-nohess} option if you don't wish
to recalculate the Hessian. It is your responsibility to ensure that
the Hessian data in the current directory are current.
The \texttt{mcmc} routine will perform \texttt{N} simulations.}

\XX{command line arguments}{\fontindexentry{tt}{-mcr}}
\XX{command line arguments}{restart Markov Chain Monte Carlo}
\begin{lstlisting}
-mcr    
\end{lstlisting} 
\afterlistingthing{Restart (and continue) a previous Markov chain Monte Carlo
routine. This will continue from where the previous routine
left off.}

\XX{command line arguments}{\fontindexentry{tt}{-mcrb}}
\begin{lstlisting}
-mcrb N  
\end{lstlisting}
\afterlistingthing{See discussion of this option elsewhere in the manual.} %xx 

\XX{command line arguments}{\fontindexentry{tt}{-mcsave}}
\XX{command line arguments}{save results from Markov Chain Monte Carlo}
\begin{lstlisting}
-mcsave N  
\end{lstlisting}
\afterlistingthing{For the usual \textsc{mcmc} routine, the results from consecutive
steps of the simulation are highly correlated. If the
parameters of interest are expensive to compute, it may be advantageous to
only compute every \texttt{N}$^\textrm{th}$ one. This option saves the results so that they
can be used in subsequent calculations.}

\XX{command line arguments}{\fontindexentry{tt}{-mceval}}
\XX{command line arguments}{use the saved results from Markov Chain Monte Carlo}
\X{\fontindexentry{tt}{mceval\_phase()}}
%xx should this be mceval?
\begin{lstlisting}
-mceval N
\end{lstlisting}
\afterlistingthing{This option will use the previously saved results from \texttt{mcmc} to evaluate
parameters of interest. The function \texttt{mceval\_phase()} can
be useful here to only calculate the parameters during this phase.}

\XX{command line arguments}{\fontindexentry{tt}{-nox}}
\XX{command line arguments}{suppressing printing}
\begin{lstlisting}
-nox  
\end{lstlisting}
\afterlistingthing{This option suppresses the printing of the current \texttt{x} vector
being sampled by the function minimizer.
Printing this out can be a significant overhead for models with
a large number of parameters.  Also, it simply irritates some users.}

\XX{command line arguments}{\fontindexentry{tt}{-ams N}}
\X{\fontindexentry{tt}{arrmblsize}}
\begin{lstlisting}
-ams N          set arrmblsize to n (ARRAY_MEMBLOCK_SIZE) 
\end{lstlisting}
\afterlistingthing{This option has the same effect as setting \texttt{arrmblsize} in the
program code, but has the advantage that it can be done at runtime.}

\XX{\fontindexentry{tt}{gradient\_structure::}}{\fontindexentry{tt}{set\_CMPDIF\_BUFFER\_SIZE}} 
\XX{command line arguments}{\fontindexentry{tt}{-cbs N}}
\begin{lstlisting}
-cbs N          set CMPDIF_BUFFER_SIZE to n 
\end{lstlisting}
\afterlistingthing{This option has the same effect as the
  \texttt{gradient\_structure::set\_CMPDIF\_BUFFER\_SIZE} function
in the program code, but has the advantage that it can be done at runtime.}

\XX{\fontindexentry{tt}{gradient\_structure::}}{\fontindexentry{tt}{set\_GRADSTACK\_BUFFER\_SIZE}}
\XX{command line arguments}{\fontindexentry{tt}{-gbs N}}
\begin{lstlisting}
-gbs N          set GRADSTACK_BUFFER_SIZE 
\end{lstlisting}
\afterlistingthing{This option has the same effect as the
\texttt{gradient\_structure::set\_GRADSTACK\_BUFFER\_SIZE } function
in the
program code, but has the advantage that it can be done at runtime. 
{\it Also note that the size is in bytes here, whereas for the included code, it is in chunks of about 36 bytes.}}

