Definition of available type of substances¶
Each simulated variable in MARS must be identified in a data file where its type is defined. There are 9 types of variables
Dissolved : type DISS
Particulate
- either type GRAV (gravel) (use key_sedim..)
- either type SAND (use key_sedim..)
- either type MUDS (use key_sedim..)
- either type PART
- either type SORB
- either type NoCP
Nota :
GRAV, SAND, MUDS, and PART are « constitutive » variables expressed in kg/m3 if you use key_sedimSORB and NoCP are « non constitutive » variable, expressed in mass/m3, with the mass unit is choose by userSORB is associated with a constitutive particulate variable et has the same particulate behavior.
- Fixed : type FIX : not advected but submitted to biogeochemical reactions (such as algae, oysters ..)
- Driving : type DRIV : not advected but forced (read from a file) in a subroutine writed by the user in usersubstance.F90
- Intermediate : type INTE : not advected but computed (combination of other variables) in a subroutine writed by the user in usersubstance.F90
Definition of number and order (rank) of variables
- The user defines all the variables in the file variable.dat but MARS places then the variables in a specific order : starting with the particulate variables (GRAV, SAND, MUD, PART, SORB, NoCP), then dissolved, then fixed, then intermediate variables.
Summary for implementation MARS with substances¶
Before compilation : cd $UDIR/CONF/CONF-CASE
- in Makefile.caparmor[_rankX] : add -Dkey_substance dans CPPFLAGS
- in parameters.F90[_rank]* : set nb_var : total number of substances
- gmake clean ; gmake
Before running :
cd $RDIR/CONF/CONF-CASE
in parasubs.txt :
- Set the name of the file which defines concentrations or fluxes in rivers and discharges : file_outflow = ‘../inputs/bidon.dat‘
- Set the name of the file which defines variables : name_filesubs = ‘../inputs/variable_cyl.dat’
- Set the start date for substances simulation : date_startsub = ‘01/01/1900 00:00:00’
- Set all the options (see parasubs.txt : namelist for substances )
cd $RDIR/CONF/inputs
- fill the specific additionnal data files for key_substances :
choice Initial conditions
choice Boundaries conditions
If atmospheric deposition : Fluxes or concentrations in atmospheric inputs
If you want an automatic calculation of flows across borders and of balances (stocks and flows) in areas : Massbalance computing (Stocks, fluxes, budgets). (Caution : it costs time calculation)
If you want to save frequently results in certain points (Tracking points)
namelist for substances : parasubs.txt¶
Definition of each variable is given into namelist file : See parasubs.txt : namelist for substances
+--------------+-------------------------------------+------------------+
| namelist | variable | CPPkey |
+--------------+-------------------------------------+------------------+
| namecosys | file_outflow | key_substance |
| | name_filesubs | |
| | filevardiag | |
| | date_startsub | |
| | l_restart_subs | |
| | l_obc_ogcm_rc | |
| | file_obc_subs_s (_n;_w ; _e) | |
| | l_out_log | |
| | l_cvrain_readfile | |
| | l_subflxatm_readfile | |
| | sflx_sub_atm_depth | |
| | l_subflxatm_xyt | |
| | file_flxatm_subs | |
| | l_bilan | |
| | name_bilfil | |
| | dtout_budget | |
| | nb_border | |
| | date_start_budget | |
| | l_driv-cst | |
| | dt_driv | |
+--------------+-------------------------------------+------------------+
variable.dat : Defined simulated substances¶
- The name of the file variable.dat is set in parasubs.txt : namelist for substances (name_filesubs )
- The variables are described one after the other, with a line of stars between each variable.
- The unit of each variable must be defined in mass/m3 or mass/L (or quantity)
- The order in which the variables are described in variable.dat is free, EXCEPT for sands that must be reported in a coarser to the finer.
Note
Examples of variable data file are given in $HOMEMARS/../EXAMPLES/
For ECOMARS : option 1 : variable_biolo_opt1.dat - for option 2 : variable_biolo_opt2.dat.
For SEDIMARS : variable_sedim.dat
Warning
ATTENTION : This documentation corresponds to the newer version V10 (from V10.6)
variable.dat : Dissolved variable
+---------------------------------------------------------+--------------------------------------------------------------------------------------+
| **************************************************** | **************************************************** |
| 1 | number of variable (unused) |
| nitrate | name of variable (unique word) |
| nitrate_NO3 | LONG_NAME of variable (NetCDF OCO format for gridded data products) |
| mole_concentration_of_nitrate_in_sea_water | STANDARD_NAME of variable (NetCDF OCO format for gridded data products) |
| micromoleN.l-1 | unit of concentration of variable |
| -0 | minimum valid value of variable (NetCDF OCO format for gridded data products |
| +100 | maximum valid value of variable (NetCDF OCO format for gridded data products |
| **DISS** | type of variable [GRAV,SAND,MUDS,PART,SORB/NoCP,DISS,FIXE,DRIV,INTE] |
| == if SAND variable : add 2 lines below | |
| == if particulate variable : add 4 more lines | |
| == if state variable : add 5 more lines | |
| 0.000 | t90 (time after which 90% of rejected matter has disappeared) in hours |
| 0.000 | uniform atmospheric deposition (unit/m2/s) (not used for FIXE) |
| 0.000 | concentration in rainwater (unit/m3 of water) |
| 5.00000 | initial concentration in water column (unit/m3) |
| 10.00000 | initial concentration in sediment ( /m3 of pore water if DISS) |
| 0.00 | initial concentration in air ( /m3 ) |
| .true. | saving in output file |
| none | name of substance read from initial conditions file |
| none | name of substance read from boundary conditions file |
| **************************************************** | **************************************************** |
+---------------------------------------------------------+--------------------------------------------------------------------------------------+
variable.dat : Particulate variable : type GRAV
+---------------------------------------------------------+--------------------------------------------------------------------------------------------+
| **************************************************** | ************************************************************************* |
| 1 | number of variable (unused) |
| grav1 | name of variable (unique word) |
| gravel | LONG_NAME of variable (NetCDF OCO format) |
| kg_concentration_of_grave_in_sea_water | STANDARD_NAME of variable (NetCDF OCO format) |
| kg.m-3 | unit of concentration of variable |
| -0 | minimum valid value of variable (NetCDF OCO format) |
| +100 | maximum valid value of variable (NetCDF OCO format) |
| **GRAV** | type of variable [GRAV,SAND,MUDS,PART,SORB/NoCP,DISS,FIXE,DRIV,INTE] |
| == if SAND variable : add 2 lines below | |
| == if GRAV variable : add 3 more lines | |
| 0.00002 | diameter of particle (used only if key_sedim) |
| 10. | critical stress of deposition (used only if key_sedim) |
| 2600. | density of particle (used only if key_sedim) |
| == if state variable : add 6 more lines below | |
| 0.000 | t90 (time after which 90% of rejected matter has disappeared) in hours |
| 0.000 | uniform atmospheric deposition (unit/m2/s) (not used for FIXE) |
| 0.000 | concentration in rainwater (unit/m3 of water) |
| 5.00000 | initial concentration in water column (unit/m3) |
| 10.00000 | initial conc. in sediment (in fract if SAND,GRAV,MUDS,PART;/kg if SORB/NoCP) |
| 0.00000 | initial conc. in air |
| .true. | saving in output file |
| none | name of substance read from initial conditions file |
| none | name of substance read from boundary conditions file |
| **************************************************** | ************************************************************************* |
+---------------------------------------------------------+--------------------------------------------------------------------------------------------+
variable.dat : Particulate variable : type SAND (coarser first, then finer sands)
+---------------------------------------------------------+--------------------------------------------------------------------------------------------+
| **************************************************** | ************************************************************************* |
| 1 | number of variable (unused) |
| sand1 | name of variable (unique word) |
| sand | LONG_NAME of variable (NetCDF OCO format) |
| kg_concentration_of_sand_in_sea_water | STANDARD_NAME of variable (NetCDF OCO format) |
| kg.m-3 | unit of concentration of variable |
| -0 | minimum valid value of variable (NetCDF OCO format) |
| +100 | maximum valid value of variable (NetCDF OCO format) |
| **SAND** | type of variable [GRAV,SAND,MUDS,PART,SORB/NoCP,DISS,FIXE,DRIV,INTE] |
| == if SAND variable : add 2 lines below | |
| .true. | TRUE if this sand variable is treated as 2D variable (used only if key_sand2D) |
| .true. | TRUE if using a ROUSE profil for output in water (only if key_sand2D and l_sand2D=T) |
| == if SAND variable : add 3 more lines | |
| 0.00002 | diameter of particle (used only if key_sedim) |
| 10. | critical stress of deposition (used only if key_sedim) |
| 2600. | density of particle (used only if key_sedim) |
| == if state variable : add 6 more lines below | |
| 0.000 | t90 (time after which 90% of rejected matter has disappeared) in hours |
| 0.000 | uniform atmospheric deposition (unit/m2/s) (not used for FIXE) |
| 0.000 | concentration in rainwater (unit/m3 of water) |
| 5.00000 | initial concentration in water column (unit/m3) |
| 10.00000 | initial conc. in sediment (in fract if SAND,GRAV,MUDS,PART;/kg if SORB/NoCP) |
| 0.00000 | initial conc. in air |
| .true. | saving in output file |
| none | name of substance read from initial conditions file |
| none | name of substance read from boundary conditions file |
| **************************************************** | ************************************************************************* |
+---------------------------------------------------------+--------------------------------------------------------------------------------------------+
variable.dat : Particulate variable : type MUDS or PART
- Settling velocity : only the first two parameters are used if not key_sedim (constant settling velocity).
- See informations about the other parameters in Definition of parameters for particulate-sediment substances in variable.dat
+---------------------------------------------------------+--------------------------------------------------------------------------------------------+
| **************************************************** | ************************************************************************* |
| 1 | number of variable (unused) |
| SPM | name of variable (unique word) |
| suspended_inorganic_particulate_matter | LONG_NAME of variable (NetCDF OCO format) |
| kg_concentration_of_SPM_in_sea_water | STANDARD_NAME of variable (NetCDF OCO format) |
| kg.m-3 | unit of concentration of variable |
| -0 | minimum valid value of variable (NetCDF OCO format) |
| +1000 | maximum valid value of variable (NetCDF OCO format) |
| **MUDS** | type of variable [GRAV,SAND,MUDS,PART,SORB/NoCP,DISS,FIXE,DRIV,INTE] |
| == if SAND variable : add 2 lines below | |
| == if MUDS or PART variable : add 4 more lines | |
| 0 | choice of free settling formulation (0 constant, 1 Van Leussen, 2 Winterwerp, 3 Wolanski) |
| .00001,.00001,.001,1.2,0.0,0.0 | min.setl.vel(m/s), max.setl.vel(m/s), + 4 additional parameters |
| 0 | choice of hindered settling formulation (0 no , 1 Scott, 2 Winterwerp, 3 Wolanski) |
| .000,.00 | 2 additional parameters |
| 0.00002 | diameter of particle (used only if key_sedim) |
| 10. | critical stress of deposition (used only if key_sedim) |
| 2600. | density of particle (used only if key_sedim) |
| == if state variable : add 6 more lines below | |
| 0.000 | t90 (time after which 90% of rejected matter has disappeared) in hours |
| 0.000 | uniform atmospheric deposition (unit/m2/s) (not used for FIXE) |
| 0.000 | concentration in rainwater (unit/m3 of water) |
| 5.00000 | initial concentration in water column (unit/m3) |
| 10.00000 | initial conc. in sediment (in fract if SAND,GRAV,MUDS,PART;/kg if SORB/NoCP) |
| 0.00000 | initial conc. in air |
| .true. | saving in output file |
| none | name of substance read from initial conditions file |
| none | name of substance read from boundary conditions file |
| **************************************************** | ************************************************************************* |
+---------------------------------------------------------+--------------------------------------------------------------------------------------------+
variable.dat : Particulate variable : type SORB
- Settling velocity : give the name of the associated constitutive particulate variable.
+---------------------------------------------------------+--------------------------------------------------------------------------------------------+
| **************************************************** | ************************************************************************* |
| 1 | number of variable (unused) |
| sorbed_phosphate | name of variable (unique word) |
| sorbed_phosphate | LONG_NAME of variable (NetCDF OCO format) |
| mole_concentration_of_sorbed_phosphate_in_sea_water | STANDARD_NAME of variable (NetCDF OCO format) |
| micromole.l-1 | unit of concentration of variable |
| -0 | minimum valid value of variable (NetCDF OCO format) |
| +100 | maximum valid value of variable (NetCDF OCO format) |
| **SORB** | type of variable [GRAV,SAND,MUDS,PART,SORB/NoCP,DISS,FIXE,DRIV,INTE] |
| == if SAND variable : add 2 lines below | |
| == if SORB variable : add 1 more | |
| suspended_inorganic_particulate_matter | name of constitutive particulate variable on which the SORB variable is sorbed |
| == if state variable : add 6 more lines below | |
| 0.000 | t90 (time after which 90% of rejected matter has disappeared) in hours |
| 0.000 | uniform atmospheric deposition (unit/m2/s) (not used for FIXE) |
| 0.000 | concentration in rainwater (unit/m3 of water) |
| 5.00000 | initial concentration in water column (unit/m3) |
| 10.00000 | initial conc. in sediment (in fract if SAND,GRAV,MUDS,PART;/kg if SORB/NoCP) |
| 0.00000 | initial conc. in air |
| .true. | saving in output file |
| none | name of substance read from initial conditions file |
| none | name of substance read from boundary conditions file |
| **************************************************** | ************************************************************************* |
+---------------------------------------------------------+--------------------------------------------------------------------------------------------+
variable.dat : Fixed variable or Driving or Intermediate variable
+---------------------------------------------------------+--------------------------------------------------------------------------------------------+
| **************************************************** | ************************************************************************* |
| 1 | number of variable (unused) |
| cumulative_dinoflagellate_carbon_production | name of variable (unique word) |
| cumulative_dinoflagellate_carbon_production | LONG_NAME of variable (NetCDF OCO format) |
| cumulative_dinoflagellate_prod_expressed_as_carbon | STANDARD_NAME of variable (NetCDF OCO format) |
| g.m-3_from_01jan | unit of concentration of variable |
| -0 | minimum valid value of variable (NetCDF OCO format) |
| +1000000 | maximum valid value of variable (NetCDF OCO format) |
| **FIXE** | type of variable [GRAV,SAND,MUDS,PART,SORB/NoCP,DISS,FIXE,DRIV,INTE] |
| == if SAND variable : add 2 lines below | |
| == if particulate variable : | |
| == if state variable : add 6 more lines below | |
| 0.000 | t90 (time after which 90% of rejected matter has disappeared) in hours |
| 0.000 | uniform atmospheric deposition (unit/m2/s) (not used for FIXE) |
| 0.000 | concentration in rainwater (unit/m3 of water) |
| 0.00000 | initial concentration in water column (unit/m3) |
| 0.00000 | initial conc. in sediment (in fract if SAND,GRAV,MUDS,PART;/kg if SORB/NoCP) |
| 0.00000 | initial conc. in air |
| .true. | saving in output file |
| none | name of substance read from initial conditions file |
| none | name of substance read from boundary conditions file |
| **************************************************** | ************************************************************************* |
+---------------------------------------------------------+--------------------------------------------------------------------------------------------+
Initial conditions¶
- If l_initfromfile = .false. (in paraspec.txt ) : Initial concentrations of substances are uniform throughout the domain and equal to the value read in variable.dat file [initial concentration in water column (unit/m3)]
- If l_initfromfile = .true. (in paraspec.txt ) and l_restart_sub=.true. (in parasubs.txt : namelist for substances ) : Initial concentrations of all substances are read in the file file_init defined in paraspec.txt
- If l_initfromfile = .true. (in paraspec.txt ) and l_restart_sub=.false. (in parasubs.txt : namelist for substances ) : Initial concentrations of substances are read in the file file_init only for substances with the same name (« name of substance read from initial conditions file » in variable.dat ) as in the file_init. For the others (name=none in variable.dat), initial concentration is uniform and equal to the value read in variable.dat file [initial concentration in water column (unit/m3)]
- If required, modify inittssub.F90 to initialize substances
Boundaries conditions¶
- If l_obc_ogcm_rc = .false. (in parasubs.txt : namelist for substances ) :
- concentrations of substances at boundaries are constant and equal to the initial value read in variable.dat file [initial concentration in water column (unit/m3)]
- no obc file to read
- If l_obc_ogcm_rc = .true. (in parasubs.txt : namelist for substances ) :
- concentrations of substances at boundaries are read in files file_obc_subs_n (_s,_e,_w) only for substances with the same name (name of substance read from obc file in variable.dat ) as in the file_obc_subs. For the others (name=none in variable.dat), obc concentration is constant and equal to the initial value read in variable.dat file [initial concentration in water column (unit/m3)]
- If using CPPkey
: key_zerograd,
- zero gradient condition can be applied for some variables, depending on the name given in variable.dat for “name of substance obc read from file”
- for variables “none” : the OBC value for these variables will be constant and equal to the value given initial condition (in variable.dat)
- for variables “zerograd” : the OBC value, when the current enter, is equal to the concentration downstream of the current (“zero gradient”) [example: west limit imin + 1: c (imin + 1) = c (imin + 2)]
- for variables with the “name of variable obc” : the OBC concentration is read from the file if obc l_obc_ogcm_rc = .true. (Otherwise it will be the initial value)
- and there is a relaxation time (the rate at which the boundary condition tends to the value prescribed for the limit depends on the obc_coefrel coefficient given in paraspec.txt. (Relaxation term in s-1).
- If obc_coef rel = 0: boundaries concentrations are equal to the prescribed conditions (initial concentrations)
- If obc_coefrel small: boundaries concentrations slowly tend to the prescribed conditions. Example: relaxation time of 10 days: obc_coefrel = 1 / 10j = 1.1e-6 s-1
- If obc_coefrel great: the concentration limits tend rapidly to the prescribed conditions. Example: relaxation time of 1 hour: obc_coefrel = 1 / = 1h 2.8e-4 s-1
- obc_coefrel should not be greater than 2 / dt
outflow.dat : Discharges fluxes or concentrations in rivers¶
- The name of the file outflow.dat is set in parasubs.txt : namelist for substances (file_outflow)
- Usualy, concentrations data are available in rivers, so river discharge is used jointly with tracer concentration to estimate the flux ; The exact name of the corresponding river must exist in river.dat file. (River Discharges : river.dat)
- If the outflow is a small discharge, only fluxes data are available. In this case, the name of the river relative to the outflow is not used.
outflow.dat :
+---------------------------------------------------------+--------------------------------------------------------------------------------------------+
| **************************************************** | **************************************************** |
| seine | name of outflow |
| .true. | location of outflow : i,j,k (.true.)/lon,lat,k (.false.) |
| 142 45 12 | location_i location_j location_k |
| .false. | flux data (.true.) or concentration data (.false.) |
| seine | name of the river relative to the outflow (needed if concentration data) |
| 1 | number of advected tracer (unused) |
| nitrate | first name of rejected tracer |
| ../../inputs/concentrations/N-NO3-seine.dat | name of file describing the time evolution of the outflow |
| 2 | number of advected tracer (unused) |
| silicium_dissous | name of second rejected tracer |
| ../../inputs/concentrations/Si-seine.dat | name of file describing the time evolution of the outflow |
| **************************************************** | **************************************************** |
+---------------------------------------------------------+--------------------------------------------------------------------------------------------+
Fluxes or concentrations in atmospheric inputs¶
Some substances are present in the atmosphere and deposited on the sea surface via precipitation (wet deposition) and dry deposition.
- Wet deposition is calculated from the concentrations of the substance given in the rainwater; the rainwater fluxes are known in the MARS model (weather forcing).
- Dry deposition is given by a flux (masse/m^2/s).
Wet deposition data is given :
- either in the variable.dat : Defined simulated substances, if an average data, constant and uniform over the entire area is sufficient.
- either in a ASCII file if the value vary with time (but keep uniform) :
- set l_cvrain_readfile=.true. in parasubs.txt : namelist for substances and a non-zero concentration in rainwater in variable.dat : Defined simulated substances for variables whith a time varying rainwater concentration.
- build one data file per variable for rainwater concentrations ; format is the same as in River Discharges : river.dat.
- Names of these files must be constructed as follows cvrain_[name_of_variable].dat
Dry deposition data is given :
either in the variable.dat : Defined simulated substances, if an average data, constant and uniform over the entire area is sufficient.
either in a file if the value vary only with time (but keep uniform) :
- set l_subflxatm_readfile=.true. and l_subflxatm_xyt=.false. in parasubs.txt : namelist for substances and a non-zero deposit in variable.dat : Defined simulated substances for variables whith a time varying dry deposit
- build one data file per variable for dry deposit fluxes ; format is the same as in River Discharges : river.dat.
- Names of these files must be constructed as follows flxatm_[name_of_variable].dat
either in a NetCDF file if spatial data are available.
- the grid is the same as MARS. Interpolation has been made previously from initial file (example : EMEP file)
- MARS interpolate then these data onto time
- set l_subflxatm_readfile=.true. and l_subflxatm_xyt=.true. in parasubs.txt : namelist for substances and a non-zero deposit in variable.dat : Defined simulated substances for variables whith a spatial and time varying dry deposit
- The data file name is given in parasubs.txt : namelist for substances (file_flxatm_subs)