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: If nsmax = 0, it is set to rho_snow_const. If nsmax > 0 and there is an existing snow pack, it is set to rho_snow_const. If nsmax > 0 and there is no snow pack, it is set to rho_snow_fresh.	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.