12runningSS3.tex

\section[Running Stock Synthesis]{\protect\hyperref[sec:RunningSS3]{Running Stock Synthesis}} \label{sec:RunningSS3}

\hypertarget{CommandLine}{}
\subsection[Command Line Interface]{\protect\hyperlink{CommandLine}{Command Line Interface}}
The name of the SS3 executable files often contains the phrase ``safe'' or ``opt'' (for optimized). The safe version includes checking for out of bounds values and should always be used whenever there is a change to the data file. The optimized version runs slightly faster but can result in data not being included in the model as intended if the safe version has not been run first. A file named \texttt{ss3.exe} is typically the safe version unless the result of renaming by the user.

On Mac and Linux computers, the executable does not include an extension (like \texttt{.exe} on Windows).
Running the executable on from the DOS command line in Windows simply require typing the executable name (without the \texttt{.exe} extension):
\begin{quote}
	\begin{verbatim}
	> ss3
	\end{verbatim}
\end{quote}


On Mac and Linux computers, the executable name must be preceded by a period and slash (unless its location has been added to the user's PATH). Note that the user may need to change permissions for Stock Synthesis to be executable before running SS3 for the first time:

\begin{quote}
	\begin{verbatim}
	> chmod a+x ss3
	> ./ss3
	\end{verbatim}
\end{quote}

An additional command has been added that allows users to specify the name of the \texttt{.par} file that is both read and output. Prior to v.3.30.22.1, the default exe name was `ss' and the default \texttt{.par} file name was \texttt{ss.par}. The code now produces a \texttt{ss3.par} file by default instead of a \texttt{ss.par} file. The code will search for the default \texttt{ss3.par} file first, and then look for a \texttt{ss.par} file in order to have backwards compatibility and will by default output a \texttt{ss3.par} file (not a \texttt{ss.par} file). If you would like to read a differently named \texttt{.par} file and produce a \texttt{.par} file with the same name, you will need to add the \texttt{modelname} command. See the below example of using \texttt{modelname} to read and produce a \texttt{.par} file with the name \texttt{ss4you}.

\begin{quote}
	\begin{verbatim}
	> ./ss3 modelname ss4you
	\end{verbatim}
\end{quote}

Additional \gls{admb} commands can follow the executable name, such as \texttt{-nohess} to avoid calculating the Hessian matrix. To see a full list of options, add \texttt{-?} after the executable name (with a space in between).

On all operating systems, a copy of the SS3 executable can either be located in the same directory as the model input files or in a central location and referenced either by adding it to the PATH or by a script files. Further discussion on script files for Windows is below.

Often there is a need to run the model with no estimation. Alternative methods to run SS3 without estimating parameters are documented in the \hyperlink{NoEst}{Running Without Estimation section}. 

As of \gls{admb} 12.3, a new command called \texttt{-hess\_step} is available to use and documented in the \hyperlink{hess-step}{Using \texttt{-hess\_step} to do additional Newton steps using the inverse Hessian}

\hypertarget{DOS}{}
\subsubsection[Example of DOS batch input file]{\protect\hyperlink{DOS}{Example of DOS batch input file}}
One file management approach is to put \texttt{ss3.exe} in its own folder (example:  C:\textbackslash SS3\_model) and to put your input files in separate folder (example:  C:\textbackslash My Documents \textbackslash SS3\_runs). Then a DOS batch file in the SS3\_runs folder can be run at the command line to start \texttt{ss3.exe}. All output will appear in SS3\_runs folder.

A DOS batch file (e.g., \texttt{SS3.bat}) might contain some explicit \gls{admb} commands, some implicit commands, and some DOS commands:

\begin{quote}
	\begin{verbatim}
	c:\SS3_model\ss3.exe -cbs 5000000000 -gbs 50000000000 \%1 \%2 \%3 \%4 
	del ss.r0*
	del ss.p0*
	del ss.b0*
	\end{verbatim}
\end{quote}


In this batch file, the \texttt{-cbs} and \texttt{-gbs} arguments allocate a large amount of memory for SS3 to use (you may need to edit these for your computer and SS3 configuration), and the \%1, \%2 etc., allows passing of command line arguments such as \texttt{-nox} or \texttt{-nohess}. You add more items to the list of \% arguments as needed.

An easy way to start a command line in your current directory (SS3\_runs) is to create a shortcut to the DOS command line prompt. The shortcut's target would be:

\begin{quote}
	\begin{verbatim}
	> %SystemRoot%\system32\cmd.exe
	\end{verbatim}
\end{quote}


\noindent And it would start in:
\begin{quote}
	\begin{verbatim}
	> %CURRDIR%
	\end{verbatim}
\end{quote}

An alternative shortcut is to have the executable within the model folder then use Ctrl+Shift+Right Click and then select either ``Open command window here'', depending upon your computer. From the command window the executable name can be typed along with additional inputs (e.g., \texttt{-nohess}) and the model run. If using the Powershell type cmd and then hit enter prior to calling the model (ss3). 

\hypertarget{SimpleBatch}{}
\subsubsection[Simple Batch]{\protect\hyperlink{SimpleBatch}{Simple Batch}}

This first example relies upon having a set of prototype SS3 input files, where a starter file named \texttt{starter.r01} can be renamed to \texttt{starter.ss} and then used in the SS3 run. The example also copies one of the output files, \texttt{ss.std}, to a new name, \texttt{ss-std01.txt}, to save it from being overwritten in subsequent runs. The example code should be put in a batch file, which can have any name with the \texttt{.bat} extension. Note that brief output from each run will be appended to \texttt{cumreport.sso} (see below).

\begin{quote}
	\begin{verbatim}
	del ss.cor
	del ss.std
	copy starter.r01 starter.ss
	c:\admodel\ss3\ss3.exe -sdonly
	copy ss.std ss-std01.txt
	\end{verbatim}
\end{quote}

The commands could be repeated, except the output should be copied to a different file, e.g., \texttt{ss-std02.txt}. This sequence can be repeated an unlimited number of times.

\hypertarget{ComplexBatch}{}
\subsubsection[Complicated Batch]{\protect\hyperlink{ComplexBatch}{Complicated Batch}}
This second example processes 25 data files from a different directory, each time using the same control file. The loop index is used in the file names, and the output is searched for particular keywords to accumulate a few key results into the file \texttt{SUMMARY.TXT}. Comparable batch processing can be accomplished by using R or other script processing programs.

\begin{quote}
	\begin{verbatim}
	del summary.txt
	del ss-report.txt
	copy /Y runnumber.zero runnumber.ss
	FOR /L \%\%i IN (1,1,25) DO (
	copy /Y ..\MakeData\A1-D1-%%i.dat  Asel.dat
	del ss.std
	del ss.cor
	del ss3.par
	c:\admodel\ss3\ss3.exe
	copy /Y ss3.par A1-D1-A1-%%i.par
	copy /Y ss.std A1-D1-A1-%%i.std
	find ``Number'' A1-D1-A1-%%i.par >> Summary.txt
	find ``hessian'' ss.cor >> Summary.txt)
	\end{verbatim}
\end{quote}


\hypertarget{NoEst}{}
\subsubsection[Running Without Estimation]{\protect\hyperlink{NoEst}{Running Without Estimation}}
There may be time when users will want to run the model without parameter estimation. The \gls{admb} command \texttt{-noest} will not work with Stock Synthesis, as it bypasses the procedure section. There are two suggested alternative approaches to do this with SS3 and \gls{admb}.  

The first approach requires the user to change the maximum phase value in the \texttt{starter.ss} file to 0 then running the model via the command widow as without calculating the hessian:

\begin{quote}
	\begin{verbatim}
	ss3 -nohess
	\end{verbatim}
\end{quote}

The second approach is done all through the command window using the following commands:

\begin{quote}
	\begin{verbatim}
	ss3 -maxfn 0 -phase 50 -nohess
	\end{verbatim}
\end{quote}

where \texttt{-maxfn} specifies the number of function calls and phase is the maximum phase for the model to start estimation where the number should be greater than the maximum phase for estimating parameters within the model. 

However, the approaches above differ in subtle ways. First, if the maximum phase is set to 0 in the starter file the total likelihood will differ by a small amount (0.25 likelihood units) compared to the second approach which sets the \texttt{-maxfn} and \texttt{-phase} in the command window. This small difference is due a dummy parameter which is evaluated by the objective function when maximum phase in the starter is set to 0, resulting in a small contribution to the total likelihood of 0.25. However, all other likelihood components should not change.  

The second difference between the two no estimation approaches is the reported number of ``Active\_count'' of parameters in the Report file. If the command line approach is used (\texttt{ss3 -maxfn 0 -phase 50 -nohess}) then the active number of parameters will equal the number of parameters with positive phases, but because the model is started in a phase greater than the maximum phase in the model, these parameters do not move from the initial values in the control file (or the par file). The first approach where the maximum phase is changed in the starter file will report the number of ``Active\_count'' parameters as 0.  

The final thing to consider when running a model without estimation is whether you are starting from the par file or the control file. If you start from the par file (specified in the starter file: 1=use ss3.par) then all parameters, including parameter deviations, will be fixed at the estimated values. However, if the model is not run with the par file, any parameter deviations (e.g., recruitment deviations) will not be included in the model run (a user could paste in the estimated recruitment deviations into the control file). 

\myparagraph{Generate \texttt{.ss\_new} files}
There may be instances that a user would like to generate the \texttt{.ss\_new} files without running the model, with or without estimation. There are two approaches that a user can take. The first is to manually change the maxphase in the \texttt{starter.ss} file to -1 and running the model as normal will generate these files without running through the model dynamics (e.g., no Report file will be created). The maxphase in the \texttt{starter.ss\_new} file will be set to -1 and will need to be manually changed back if the intent is to replace the original (i.e., \texttt{starter.ss}) file with the new files (i.e., \texttt{starter.ss\_new}). The second approach is to modify the maxphase via the command line input. Calling the model using the commands:

\begin{quote}
	\begin{verbatim}
	ss3 -stopph -1
	\end{verbatim}
\end{quote}  

where -1 is the maximum phase for the model to run through (e.g., can be other values if a user would like to only run through a specific parameter phase). This approach will create all the new files with the \texttt{starter.ss\_new} reflecting the original maxphase value in the \texttt{starter.ss} file. This approach is available in v.3.30.16 and later.

\hypertarget{hess-step}{}
\subsubsection[Using \texttt{-hess\_step} to do additional Newton steps using the inverse Hessian]{\protect\hyperlink{hess-step}{Using \texttt{-hess\_step} to do additional Newton steps using the inverse Hessian}}

The optimizer in \gls{admb} is designed to run until the maximum absolute gradient (mag) is small enough (e.g., 1e-05), after which it quits and does the uncertainty calculations. But if run for longer it cannot appreciably decrease this mag. In many cases it is interesting or advisable to get closer to the mode to confirm convergence of the model. 

A new feature as of \gls{admb} 12.3 called ``-hess\_step'' takes Newton steps to update the \gls{mle} using the information in the Hessian calculated as MLE\textsubscript{new} = MLE-(inverse~Hessian)*(gradient), where the Hessian and gradient are calculated from the original \gls{mle}. If the mag improves then this corroborates the optimizer has converged and that the negative log likelihood surface is approximately quadratic at the mode as assumed in the asymptotic uncertainty calculations. The downside is the high computational cost due to the extra matrix calculations.

The feature is used by optimizing normally, and then from the command line running \texttt{-hess\_step} for defaults (recommended), \texttt{-hess\_step N}, or \texttt{-hess\_step\_tol eps} where N and eps are the maximum number of steps to take and the tolerance (i.e., a very small number like 1e-10) after which to stop. When running the Hessian first and then the \texttt{-hess\_step}, \gls{admb} will prompt you to run it with -binp \texttt{ss.bar}.

\hypertarget{ParamProfiles}{}
\subsubsection[Running Parameter Profiles]{\protect\hyperlink{ParamProfiles}{Running Parameter Profiles}}
Users will often want to run profiles over specific parameter to evaluate the information in the model to estimate the parameter based on changes in the log likelihood. There are two ways this can be done.

The first option is the use functions within \texttt{r4ss} to run the profile, summarize quantities across runs, and plot the output. The \texttt{SS\_profile()} function will run the profile based on function inputs, \texttt{SSgetoutput()} will read quantities from each run Report file, \texttt{SSsummarize()} will summarize key model quantities, and the \texttt{SSplotProfile()} and \texttt{PinerPlot()} functions can be used to visualize results. Additional information regarding \texttt{r4ss} can be found in the \hyperref[sec:r4ss]{r4ss section}. 

The second way is to create and run a batch file to profile over parameters. This example will run a profile on natural mortality and spawner-recruitment steepness, of course. Edit the control file so that the natural mortality parameter and steepness parameter lines have the phase set to -9999. Edit \texttt{starter.ss} to refer to this control file and the appropriate data file.

%\begin{center}
	\begin{longtable}{p{0.5cm} p{16cm}}		
		& Create a \texttt{profilevalues.ss} file \\
		& 2	\# number of parameters using profile feature \\
		& 0.16	\# value for first selected parameter when runnumber equals 1 \\
		& 0.35	\# value for second selected parameter when runnumber equals 1 \\
		& 0.16	\# value for first selected parameter when runnumber equals 2 \\
		& 0.40	\# value for second selected parameter when runnumber equals 2 \\
		& 0.18	\# value for first selected parameter when runnumber equals 3 \\
		& 0.40	\# value for second selected parameter when runnumber equals 3 \\
		& etc.;  make it as long as you like. \\
	\end{longtable}

Create a batch file that looks something like this. Or make it more complicated as in the example above.


\begin{quote}
\begin{verbatim}
	del cumreport.sso
	copy /Y runnumber.zero runnumber.ss  % so you will start with runnumber=0 
	C:\SS330\ss3.exe 
	C:\SS330\ss3.exe 
	C:\SS330\ss3.exe 
\end{verbatim}
\end{quote}


Repeat as many times as you have set up conditions in the \texttt{profilevalues.ss} file.
The summary results will all be collected in the \texttt{cumreport.sso} file. Each step of the profile will have a unique run number and its output will include the values of the natural mortality and steepness parameters for that run.

\hypertarget{RestartRun}{}
\subsubsection[Re-Starting a Run]{\protect\hyperlink{RestartRun}{Re-Starting a Run}}
Model runs can be restarted from a previously estimated set of parameter values. In the \texttt{starter.ss} file, enter a value of 1 on the first numeric input line. This will cause the model to read the file \texttt{ss3.par} and use these parameter values in place of the initial values in the control file. This option only works if the number of parameters to be estimated in the new run is the same as the number of parameters in the previous run because only actively estimated parameters are saved to the file \texttt{ss3.par}. The file \texttt{ss3.par} can be edited with a text editor, so values can be changed and rows can be added or deleted. However, if the resulting number of elements does not match the setup in the control file, then unpredictable results will occur. Because \texttt{ss3.par} is a text file, the values stored in it will not give exactly the same initial results as the run just completed. To achieve greater numerical accuracy, the model can also restart from \texttt{ss.bar} which is the binary version of \texttt{ss3.par}. In order to do this, the user must make the change described above to the \texttt{starter.ss} file and must also enter -binp \texttt{ss.bar} as one of the command line options.

\hypertarget{OutputSubfol}{}
\subsubsection[Optional Output Subfolders]{\protect\hyperlink{OutputSubfol}{Optional Output Subfolders}}
As of v.3.30.19, users can optionally send \texttt{.sso} and \texttt{.ss\_new} extension files to subfolders. To send files with a \texttt{.sso} extension to a subfolder within the model folder, create a subfolder called sso before running the model. To send files with a \texttt{.ss\_new} extension to a separate subfolder, create a folder called ssnew before running the model.

\hypertarget{SS3inPath}{}
\subsection[Putting Stock Synthesis in your PATH]{\protect\hyperlink{SS3inPath}{Putting Stock Synthesis in your PATH}}
Instead of copying the SS3 executable to each model folder, SS3 can be put in your system path, which is a list of folders that your operating system looks in whenever you type the name of a program on the command line. This approach saves on storage space since the SS3 binary (i.e., the SS3 executable or exe) is about 2.2 MB and having it located in each folder can be prohibitive in a large-scale simulation testing study. Even if you are not running a large simulation study, putting SS3 in your path may still be convenient, as you can use the same executable on many models, there is no need to specify a full file path to the executable each time you run a model, and no need to create a batch file that refers to the executable's location.

\hypertarget{Unix}{}
\subsubsection[For Unix (OS X and Linux)]{\protect\hyperlink{Unix}{For Unix (OS X and Linux)}}
To check if SS3 is in your path, assuming the binary is named SS3: open a Terminal window and type \texttt{which SS3} and hit enter. If you get nothing returned, then SS3 (named SS3 or \texttt{SS3.exe}) is not in your path. The easiest way to fix this is to move the SS3 binary to a folder that's already in your path. To find existing path folders type \texttt{echo \$PATH} in the terminal and hit enter. Now move the SS3 binary to one of these folders.

For example, in a Terminal window type:

\begin{quote}
   \begin{verbatim}
    sudo cp ~/Downloads/SS3 /usr/bin/
  \end{verbatim}
\end{quote}

to move a binary called SS3 from the ``Downloads'' folder to \texttt{/usr/bin}. You will need to use \texttt{sudo} and enter your password after to have permission to move a file to a folder like \texttt{/usr/bin/}, because doing so edits the system for other users also.

Also note that you may need to add executable permissions to the SS3 binary after downloading it. You can do that by switching to the folder where you placed the binary
(\texttt{cd /usr/bin/} if you followed the instructions above), and running the command:

\begin{quote}
   \begin{verbatim}
    sudo chmod +x SS3
    \end{verbatim}
\end{quote}

Check that SS3 is now executable and in your path:

\begin{quote}
   \begin{verbatim}
    which SS3
    \end{verbatim}
\end{quote}

If you followed the instructions above, you will see the following line returned:

\begin{quote}
   \begin{verbatim}
    /usr/bin/SS3
  \end{verbatim}
\end{quote}

If you have previously modified your path to add a non-standard location for the SS3 binary, you may need to also tell R about the new path. The path that R sees may not include additional paths that you have added through a configuration file like \texttt{.bash\_profile}. If needed, you can add to the path that R sees by including a line like this in your \texttt{.Rprofile} file (\texttt{.Rprofile} is an invisible file in your home directory).

\begin{quote}
   \begin{verbatim}
    Sys.setenv(PATH=paste(Sys.getenv(``PATH''),``/my/folder'',sep=``'':''))
    \end{verbatim}
\end{quote}

\hypertarget{Windows}{}
\subsubsection[For Windows]{\protect\hyperlink{Windows}{For Windows}}
To check if SS3 is in your path for Windows, open a DOS prompt (Command Prompt) and type \texttt{SS3 -?} and hit enter. If the prompt returns a message like \texttt{SS3 is not recognized...}, then SS3 is not in your path (assuming the SS3 executable is called SS3.exe).

To add the SS3 binary file to your path, follow these steps:

\begin{enumerate}
  \item Find the correct version of the SS3.exe binary on your computer (or download from the \href{https://github.com/nmfs-ost/ss3-source-code/releases}{SS3 releases}).
  \item Move to and note the folder location. E.g., \texttt{C:/SS3/}
  \item Click on the start menu and type \texttt{environment}
  \item Choose \texttt{Edit environment variables for your account} under Control Panel
  \item Click on \texttt{PATH} if it exists, create it if it does not exist 
  \item Choose `PATH` and click edit
  \item In the \texttt{Edit User Variable} window add to the end of the \texttt{Variable value} section a semicolon and the SS3 folder location you recorded earlier.
     E.g., \texttt{;C:/SS3}. Do not overwrite what was previously in the \texttt{PATH} variable.
  \item Restart your computer
  \item Go back to the DOS prompt and try typing \texttt{SS3 -?} and hitting return again.
\end{enumerate}

\hypertarget{SS3inR}{}
\subsection[Running Stock Synthesis from R]{\protect\hyperlink{SS3inR}{Running Stock Synthesis from R}}
Use \texttt{system(``path/to/ss3'')} to run Stock Synthesis from within the R console, where \texttt{path/to/ss3} is the path to and name of the Stock Synthesis binary.

Alternatively, use the function \texttt{run()} from the \href{https://r4ss.github.io/r4ss/index.html}{\texttt{r4ss}} package within the R console:

\begin{quote}
  \begin{verbatim}
  # run model, in directory folder_1, using the SS3 executable
  # named ss3 that is in the path.
  r4ss::run(dir = ``folder_1'',
            exe = ``ss3'')
  \end{verbatim}
\end{quote}



Running SS3 from within R may be desirable for setting up simulations where many runs of SS3 models are required (e.g., \href{https://github.com/ss3sim/ss3sim}{\texttt{ss3sim}}) or if \texttt{r4ss} is already used to read model output. Additional information regarding \texttt{r4ss} can be found in the \hyperref[sec:r4ss]{r4ss section}. 

\hypertarget{SSI}{}
\subsection[The Stock Synthesis GUI (SSI)]{\protect\hyperlink{SSI}{The Stock Synthesis GUI (SSI)}}
\href{https://vlab.noaa.gov/web/stock-synthesis/document-library/-/document_library/0LmuycloZeIt/view/5042951}{\gls{ssi}} (a.k.a. the SS3 GUI) provides an interface for loading, editing, and running model files, and also can link to \texttt{r4ss} to generate plots. Note that \gls{ssi} is not maintained for Stock Synthesis versions after v.3.30.21.

\hypertarget{SAC}{}
\subsection[The Stock Assessment Continuum Tool]{\protect\hyperlink{SAC}{The Stock Assessment Continuum Tool}}
\href{https://github.com/shcaba/SS-DL-tool}{The Stock Assessment Continuum Tool} (previously known as the Stock Synthesis Data-limited Tool) is a Shiny-based application that uses SS3 as the flexible framework to apply a variety of model types depending on the available data (catch time-series, age-composition, length-composition, abundance index data). It is meant to make SS3 accessible to users, open up many features and tools associated with SS3, provide an easy way to enter data in the model, and make model specification and uncertainty exploration easier.

\hypertarget{Debugging}{}
\subsection[Debugging Tips]{\protect\hyperlink{Debugging}{Debugging Tips}}
When input files are causing the program to crash or fail to produce sensible results, there are a few steps that can be taken to diagnose the problem. Before trying the steps below, examine the \texttt{echoinput.sso} file. It is highly annotated, so you should be able to see if the model is interpreting your input files as you intended. Additionally, users should check the \texttt{warning.sso} file when attempting to debug a non-running model.

\begin{enumerate}
	\item Set the turn\_off\_phase switch to 0 in the \texttt{starter.ss} file. This will cause the mode to not attempt to adjust any parameters and simply converges a dummy parameter. It will still produce a \texttt{Report.sso} file, which can be examined to see what has been calculated from the initial parameter values.
	\item Turn the verbosity level to 2 in the \texttt{starter.ss} file. This will cause the program to display the value of each likelihood component to the screen on each iteration. So if the program is creating an illegal computation (e.g., divide by zero), it may show you which likelihood component contains the problematic calculation. If the program is producing a \texttt{Report.sso} file, you may then see which observation is causing the illegal calculation.
	\item Run the program with the command \texttt{ss3 >>SSpipe.txt}. This will cause all screen display to go to the specified text file (note, delete this file before running because it will be appended to). Examination of this file will show detailed statements produced during the reading and preprocessing of input files.
	\item If the model fails to achieve a proper Hessian it exits without writing the detailed outputs in the FINAL\_SECTION. If this happens, you can do a run with the \texttt{-nohess} option so you can view the \texttt{Report.sso} to attempt to diagnose the problem.
	\item If the problem is with reading one or more of the input files, please note that certain Mac line endings cannot be read by the model (although this is a rare occurrence). Be sure to save the text files with Windows or Linux style line endings so that the executable can parse them.
\end{enumerate}

\hypertarget{KeyboardTips}{}
\subsection[Keyboard Tips]{\protect\hyperlink{KeyboardTips}{Keyboard Tips}}
Typing ``N'' during a run will cause \gls{admb} to immediately advance to the next phase of estimation.

Typing ``Q''  during a run will cause \gls{admb} to immediately go to the final phase. This bypasses estimation of the Hessian and will produce all the model outputs, which are coded in the FINAL\_SECTION.

\hypertarget{RunningMCMC}{}
\subsection[Running MCMC]{\protect\hyperlink{RunningMCMC}{Running MCMC}}
 Running SS3 with \gls{mcmc} can be done through command line options using the default \gls{admb} \gls{mcmc} algorithm (described below). Another possibility is using the R package \texttt{adnuts}. See the \href{https://cran.r-project.org/web/packages/adnuts/vignettes/adnuts.html}{\texttt{adnuts} vignette} for more information. The \href{https://www.admb-project.org/developers/mcmc/mcmc-guide-for-admb.pdf}{\gls{mcmc} guide for \gls{admb}} provides the most comprehensive guidance available for using \gls{mcmc} with \gls{admb} models (such as SS3). Additional guidance is available in \citep{monnahan2019overcoming}.

 Running SS3 with \gls{mcmc} (instead of \gls{mle}) provides \gls{mpd} estimates, report file, Hessian matrix and the \texttt{.cor} file. Parameters stuck on bounds which will degrade efficiency of \gls{mcmc} implementation. Two commands are needed to obtain the model results:
 
\noindent Run SS3 with arguments -mcmc xxxx -mcsave yyyy
 \begin{itemize}
 	\item Where: xxxx is the number of iterations for the chain, and yyyy is the thinning interval (1000 is a good place to start).
 	\item \gls{mcmc} chain starts at the \gls{mpd} values.
 	\item Recommended: Remove existing \texttt{.psv} files in run directory to generate a new chain.
 	\item Recommended: Before running, set the run detail switch in starter file to 0 to limit printing to the screen; reporting to screen will slow \gls{mcmc} progress.
 	\item Optional: Add \texttt{-nohess} to use the existing Hessian file without re-estimating.
 	\item Optional: To start the \gls{mcmc} chain from specific values change the par file: run the model with estimation, adjust the par file to the values that the chain should start from, change within the starter file for the model to begin from the par file, and call the \gls{mcmc} function using \texttt{ss3 -mcmc xxxx - mcsave yyyy -nohess -noest}.
 \end{itemize}
	
\noindent Run SS3 with argument -mceval to get more summaries
\begin{itemize}
	\item This generates the posterior output files.
	\item Optional: Modify starter file entries to add a burn-in and thinning interval above and beyond the \gls{admb} thinning interval applied at run time.
	\item Recommended: \gls{mcmc} always begins with the maximum posterior density values and so a burn-in > 0 should always be used.
	\item This step can be repeated for alternate forecast options (e.g., catch levels) without repeating step 2.
\end{itemize}

Note that when the model is switched to \gls{mcmc} or MCEVAL mode, all the bias adjustment factors become 1.0 for any years with recruitment deviations. A report file is not created after completing \gls{mcmc} because it would show values based only on the last \gls{mcmc} step.

\pagebreak