.. _doc.module.substance1.V10: .. _definition_substance: 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_sedim | SORB and NoCP are « **non constitutive** » variable, expressed in **mass/m3**, with the mass unit is choose by user | SORB 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. .. image:: FIG/SUBS/type_variables.jpg .. _implementation_substance: 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 :ref:`doc.parasubs` ) * cd *$RDIR/CONF/inputs* * fill the specific additionnal data files for key_substances : * :ref:`doc_variabledat` * :ref:`river_substance` * choice :ref:`initial_substance` * choice :ref:`boundaries_substance` * If atmospheric deposition : :ref:`atmospheric_substance` * If you want an automatic calculation of flows across borders and of balances (stocks and flows) in areas : :ref:`budget_substance`. (Caution : it costs time calculation) * If you want to save frequently results in certain points (:ref:`tracking_substance`) **namelist for substances** : **parasubs.txt** ----------------------------------------------- Definition of each variable is given into namelist file : See :ref:`doc.parasubs` :: +--------------+-------------------------------------+------------------+ | 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 | | +--------------+-------------------------------------+------------------+ .. _doc_variabledat: **variable.dat** : Defined simulated substances ----------------------------------------------- * The name of the file *variable.dat* is set in :ref:`doc.parasubs` (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 :ref:`definition_parasubstancesed` :: +---------------------------------------------------------+--------------------------------------------------------------------------------------------+ | **************************************************** | ************************************************************************* | | 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_substance: Initial conditions ------------------ * If **l_initfromfile = .false.** (in :ref:`doc.paraspec` ) : 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 :ref:`doc.paraspec` ) and **l_restart_sub=.true.** (in :ref:`doc.parasubs` ) : Initial concentrations of all substances are read in the file *file_init* defined in paraspec.txt * If **l_initfromfile = .true.** (in :ref:`doc.paraspec` ) and **l_restart_sub=.false.** (in :ref:`doc.parasubs` ) : 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_substance: Boundaries conditions ------------------------ * If **l_obc_ogcm_rc = .false.** (in :ref:`doc.parasubs` ) : * 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 :ref:`doc.parasubs` ) : * 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 .. _river_substance: **outflow.dat** : Discharges fluxes or concentrations in rivers ------------------------------------------------------------------ * The name of the file outflow.dat is set in :ref:`doc.parasubs` (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. (:ref:`doc_river`) * 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 | | **************************************************** | **************************************************** | +---------------------------------------------------------+--------------------------------------------------------------------------------------------+ .. _atmospheric_substance: 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 :ref:`doc_variabledat`, 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 :ref:`doc.parasubs` and a non-zero concentration in rainwater in :ref:`doc_variabledat` for variables whith a time varying rainwater concentration. * build one data file per variable for rainwater concentrations ; format is the same as in :ref:`doc_river`. * Names of these files must be constructed as follows **cvrain_[name_of_variable].dat** **Dry deposition data** is given : * either in the :ref:`doc_variabledat`, 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 :ref:`doc.parasubs` and a non-zero deposit in :ref:`doc_variabledat` for variables whith a time varying dry deposit * build one data file per variable for dry deposit fluxes ; format is the same as in :ref:`doc_river`. * 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 :ref:`doc.parasubs` and a non-zero deposit in :ref:`doc_variabledat` for variables whith a spatial and time varying dry deposit * The data file name is given in :ref:`doc.parasubs` (*file_flxatm_subs*)