FISHERIES FORCING PARAMETERS
Atlantis can take a lot of externally forced tracer and parameter values. Details on such forcing files are given in the force.prm file.
The minimum force.prm file will contain the pathname and load information for a hydrodynamics forcing file and nothing else. However, in most models a lot more of physical, ecological and socio-economic processes are forced and pathnames for all these files will be required in force.prm. See table 12 below for the list and application examples of different forcing options.
Absolute time in Atlantis: model time, hydro time and TS time
The time (t) entry in the initial_conditions.nc file indicates the actual absolute time in calendar years that marks the start data and time of the model simulation. For example:
t:units = "seconds since 2000-01-01 00:00:00 +10"
This indicates that this model starts at midnight on the first of January 2002. This is the main Atlantis time (called model time). The hydrodynamics forcing file also has its own absolute start time, which is called hydro time; this does not have not to match with the model time. For example, the hydrodynamics data might have five calendar years and start from 2002 July. Atlantis will try to match the model time to the hydro time. In the example, above Atlantis will start the run by loading in the hydrodynamics beginning in January not July and run from there, matching the month of the year when rewinding the hydro data.
The time series forcing files also have a parameter indicating the absolute time of the start (TS time). For example, the forcing data may start from 1990 July. On read in Atlantis will by default convert these times into model time, skipping that part of the time series that occurs before model time begins. In the example here, the first 10 years of TS data will be skipped, and only the forcing information from year 11 will be used. Alternatively, if TS time starts later than the model time, Atlantis will run the simulation withouth any forcing until the model time matches the TS time.
Users have an option to match the TS time not to the model time but to the hydro time. This is done by setting ts_on_hydro_time=1. If ts_on_hydro_time=0 then the default will be used (matching to model time). However, keep in mind that if TS time is matched to hydro time any rewinding of hydrodynamics data will also mean the rewinding of the forcing data. For example, if 50 years of forcing data is available and the model runs for 50 years all forcing will be used if TS and model times match. However, if TS is matched to hydro time and the hydrodynamics is rewound every 5 years, then only 5 years of TS values will be used before the TS file is rewound along with the hydrodynamics data.
Note that the rewinding of TS filed described above (done when ts_on_hydro_time=1) is not the same as specific rewind options associated with most TS files. The specific TS rewind parameters apply when the time series of the run (either on model or hydro time) exceeds the time series given the TS file. See details on the TS file format below
It is recommended that users download the sample South East Tasmanian (SETas) model input files that give details on the structure of the forcing and other parameter files. The table below lists currently available forcing options
Format of the time series (TS) forcing files
The TS forcing files have a standard input format read by Atlantis. At the top of the file the user can provide a comment on what the file represents (marked by a single # at the start of each line). Then the user needs to provide a description of variables in each column of the TS data file (Atlantis needs this to know what the variable name is, its units and missing value marker). Atlantis recognises these entries as column description with ## at the start of each line. If a single # is given Atlantis will assume it is a comment and ignore it, so if you are having read-in issues make sure you have all column decriptions beginning with ##. Underneath this header section is the actual data table in columns. The number of columns in the data should be the same as the number of column descriptions.
The first column always indicates time and is given in the units defined (typically days). The data in the TS file can be given at longer time intervals, such as every 30 or every 365 days. If forcing data is not given for every timestep of the model Atlantis will either use the the last valid value (i.e. the last value before the gap in the data) or interpolates between the last valid value and the next (future) value in the time series file. The handling of patchy data is determined by the typeXXXXts parameter, such as typeCatchts or typeDiscardts. If typeXXXXts is 1 the same value is used throughout the period between two forcing time steps, if typeXXXXts is 0 then Atlantis will interpolate the value. Not all forcing files have the typeXXXXts parameter and if this parameter is not available it means that Atlantis will interpolate values. For example, if the value on day 1 was 10 and the value on day 5 is 50, setting typeXXXXts to 1 means that on day 2, 3 and 4 the value returned will be 10, while on day 5 value it will be 50. Setting typeXXXXts to 0 means that the value returned on day 2 is 20, day 3 value is 30 and day 4 value is 40. See further details about the interpolation here
Make sure you chose the correct value for the rewind parameter, as that will determine what happens if forcing file time series is shorter than the model run: rewind=0 means that the last value will be used for the remaining of the run, rewind=1 means that the time series will be reused from the start. More details on the structure of different TS files can be found here
# THIS FIRST LINES ARE A COMMENT ON THE SOURCE OF THE DATA
# GDP time series for Australia 1972 to 2008 based on treasury projections in 2006 Budget
# Fuel cost time series from autoregressive cost model based on Australian TACC diesel cost data #
# - EVERYTHING BELOW IS READ BY ATLANTIS AND MUST BE IN A STANDARD FORM # COLUMNS 3 # # COLUMN1.name Time
## COLUMN1.long_name Time
## COLUMN1.units days since 1972-01-01 00:00:00 +10 ## COLUMN1.missing_value 0 ## ## COLUMN2.name GDP ## COLUMN2.long_name GDP ## COLUMN2.units dollars ## COLUMN2.missing_value 0 ## ## COLUMN3.name FuelCost ## COLUMN3.long_name FuelCost ## COLUMN3.units dollars ## COLUMN3.missing_value 0 ## 1 0.206 0.64 2 0.207 0.68 3 0.208 0.69 4 0.209 0.65 5 0.204 0.64 6 0.202 0.63 7 0.210 0.62
NOTE: If you are having issues reading a TS file 1) Make sure there are no extra spaces or tabs after the name of the column (this can sometimes happen if you have created your TS file in excel and then pasted on to a text editor). Atlantis should now ignore those spaces, but in the past it was an issue. 2) Make sure the model is space not tab delimited. Again Atlantis should now be able to read either option, but just to be careful. 3) If a collaborator created the file for you and they use a different operating system, make sure the file is in the correct file type for your machine (in text-pad, text wrangler etc check that it is a windows type if you are on a windows machine and linux if you do not use windows). See chapter 2.2 for file conversion details.
| Forcing | Parameters needed in force.prm |
|---|---|
| Forcing of physical parameters | |
| Hydrodynamics | This is the minimum forcing required to run Atlantis. See chapter 4 for details on hydrodynamic forcing files. nhdfiles gives the number of hydrodynamics files that will be supplied (read in). It is possible to put all the forcing time series into one file, but these files can get very big. Therefore, it is often easier to split the series into a number of smaller files. Atlantis will read these files in the order given, using forcing data from the first file, then from the second one and so on. Once the data from the last file is used, Atlantis will return to the first file and start reading from there again. The hydrodynamics files are automatically looped. For other forcing input files an additional parameter (_rewind) indicates whether the forcing data should be looped when the time series finishes (=1) or stay on the last value (=0) Note that the pathway to the file is tagged for Atlantis by the parameter name hdN.name where N indictes the number of the file, remembering that numbering in C (and thus Atlantis) starts at 0. So hd0.name, hd1.name, hd2.name and so on. For example, the following would indicate there are 2 hydrodynamic files and that they are located in the directory the model is being run from. nhdfiles 2 hd0.name hydrofile1.nc hd1.name hydrofile2.nc The following indicate the files are stored in the inputs sub-directory (a directory one level down from the run directory) hd0.name inputs/hydrofile1.nc hd1.name inputs/hydrofile2.nc Finally if the inputs folder is in the directory that is at the same level than the run directory then the path to the hydrodynamics files should read as hd0.name ../inputs/hydrofile1.nc hd1.name ../inputs/hydrofile2.nc For more information on how to indicate a path see, for example, this Wikipedia site |
| Temperature | Atlantis can calculate the temperature dynamically, but most models use temperature forcing from more accurate hydrodynamic modes. See chapter 4 for details of temperature forcing files. The lay out of the list of files is as for the hydro file – with as many files listed as given by the ntempfiles parameter. use_tempfiles 1 if temperature forcing (NC files) are being used ntempfiles N where N is the number of files being provided Temperature0.name temp1.nc the path and filename of the first file Temperature1.name temp2.nc the path and filename of the second file Temperature2.name temp3.nc the path and filename of the third file … temp_rewind 0 flag indicating whether to rewind (loop over) the temperature forcing data (1) or not (0) |
| Salinity | Atlantis can also load in salinity forcing from more accurate hydrodynamic modes. See chapter 4 for details of salinity forcing files. The lay out of the salinity parameters and file name list is as for temperature. use_saltfiles 1 nsaltfiles N Salinity0.name salt1.nc Salinity1.name salt2.nc … salt_rewind 0 (or 1) |
| pH forcing | If pH is tracked, it is possible to calculate it dynamically or provide external forcing values from specific models. The pH forcing is provided through spatial NC files in the same way as for temperature and salinity. use_phFiles 0 npHfiles N pH0.name pHforceA.nc pH1.name pHforceB.nc pH_rewind 0 |
| forcing of other tracers | It is possible to force any other tracers with external data. See details on the wiki here. When new data is read in at the end of the timestep any existing value is overwritten with the value from the NC forcing file. This has been used for contaminants and for oxygen (e.g. when internal Atlantis calculations were not reproducing oxygen dynamics sufficiently well). This is a useful option, but should be used with care for any tracers that contains N (and P or C if tracking those tracers), as it can violate the assumption of conservation of matter. use_force_tracers 1 (this flag indicates whether additional tracer forcing files should be read it (1) or not (0)) nforceTracers N (where N is the number of tracers that will be forced) tracerNames nameA nameB … The list of tracer names (matching the names used in the initial_condition.nc file) that will be forced – with each name on a new line. For example, nforceTracers 2 tracerNames 2 Oxygen Arsenic For each tracer listed you must then give the filenames using the format TRACERNAME_nFiles N (where TRACERNAME is the name of the tracer and N is the number of files to be loaded) TRACERNAME_File0.name TRACER_1.nc (path and filename for the first forcing file for the tracer) TRACERNAME_File0.name TRACER_2.nc (path and filename for second file etc) TRACERNAME_rewind 0 (whether to rewind the forcing files (1) or not (0)) for example Arsenic_nFiles 1 Arsenic_File0.name Arsenic.nc Arsenic_rewind 0 |
| Point sourcing of nutrients | Even though Atlantis calculates internal nutrient dynamics, it is relatively common to force additional nutrient inputs (e.g. from sewage outfalls, river mouth, upwellings etc). For example, the California Current, Guam, Gulf of Mexico and Chesapeake Bay models all use nutrient loading -forcing with nutrient time series (Brand et al. 2007; Ainsworth et al. 2015; Weijerman et al. 2015). While such inputs are mostly used to imitate nutrient inputs from sources clearly outside the model domain (e.g. rivers), they can also be used as a proxy for multi-decadal trends in ocean productivity, even if full multi-decadal oceanographic data is not available and must be ‘looped’. Externally forced nutrients sources (or sinks if negative values are given) are provided as TS files npointss N (where N is the number of externally supplied point source/sink files) For each TS file the following details must be given pss0.name XXXX (where XXX is a meaningful name for the point, such as a river name, used so the modeller knows what this point represents; this name is NOT used by Atlantis) pss0.location X Y Z (e.g. 3951091.3 1789202.7 -1) pss0.data PSSTS1.ts (path and filename of the forcing TS file) pss0.rewind 1 (whether to rewind the forcing file (1) or not (0)) |
Note! The location values (X Y Z) has three values – coordinates to input the point source (3951091.3 1789202.7) and the depth (-1). To make sure the point source is deposited in the desired box it is a good idea to ensure the X Y values match the “inside” point of the box as given in the BGM file (see chapter 3).
The last number in the location is very important as it will determine the correct reading of the forcing data. For point source data the depth must be a negative number for it to be deposited in the water. Other time series forcing files (e.g. for catch) follow a similar format to the PSS files – requiring a name, location, data (filename) and rewind flag. However, for these forcing files the third number gives the box ID number (from BGM file, see chapter 3) not a depth.
| Forcing | Parameters needed in force.prm |
|---|---|
| Bottom stress | Bottom stress values are used to calculate resuspension and additional macrophyte mortality due to wave action. Atlantis can calculate bottom stress values dynamically, but if processes affected by bottom stress are a focus of the study it is recommended to force stress externally from more precice hydrodynamic models. At present there is no flag to indicate whether this file will be loaded (future releases are likely to switch to a flag as for temperature and salinity, e.g. use_stressfiles). At present if the BottomStress tag is in the force.prm then the listed file will be read automatically. BottomStress stress.nc (the path and filename of the stress NC input file). If you do not wish to use bottom stress simply omit the BottomStress entry from the force.prm file. |
| Precipiation and evaporation | See chapter 5.2 on how the precipitation forcing data is used. As in case of bottom stress, precipitation and evaporation are forced through spatial NC files. They will be loaded if the tag name is present in the fore.prm file (if not provided the model will not look to load the files). Precipitation rain.nc (path and filename for the precipitation) Evaporation evap.nc (path and filename for the evaporation) These files will not rewind. |
| Solar radiation | Solar radiation can be calculated dynamically by Atlantis or can be forced through a time series TS file. In the later case (TS file used) the same value is used for the entire model domain. If you do not wish to load a solar TS file do not provide a Solar_radiation entry in force.prm and set lim_sun_hours to 1 in the biology.prm file. As with bottom stress the solar radiation file will be loaded if the tag name is present in the fore.prm file Solar_radiation solar.ts (path and filename for the solar forcing file) Solar_radiation_rewind 0 (a flag indicating whether to rewind the data file (1) or not (0)) |
| CO2 concentrations | Time series of atmospheric CO2 concentrations. This is used to dynamically calculate pH values and is required if trac_pH=1 in run.prm. See further details on the wiki here |
| Ice | If ice is modelled dynamically, the user must provide ice forcing data. See details on the wiki here |
| Forcing of ecological parameters | |
| Forcing of recruitment | Recruitment can be forced in two ways, see details on the wiki here The first is to use a single recruitment time series across the entire model domain. To do this the tag Recruitment_time_series must be added to the force.prm file Recruitment_time_series filename.ts (path and filename for the time series) This time series provides a TS file of recruits entering the entire model domain. Box specific forcing of recruitment is also allowed as described in the link above. The second way is to allow for time series of recruitment to be read in for specific boxes. To do this set nMultRects N (the number of boxes where recruitment time series will be provide) typeMultRects 1 (the type of time series – whether to use the last value (0) or interpolate between values (1)) The for each of the N boxes you need to provide the following: MultRects0.name Meaningful_name MultRects0.location X Y BOXID (e.g. 4924432.61 3298510.07 94) MultRects0.data filename1.ts (path and filename of the TS file for box BOXID) MultRects0.rewind 0 (whether to rewind the file (1) or not (0)) MultRects1.name Meaningful_nameB MultRects1.location X Y BOXID2 MultRects0.data filename2.ts MultRects0.rewind 0 … |
| Recruitment scaling | Recruitment can also be scaled by a time series of species-specific scalars provided in a time series (TS) file. To use this option include the tag Recruitment_enviro_forcing in the force.prm file Recruitment_enviro_forcing scalarfile.ts (path and filename for the time series) More details are given on the wiki |
| Recruit size | Representing differential survival can be done in two ways, both of which use a time series file. To activate these set flag_modify_KWSR in the biology.prm file to a value greater than 0. In both cases KWRR will be reset so that it is KWSR * X_RS. If flag_modify_KWSR is set to 1 then the model will load a time series of multipliers to apply to the constant KWSR supplied for the group in the biology.prm file. If flag_modify_KWSR is set to 2 then the model will load a time series file of values to use for KWSR. In both cases the file for KWSR is supplied in force.prm as follows KWSR_forcing KWSR_filename.ts |
| Larval connectivity matrix | To activate set use_larvalfiles 1 in the force.prm and then provide the filename of the connectivity matrix per species using larval dispersal Larval0.name connectfile.nc (path and filename for the connectivity matrix NC file) Larval_rewind 0 (a flag indicating whether to rewind the file (1) or not (0)) The NC file must contain an entry XXX_Connnectivity (where XXX is the group code from the functional_groups.csv file). These entries are annual connectivity matrices. If there are les entries than there are years in the run then the rewind flag will dictate whether the file is rewound or not. This is recent functionality that has not been widely used. It allows to enter larval dispersal matrix. See further details here If you want this connectivity matrix to be used completely in place of recruit_hdistrib (rather than in combination with it) then set the flag larvae_connect_only to 1. |
| Linear mortality scaling | External scalar on linear mortality (mortsc in chapters on Ecology routines) – can also be supplied as an additional site specific mortality rate rather than a scalar. This can be provided as a TS file or spatially with box-specific values as an NC file. See details here on how the external mortality scaling is set and calculated. |
| Scaling of size, growth rate or maturation proportion | The scaling of growth and maturation has been used to explore ecological consequences of long-term trends in life-history traits (e.g. Audzijonyte et al. 2013; Audzijonyte & Kuparinen 2016). The scaling is forced through external forcing scalars on size (SN and RN values), growth rate (mum parameter) or maturation (FSPB parameter). The scalars are applied by scaling the existing values. See further details on size change forcing here and on mum and FSPB scalar here |
Forcing of fisheries and socio-economic parameters
It is possible to provide forced catches, discards, effort and other socio-economic parameters. Forced catches and discards, in particular, have been used to parameterise the model and emergent biomasses given the known catch history. See, for example, details in Fulton et al. 2007 and Link et al. 2011. The catch and discard forcing files are provided as box-specific species-specific time series. At each timestep Atlantis will then take the forced catch from the species biomass. See further details in the description of the Harvest submodel.
| Forcing | Parameters needed in force.prm |
|---|---|
| Catch | To force catches use the following parameters nCatchts N (where N is the number of catch force time series (TS) files) typeCatchts 1 (whether to use the last value (1) or interpolate (0) between the two forcing time steps) This is followed by the actual box-specific forcing file information. Atlantis will attempt to take the forced catch from the specified box. If not enough biomass is available Altnaits will first try to take the biomass form younger age classes, then may look to neighbouring boxes (depending on the flagimposecatch setting in harvest.prm) and if it still can’t fill it will hold it over (“carry over”) and add the remaining amount to the biomass to take the following day. If at the end of the year there still remains catch that cannot be taken it is noted in the log.txt file and the “carry over catch” is zeroed to start again in the new year. Catchts0.name meaningful_name (e.g. box0catch; this is NOT used by Atlantis) Catchts0.location X Y BOXID (e.g. e.g. 370889.3287 -717418.8373 0. This is the x, y and box ID indicating the box where the catch will be extracted. It is safest to use the “inside” point of the box BOXID as given in the BGM file - see chapter 3 on details about model geometry) Catchts0.data catchfile1.ts (path and filename of the catch TS file) Catchts0.rewind 0 (whether to rewind the data file (1) or not (0)) |
| Discard | The entry format is as for catches above, but instead of catches provide discard values for the specified boxes nDiscardts N (where N is the number of time series (TS) files) typeDiscardts 1 (whether to use the last value (1) or interpolate (0) between the two forcing time steps) Discardts0.name meaningful_name Discardts0.location X Y BOXID Discardts0.data disfile1.ts (path and filename of the TS file) Discardts0.rewind 0 (whether to rewind the data file (1) or not (0)) |
| MPA | This forcing file “closes” a proportion of the box to fishing (with the columns in the TS file being the closure per fishery), simulating marine protected areas (MPA). This is used in place of the MPA vectors in harvest.prm and is useful where MPAs vary through time. Further details are provided in the Harvest submodel description nMPAts N (where N is the number of time series (TS) files) typeMPAts 1 (whether to use the last value (1) or interpolate (0) between the two forcing time steps) MPAts0.name meaningful_name MPAts0.location X Y BOXID MPAts0.data mapfile1.ts (path and filename of the TS file) MPAts0.rewind 0 (whether to rewind the data file (1) or not (0)) |
| Effort | This forcing file provides the effort time series to apply in a box (with the columns of the TS file giving the effort per fishery) Further details are provided in the Harvest submodel description nEffortts N (where N is the number of time series (TS) files) typeEffortts 1 (whether to use the last value (1) or interpolate (0) between the two forcing time steps) Effortts0.name meaningful_name Effortts0.location X Y BOXID Effortts0.data effortfile1.ts (path and filename of the TS file) Effortts0.rewind 0 (whether to rewind the data file (1) or not (0)) |
| Residuals | These time series provide the price residuals per market if using the economics model and forcing historical prices. One time series is required per market, with the columns providing the residual values per species. nResidualts N (where N is the number of time series (TS) files) typeResidualts 1 (whether to use the last value (1) or interpolate (0) between the two forcing time steps) Residualts0.name market_name (NOT used by Atlantis) Residualts0.location X Y BOXID (x,y location and box ID for the port which supplies the market) Residualts0.data resid_file1.ts (path and filename of the TS file) Residualts0.rewind 0 (whether to rewind the data file (1) or not (0)) |
| Economic statistics | Economic statistics include GDP and fuel costs. They are used in the economically driven dynamic fishing calculations. They are not box specific, but just time series values that apply across the entire model. nEconts 1 (typically 1 or 0; only non-zero if using the economic effort model) typeEconts 0 (whether to use the last value (1) or interpolate (0) between the two forcing time steps) Econts0.name meaningful_name (NOT used by Atlantis) Econts0.location X Y BOXID (x, y and box ID of any dynamic box in the model; by convention set to the values for the box with the larget market port) Econts0.data econ_file1.ts (path and filename of the TS file) Econts0.rewind 0 (whether to rewind the data file (1) or not (0)) |
Note! Remember that the third number of the location is the box ID number (from BGM file, see chapter 3). It is very important to give this number correctly or else Atlantis will not read or apply the forcing inputs correctly.
: Table 12. List and description of external forcing options available in Atlantis