6.11. model_grid.nml

This file sets up the grid configuration for the run. It contains five namelists - JULES_INPUT_GRID, JULES_LATLON, JULES_LAND_FRAC, JULES_MODEL_GRID and JULES_SURF_HGT.

Each run of JULES involves two grids: the input grid and the model grid. The input grid is the grid on which all input data are held. The model grid is the set of points on which the model is run. The model grid is the grid of points that will be processed by JULES, and is a subset of the input grid.

As discussed in General principles, the input grid consists of three pieces of information:

1. Whether the grid is 1D or 2D.
2. The size of each dimension.
3. The name of each dimension in the input file(s).

The latitude, longitude and land fraction of each point are then read in on the full input grid as specified by the namelists. A subset of the input grid to use as the model grid can then be specified in various ways described below (e.g. land points only, all points within certain latitude/longitude bounds).

In most cases, the model grid will be represented internally as a vector of points, even when the input grid is 2D. Numerically, this makes no difference. The only time that the model grid will be 2D is when the input grid is 2D, force_1d_grid = F and the model grid is a contiguous rectangular subsection of the input grid.

6.11.1. JULES_INPUT_GRID namelist members

Warning

The dimension names specified in this namelist will be used for all input files.

JULES_INPUT_GRID::grid_is_1d

Type:logical Default:F

Indicates if the input grid is 1D or 2D.

TRUE

Variables have one grid dimension in the input file(s) - a points dimensions (e.g. a vector of land points with grid dimension “land”).

FALSE

Variables have two grid dimensions in the input file(s) - an x and a y dimension.

Only used when grid_is_1d = TRUE

JULES_INPUT_GRID::grid_dim_name

Type:character Default:“land”

The name of the single grid dimension.

Note

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

JULES_INPUT_GRID::npoints

Type:integer Permitted:>= 1 Default:0

The size of the single grid dimension.

Only used when grid_is_1d = FALSE

JULES_INPUT_GRID::x_dim_name

Type:character Default:“x”

The name of the x dimension.

Note

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

JULES_INPUT_GRID::y_dim_name

Type:character Default:“y”

The name of the y dimension.

Note

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

JULES_INPUT_GRID::nx

Type:integer Permitted:>= 1 Default:0

The size of the x dimension.

JULES_INPUT_GRID::ny

Type:integer Permitted:>= 1 Default:0

The size of the y dimension.

JULES_INPUT_GRID::time_dim_name

Type:character Default:“time”

The name of the time dimension in any input files containing time varying data.

Note

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

JULES_INPUT_GRID::pft_dim_name

Type:character Default:“pft”

The dimension name used when variables have an additional dimension of size npft.

Note

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

JULES_INPUT_GRID::cpft_dim_name

Type:character Default:“cpft”

The dimension name used when variables have an additional dimension of size ncpft.

Note

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

JULES_INPUT_GRID::nvg_dim_name

Type:character Default:“nvg”

The dimension name used when variables have an additional dimension of size nnvg.

Note

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

JULES_INPUT_GRID::type_dim_name

Type:character Default:“type”

The dimension name used when variables have an additional dimension of size ntype.

Note

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

JULES_INPUT_GRID::tile_dim_name

Type:character Default:“tile”

The dimension name used when variables have an additional dimension of size ntiles.

Note

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

JULES_INPUT_GRID::soil_dim_name

Type:character Default:“soil”

The dimension name used when variables have an additional dimension of size sm_levels.

Note

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

JULES_INPUT_GRID::snow_dim_name

Type:character Default:“snow”

The dimension name used when variables have an additional dimension of size nsmax.

Note

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

JULES_INPUT_GRID::scpool_dim_name

Type:character Default:“scpool”

The dimension name used when variables have an additional dimension of size dim_cs1.

Note

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

JULES_INPUT_GRID::bedrock_dim_name

Type:character Default:“bedrock”

The dimension name used when variables have an additional dimension of size ns_deep.

Note

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

6.11.2. JULES_LATLON namelist members

Used when input grid consists of a single location (1D and npoints = 1 or 2D and nx = ny = 1

JULES_LATLON::latitude

Type:real Default:None

The latitude of the single grid location.

JULES_LATLON::longitude

Type:real Default:None

The longitude of the single grid location.

Used for any input grid with more than a single location

JULES_LATLON::file

Type:character Default:None

The name of the file to read latitude and longitude from.

JULES_LATLON::lat_name

Type:character Default:None

The name of the variable containing the latitude data.

In the file, the variable must have no levels dimensions and no time dimension.

JULES_LATLON::lon_name

Type:character Default:None

The name of the variable containing the longitude data.

In the file, the variable must have no levels dimensions and no time dimension.

6.11.3. JULES_LAND_FRAC namelist members

Land fraction is the fraction of each gridbox that is land. Currently, JULES considers any gridbox with land fraction > 0 to be 100% land, and all others to be 100% sea (or sea-ice). Land fraction data can be used to select only land points from the full input grid (see below).

Warning

When the input grid consists of a single location (1D and npoints = 1 or 2D and nx = ny = 1), that single location is assumed to be 100% land.

For any input grid with more than a single location, the following are used:

JULES_LAND_FRAC::file

Type:character Default:None

The name of the file to read land fraction data from.

JULES_LAND_FRAC::land_frac_name

Type:character Default:None

The name of the variable containing the land fraction data.

In the file, the variable must have no levels dimensions and no time dimension.

6.11.4. JULES_MODEL_GRID namelist members

Members of this namelist are used to select the points to be modelled from the input grid. This can be done in various ways (see the Examples).

JULES_MODEL_GRID::land_only

Type:logical Default:T

TRUE

Model land points only (from the points that are selected with other options).

FALSE

Model all selected points.

If use_subgrid = FALSE (see below), the land points will be extracted from the full input grid.

If use_subgrid = TRUE, then the subgrid extraction takes place first, and the land points will be extracted from the specified subgrid.

JULES_MODEL_GRID::force_1d_grid

Type:logical Default:F

TRUE

Force the model grid to be 1D, even if it would otherwise have been 2D.

FALSE

The model grid takes its default shape.

JULES_MODEL_GRID::use_subgrid

Type:logical Default:F

TRUE

The model grid is a subset of the full input grid, specified using some valid combination of the options below.

FALSE

The model grid is the full input grid.

Only used if use_subgrid = TRUE

JULES_MODEL_GRID::latlon_region

Type:logical Default:None

TRUE

Subset of points to model will be selected using latitude and longitude bounds.

FALSE

Subset of points to model will be selected using a list of latitude and longitude for each point.

Only used if latlon_region = TRUE

JULES_MODEL_GRID::lat_bounds

Type:real(2) Default:None

The lower and upper bounds (in that order) for the latitude to use. The model grid will only contain points where lat_bounds(1) <= latitude <= lat_bounds(2).

JULES_MODEL_GRID::lon_bounds

Type:real(2) Default:None

The lower and upper bounds (in that order) for the longitude to use. The model grid will only contain points where lon_bounds(1) <= longitude <= lon_bounds(2).

Only used if latlon_region = FALSE

JULES_MODEL_GRID::npoints

Type:integer Permitted:>= 1 Default:0

The number of points to model.

JULES_MODEL_GRID::points_file

Type:character Default:None

The name of the file containing the latitude and longitude for each point.

Each line in the file should contain the latitude and longitude (in that order) for a point.

6.11.5. JULES_SURF_HGT namelist members

This namelist sets the elevation of each surface tile, relative to the gridbox mean elevation. Note that the gridbox mean elevation is not required anywhere in JULES but is implicit in the near-surface meteorological data that are provided (higher locations will tend to be colder, have lower pressure, etc.). The elevation of each tile is used to alter the values of the air temperature and humidity over that tile. All tile elevations must be greater than zero, i.e. tile can only be higher than the gridbox average, because the assumptions used to alter the air temperature and humidity only hold for moving to higher elevations. For many applications, the tile elevation can be set to zero.

JULES_SURF_HGT::zero_height

Type:logical Default:T

Switch used to simplify the initialisation of tile elevation.

Note

If l_aggregate = TRUE, this switch is also set to TRUE.

TRUE

Set all tile elevations to zero. This is a very common configuration.

FALSE

Set tile heights using specified data.

Used if zero_height = FALSE and the input grid consists of a single location

JULES_SURF_HGT::surf_hgt_io

Type:real(ntiles) Default:None

The tile elevations for each tile for the single location.

Used if zero_height = FALSE and the input grid consists of more than one location

JULES_SURF_HGT::file

Type:character Default:None

The name of the file to read tile elevation data from.

JULES_SURF_HGT::surf_hgt_name

Type:character Default:None

The name of the variable containing the tile elevation data.

In the file, the variable must have a single levels dimension of size ntiles called tile_dim_name.

6.11.6. Examples

6.11.6.1. ASCII data at a single location

&JULES_INPUT_GRID
  nx = 1,
  ny = 1
/

&JULES_LATLON
  latitude  = 52.168,
  longitude = 5.744
/

&JULES_LAND_FRAC /

&JULES_MODEL_GRID /

&JULES_SURF_HGT
  zero_height = T
/

JULES_INPUT_GRID

The default value of grid_is_1d, FALSE, is used. This means the user has to specify the extents, nx and ny, of the input grid. Since all the input data is ASCII, no dimension names are required.

JULES_LATLON

The latitude and longitude of the single location are specified directly in the namelist.

JULES_LAND_FRAC

The land fraction at the single location is assumed to be 100%, so nothing is required.

JULES_MODEL_GRID

Use default options to select the model grid (i.e. land points only from the full input grid). In this case, this leaves the single location as the model grid.

6.11.6.2. Examples of gridded runs

All the examples in this section assume gridded NetCDF data.

6.11.6.2.1. Specifying a 1D input grid

In this example, input files contain data on a vector of land points. The land points dimension is called “land”. The time dimension for time-varying variables is called “time”. The default dimension names are used for all additional dimensions (e.g. pft, tile).

&JULES_INPUT_GRID
  grid_is_1D = T,
  
  npoints = 15238,
  grid_dim_name = "land",
  
  time_dim_name = "time"
/

6.11.6.2.2. Specifying a 2D input grid

In this example, input files contain data on a 2D latitude/longitude grid. The x dimension is called “lon” and the y dimension is called “lat”. The time dimension for time-varying variables is called “time”. Variables with an extra tiles dimension use the dimension name “pseudo” for that dimension. All other additional dimensions use their default names.

&JULES_INPUT_GRID
  grid_is_1D = F,

  nx = 96,
  ny = 56,

  x_dim_name = "lon",
  y_dim_name = "lat",

  tile_dim_name = "pseudo",

  time_dim_name = "time"
/

6.11.6.2.3. Specifying a subgrid using a given range of latitude and longitude

This can be used with either a 1D or 2D input grid.

&JULES_LATLON
  file = 'lat_lon.nc',
  
  lat_name = 'latitude',
  lon_name = 'longitude'
/

&JULES_LAND_FRAC
  file = 'land_mask.nc',

  land_frac_name = 'land_frac'
/

&JULES_MODEL_GRID
  land_only = F,

  use_subgrid = T,

  latlon_region = T,

  lat_bounds = 55.0  57.0,
  lon_bounds = -5.0  -3.0
/

This setup reads latitude, longitude and land fraction for each gridbox in the full input grid (1D or 2D) from the named variables in the specified files.

In JULES_MODEL_GRID, use_subgrid indicates that a subset of the input grid will be selected as the model grid. latlon_region then indicates that latitude and longitude bounds will be used to select the subgrid. land_only = FALSE means that sea and sea-ice points will remain in the model grid if any are selected. The model grid will then be a vector containing the selected points (those that fall within the latitude/longitude bounds), even if those points could be used to form a rectangular region.

6.11.6.2.4. Specifying a subgrid using a list of points

This can be used with either a 1D or 2D input grid.

&JULES_LATLON
  file = 'lat_lon.nc',

  lat_name = 'latitude',
  lon_name = 'longitude'
/

&JULES_LAND_FRAC
  file = 'land_mask.nc',

  land_frac_name = 'land_frac'
/

&JULES_MODEL_GRID
  use_subgrid = T,

  latlon_region = F,

  npoints = 4,
  points_file = 'points.txt'
/

This setup reads latitude, longitude and land fraction for each gridbox in the full input grid (1D or 2D) from the named variables in the specified files.

In JULES_MODEL_GRID, use_subgrid indicates that a subset of the input grid will be selected as the model grid. latlon_region then indicates that a list of latitudes and longitudes will be used to select the subgrid. land_only is not given, meaning it takes its default value, TRUE. This means that any sea or sea-ice points specified in the list of points will be discarded. The model grid will then be a vector containing the selected points (those with the given latitude/longitude).

Assuming that the input grid is a 1 degree grid and the latitude and longitude are given at the centre of the gridbox, points.txt should look like the following:

55.5  -4.5
55.5  -3.5
56.5  -4.5
56.5  -3.5

6.11.6.2.5. The only configuration that yields a 2D model grid

&JULES_INPUT_GRID
  grid_is_1d = F,

  nx = 96,
  ny = 56,
  
  # ...
/

&JULES_LATLON
  # <specified from file>
/

&JULES_LAND_FRAC
  # <specified from file>
/

&JULES_MODEL_GRID
  land_only = F
/

In general, the only configuration that yields a 2D model grid is:

• 2D input grid
• The model grid is the full input grid, including any non-land points

If the input grid is a 2D region where every point is land (i.e. not the whole globe), then land_only = TRUE would also yield a 2D model grid. If any options are set that mean some points from the input grid are not modeled, the model grid will be a vector of points. Computationally, this makes no difference.