6.30. initial_conditions.nml

This file contains a single namelist called JULES_INITIAL that is used to set up the initial state of prognostic variables.

6.30.1. JULES_INITIAL namelist members

The values of all prognostic variables must be set at the start of a run. This initial state, or initial condition, can be read from a “dump” from an earlier run of the model, or may be read from a different file. Another option is to prescribe a simple or idealised initial state by giving constant values for the prognostic variables directly in the namelist. It is also possible to set some fields using values from a file (e.g. a dump) but to set others to constants given in the namelist.

JULES_INITIAL::dump_file
Type:logical
Default:F

Indicates whether the given file is a dump from a previous run of JULES.

TRUE
The file is a JULES dump file.
FALSE
The file is not a JULES dump file.
JULES_INITIAL::total_snow
Type:logical
Default:F

Switch controlling simplified initialisation of snow variables.

TRUE
Only the total mass of snow on each tile (see snow_tile in List of initial condition variables) is required to be input, and all related variables will be calculated from this or simple assumptions made. All the snow is assumed to be on the ground (not in the canopy).
FALSE
All snow variables required for the current configuration must be input separately (see List of initial condition variables).

Members used to set up spatially varying properties

JULES_INITIAL::file
Type:character
Default:None

The file to read initial conditions from.

If use_file (see below) is FALSE for every variable, this will not be used.

If dump_file = TRUE, this should be a JULES dump file.

If dump_file = FALSE, this should be a file conforming to the JULES input requirements. This file name may use variable name templating.

JULES_INITIAL::nvars
Type:integer
Permitted:>= 0
Default:0

The number of initial condition variables that will be provided.

See List of initial condition variables for those required for a particular configuration.

Note

If dump_file = TRUE and nvars = 0, then the model will attempt to initialise all required variables from the given dump file.

JULES_INITIAL::var
Type:character(nvars)
Default:None

List of initial condition variable names as recognised by JULES (see List of initial condition variables). Names are case sensitive.

Note

For ASCII files, variable names must be in the order they appear in the file.

JULES_INITIAL::use_file
Type:logical(nvars)
Default:T

For each JULES variable specified in var, this indicates if it should be read from the specified file or whether a constant value is to be used.

TRUE
The variable will be read from the file.
FALSE
The variable will be set to a constant value everywhere using const_val below.
JULES_INITIAL::var_name
Type:character(nvars)
Default:‘’ (empty string)

For each JULES variable specified in var where use_file = TRUE, this is the name of the variable in the file containing the data.

If the empty string (the default) is given for any variable, then the corresponding value from var is used instead.

This is not used for variables where use_file = FALSE, but a placeholder must still be given in that case.

Note

For ASCII files, this is not used - only the order in the file matters, as described above.

JULES_INITIAL::tpl_name
Type:character(nvars)
Default:None

For each JULES variable specified in var, this is the string to substitute into the file name in place of the variable name substitution string.

If the file name does not use variable name templating, this is not used.

JULES_INITIAL::const_val
Type:real(nvars)
Default:None

For each JULES variable specified in var where use_file = FALSE, this is a constant value that the variable will be set to at every point in every layer.

This is not used for variables where use_file = TRUE, but a placeholder must still be given.

JULES_INITIAL::l_broadcast_soilt
Type:logical
Default:False

Switch to allow non-soil tiled initial condition data to be broadcast to all soil tiles. This is only used when l_tile_soil is enabled. This helps distribute the model state, for example from a non-soil tiled run into a new run with soil tiling. Spin up of the model state should be considered when using this option.

Note that if l_tile_soil = TRUE and values on soil tiles are available to define the initial state (e.g. from a previous run with soil tiling), l_broadcast_soilt should be set to FALSE. Setting it to TRUE will result in the run failing because it will attempt to read a non-tiled variable.

6.30.1.1. List of initial condition variables

All input to the model must be on the same grid (see Input files for JULES), and initial conditions are no different. Even when the variable is only required for land points, values must be provided for the full input grid. Variables read as initial conditions must have no time dimension.

The variables it is possible to specify as initial conditions can be grouped into ‘types’ depending on the number and size of the levels dimensions they are required to have. For NetCDF files, the dimension names are those specified in the JULES_INPUT_GRID namelist. For variables with no type specified, no levels dimensions should be used.

The required levels dimensions for each initial condition ‘type’ are given in the following table:

Type Number of levels dimensions Levels dimension name(s) Levels dimension size(s)
soil 1 soil_dim_name sm_levels
pft 1 pft_dim_name npft
cpft 1 cpft_dim_name ncpft
type 1 type_dim_name ntype (npft + nnvg)
tile 1 tile_dim_name ntiles (1 if l_aggregate = TRUE, ntype otherwise)
sclayer 1 sclayer_dim_name

Number of soil biogeochemistry layers.

If using the single-pool moodel (soil_bgc_model = 1 ) this is 1.

If using the RothC model (soil_bgc_model = 2) with l_layeredc = FALSE this is 1, else with l_layeredc = TRUE this is equal to sm_levels.

If using the ECOSSE model (soil_bgc_model = 3) this is equal to dim_cslayer.

scpool 2 scpool_dim_name, sclayer_dim_name number of soil carbon pools (1 if soil_bgc_model = 1, 4 otherwise) and number of soil biogeochemistry layers (see sclayer above)
bedrock 1 bedrock_dim_name

ns_deep

Only applicable if l_bedrock = TRUE

snow 2 tile_dim_name, snow_dim_name

ntiles (see above), nsmax

Only applicable if nsmax > 0

The required variables for a particular configuration, along with their ‘type’ as specified above, are given in the following table.

Name Description Type
Always required
canopy Amount of intercepted water that is held on each tile (kg m-2). tile
cs

Soil carbon (kg m-2).

If using the single-pool model (soil_bgc_model = 1), this is the total soil carbon.

Otherwise, this is the carbon in each of the 4 pools of the RothC or ECOSSE models.

scpool
snow_tile

If can_model /= 4, this is the total snow on the tile (since there is a single store which doesn’t distinguish between snow on canopy and under canopy).

If can_model = 4 (and then only at tiles where cansnowpft = TRUE), snow_tile is interpreted as the snow on the canopy, except when overridden by total_snow = TRUE.

If total_snow = TRUE, snow_tile is used to hold the total snow on the tile (and is subsequently put onto the ground at tiles that distinguish between ground and canopy stores).

Further details of snow initialisation are given below.

tile
t_soil Temperature of each soil layer (K). soil
tstar_tile Temperature of each tile (K). This is the surface or skin temperature. tile
Required if can_rad_mod = 1
gs

Surface conductance for water vapour (m s-1).

This is used to start the iterative calculation of gs for the first timestep only.

None
Required if sthuf is not prescribed for all levels in JULES_PRESCRIBED
sthuf Soil wetness for each soil layer. This is the mass of soil water (liquid and frozen), expressed as a fraction of the water content at saturation. soil
Required if l_phenol = TRUE
lai Leaf area index of each PFT. pft
Required if l_triffid = TRUE
canht Height (m) of each PFT. pft
Required if l_veg_compete = TRUE
frac The fraction of land area of each gridbox that is covered by each surface type. type
Required if l_irrig_dmd = TRUE
sthu_irr Unfrozen soil wetness of each layer as a fraction of saturation in irrigated fraction. soil
Required if ncpft > 0
cropdvi Development index for each crop pft. cpft
croprootc Root carbon pool for each crop pft (kg m-2). cpft
cropharvc Carbon in ‘harvest parts’ pool for each crop pft (kg m-2) . cpft
cropreservec Carbon in stem reserves pool for each crop pft (kg m-2). cpft
croplai Leaf area index of each crop pft. cpft
cropcanht Height (m) of each crop pft. cpft
Required if l_top = TRUE
sthzw

Soil wetness in the deep LSH/TOPMODEL layer beneath the standard soil column.

This is the mass of soil water (liquid and frozen), expressed as a fraction of the water content at saturation.

None
zw Depth from the surface to the water table (m). None
Required if l_bedrock = TRUE
tsoil_deep Temperature of each bedrock layer (K) bedrock
Required if l_snow_albedo = TRUE
rgrain Snow surface grain size (μm) on each tile. None
Required if total_snow = FALSE
rho_snow

Bulk density of lying snow (kg m-3).

If total_snow = TRUE then this is set as follows:

tile
snow_depth

Depth of snow (kg m).

If total_snow = TRUE, this is calculated from mass and density of snow.

tile
Required if total_snow = FALSE and can_model = 4
snow_grnd

Amount of snow on the ground, beneath the canopy (kg m-2), on each tile.

If total_snow = TRUE this is set to snow_tile at tiles where can_model = 4 is active, and to zero at all other tiles.

tile
Required if total_snow = FALSE and nsmax > 0
nsnow

The number of snow layers on each tile.

If total_snow = TRUE this is calculated from the snow depth.

tile
snow_ds

Depth of snow in each layer (kg m).

If total_snow = TRUE this is calculated from the snow depth and the number of snow layers.

snow
snow_ice

Mass of frozen water in each snow layer (kg m-2).

If total_snow = TRUE all snow is assumed to be ice.

snow
snow_liq

Mass of liquid water in each snow layer (kg m-2).

If total_snow = TRUE this is set to zero.

snow
tsnow

Temperature of each snow layer (K).

If total_snow = TRUE this is set to the temperature of the top soil layer.

snow
Required if total_snow = FALSE, nsmax > 0 and l_snow_albedo = TRUE
rgrainl

Snow grain size (μm) on each tile in each snow layer.

If total_snow = TRUE this is set to rgrain.

snow
Required if l_triffid = TRUE and l_landuse = TRUE
frac_agr_prev Gridbox agricultural/crop fraction from previous TRIFFID timestep. none
wood_prod_fast Carbon content of the wood products pool with a fast decay rate. none
wood_prod_med Carbon content of the wood products pool with a medium decay rate. none
wood_prod_slow Carbon content of the wood products pool with a slow decay rate. none
Required if l_triffid = TRUE and l_landuse = TRUE and l_trif_crop = TRUE
frac_past_prev Gridbox pasture fraction from previous TRIFFID timestep. none
Required if using RothC (soil_bgc_model = 2) with l_nitrogen = TRUE., or if using ECOSSE (soil_bgc_model = 3) with l_soil_n = TRUE.  
ns Soil nitrogen (kg m-2). scpool
Required if using RothC (soil_bgc_model = 2) and l_nitrogen = TRUE.  
n_inorg Soil inorganic nitrogen (kg m-2). sclayer
Required if using ECOSSE (soil_bgc_model = 3) and l_soil_n = TRUE.  
n_amm Soil ammonium (kg m-2). sclayer
n_nit Soil nitrate (kg m-2). sclayer
Required if l_rivers = TRUE, i_river_vn = ‘2’ and dump_file = TRUE
rfm_surfstore_rp Surface water storage on river routing points (m3) none
rfm_substore_rp Sub-surface water storage on river routing points (m3) none
rfm_flowin_rp Surface flow into a grid box on river routing points (m3) none
rfm_bflowin_rp Sub-surface flow into a grid box on river routing points (m3) none
Required if l_rivers = TRUE, i_river_vn = ‘1,3’ and dump_file = TRUE
rivers_sto_rp Water storage (kg) none

Warning

if l_rivers = TRUE, i_river_vn = ‘2’ and dump_file = FALSE,
rfm_surfstore_rp, rfm_substore_rp, rfm_flowin_rp and rfm_bflowin are initialised to zero.

Warning

if l_rivers = TRUE, i_river_vn = ‘1,3’ and dump_file = FALSE, rivers_sto_rp is initialised to zero.

6.30.2. Examples of specification of initial state

6.30.2.1. Specification of initial state at a single point

This assumes that l_phenol = FALSE, l_triffid = FALSE, soil_bgc_model = 1 and nsmax = 0.

&JULES_INITIAL
  file = "initial_conditions.dat",

  nvars = 8,
  var       = 'canopy'  'tstar_tile'   'cs'  'gs'  'rgrain'  'snow_tile'  'sthuf'  't_soil',
  use_file  =       F             F      F     F         F            F        T         T ,
  const_val =     0.0        276.78   12.1   0.0      50.0          0.0
/

Or using the alternative list syntax (see Introduction to Fortran namelists):

&JULES_INITIAL
  file = "initial_conditions.dat",

  nvars = 8,
  var(1) = 'canopy',      use_file(1) = F,  const_val(1) = 0.0 ,
  var(2) = 'tstar_tile',  use_file(2) = F,  const_val(2) = 276.78,
  var(3) = 'cs',          use_file(3) = F,  const_val(3) = 12.1,
  var(4) = 'gs',          use_file(4) = F,  const_val(4) = 0.0,
  var(5) = 'rgrain',      use_file(5) = F,  const_val(5) = 50.0,
  var(6) = 'snow_tile',   use_file(6) = F,  const_val(6) = 0.0,
  var(7) = 'sthuf',       use_file(7) = T,
  var(8) = 't_soil',      use_file(8) = T,
/

This shows how a mixture of constant values and initial state from a file can be used. In this case, the first 6 variables will be set to constant values everywhere (use_file = FALSE) with the last 2 read from the specified file (use_file = TRUE).

file specifies an ASCII file to read the variables for which use_file = TRUE from.

Since the variables are arranged such that all those with use_file = FALSE are first, we need only supply constant values for those variables that require them.

The contents of initial_conditions.dat should look similar to:

# sthuf(1:4)                    t_soil(1:4)
  0.749  0.743  0.754  0.759    276.78  277.46  278.99  282.48

The data for each soil layer is given in consecutive columns. A comment line is used to indicate which columns comprise which variable (see Input files for JULES for more details).

Specifying initial state for gridded data using NetCDF files is similar, except that:

  • var_name is required for each variable read from file.
  • If variable name templating is used, tpl_name is required for each variable read from file.

6.30.2.2. Specification of initial state from an existing dump file

In this example, we use an existing dump file (from a previous run) to set the initial values of all required variables.

&JULES_INITIAL
  dump_file = T,
  file = "jules_dump.nc"
/

dump_file = TRUE indicates that the given file should be interpreted as a JULES dump file.

file specifies the dump file to read (in this case a NetCDF dump file).

Since it is not specified, nvars takes its default value of 0, which indicates that JULES should attempt to read all required variables from the given dump file.