Configuration
Note
Support for full geographic meshes exists, however there is currently an issue with computing surface normals. Thus projected coordinate systems should only be used.
Note
Regardless of input coordinate system all input points are specified in latitude and longitude in WSG84.
Schema
The config file is a JSON file. However, it does support C-style comments: //
and /** **/
are both valid.
There are a few required sections: modules
, meshes
, forcing
.
The general layout of a CHM config JSON file is
{
"option":
{
"option_a": true,
"option_b": 1234,
...
},
"modules":
[
"module1",
"module2",
...
],
"config":
{
"module1":
{
...
},
...
}
"meshes":
{
...
},
"forcing":
{
...
},
"output":
{
...
}
}
For every section, if a top-level key:value pair is found and the value contains “.json”, that file is loaded and inserted into this option. The key-value is not used, and may be anything. Key names are enclosed in quotes (” “). Although it tends to make more sense to arrange the keys in the shown order, the order does not matter (anywhere) and will be read correctly.
Warning
The modules
key is an array and requires the use of [ ]
Warning
Do not prefix a number with zero (0). This is the octal prefix and it will cause the JSON parser to choke on lines that otherwise look fine.
Note
A user can specify a number as "5"
or 5
. Internally to CHM it will be converted to a numeric type. Thus, both are fine, however a non-string should be preferred. This is similar for "true"
and true
.
Note
Boolean types are case sensitive.
Sections
option
This section contains options for CHM and the simulation in general. This is a required section.
{
"option":
{
"station_N_nearest": 1,
"interpolant": "nearest",
"per_triangle_timeseries": false,
"ui": false,
"debug_level": "debug",
"prj_name": "SnowCast",
"enddate": "20180501T050000"
}
}
- station_search_radius
- Type:
double
- Default:
None
The search radius (meters) surrounding any given triangle within which to search for a station. This is used to ensure only “close” stations are used. Cannot be used when
station_N_nearest
is set. Based off the center of the triangle.
- station_N_nearest
- Type:
int
- Default:
5
Use the nearest N stations to include for the interpolation at a triangle. Based off the center of the triangle.
Both
station_search_radius
andstation_N_nearest
cannot be simultaneously specified. If neither is specific, thenstation_N_nearest:5
is used as default. If theinterpolant
mode isnearest
, then this is automatically set to 1.
- interpolant
- Type:
string
- Default:
“spline”
Chooses either thin plate spline with tension (spline) or inverse distance weighting (idw). Nearest selects the closest station and only uses that with no interpolation.
"interpolant" : "idw" "interpolant" : "spline" "interpolant" : "nearest"
- point_mode
- Type:
{ }
- Required:
No
Point mode selects that the model should be run in point mode, versus distributed mode.
There is one optional key that need to be specified:
forcing
(string)
forcing
needs to correspond to a specific input point as defined in the forcing sectionUsage of this key also requires adding
point_mode
to the module list. Lastly, no modules which are definedparallel:domain
may be used when point_mode is enabled.
"point_mode":
{
"forcing":"UpperClearing"
},
"point_mode":
{
// empty to just enable it
},
- notification_script
- Type:
string
- Default:
None
Path to a script to call upon model execution. This is useful for sending a notification to a computer or phone upon the completion of a long model run.
"notification_script":"./finished.sh"
And example of what finished.sh
might do is below, which triggers a
notification to Pushbullet thus showing up on all computers and phones
that the account is active on:
#!/bin/bash
curl -s -u <token here>: https://api.pushbullet.com/v2/pushes -d type=note -d title="Finished model run" >/dev/null
- debug_level
- Type:
string
- Default:
“Debug”
This controls the verbosity of the output. Options are:
verbose [ all messages ]
debug [ most messages useful for debugging ]
warning [only warnings]
error [ only errors which terminate model execution ]
Currently most useful internal messages are debug level.
"debug_level":"debug"
- startdate
- Type:
string
- Default:
None
Allows for a different start time than that specified by the input timeseries.
In the same ISO format as the forcing data: YYYYMDTHMS
.
"startdate":"20010501T000000"
- enddate
- Type:
string
- Default:
None
Allows for a different end time than that specified by the input timeseries.
In the same ISO format as the forcing data: YYYYMDTHMS
.
"enddate":"20010502T000000"
modules
Modules to run. These are a comma separated list of keys. This is a required section.
A few notes:
order as defined in this list has no bearing on the order modules execute
may be commented out to remove them from execution
names are case sensitive
point_mode
module is required to enable point mode, in addition to being enabled inoption.point_mode
.
Note
Modules are in a list ([ ]
)
"modules":
[
"Liston_wind",
"Burridge_iswr",
"slope_iswr",
"Liston_monthly_llra_ta",
"kunkel_rh",
"Thornton_p",
"Walcek_cloud",
"Sicart_ilwr",
"Harder_precip_phase",
"snobal",
"Gray_inf",
"Richard_albedo"
]
remove_depency
Under some edge cases, a cyclic dependency is created when a module B depends on module A’s output, and module A depends on module B’s output. There is no way to automatically resolve this. It requires the modeller to manually break the cycle and force one module to run ahead of another (essentially time-lagged).
An example of this occurring is that the albedo model requires knowledge of SWE, provided by the snowmodel. However, the snowmodel requires albedo to run. Therefore, the modeller may define that the albedo routine is run first, then the snowpack model.
Specifically: if module A depends on B (A->B), then to remove the decency of B from A, specify it as
"A":"B"
This can be thought of as
A
needs to come beforeB
. If the specified modules are not added to the modules list, they are ignored."remove_depency": { "Richard_albedo":"snobal" }
config
Each module, upon creation is provided a configuration instance. These configuration data are set by creating a key that exactly matches the module name. If a section is added, but that module isn’t specified, the section is ignored.
- module_name
- Type:
{ }
For example:
"config":
{
"slope_iswr":
{
"no_slope":true
}
},
If the configuration is sufficiently large or cumbersome, it may be best to have it in a separate file. This can be specified as
//consider this in CHM.json
"config":
{
"simple_canopy":"canopy.json"
}
And canopy.json
is
"canopy":
{
"LAI":3
}
Note that the sub-keys for a module’s configuration are entirely dependent upon the module. Please see the module’s help for specific options.
meshes
This section defines the mesh and optional the parameter files to use. It is a require section. This section has two keys:
- mesh
- Type:
string
File path to the
.mesh
file produced by mesher.
- parameters
- Type:
{ }
Optionally, A set of key:value pairs to other
.param
files that contain extra parameters to be used. These are in the format{ "file":"<path>"" }
"meshes":
{
"mesh":"meshes/granger30.mesh",
"parameters":
{
"file":"meshes/granger30.param",
"file":"meshes/granger30_surface.param"
}
}
If CHM is in MPI mode, then HDF5-based meshes need to be used to ensure fast partial loading of the mesh on a per-MPI rank basis. Please see meshgen for how to convert the mesh.
parameter_mapping
The parameters may be classified values for use in a look-up table. For example, the landcover may be a numeric class value and values such as LAI need to be obtained from a lookup table. These parameters may be either specified directly in the file or located in another file:
"parameter_mapping":
{
"soil":"parameters/wolf_soil_param.json"
}
or as a key:value pair. In all cases, the parameter name is how it will be referenced in the module that is looking for it. Please see the module’s documentation for what the expected format is.
{
"landcover":
{
"20":
{
"desc":"lake",
"is_waterbody":true
},
"31":
{
"desc":"snow ice"
}
}
}
output
Output may be either to an ascii-timeseries for a specific triangle on the mesh or it may be the entirety of the mesh. The two output types are set by:
a key named
"mesh":{ ... }
will enable the entire mesh outputall other keys (
"some_name":{...}`
) are assumed to be the names of output timeseries
Both mesh and timeseries can be used together.
- output_dir
- Type:
string
- Default:
“output”
The output directory name.
timeseries output
The name of the timeseries
key is used to uniquely identify this output: "output_name"{ ... }
.
If using point_mode
, this name corresponds to the output
key. If a lot of stations are to be
output, consider keeping them in a separate file and inserting using the top-level “.json” behaviour.
- longitude
- Type:
float
WGS84 longitude of output point. The triangle that contains this point is then selected for output. An error is raised if no triangle contains the point.
- latitude
- Type:
float
WGS84 latitude of output point. The triangle that contains this point is then selected for output. An error is raised if no triangle contains the point.
- file
The output file name. The output is in csv format and each column is a variable.
"output":
{
"more_stations":"mystations.json",
"UpperClearing":
{
"longitude": "-115.175362",
"latitude": "50.956547",
"file": "uc.txt"
}
}
where mystations.json
would look like
{
"some_station":
{
"longitude": "-115.175362",
"latitude": "50.956547",
"file": "somestation.txt"
}
}
mesh
The entire mesh may be written to Paraview’s vtu format for
visualization in Paraview and for analysis. This is denoted by a "mesh":{ ... }
key.
For more details, please see the output section.
- base_name
- Type:
string
The base file name to be used.
- variables
- Type:
[ "variable", ... ]
The default behaviour to is write every variable at each timestep. This may produce an undesirable amount of output. This takes a list of variables to output.
"variables": [
"t",
"U_2m_above_srf",
"swe",
"iswr"
],
Example:
"output":
{
"mesh": {
"base_name": "SC",
"variables": [
"t",
"U_2m_above_srf",
"swe",
"iswr"
],
"frequency": "24",
"write_parameters": false,
"write_ghost_neighbors": false
}
}
forcing
Input forcing can be either a ASCII timeseries or a NetCDF. Please see forcing for more details.
Input forcing stations do not need to be located within the simulation domain. Therefore they can act as ‘virtual stations’ so-as to use reanalysis data, or met stations located outside of the basin.
An example of this is shown below, where each black point is a virtual station, representing the center for a NetCDF grid cell from a NWP product.
- UTC_offset
- type:
int
- default:
0
If the input timeseries it not UTC, then this is the correction to account for UTC offset (all solar radiation calculations are in UTC). This is Positive west!
- use_netcdf
- Type:
boolean
- Default:
false
Specify if a NetCDF (.nc) file will be used. Cannot be used along with ASCII inputs!
Note
ASCII and NetCDF inputs cannot be mixed. It is one or the other.
ASCII timeseries
This is given as "station_name":{ ... }
. If using point_mode
, then the value station_name
must exactly match the input
used for option.point_mode
.
- file
A relative or absolute path to an input forcing file
- latitude
- Type:
double
Latitude of the input station, WGS84. Positive North. Not “N” or “S” suffix
- longitude
- Type:
double
Longitude of the input station, WGS84. Positive East. Not “N” or “S” suffix
- elevation
- Type:
double
Elevation is given in meters. It does not need to be equal to the elevation of the triangle upon which it lies if the station is located in the simulation domain. This value is used in the lapse rate equations to interpolate the data.
If required, forcing station definitions can be located in an external
file. For the external file, the name of the key doesn’t matter. The
external file should contain the stations in the format as per above. It
does not require an addition "forcing":
section definition.
"forcing":
{
"some_station":
{
//definition
},
"reanalysis_extract_1": "external_file_1.json",
"reanalysis_extract_2": "external_file_2.json",
}
where external_file_*.json
looks like
{
"station1":
{
//details here
},
"station2":
{
//details here
}
}
Filters
Filters perform an operation on the data prior to being passed to a module. They allow for things such as wind-undercatch corrections to be done on the fly.
If a filter is defined, it must be defined on the forcing file and operate upon a variable that exists in the forcing data. They are given as:
"filter_name": { ... }`
. The configuration values are filter-specific; please see the filter documentation for what is required. Multiple filters may be specified.
"buckbrush":
{
"file": "bb_m_2000-2008",
"latitude": 60.52163,
"longitude": -135.197151,
"elevation": 1305,
"filter":
{
"scale_wind_speed": {
"Z_F": 4.6,
"variable": "u"
},
"goodison_undercatch": {
"variable": "p"
}
}
}
Warning
Filters run in the order defined in the configuration file.
Example
"forcing":
{
"UTC_offset": 8,
"buckbrush":
{
"file": "bb_m_2000-2008",
"latitude": 60.52163,
"longitude": -135.197151,
"elevation": 1305,
"filter":
{
"scale_wind_speed":
{
"Z_F": 4.6,
"variable": "u"
},
"goodison_undercatch":
{
"variable":"p"
}
}
},
"alpine":
{
"file": "alp_m_2000-2008",
"latitude": 60.567267,
"longitude": -135.184652,
"elevation": 1559,
"filter": {
"scale_wind_speed": {
"Z_F": 2.5,
"variable": "u"
},
"goodison_undercatch":
{
"variable":"p"
}
}
}
}
NetCDF
The use NetCDF as input creates virtual stations at the cell-centres. The NetCDF file is lazy loaded as required for each triangle, so only the values required are loaded. The variable names, like for ASCII inputs, needs to correspond to the values expected by the filters.
Warning
NetCDF and point_mode
are not supported.
Filters
Filters are the same as for ASCII with one important distinction: every specified filter is run for every virtual station (i.e., grid cell centre).
"filter": {
"scale_wind_speed": {
"Z_F": "40",
"variable": "u"
}
}
Example
"forcing": {
"UTC_offset": "0",
"use_netcdf": true,
"file": "GEM-CHM_2p5_west_2017100106_2018080105.nc",
"filter": {
"scale_wind_speed": {
"Z_F": "40",
"variable": "u"
}
}
}
checkpoint
CHM can save its state after a timestep, allowing CHM to resume from this timestep. Further details on can be found in the Checkpointing section.
- save_checkpoint
- Type:
boolean
- Default:
false
Enable checkpointing. One of
frequency
oron_last
must be set. Must be set true to enable the checkpointing.
- frequency
- Type:
int64
- Default:
empty
The frequency of checkpointing. Checkpoints every
frequency
timesteps. Can be used withon_last
to produce checkpoints everyfrequency
timesteps as well as on the last timestep.
- on_last
- Type:
bool
- Default:
false
Check point only on the last timestep. Can be used with
frequency
, but does not requirefrequency
to be set.
- load_checkpoint_path
- Type:
string
- Default:
empty
Path to checkpoint file to load from (specifically, the json file). Can be used with the other checkpointing options.
"checkpoint":
{
"save_checkpoint": true,
"frequency": 4,
"on_last": true,
"load_checkpoint_path":"output/checkpoint/checkpoint_20001001T140000.np1.json"
}