6.19. 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, JULES_RIVERS_PROPS, JULES_OVERBANK_PROPS, URBAN_PROPERTIES and JULES_CO2.

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.19.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).

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 active l_top = TRUE and therefore fsat is being calculated) then all groundwater-maintained wetlands must be excluded from frac_name. If overbank inundation is being simulated (i.e. l_riv_overbank = TRUE) then all fluvial wetlands must be excluded from frac_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 called type_dim_name, and should not have a time dimension.

6.19.2. JULES_VEGETATION_PROPS namelist members

This namelist specifies how spatially-varying properties of vegetation should be set.

At present only one variable - t_growth_gb - can be specified via this namelist, and this is only required if thermal adaptation of photosynthetic capacity is selected (photo_acclim_model = 1).

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 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_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 where use_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.19.2.1. List of vegetation parameters

Name Description
t_growth_gb Average temperature (growth temperature) for thermal adaptation of photosynthetic capacity (degrees Celsius), 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). This variable should not have a time dimension nor any “levels” dimension.

6.19.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 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_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 where use_file = FALSE, this is a constant value that the variable will be set to at every point in every layer (overriding const_z = FALSE).

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

6.19.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
albsoil Soil albedo. A single (averaged) waveband is used. None
b Exponent in soil hydraulic characteristics. soil_dim_name
hcap Dry heat capacity (J m-3 K-1). soil_dim_name
hcon Dry thermal conductivity (W m-1 K-1). soil_dim_name
satcon Hydraulic conductivity at saturation (kg m-2 s-1). soil_dim_name
sathh

If l_vg_soil = TRUE (using van Genuchten model), sathh = 1 / α, where α (m-1) is a parameter of the van Genuchten model.

If l_vg_soil = FALSE (using Brooks and Corey model), sathh is the absolute value of the soil matric suction at saturation (m). The suction at saturation is generally less than zero, but JULES uses the absolute value.

soil_dim_name
sm_crit

Volumetric soil moisture content at the critical point (m3 water per m3 soil). If l_use_pft_psi = F, the point at which soil moisture stress starts to restrict transpiration is a function of sm_crit, sm_sat and the pft-dependent parameter fsmc_p0_io .

sm_crit is also used to calculate the surface conductance of bare soil.

soil_dim_name
sm_sat

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.

sm_sat > 0 indicates a soil point.

soil_dim_name
sm_wilt

Volumetric soil moisture content at the wilting point (m3 water per m3 soil). If l_use_pft_psi = F, sm_wilt is the limit where soil moisture stress completely prevents transpiration.

sm_wilt is also used to calculate soil respiration.

soil_dim_name
clay

Soil clay content (g clay per g soil). Only required for the RothC and ECOSSE soil carbon models (soil_bgc_model = 2 or 3).

Note

To allow backwards compatibility when using the RothC model (soil_bgc_model = 2), if the clay content is not available it is set to 0.0 in the code.

However, this is wrong - if it is not available it should be set to 0.23.

sclayer_dim_name
soil_ph Soil pH. Only required for the ECOSSE soil carbon model (soil_bgc_model = 3). sclayer_dim_name

6.19.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 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_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 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 in that case.

6.19.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
fexp

Decay factor describing how the saturated hydraulic conductivity decreases with depth below the standard soil column (m-1).

Routinely set between 1 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.

ti_mean (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)
ti_sig (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.19.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 where use_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 where use_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 where use_file = TRUE, but a placeholder must still be given.

6.19.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
slope Mean value of the topographic slope in the gridbox (deg).

6.19.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 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_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.

6.19.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 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_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 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 in that case.

6.19.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
cropsowdate

The sowing date for each crop.

The sowing date should be a real number, with 0 < nint(sowing_date) < number of days in year. For example, for a 365 day year, sow_date = 1.0 is Jan 1st and sow_date = 365.0 is Dec 31st.

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 l_prescsow = TRUE.

cropttveg Thermal time between emergence and flowering (degree days).
cropttrep Thermal time between flowering and maturity/harvest (degree days).
croplatestharvdate

The latest possible harvest date for each crop. croplatestharvdate is only a required variable when l_croprotate = TRUE and l_prescsow = TRUE.

croplatestharvdate is not a required variable when l_croprotate = FALSE and l_prescsow = TRUE but will be used if provided in the ancillary file

croplatestharvdate is not a required variable and is only used if provided as an ancillary when l_prescsow = TRUE.

See also

References:

6.19.8. JULES_IRRIG namelist members

This namelist specifies the different options available for setting up the irrigation.

Note

Irrigation can be applied at a constant rate in three ways:
    1. To apply a constant irrigation to all tiles the irrigation settings are as follows: frac_irrig_all_tiles=T, set_irrfrac_on_irrtiles=F and set a value for const_irr_frac in this namelist.
    1. To apply a constant irrigation to only specific tiles the irrigation settings are as follows: frac_irrig_all_tiles=F and set_irrfrac_on_irrtiles=T and set a value for const_irrfrac_irrtiles in this namelist.
    1. To apply a constant irrigation to specific tiles as an average across the gridbox, which is the way irrigation on specific tiles was done prior to vn5.7, the irrigation settings are as follows:frac_irrig_all_tiles=F, set_irrfrac_on_irrtiles=F and set a value for const_frac_irr.

In both option 2 and 3, irrigtiles is the index of tiles you wish to irrigate, the length of which is nirrigtiles e.g. if you include wheat and maize in your run at index 5 and 6 then irrigtiles=5,6 and nirrigtiles=2.

JULES_IRRIG::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::frac_irrig_all_tiles
Type:logical
Default:T

If T, then irrigation fraction is applied to all tiles, and F, it is applied only to the tiles specified in irrigtiles.

JULES_IRRIG::set_irrfrac_on_irrtiles
Type:logical
Default:F

If F then irrigation is applied as an average across the gridbox and not to specific tiles. If T, then the irrigation fraction is only applied to the tile specified in irrigtiles. Both frac_irrig_all_tiles and set_irrfrac_on_irrtiles cannot be set to T.

JULES_IRRIG::nirrtile
Type:integer
Default:None

The number of tile types to be irrigated. Only used if frac_irrig_all_tiles = F.

JULES_IRRIG::irrigtiles
Type:integer(nirrtile)
Default:None

Indices of the tiles to be irrigated. Only used if frac_irrig_all_tiles = F.

JULES_IRRIG::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 file.
FALSE
Irrigated fraction is set to the constant value specified in const_frac_irr.
JULES_IRRIG::file
Type:character
Default:None

The file from which irrigation fractions are read, including path.

JULES_IRRIG::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::const_frac_irr
Type:real
Default:none

The constant irrigated fraction to be applied to all grid points.

JULES_IRRIG::const_irrfrac_irrtiles
Type:real
Default:none

The constant irrigated fraction to be applied to specific tiles given in irrigtiles.

6.19.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 grid - The grid on which the river routing will run, and on which river routing ancillaries will be provided

Currently, information about the river routing 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 grid must be 2D, 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 grid is used, both the x and y dimensions and corresponding latitude and longitude values must be specified for each grid point.

For some applications, the model input and river routing grids may not be coincident. Note that functionality only currently exists to regrid between regular (but non-identical) model input and river routing grids. If a non-regular model input grid is specified, it is assumed that the model input and river routing grids will be coincident.

Members used to define the river routing grid

JULES_RIVERS_PROPS::rivers_reglatlon
Type:logical
Default:T

Flag indicating if the river routing grid is regular in latitude and longitude.

TRUE
River routing grid is regular in latitude and longitude.
FALSE
River routing grid is not regular in latitude and longitude (e.g. grid defined relative to a rotated pole, National Grid, etc). Only i_river_vn = 2 should be used in this case. Note that the model input and river routing grids must be coincident in this case and rivers_regrid must also be set to false.
JULES_RIVERS_PROPS::x_dim_name
Type:character
Default:None

The name of the x dimension for the river routing grid.

Note

For ASCII files, this can be anything. For NetCDF files, it should the name of the dimension in input file(s).

Warning

Values for the x dimension of the river routing 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 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 grid.

Note

For ASCII files, this can be anything. For NetCDF files, it should the name of the dimension in input file(s).

Warning

Values for the y dimension of the river routing 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 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 grid.

JULES_RIVERS_PROPS::ny
Type:integer
Permitted:>= 1
Default:None

The size of the y dimension of the river routing grid.

Members used to define the relationship between the model input grid and the river routing grid

JULES_RIVERS_PROPS::rivers_regrid
Type:logical
Default:T

Flag indicating if the model input and river routing grids are identical, i.e. whether regridding of variables to and from the river routing grid is required. Note this is only currently possible if rivers_reglatlon is TRUE.

TRUE
River routing and model input grids differ and regridding is required.
FALSE
River routing and model input grids are identical.

Warning

Currently, regridding between model input and river routing grids must only be used with regular lat/lon model input and river routing 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:JULES_RIVERS_PROPS::nx

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:JULES_RIVERS_PROPS::ny

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 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 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 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 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 National Grid 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 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_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 where use_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.19.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 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 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 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 grid is the same as the 2D regular lat-lon grid containing the model input grid
  rivers_regrid = F
/

6.19.9.2. List of rivers properties

The following table summarises river routing grid properties required to run RFM or TRIP river routing algorithms, specified from an ancillary file if use_file = TRUE.

Name Description
area

Drainage area (in number of grid boxes) draining into a given grid box.

This does not include the grid point itself, and so an extra point to account for the grid point itself must be added where catchment area calculations are required.

This is used if i_river_vn = 2 to define river, land and sea points using the a_thresh parameter.

If not available, all points with a valid direction are set to (a_thresh + 1) by default (i.e. river points).

direction

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 [1 = N, 2 = NE, 3 = E, 4 = SE, 5 = S, 6 = SW, 7 = W, 8 = NW].

This numbering system is based on the TRIP implementation, and may not be standard. Users should take care to ensure that the input ancillary is defined as required.

sequence

River routing network pathway number.

Used by TRIP river routing only (i.e. i_river_vn = 1,3). See Oki et al. (1999) for details.

latitude_2d If rivers_reglatlon = FALSE, the unique 2D location of each river grid point must be specified.
longitude_2d If rivers_reglatlon = FALSE, the unique 2D location of each river grid point must be specified.

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.19.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 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 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_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 where use_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.19.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
logn_mean

Mean of ln(elevation-elev_min) for each grid cell (in units ln(m))

This is only used if l_riv_hypsometry = TRUE

logn_stdev

Standard deviation of ln(elevation-elev_min) for each grid cell (in units ln(m))

This is only used if l_riv_hypsometry = TRUE

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.19.11. 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 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.

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 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.

6.19.11.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
wrr Repeating width ratio (or canyon fraction, W/R) If l_urban_empirical = TRUE then this is updated with calculated values.
The following apply to MORUSES only
hwr Height-to-width ratio (H/W) See for wrr above.
hgt Building height (H) See for wrr above.
ztm Effective roughness length of urban areas If l_moruses_macdonald = TRUE then this is updated with calculated values.
disp Displacement height See for ztm above.
albwl Wall albedo Data only used if l_moruses_albedo = TRUE.
albrd Road albedo See for albwl above.
emisw Wall emissivity Data only used if l_moruses_emissivity = TRUE.
emisr Road emissivity See for emisw above.

Footnotes

[1]For more information on the urban geometry used please see the JULES technical documentation.

6.19.12. 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.19.13. CABLE_PROGS namelist members

This namelist specifies how CABLE prognostic variables should be set initially if the CABLE land surface model is being used.

CABLE_PROGS::file
Type:character
Default:None

The file to read initial values for CABLE prognostic variables from.

If use_file is FALSE for every variable, this will not be used.

This file name can use variable name templating.

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

The number of prognostic variables that will be provided (see List of CABLE prognostic variables).

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

List of CABLE prognostic variable names as recognised by CABLE (see List of CABLE prognostic variables). Names are case sensitive.

Note

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

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

For each CABLE 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.
CABLE_PROGS::var_name
Type:character(nvars)
Default:‘’ (empty string)

For each CABLE 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.

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

For each CABLE 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 in that case.

6.19.13.1. List of CABLE prognostic variables

Values are set for each tile of each grid point and for each layer of soil or snow.

Name Description
SoilTemp_CABLE Temperature of each soil layer (K).
SoilMoisture_CABLE Soil moisture content of each soil layer (kg m-2).
FrozenSoilFrac_CABLE Frozen soil moisture content of each soil layer as a fraction of saturation.
SnowDepth_CABLE Depth of each snow level (m).
SnowMass_CABLE Mass of each each snow level (kg).
SnowTemp_CABLE Temperature for each snow layer (K).
SnowDensity_CABLE Density for each snow layer (kg m-3).
SnowAge_CABLE Age of each snow layer
OneLyrSnowDensity_CABLE Snow density when all snow treated as one layer. (kg m-3)
ThreeLayerSnowFlag_CABLE Flag for 3 layer snow pack (0 - false, 1 - true)

6.19.14. References for ancillaries