7. RUN PARAMETERS
The run.prm provides all the key information required to control the model run, load optional submodels and also parameters controlling the debugging and detailed output. The table below lists the main parameters used in the run.prm, but please remember to follow the news on the Atlantis wiki as new parameters are sometimes added.
| Parameter | Meaning |
|---|---|
| General parameters controlling the run | |
| title | Title of the run. Ideally this should be an informative title (e.g. SE Tasmania model with constant forced fishing and base level fishing pressure on FMM increased 2000 fold) as it will written at the start of the log.txt file and into the output.nc file and will be displayed on the top of plots in visualization tools such as OLIVE or DIVE |
| dt | Timestep of the model. The timestep is typically given in hours (e.g. “12 hour”), however Atlantis reads the units together with the numerical value so other units “minute” or “day” may also be used. Typically the timestep is set to 12 or 24 hours, but it can be set to other intervals as well. It is not typically recommended to make it >24h and one should think carefully whether shorter than 12h is really needed, as the model will run slower. Some coastal, very dynamic, areas have 6h or even 3h timesteps, but that will require high resolution hydrodynamic forcing data. |
| tstop | Day on which the model run will end. If you want to run the model for 10 years, set this to 3651 (technically 3650, however given most output is done annually it is best to add an extra day to make sure the final output is printed before the model stops). |
| tburnday | Number of days that define the burn-in period. At the end of this period the “virgin” state of the model is stored. This means that every comparison of species biomass to the original or “virgin” state will use values stored at the end of the burn-in period and not those set in the initial conditions. This is useful for models that have unstable dynamics at the start of the model run. |
| Output files and reporting | |
| toutstart | Day on which to start writing the output. This is normally set to 0, but can be set to a larger value for long runs if there is a need to save memory and there is no interest in the burn-in period dynamics. |
| toutinc | Periodicity in days for the Ecology submodel snap shot output to the NC files, in days. In longer runs, this is often set to monthly (30) or yearly (365) so file sizes do not become very large. In poorly behaved runs (that are crashing), or ones with extreme events which condition subsequent behaviour, fine scale output (e.g. at the same level as the timestep) may be required. However, remember that a lot of output is written at each reporting period, so make sure you set reasonable values for long well-behaved runs (quarterly or even yearly). Note that in Atlantis all years are 365 days long. If monthly output is required and it is set to 30 days then after one year the output would be shifting by 5 days every year. |
| toutfinc | Periodicity of the cumulative output from the Harvest submodel (catches, quotas, discards, etc) to the NC files (CATCH.nc, TOTCATCH.nc). These values are the sum of all effort, catch (etc) since the last output dump. Unlike the ecology output, they are not snap shot values. |
| tsumout | Periodicity of the output to the TXT files. |
| flagannual_Mest | If 1, estimates of mortality per predator are written out annually, otherwise they are written at the tsumout frequency |
| fishout | If 1, it switches on the fisheries output (it is recommended that this is on if you have fisheries in your model, but is unnecessary if it is an ecology model only). |
| flagreusefile | Whether to replace or append ouputs to the existing files, when starting a new run. If it is set to 0 Atlantis will quit with a message that a file with such name already exists. If it is set to 1 results will be appended to the existing file, if set to 2 it will overwrite (replace) the existing file without warning. NOTE: This is old code. If you really want it to append please run a test first to see if it worked. If not, let the developers know, as it likely needs updating. Setting flagreusefile to 0 or 2 is recommended. |
| flag_age_output | If set to 1, an additional output file agebiomindex.txt will be created and the total biomass output will be given for each cohort. This can bea very useful output file, because without it you will need to run a specially written script over the output.nc file to determine the biomass per age group per functional group. |
| Parameters loading different submodel or options | |
| flagecon_on | If 0 the Economics submodel is not loaded |
| flag_fisheries_on | If 0 the Harvest submodel is not loaded |
| flag_skip_biol | If 1 the Ecology submodel is not loaded – only for debugging! |
| flag_skip_phys | If 1 the Physics submodel is not loaded. This will actually produce an error message and Atlantis will quit. So this value should be NEVER set to 1. |
| fishmove | If 0 all age structured group movements (vertical and horizontal) are turned off |
| external_populations | Flag indicating whether a age structured population dynamics model is used to track growth and mortality while an age-structured group is outside the model domain (1) or whether a simple growth and mortality correction is applied to migrators on their return to the system (0) |
| Parameters controlling detailed outputs for a specific box and diagnostic reporting The outputs are written into the log.txt file for model tuning and debugging purposes. |
|
| debug_it | If 1 - give detailed outputs of all processes for a selected box and time period into the log.txt file |
| checkbox | Box number for which to give detailed outputs into log.txt file |
| checkstart | Day on which the detailed output in the log.txt file for the box above should start |
| checkstop | Day on which the detailed output in the log.txt file for the box above should end Note! Detailed output will likely produce a huge amount of data, so make sure the time period of detailed reporting is not too long or the run is short |
| debug | This parameter has a lot of options about what topic area or code path to give detailed outputs for (for debugging). These settings trigger fprintf lines in the code and print information to the log.txt file. Each setting focuses on different processes. Setting it to 0 turns off detailed outputs. Other parameter values include debug = 1 (for fisheries catch fprintf) debug = 2 (for discards) debug = 3 (for forced fish catches) debug = 4 (for the assessment model processes) debug = 5 (for spatial management) debug = 6 (for basic effort options) debug = 7 (for economically driven effort allocation model) debug = 8 (for economic calculations) debug = 9 (for quota setting and handling) debug = 10 (for aging in age structured groups) debug = 11 (for recruitment in age structured groups) debug = 12 (for spawning in age structured groups) debug = 13 (for migration in/out of model domain) debug = 14 (for movement within the model domain) debug = 15 (for stock-based allocations within a functional group) debug = 16 (for basic overall biomass calculations) debug = 17 (for feeding) debug = 18 (for all ecological processes) debug = 20 (print biology process function parameters) debug = 21 (print prey function parameter) debug = 22 (debug clam - atlantis linkage) debug = 23 (for deposition in the physics sub-model) debug = 24 (for the forced mortality scalar) debug = 25 (for the forced growth scalar) debug = 26 (for FSPB additions) debug = 27 (for debugging the C and P code) debug = 28 (for debugging the SS3 tiered code) debug = 29 (for external scaling) This list changes as new debugging issues arise. So if you want to know the latest list, the entire list of currently available debugging options can be seen in the atlantisboxmodel.h file (around line 750) in the Header files subfolder of the atlantismain library. There is also a list on the Atlantis wiki |
| fishtest | If 1, count up total population of age structured groups after each main subroutine |
| flaggape | Periodically list prey vs gape statistics in log.txt |
| flagchecksize | Periodically list relative size in log.txt. This is useful during model calibration for seeing the current size versus size given in the initial conditions. |
| flagagecheck | Periodically list age structure per cohort in log.txt |
| flagdietcheck | Writes detailed diet output per box and layer to DetailedDietCheck.txt If set to 1 then it is total consumption, if set to 2 then it returns proportions |
| checkNH | Give detailed logged output for NH fluxes in the box selected with checkbox. Useful understanding what groups may be at fault if you get an “unstable variable” crashing the model before completion of the run. |
| checkDL | Give detailed logged output for DL fluxes in checkbox. Useful understanding what groups may be at fault if you get an “unstable variable” crashing the model before completion of the run. |
| checkDR | Give detailed logged output for DR fluxes in checkbox. Useful understanding what groups may be at fault if you get an “unstable variable” crashing the model before completion of the run. |
| checkbiom | Give detailed logged output for biomasses of which_check group in the checkbox (see above) |
| which_fleet | ID number of fleet to track (if don’t want to track anything set this to a value greater than the number of fisheries in your model). The ID is the same as in the fisheries.csv file |
| which_check | ID number of group to track (if don’t want to track anything set this to a value greater than the number of functional groups in your model). The ID is the same as in the functional_groups.csv file |
| habitat_check | Which distribution type (0-water column, 1- sediment, 2- epibenthic, 3- land, 4-ice) to report for the group marked with which_check. Some groups are ony tracked in one distribution type, others are tracked in both water column and sediments. |
| move_check | ID number of group for which movements should be tracked |
| Key parameters determining the model runs and inputs | |
| flaghemisphere | 0=southern, 1=northern hemisphere. This flag is important in calculating winds and circulation (affects coriolos and seasons). |
| flagAllowLand | If set to 1 if the model includes dynamic land components (this requires a large number of additional inputs). If set to 0 any land boxes are treated as boundary boxes and are not executed. |
| flagIsEstuary | Flag to indicate if the model is estuary. If true a SED sediment tracer is required in the initial conditions input file and tidal emptying of shallow boxes is allowed (with fish moved to the nearest water channel). |
| flagIsPolar | Flag to indicate whether the model is in polar regions and so will have 24 hours of nigh/daylight seasonally |
| flag_use_deltaH | Flag to indicate that when using pH tracking and parameter corrections use ∆ [H+] rather than pH per se. |
| trackAtomicRatio | If set to 1, then not only N, but also P and C are tracked. This will require many additional tracers in the input files. |
| track_rugosity_arag | If set to 1, rugosity and aragonite saturation will be tracked and additional parameters required. Important for modelling corals and sponges. |
| track_pH | If set to 1, pH values will be tracked – important for ocean acidification simulations. |
| track_contaminants | If set to 1, contaminants will be tracked. This will require information on the number and name of the contaminants to be tracked, as well as additional tracers and initial conditions (so as to allow for the tracking of contaminants through each of the functional groups in the model). |
| Other parameters | |
| mirror_invalid | If this flag set to 1 and the hydrodynamics model attempts to send water from one cell into an invalid cell (e.g. a layer in a box that does not exist) the water flow will instead will be sent into the layer closest to the intended destination layer. This option was needed because historically some hydrodynamic models tried to send water into layers below what Atlantis was modelling, so water had to be redirected to the extant bottom layer instead. Set this flag to 0 if your hydrodynamic forcing is working well or you want Atlantis to quit with a warning that something is wrong with the hydrodynamic forcing files. |
| flag_replicated_old | This flag is used to maintain legacy code options. While we fix true bugs sometimes we also update the code to better represent a process where we had made a rough first attempt that can now be done in a better way. However, such changes can change model dynamics and so for legacy models we need to keep the legacy options. When set to 1, the new code changes are not applied and the old results can be reproduced. However, for all new models it is recommended that this flag be set to 0, as the new code is more rigorous and defensible. |
| flag_replicated_old_PPmort | Flag is used to maintain old plankton mortality assumptions (from very early code versions that persisted as potential bug into newer models). Turning it on zeroes out phytoplankton mortality and only allows for lysis in phytoplankton. However, for all new models it is recommended that this flag be set to 0 so parameter application is transparent and contaminants are transferred appropriately. If you are transitioning an old model and want to have this flag turned off but maintain your old model as close as possible keep your lysis values as is and zero out mL. |
| flag_replicate_old_calendar | This flag specifically allows for legacy models and the influence of environment on the distribution of recruits to be replicated in the newer code. It is recommended that all new models have this set to 0. |
| flag_old_embryo_init | This flag is to allow legacy models to have the same starting conditions under the new code as they did in older version. In the past, rather than use the stock-recruit relationship for a species to dictate the larvae already in the water column at the start of the model run a simpler linear relationship with spawning stock was used. This has now been replaced by the use of the stock-recruit relationship (for improved consistency). All new models should set this parameter to 0, but legacy models trying to reproduce past model runs should set this value to 1. |
| check_dups | If set to 1, Atlantis will check for duplicated parameters in the parameter files before starting the run. This can be used to ensure that same parameter is not entered twice with different values. However, it takes a LONG time to execute (especially for big models). If it is set to 1 the model run will not start for quite a while until all possible duplicates are checked. If you are concerned about duplicate entries, go through the file once with this until all duplicates are found and then turn it off. |
| flagscaleinit | If set to 1 this will cause the vector init_scalar to be read in. This vector contains one value per group listed in the functional_groups.csv file. These values are used to modify (scale) the initial conditions without requiring that nc file to be modified – for the vertebrates the number per age class is scaled and for biomass pools the biomass per cell and layer is scaled (for those groups in the water column, sediment layers and the epibenthos). |
| flag_sanity_check | Set this to 1 to make sure that species with a gestation or recruitment period that is about the same length as the time between reproduction (spawning) events do not get cascading population growth (where recruits from one event accidentally also contribute to the next event). To replicate old code versions set this value to 0. |
| flagpassivetracer | Set to 1 if you want to do particle tracking to validate physical forcing. This will require adding the SED_i variable to the initial_conditions.nc file. |
| flagenviro_warn | Set to 1 if you want warnings about when environmental conditions constrain spawning or movement in a cell |