6.21. ancillaries.nml
¶
This file sets up spatially varying ancillary values. It contains the following namelists: JULES_FRAC
, JULES_VEGETATION_PROPS
, JULES_SOIL_PROPS
, JULES_TOP
, JULES_PDM
, JULES_AGRIC
, JULES_CROP_PROPS
, JULES_IRRIG_PROPS
, JULES_RIVERS_PROPS
, JULES_OVERBANK_PROPS
, JULES_WATER_RESOURCES_PROPS
, URBAN_PROPERTIES
, JULES_CO2
and JULES_FLAKE
.
Data associated with each of these namelists can optionally be read from the dump file (if present) by setting read_from_dump
to true. This functionality provides closer alignment with UM functionality and can help ensure that the correct ancillary data remain associated with the model state.
6.21.1. JULES_FRAC
namelist members¶
This namelist specifies the fraction of the land area in each gridbox that is covered by each of the surface types. If l_veg_compete
= TRUE, then the fraction of each surface type is modelled and the initial state should be specified in JULES_INITIAL
. In all other cases, it must be read here.
Note that all land points must be either soil points (indicated by values > 0 of the saturated soil moisture content), or land ice points (indicated by the fractional coverage of the ice surface type - if used - being one). The fractional cover of the ice surface type in each gridbox must be either zero or one - there cannot be partial coverage of ice within a gridbox.
If using either URBAN-2T or MORUSES then the total urban fraction can be specified instead of the separate urban_canyon
and urban_roof
contributions. When initialising, if the roof fraction is zero, the canyon fraction will be interpreted as the total urban fraction and be partitioned according to canyon fraction (W/R, see URBAN_PROPERTIES
).
Note
For runs with dynamic vegetation (TRIFFID, l_triffid
= TRUE) and l_veg_compete
= TRUE, then the fraction of each surface type is being modelled and the initial state should be specified in JULES_INITIAL
(which will override any settings given in this section). In all other cases, frac must be read here.
- JULES_FRAC::read_from_dump¶
- Type:
logical
- Default:
F
- TRUE
Populate variables associated with this namelist from the dump file. All other namelist members are ignored.
- FALSE
Use the other namelist members to determine how to populate variables.
- JULES_FRAC::file¶
- Type:
character
- Default:
None
The name of the file to read surface type fractional coverage data from.
- JULES_FRAC::frac_name¶
- Type:
character
- Default:
‘frac’
The name of the variable containing the surface type fractional coverage data.
Note
This is only used for NetCDF files. For ASCII files, the surface type fractional coverage data is expected to be the first (ideally only) variable in the file.
Note
The open water fraction of this array (given by
lake
) should contain permanent water, and wetland extents that are not being otherwise simulated. If groundwater inundation is being simulated (i.e. TOPMODEL is activel_top
= TRUE and therefore fsat is being calculated) then all groundwater-maintained wetlands must be excluded fromfrac_name
. If overbank inundation is being simulated (i.e.l_riv_overbank
= TRUE) then all fluvial wetlands must be excluded fromfrac_name
. Finally, note that simulation of a potential future climate scenario with greatly reduced areas for lakes that are currently ‘permanent’ would require suitable modification of the ancillary provided here.In the file, the variable must have a single levels dimension of size
ntype
calledtype_dim_name
, and should not have a time dimension.
6.21.2. JULES_VEGETATION_PROPS
namelist members¶
This namelist specifies how spatially-varying properties of vegetation should be set.
At present only one variable - t_home_gb
- can be specified via this namelist, and this is only required if thermal adaptation of photosynthetic capacity is selected (photo_acclim_model
= 1 or 3).
Note that Leaf Area Index and vegetation height are specified elsewhere - see JULES_PRESCRIBED
.
- JULES_VEGETATION_PROPS::read_from_dump¶
- Type:
logical
- Default:
F
- TRUE
Populate variables associated with this namelist from the dump file. All other namelist members are ignored.
- FALSE
Use the other namelist members to determine how to populate variables.
- JULES_VEGETATION_PROPS::file¶
- Type:
character
- Default:
None
The file to read vegetation properties from.
If
use_file
is FALSE for every variable, this will not be used.This file name can use variable name templating.
- JULES_VEGETATION_PROPS::nvars¶
- Type:
integer
- Permitted:
>= 0
- Default:
0
The number of vegetation property variables that will be provided (see List of vegetation parameters).
- JULES_VEGETATION_PROPS::var¶
- Type:
character(nvars)
- Default:
None
List of vegetation variable names as recognised by JULES (see List of vegetation parameters). Names are case sensitive.
Note
For ASCII files, variable names must be in the order they appear in the file.
- JULES_VEGETATION_PROPS::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_VEGETATION_PROPS::var_name¶
- Type:
character(nvars)
- Default:
‘’ (empty string)
For each JULES variable specified in
var
whereuse_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_VEGETATION_PROPS::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_VEGETATION_PROPS::const_val¶
- Type:
real(nvars)
- Default:
None
For each JULES variable specified in
var
whereuse_file
= FALSE, this is a constant value that the variable will be set to at every point.This is not used for variables where
use_file
= TRUE, but a placeholder must still be given in that case.
6.21.2.1. List of vegetation parameters¶
Name |
Description |
---|---|
|
Average temperature (home temperature) for thermal adaptation of photosynthetic capacity (K), e.g. a multi-decadal average or pre-industrial temperature. Suggestions as to how to calculate a suitable temperature can be found in Kattge and Knorr (2007) or Kumarathunge et al (2019). This variable should not have a time dimension nor any “levels” dimension. |
6.21.3. JULES_SOIL_PROPS
namelist members¶
This namelist specifies how spatially varying soil properties should be set.
- JULES_SOIL_PROPS::read_from_dump¶
- Type:
logical
- Default:
F
- TRUE
Populate variables associated with this namelist from the dump file. All other namelist members are ignored.
- FALSE
Use the other namelist members to determine how to populate variables.
- JULES_SOIL_PROPS::const_z¶
- Type:
logical
- Default:
F
Switch indicating if soil properties are to be uniform with depth.
- TRUE
Soil characteristics do not vary with depth.
- FALSE
Soil characteristics vary with depth. For any variable this is ignored if a constant value is to be used (see
const_val
).
- JULES_SOIL_PROPS::file¶
- Type:
character
- Default:
None
The file to read soil properties from.
If
use_file
is FALSE for every variable, this will not be used.This file name can use variable name templating.
- JULES_SOIL_PROPS::nvars¶
- Type:
integer
- Permitted:
>= 0
- Default:
0
The number of soil property variables that will be provided (see List of soil parameters).
- JULES_SOIL_PROPS::var¶
- Type:
character(nvars)
- Default:
None
List of soil variable names as recognised by JULES (see List of soil parameters). Names are case sensitive.
Note
For ASCII files, variable names must be in the order they appear in the file.
- JULES_SOIL_PROPS::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_SOIL_PROPS::var_name¶
- Type:
character(nvars)
- Default:
‘’ (empty string)
For each JULES variable specified in
var
whereuse_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_SOIL_PROPS::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_SOIL_PROPS::const_val¶
- Type:
real(nvars)
- Default:
None
For each JULES variable specified in
var
whereuse_file
= FALSE, this is a constant value that the variable will be set to at every point in every layer (overridingconst_z
= FALSE).This is not used for variables where
use_file
= TRUE, but a placeholder must still be given in that case.
6.21.3.1. List of soil parameters¶
If const_z
= FALSE, variables read from file must have a single levels dimension. For most variables this dimension must be of size sm_levels
and called soil_dim_name
; exceptions to this rule are indicated in the table below.
If const_z
= TRUE, variables read from file must have no levels dimensions.
If soil tiling is selected (l_tile_soil
= TRUE), ancillary fields can be specified for each soil tile (l_broadcast_ancils
= FALSE), or values can be read for one soil tile and copied to all tiles (l_broadcast_ancils
= TRUE).
In all cases, the variables must have no time dimension.
Name |
Description |
Levels name |
---|---|---|
|
Soil albedo. A single (averaged) waveband is used. |
None |
|
|
|
|
Dry heat capacity (J m-3 K-1). |
|
|
Dry thermal conductivity (W m-1 K-1). |
|
|
Hydraulic conductivity at saturation (kg m-2 s-1). |
|
|
If If |
|
|
Volumetric soil moisture content at the critical point (m3 water per
m3 soil). If
|
|
|
Volumetric soil moisture content at saturation (m3 water per m3 soil). Note This field is used to distinguish between soil points and land ice points.
|
|
|
Volumetric soil moisture content at the wilting point (m3 water
per m3 soil). If
|
|
|
Soil clay content (g clay per g soil). Only required for the 4-pool and ECOSSE soil
carbon models ( Note To allow backwards compatibility when using the 4-pool model
( However, this is wrong - if it is not available it should be set to 0.23. |
|
|
Soil pH. Only required for the ECOSSE soil carbon model
( |
6.21.4. JULES_TOP
namelist members¶
This namelist reads spatially varying parameter values for the TOPMODEL-type parameterisation of runoff. The values are only used if l_top
= TRUE. The description below is very brief. For further details, see the references under l_top
.
- JULES_TOP::read_from_dump¶
- Type:
logical
- Default:
F
- TRUE
Populate variables associated with this namelist from the dump file. All other namelist members are ignored.
- FALSE
Use the other namelist members to determine how to populate variables.
- JULES_TOP::file¶
- Type:
character
- Default:
None
The file to read TOPMODEL properties from.
If
use_file
is FALSE for every variable, this will not be used.This file name can use variable name templating.
- JULES_TOP::nvars¶
- Type:
integer
- Permitted:
>= 0
- Default:
0
The number of TOPMODEL property variables that will be provided. At present, all variables are required for runs using TOPMODEL (see List of TOPMODEL parameters).
- JULES_TOP::var¶
- Type:
character(nvars)
- Default:
None
List of TOPMODEL variable names as recognised by JULES (see List of TOPMODEL parameters). Names are case sensitive.
Note
For ASCII files, variable names must be in the order they appear in the file.
- JULES_TOP::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_TOP::var_name¶
- Type:
character(nvars)
- Default:
‘’ (empty string)
For each JULES variable specified in
var
whereuse_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_TOP::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_TOP::const_val¶
- Type:
real(nvars)
- Default:
None
For each JULES variable specified in
var
whereuse_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 in that case.
6.21.4.1. List of TOPMODEL parameters¶
All of the TOPMODEL variables listed below are expected to have no levels dimensions and no time dimension.
Name |
Description |
---|---|
|
Decay factor describing how the saturated hydraulic conductivity decreases with depth below the standard soil column (m-1). Routinely set between 2 and 3 m-1. Gedney & Cox (2003, J Hydromet) used value 0.5 m-1; Niu & Yang (2003, Global & Planet. Change) suggested a global mean value of 2.0 m-1. |
|
(Spatial, not temporal) mean value of the topographic index in each gridbox. Value 5.99 is the global mean given in Marthews et al. (2015, HESS) |
|
(Spatial, not temporal) standard deviation of the topographic index in each gridbox. Values <0.5 are updated to =0.5 internally to allow at least some variability |
6.21.5. JULES_PDM
namelist members¶
This namelist reads spatially varying parameter values for the PDM-type parameterisation of runoff. The values are only used if l_pdm
= TRUE. The description below is very brief. For further details, see the references under l_pdm
.
- JULES_PDM::file¶
- Type:
character
- Default:
None
The file to read PDM properties from.
If
use_file
is FALSE for every variable, this will not be used.This file name can use variable name templating.
- JULES_PDM::nvars¶
- Type:
integer
- Permitted:
>= 0
- Default:
0
The number of PDM property variables that will be provided (see List of PDM parameters). At present, only the topographic slope can be provided.
- JULES_PDM::var¶
- Type:
character(nvars)
- Default:
None
List of PDM variable names as recognised by JULES (see List of PDM parameters). Names are case sensitive.
Note
For ASCII files, variable names must be in the order they appear in the file.
- JULES_PDM::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_PDM::var_name¶
- Type:
character(nvars)
- Default:
None
For each JULES variable specified in
var
whereuse_file
= TRUE, this is the name of the variable in the file containing the data.This is not used for variables where
use_file
= FALSE, but a placeholder must still be given.Note
For ASCII files, this is not used - only the order in the file matters, as described above.
- JULES_PDM::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_PDM::const_val¶
- Type:
real(nvars)
- Default:
None
For each JULES variable specified in
var
whereuse_file
= FALSE, this is a constant value that the variable will be set to at every point in every layer. make html This is not used for variables whereuse_file
= TRUE, but a placeholder must still be given.
6.21.5.1. List of PDM parameters¶
All of the PDM variables listed below are expected to have no levels dimensions and no time dimension.
Name |
Description |
---|---|
|
Mean value of the topographic slope in the gridbox (deg). |
6.21.6. JULES_AGRIC
namelist members¶
If the TRIFFID vegetation model is used, the fractional area of agricultural land in each gridbox is specified using this namelist. Otherwise, the values in this namelist are not used.
- JULES_AGRIC::read_from_dump¶
- Type:
logical
- Default:
F
- TRUE
Populate frac_agr, frac_past, and frac_biocrop from the dump file. All other namelist members are ignored.
- FALSE
Use the other namelist members to determine how to populate variables.
- JULES_AGRIC::zero_agric¶
- Type:
logical
- Default:
T
Switch used to simplify the initialisation of agricultural fraction.
- TRUE
Set agricultural fraction at all points to zero.
- FALSE
Set agricultural fraction using specified data.
Used if zero_agric
= FALSE and the input grid consists of a single location
- JULES_AGRIC::frac_agr¶
- Type:
real
- Default:
None
The agricultural fraction for the single location.
Used if zero_agric
= FALSE and the input grid consists of more than one location
- JULES_AGRIC::file¶
- Type:
character
- Default:
None
The name of the file to read agricultural fraction data from.
- JULES_AGRIC::agric_name¶
- Type:
character
- Default:
‘frac_agr’
The name of the variable containing the agricultural fraction data.
In the file, the variable must have no levels dimensions and no time dimension.
- JULES_AGRIC::zero_past¶
- Type:
logical
- Default:
T
Switch used to simplify the initialisation of pasture fraction. Pasture fraction can only be used if
l_trif_crop
is TRUE.- TRUE
Set pasture fraction at all points to zero.
- FALSE
Set pasture fraction using specified data.
Used if zero_past
= FALSE and the input grid consists of a single location
- JULES_AGRIC::frac_past¶
- Type:
real
- Default:
None
The pasture fraction for the single location.
Used if zero_past
= FALSE and the input grid consists of more than one location
- JULES_AGRIC::file_past¶
- Type:
character
- Default:
None
The name of the file to read pasture fraction data from.
- JULES_AGRIC::pasture_name¶
- Type:
character
- Default:
‘frac_past’
The name of the variable containing the pasture fraction data.
In the file, the variable must have no levels dimensions and no time dimension.
- JULES_AGRIC::zero_biocrop¶
- Type:
logical
- Default:
T
Switch used to simplify the initialisation of bioenergy fraction. Bioenergy fraction can only be used if
l_trif_biocrop
is TRUE.- TRUE
Set bioenergy fraction at all points to zero.
- FALSE
Set bioenergy fraction using specified data.
Used if zero_biocrop
= FALSE and the input grid consists of a single location
- JULES_AGRIC::frac_biocrop¶
- Type:
real
- Default:
None
The bioenergy fraction for the single location.
Used if zero_biocrop
= FALSE and the input grid consists of more than one location
- JULES_AGRIC::file_biocrop¶
- Type:
character
- Default:
None
The name of the file to read bioenergy fraction data from.
- JULES_AGRIC::biocrop_name¶
- Type:
character
- Default:
‘frac_biocrop’
The name of the variable containing the bioenergy fraction data.
In the file, the variable must have no levels dimensions and no time dimension.
Specify the day of year on which harvesting occurs. Only used if l_trif_biocrop
= TRUE. A placeholder value must be set for all PFTs, though will only be used for PFTs with harvest_type_io
= 2.
- JULES_AGRIC::read_harvest_doy_from_dump¶
- Type:
logical
- Default:
F
- TRUE
Populate harvest_doy from the dump file. All other namelist members are ignored.
- FALSE
Use the other namelist members to determine how to populate variables.
- JULES_AGRIC::file_harvest_doy¶
- Type:
character
- Default:
None
The name of the file to read harvest day-of-year data from.
- JULES_AGRIC::harvest_doy_name¶
- Type:
character
- Default:
‘harvest_doy’
The name of the variable containing the harvest day-of-year data.
Note
This is only used for NetCDF files. For ASCII files, the harvest day-of-year data is expected to be the first (ideally only) variable in the file.
6.21.7. JULES_CROP_PROPS
namelist members¶
- JULES_CROP_PROPS::read_from_dump¶
- Type:
logical
- Default:
F
- TRUE
Populate variables associated with this namelist from the dump file. All other namelist members are ignored.
- FALSE
Use the other namelist members to determine how to populate variables.
- JULES_CROP_PROPS::file¶
- Type:
character
- Default:
None
The file from which crop properties are read.
If
use_file
is FALSE for every variable, this will not be used.This file name can use variable name templating.
- JULES_CROP_PROPS::nvars¶
- Type:
integer
- Permitted:
>= 0
- Default:
0
The number of crop property variables that will be provided (see List of spatially-varying crop properties).
- JULES_CROP_PROPS::var¶
- Type:
character(nvars)
- Default:
None
List of variable names for spatially-varying crop properties as recognised by JULES (see List of spatially-varying crop properties). Names are case sensitive.
Note
For ASCII files, variable names must be in the order they appear in the file.
- JULES_CROP_PROPS::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_CROP_PROPS::var_name¶
- Type:
character(nvars)
- Default:
‘’ (empty string)
For each JULES variable specified in
var
whereuse_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_CROP_PROPS::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_CROP_PROPS::const_val¶
- Type:
real(nvars)
- Default:
None
For each JULES variable specified in
var
whereuse_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 in that case.
6.21.7.1. List of spatially-varying crop properties¶
All of the crop variables listed below are expected to have a single levels dimension of size ncpft
called cpft_dim_name
.
Name |
Description |
---|---|
|
The sowing date for each crop. The sowing date should be a real number, with If a crop requires two sowing dates per year, it should be treated as two separate crops with identical parameters apart from the sowing date. Note Only required if |
|
Thermal time between emergence and flowering (degree days). |
|
Thermal time between flowering and maturity/harvest (degree days). |
|
The latest possible harvest date for each crop.
croplatestharvdate is only a required variable when
croplatestharvdate is not a required variable when
croplatestharvdate is not a required variable and is only used if provided as an ancillary when
|
See also
References:
Osborne et al, JULES-crop: a parametrisation of crops in the Joint UK Land Environment Simulator, Geosci. Model Dev., 8, 1139-1155, 2015.
Mathison et al, ‘Developing a sequential cropping capability in the JULESvn5.2 land–surface model’, Geosci. Model Dev. Discuss., https://doi.org/10.5194/gmd-2019-85, in review, 2019
6.21.8. JULES_IRRIG_PROPS
namelist members¶
This namelist specifies the options available for initialising irrigated fraction.
- JULES_IRRIG_PROPS::read_from_dump¶
- Type:
logical
- Default:
F
- TRUE
Populate variables associated with this namelist from the dump file. All other namelist members are ignored.
- FALSE
Use the other namelist members to determine how to populate variables.
- JULES_IRRIG_PROPS::read_file¶
- Type:
logical
- Default:
T
Indicates if irrigated fraction is to be read from file.
- TRUE
Irrigated fraction is read from the file specified in
irrig_frac_file
.- FALSE
Irrigated fraction is set to the constant value specified in
const_frac_irr
.
- JULES_IRRIG_PROPS::irrig_frac_file¶
- Type:
character
- Default:
None
The file from which irrigation fractions are read, including path.
- JULES_IRRIG_PROPS::var_name¶
- Type:
character
- Default:
‘frac_irig’
The name of the variable containing the irrigated fraction data.
Note
This is only used for NetCDF files. For ASCII files, the irrigated fraction data is expected to be the first (ideally only) variable in the file.
In the file, the variable must have no levels or time dimensions.
- JULES_IRRIG_PROPS::const_frac_irr¶
- Type:
real
- Default:
none
The constant irrigated fraction to be applied to all grid points.
- JULES_IRRIG_PROPS::const_irrfrac_irrtiles¶
- Type:
real
- Default:
none
The constant irrigated fraction to be applied to specific surface tiles given in
irrigtiles
.
6.21.9. JULES_RIVERS_PROPS
namelist members¶
This namelist specifies how spatially varying river routing properties should be set.
Note
read_from_dump
is not currently implemented for this namelist, although initial condition variables can be read from a dump file if i_river_vn
is 1
, 2
, or 3
(see JULES_INITIAL
).
Note
The river routing code in JULES is still in development. Users should ensure that results are as expected, and provide feedback where deficiencies are identified.
Note
The grid on which the river routing will run, and on which river routing ancillaries must be provided, could potentially differ from the input/model grid specified in model_grid.nml.
For the duration of this document, the following nomenclature will be used:
Model input grid - The full JULES input grid specified in
JULES_INPUT_GRID
.River routing input grid - The grid on which river routing ancillaries will be provided
Currently, information about the river routing input grid and its relationship to the model input grid is specified in JULES_RIVERS_PROPS
.
While the model input can be defined on a 1D grid, the river routing input grid must be defined on a 2D grid, as defined through the x and y dimensions of the rivers ancillary file. See x_dim_name
and y_dim_name
for further details. If a non-regular model and river routing input grid is used, both the x and y dimensions and corresponding latitude and longitude values must be specified for each grid point.
However, internally JULES converts the river routing input grid to a 1D river routing model grid, with length np_rivers
, which is the number of valid routing points in the river routing ancillaries. All river routing output is either defined on the 1D river routing model grid or is regridded to the model grid.
For some applications, the model input and river routing input grids may not be coincident. Note that functionality only currently exists to regrid between regular (but non-identical) model input and river routing input grids. If a non-regular model input grid is specified, it is assumed that the model input and river routing input grids will be coincident.
Members used to define the river routing input grid
- JULES_RIVERS_PROPS::rivers_reglatlon¶
- Type:
logical
- Default:
T
Flag indicating if the river routing input grid is regular in latitude and longitude.
- TRUE
River routing input grid is regular in latitude and longitude.
- FALSE
River routing input grid is not regular in latitude and longitude (e.g. grid defined relative to a rotated pole, Ordnance Survey (British) National Grid (BNG) OSGB36, etc). Only
i_river_vn
=2
should be used in this case. Note that the model input and river routing input grids must be coincident in this case andrivers_regrid
must also be set to false.
- JULES_RIVERS_PROPS::coordinate_file¶
- Type:
character
- Default:
None
The file from which to read coordinate information for the river routing input grid. This is only used when
file
includes variable-name templating, i.e. it is only used when ancillary variables will come from multiple files, in which case this variable is used to provide clarity as to where the coordinates are read from.
- JULES_RIVERS_PROPS::x_dim_name¶
- Type:
character
- Default:
None
The name of the x dimension for the river routing input grid (it may, but does not have to, coincide with
x_dim_name
).Note
For ASCII files, this can be anything. For NetCDF files, it should be the name of the dimension in
file
(if that does not include variable-name templating) or incoordinate_file
(iffile
includes templating).Warning
Values for the x dimension of the river routing input grid will need to be read from the input file to define the grid, so it is assumed that the file contains a variable of the same name. If a non-regular river routing input grid is used, a 2D longitude field will also be needed to define the x-location of each grid point, read in via the longitude_2d ancillary field.
- JULES_RIVERS_PROPS::y_dim_name¶
- Type:
character
- Default:
None
The name of the y dimension for the river routing input grid (it may, but does not have to, coincide with
y_dim_name
).Note
For ASCII files, this can be anything. For NetCDF files, it should be the name of the dimension in
file
(if that does not include variable-name templating) or incoordinate_file
(iffile
includes templating).Warning
Values for the y dimension of the river routing input grid will need to be read from the input file to define the grid, so it is assumed that the file contains a variable of the same name. If a non-regular river routing input grid is used, a 2D latitude field will also be needed to define the y-location of each grid point, read in via the latitude_2d ancillary field.
- JULES_RIVERS_PROPS::nx¶
- Type:
integer
- Permitted:
>= 1
- Default:
None
The size of the x dimension of the river routing input grid.
- JULES_RIVERS_PROPS::ny¶
- Type:
integer
- Permitted:
>= 1
- Default:
None
The size of the y dimension of the river routing input grid.
Members used to define the relationship between the model input grid and the river routing input grid
- JULES_RIVERS_PROPS::rivers_regrid¶
- Type:
logical
- Default:
T
Flag indicating if the model input and river routing input grids are identical, i.e. whether regridding of variables to and from the river routing input grid is required. Note this is only currently possible if
rivers_reglatlon
is TRUE.- TRUE
River routing input and model input grids differ and regridding is required.
- FALSE
River routing input and model input grids are identical.
Warning
Currently, regridding between model input and river routing input grids must only be used with regular lat/lon model input and river routing input grids.
If a 1D model input grid is specified in
JULES_INPUT_GRID
, it must be possible to define a 2D regular lat/lon grid containing all the points in the model input grid. This is done using the variables below.
An example with the GSWP2 (land points only) forcing data is given below.
Only used when JULES_INPUT_GRID::grid_is_1d
= TRUE or for a parallel standalone run.
- JULES_RIVERS_PROPS::nx_grid¶
- Type:
integer
- Permitted:
>= 1
- Default:
The size of the x dimension of the 2D regular lat/lon grid containing the model input grid.
- JULES_RIVERS_PROPS::ny_grid¶
- Type:
integer
- Permitted:
>= 1
- Default:
The size of the y dimension of the 2D regular lat/lon grid containing the model input grid.
- JULES_RIVERS_PROPS::reg_lat1¶
- Type:
real
- Default:
Latitude of lower-left corner of river routing input grid
The latitude of the lower-left corner of the 2D regular lat-lon grid containing the model input grid.
- JULES_RIVERS_PROPS::reg_lon1¶
- Type:
real
- Default:
Longitude of lower-left corner of river routing input grid
The longitude of the lower-left corner of the 2D regular lat/lon grid containing the model input grid.
- JULES_RIVERS_PROPS::reg_dlat¶
- Type:
real
- Default:
Latitude spacing of river routing input grid
The latitude spacing of the 2D regular lat/lon grid containing the model input grid.
- JULES_RIVERS_PROPS::reg_dlon¶
- Type:
real
- Default:
Longitude spacing of river routing input grid
The longitude spacing of the 2D regular lat/lon grid containing the model input grid.
Only used when rivers_reglatlon
= FALSE
- JULES_RIVERS_PROPS::rivers_dx¶
- Type:
real
- Permitted:
> 0
- Default:
0
The constant size of the rivers grid (in m) if non-regular in latitude/longitude (e.g. if defined in Ordnance Survey (British) National Grid (BNG) OSGB36 coordinates).
Members used to determine how river routing variables are set
- JULES_RIVERS_PROPS::file¶
- Type:
character
- Default:
None
The file to read river routing properties from.
If
use_file
is FALSE for every variable, this will not be used.This file name can use variable name templating.
- JULES_RIVERS_PROPS::nvars¶
- Type:
integer
- Permitted:
>= 0
- Default:
0
The number of river routing property variables that will be provided (see List of rivers properties).
For RFM, at least direction is currently required
For TRIP, at least direction and sequence are required
- JULES_RIVERS_PROPS::var¶
- Type:
character(nvars)
- Default:
None
List of river routing variable names as recognised by JULES (see List of rivers properties). Names are case sensitive.
Note
For ASCII files, variable names must be in the order they appear in the file.
- JULES_RIVERS_PROPS::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_RIVERS_PROPS::var_name¶
- Type:
character(nvars)
- Default:
‘’ (empty string)
For each JULES variable specified in
var
whereuse_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_RIVERS_PROPS::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_RIVERS_PROPS::const_val¶
- Type:
real(nvars)
- Default:
None
For each JULES variable specified in
var
whereuse_file
= FALSE, this is a constant value that the variable will be set to at every point.This is not used for variables where
use_file
= TRUE, but a placeholder must still be given in that case.
6.21.9.1. Example¶
The following gives an example of how you would set up the namelists to use routing with the GSWP2 forcing data.
The model input grid is the GSWP2 grid, i.e. a land-points-only, 1D grid where points lie on a 1° x 1° grid. The river routing input grid is a 2D 1° x 1° grid.
Since both grids are 1° x 1°, we define the 2D regular lat-lon grid containing the model input grid to be the river routing input grid, which means we don’t need any regridding of variables.
&JULES_INPUT_GRID
grid_is_1d = T,
npoints = 15238,
grid_dim_name = "land"
# ...
/
# ...
&JULES_RIVERS_PROPS
# Define the river routing input grid to be a 2D regular lat-lon grid
rivers_reglatlon = T,
x_dim_name = "longitude",
nx = 360,
y_dim_name = "latitude",
ny = 180,
# Define the 2D regular lat-lon grid containing the model input grid to be a 2D 1\ |deg| x 1\ |deg| grid
nx_grid = 360,
ny_grid = 180,
reg_lat1 = -89.5,
reg_lon1 = -179.5,
reg_dlat = 1.0,
reg_dlon = 1.0,
# No regridding required since the river routing input grid is the same as the 2D regular lat-lon grid containing the model input grid
rivers_regrid = F
/
6.21.9.2. List of rivers properties¶
The following table summarises river routing input grid properties required to run RFM or TRIP river routing algorithms, specified from an ancillary file if use_file
= TRUE.
Name |
Description |
---|---|
|
Drainage area (in number of grid boxes) draining into a given grid box. This is used if If this field is not available, all points are treated as rivers. The drainage area does not include the grid point itself, and so an extra point must be added where catchment area calculations are required. |
|
Flow direction for each river routing grid box, defining the next grid box into which surface or sub-surface water will be routed. This is specified as an integer according to Although these are referred to via compass directions, they are used as “grid-relative” directions. e.g. “N” means “same column, one row up”, “E” means “one column over, same row”. Thus for a rotated grid (columns do not run S-N on the Earth), the point “same column, one row up” does does not lie immediately N. Additionally, 9: river mouth (outflow to sea) 10: inland drainage point (an endorheic catchment; no outflow from grid box) All other values (<1 or >10) are excluded from the river calculations (effectively treated as sea). Note that at present any river flow at an inland drainage point is NOT added to the soil moisture (in standalone JULES). |
|
River routing network pathway number. Used by TRIP river routing only (i.e. |
|
If |
|
If |
See also
References:
Bell, V.A. et al. (2007) Development of a high resolution grid-based river flow model for use with regional climate model output. Hydrology and Earth System Sciences. 11 532-549
Oki, T., et al (1999) Assessment of annual runoff from land surface models using Total Runoff Integrating Pathways (TRIP). Journal of the Meteorological Society of Japan. 77 235-255
6.21.10. JULES_OVERBANK_PROPS
namelist members¶
This namelist specifies how the river overbank inundation properties should be set.
Note
read_from_dump
is not currently implemented for this namelist.
Note
The grid here MUST coincide exactly with the river routing input grid specified in JULES_RIVERS_PROPS
.
Members used to determine how overbank inundation variables are set
- JULES_OVERBANK_PROPS::file¶
- Type:
character
- Default:
None
The file to read overbank inundation properties from (can be the same file as specified in
JULES_RIVERS_PROPS
).If
use_file
is FALSE for every variable, this will not be used.This file name can use variable name templating.
- JULES_OVERBANK_PROPS::nvars¶
- Type:
integer
- Permitted:
>= 0
- Default:
0
The number of overbank inundation property variables that will be provided (see List of overbank inundation properties).
- JULES_OVERBANK_PROPS::var¶
- Type:
character(nvars)
- Default:
None
List of overbank inundation variable names as recognised by JULES (see List of overbank inundation properties). Names are case sensitive.
Note
For ASCII files, variable names must be in the order they appear in the file.
- JULES_OVERBANK_PROPS::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_OVERBANK_PROPS::var_name¶
- Type:
character(nvars)
- Default:
‘’ (empty string)
For each JULES variable specified in
var
whereuse_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_OVERBANK_PROPS::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_OVERBANK_PROPS::const_val¶
- Type:
real(nvars)
- Default:
None
For each JULES variable specified in
var
whereuse_file
= FALSE, this is a constant value that the variable will be set to at every point.This is not used for variables where
use_file
= TRUE, but a placeholder must still be given in that case.
6.21.10.1. List of overbank inundation properties¶
The following table summarises overbank inundation grid properties, specified from an ancillary file if use_file
= TRUE.
Name |
Description |
---|---|
|
Mean of ln(elevation-elev_min) for each grid cell (in units ln(m)) This is only used if Note that elev_min is DEM minimum, not river/lake bed level (therefore large values close to water bodies can occur in floodplain gridcells) |
|
Standard deviation of ln(elevation-elev_min) for each grid cell (in units ln(m)) This is only used if |
See also
References:
Appx B of Lewis HW, Castillo Sanchez JM, Graham J, Saulter A, Bornemann J, Arnold A, Fallmann J, Harris C, Pearson D, Ramsdale S, Martínez de la Torre A, Bricheno L, Blyth E, Bell VA, Davies H, Marthews TR, O’Neill C, Rumbold H, O’Dea E, Brereton A, Guihou K, Hines A, Butenschon M, Dadson SJ, Palmer T, Holt J, Reynard N, Best M, Edwards J & Siddorn J (2018). The UKC2 regional coupled environmental prediction system. Geoscientific Model Development 11:1-42.
6.21.11. JULES_WATER_RESOURCES_PROPS
namelist members¶
This namelist specifies how the water resource ancillary properties should be set.
Members used to determine how water resource variables are set
- JULES_WATER_RESOURCES_PROPS::read_from_dump¶
- Type:
logical
- Default:
F
- TRUE
Populate variables associated with this namelist from the dump file. All other namelist members are ignored.
- FALSE
Use the other namelist members to determine how to populate variables.
- JULES_WATER_RESOURCES_PROPS::file¶
- Type:
character
- Default:
None
The file to read water resource ancillary properties from.
If
use_file
is FALSE for every variable, this will not be used.This file name can use variable name templating.
- JULES_WATER_RESOURCES_PROPS::nvars¶
- Type:
integer
- Permitted:
>= 0
- Default:
0
The number of water resource property variables that will be provided (see List of water resources properties).
- JULES_WATER_RESOURCES_PROPS::var¶
- Type:
character(nvars)
- Default:
None
List of water resource variable names as recognised by JULES (see List of water resources properties). Names are case sensitive.
Note
For ASCII files, variable names must be in the order they appear in the file.
- JULES_WATER_RESOURCES_PROPS::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_WATER_RESOURCES_PROPS::var_name¶
- Type:
character(nvars)
- Default:
‘’ (empty string)
For each JULES variable specified in
var
whereuse_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_WATER_RESOURCES_PROPS::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_WATER_RESOURCES_PROPS::const_val¶
- Type:
real(nvars)
- Default:
None
For each JULES variable specified in
var
whereuse_file
= FALSE, this is a constant value that the variable will be set to at every point.This is not used for variables where
use_file
= TRUE, but a placeholder must still be given in that case.
6.21.11.1. List of water resources properties¶
The following table summarises ancillary fields for the water resources code, specified from an ancillary file if use_file
= TRUE.
Name |
Description |
---|---|
|
Fraction of water that is lost during conveyance from source to user. |
|
Irrigation efficiency.
This is only used if |
|
Target for the fraction of demand that will be met from surface water (rather than groundwater). |
6.21.12. URBAN_PROPERTIES
namelist members¶
- URBAN_PROPERTIES::file¶
- Type:
character
- Default:
None
The file to read urban properties from.
If
use_file
(see below) is FALSE for every variable, this will not be used.This file name can use variable name templating.
- URBAN_PROPERTIES::nvars¶
- Type:
integer
- Permitted:
>= 0
- Default:
0
The number of urban property variables that will be provided.
The required variables depend on whether MORUSES is used or not:
If MORUSES is on, all variables must be given. However, depending on the configuration of MORUSES, not all given variables will be used. Those that will not be used could be set to constant values to avoid setting them from file.
If MORUSES is not on, only
wrr
is required.
- URBAN_PROPERTIES::var¶
- Type:
character(nvars)
- Default:
None
List of urban property variable names as recognised by JULES (see List of urban properties). Names are case sensitive.
Note
For ASCII files, variable names must be in the order they appear in the file.
- URBAN_PROPERTIES::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.
- URBAN_PROPERTIES::var_name¶
- Type:
character(nvars)
- Default:
‘’ (empty string)
For each JULES variable specified in
var
whereuse_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.Note
For ASCII files, this is not used - only the order in the file matters, as described above.
- URBAN_PROPERTIES::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.
- URBAN_PROPERTIES::const_val¶
- Type:
real(nvars)
- Default:
None
For each JULES variable specified in
var
whereuse_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.
6.21.12.1. List of urban properties¶
All of the urban property variables listed below are expected to have no levels dimensions and no time dimension.
Variable name |
Description [1] |
Notes |
---|---|---|
|
Repeating width ratio (or canyon fraction, W/R) |
If |
The following apply to MORUSES only |
||
|
Height-to-width ratio (H/W) |
See for |
|
Building height (H) |
See for |
|
Effective roughness length of urban areas |
If |
|
Displacement height |
See for |
|
Wall albedo |
Data only used if |
|
Road albedo |
See for |
|
Wall emissivity |
Data only used if |
|
Road emissivity |
See for |
Footnotes
6.21.13. JULES_CO2
namelist members¶
- JULES_CO2::read_from_dump¶
- Type:
logical
- Default:
F
- TRUE
Populate variables associated with this namelist from the dump file. All other namelist members are ignored.
- FALSE
Use the other namelist members to determine how to populate variables.
- JULES_CO2::co2_mmr¶
- Type:
real
- Default:
5.241e-4
Concentration of atmospheric CO2, expressed as a mass mixing ratio.
6.21.14. JULES_FLAKE
namelist members¶
- JULES_FLAKE::read_from_dump¶
- Type:
logical
- Default:
F
- TRUE
Populate variables associated with this namelist from the dump file. All other namelist members are ignored.
- FALSE
Use the other namelist members to determine how to populate variables.
- JULES_FLAKE::file¶
- Type:
character
- Default:
None
The file to read the FLake parameters from.
- JULES_FLAKE::nvars¶
- Type:
integer
- Permitted:
>= 0
- Default:
0
The number of FLake variables that will be provided. (At the moment lake depth is the only variable that needs to be provided).
- JULES_FLAKE::var¶
- Type:
character(nvars)
- Default:
None
List of FLake parameter variable names as recognised by JULES (see List of FLake parameters). Names are case sensitive.
Note
For ASCII files, variable names must be in the order they appear in the file.
- JULES_FLAKE::var_name¶
- Type:
character(nvars)
- Default:
‘’ (empty string)
For each JULES variable specified in
var
whereuse_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_FLAKE::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_FLAKE::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_FLAKE::const_val¶
- Type:
real(nvars)
- Default:
5.0m
For each JULES variable specified in
var
whereuse_file
= FALSE, this is a constant value that the variable will be set to for every point or gridbox.This is not used for variables where
use_file
= TRUE, but a placeholder must still be given.
6.21.14.1. List of FLake parameters¶
Name |
Description |
---|---|
|
For each gridbox, the depth of the lakes should be provided in meters. Note that for deep lakes FLake will assume an artificial lake bottom at 50m depth. |
6.21.15. References for ancillaries¶
Kattge, J. and Knorr, W., 2007, Temperature acclimation in a biochemical model of photosynthesis: a reanalysis of data from 36 species, Plant, Cell and Environment, 30: 1176–1190, https://doi.org/10.1111/j.1365-3040.2007.01690.x.