NML
glm_nml
¶
BirdModelBlock
¶
Bases: _BaseBlock
Construct the &bird_model model parameters.
The &bird_model parameters define the surface irradiance based on the
Bird Clear Sky Model (BCSM) (Bird, 1984). BirdModelBlock provides the
means to construct a dictionary containing these parameters for use in the
glm_nml.GLMNML class. Model parameters are set as attributes upon
initialising an instance of the class or using the set_attributes()
method. The get_params() method returns the parameter dictionary and
performs optional error checking to ensure compliant parameters.
Attributes:
| Name | Type | Description |
|---|---|---|
AP |
Union[float, None]
|
Atmospheric pressure (hPa). Default is |
Oz |
Union[float, None]
|
Ozone concentration (atm-cm). Default is |
WatVap |
Union[float, None]
|
Total Precipitable water vapor (atm-cm). Default is |
AOD500 |
Union[float, None]
|
Dimensionless Aerosol Optical Depth at wavelength 500 nm. Default is
|
AOD380 |
Union[float, None]
|
Dimensionless Aerosol Optical Depth at wavelength 380 nm. Default is
|
Albedo |
Union[float, None]
|
Albedo of the surface used for Bird Model insolation calculation.
Default is |
Examples:
>>> from glmpy.nml import glm_nml
>>> bird_model = glm_nml.BirdModelBlock(
... AP=973,
... Oz=0.2
... )
>>> bird_model_attrs = {
... "Oz": 0.279,
... "WatVap": 1.1,
... "AOD500": 0.033,
... "AOD380": 0.038,
... "Albedo": 0.2
... }
>>> bird_model.set_attributes(bird_model_attrs)
get_params(check_params=False)
¶
Returns a dictionary of model parameters.
Consolidate the model parameters set during class instance
initialisation, or updated through set_attributes(), into a
dictionary suitable for use with the glm_nml.GLMNML class.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
check_params |
bool
|
If |
False
|
Returns:
| Type | Description |
|---|---|
dict[str, Any]
|
A dictionary containing the configuration block parameters. |
set_attrs(attrs_dict)
¶
Set attributes for an instance of a configuration block class.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
attrs_dict |
dict
|
A dictionary of GLM parameters to set the respective attributes in the configuration block class instance. |
required |
Examples:
>>> from glmpy.nml import glm_nml
>>> glm_setup_attrs = {
... "sim_name": "Example Simulation #1",
... "max_layers": 500,
... "min_layer_thick": 0.15,
... "max_layer_thick": 1.50,
... "min_layer_vol": 0.025,
... "density_model": 1,
... "non_avg": False
... }
>>> glm_setup = glm_nml.SetupBlock()
>>> glm_setup.set_attrs(glm_setup_attrs)
GLMNML
¶
Write GLM NML files.
The General Lake Model (GLM) namelist file (.nml) describes the parameter
configuration for running simulations. The GLMNML class builds a NML
file by combining dictionaries of parameters that correspond with each
configuration block, e.g., &glm_setup, &morphometry, and &time. Each
dictionary of parameters can be constructed using the respective block
classes, e.g., glm_nml.SetupBlock, glm_nml.MorphometryBlock, and
glm_nml.TimeBlock.
An optional check_errors argument can be set to raise errors when
parameters from separate configuration blocks are in conflict. The NML
file can be saved using the write_nml() method.
Attributes:
| Name | Type | Description |
|---|---|---|
glm_setup |
dict
|
Dictionary of |
morphometry |
dict
|
Dictionary of |
time |
dict
|
Dictionary of |
init_profiles |
dict
|
Dictionary of |
mixing |
Union[dict, None]
|
Dictionary of |
output |
Union[dict, None]
|
Dictionary of |
meteorology |
Union[dict, None]
|
Dictionary of |
light |
Union[dict, None]
|
Dictionary of |
bird_model |
Union[dict, None]
|
Dictionary of |
inflow |
Union[dict, None]
|
Dictionary of |
outflow |
Union[dict, None]
|
Dictionary of |
sediment |
Union[dict, None]
|
Dictionary of |
snow_ice |
Union[dict, None]
|
Dictionary of |
wq_setup |
Union[dict, None]
|
Dictionary of |
Examples:
Import the glm_nml module:
Initialise instances of the NML configuration block classes:
>>> glm_setup = glm_nml.SetupBlock()
>>> morphometry = glm_nml.MorphometryBlock()
>>> time = glm_nml.TimeBlock()
>>> init_profiles = glm_nml.InitProfilesBlock()
>>> mixing = glm_nml.MixingBlock()
>>> output = glm_nml.OutputBlock()
>>> meteorology = glm_nml.MeteorologyBlock()
>>> light = glm_nml.LightBlock()
>>> bird_model = glm_nml.BirdModelBlock()
>>> inflow = glm_nml.InflowBlock()
>>> outflow = glm_nml.OutflowBlock()
>>> sediment = glm_nml.SedimentBlock()
>>> snow_ice = glm_nml.SnowIceBlock()
>>> wq_setup = glm_nml.WQSetupBlock()
Set the instance attributes from dictionaries of GLM parameters (omitted for brevity):
>>> glm_setup.set_attributes(glm_setup_attrs)
>>> morphometry.set_attributes(morphometry_attrs)
>>> time.set_attributes(time_attrs)
>>> init_profiles.set_attributes(init_profiles_attrs)
>>> mixing.set_attributes(mixing_attrs)
>>> output.set_attributes(output_attrs)
>>> meteorology.set_attributes(meteorology_attrs)
>>> light.set_attributes(light_attrs)
>>> bird_model.set_attributes(bird_model_attrs)
>>> inflow.set_attributes(inflow_attrs)
>>> outflow.set_attributes(outflow_attrs)
>>> sediment.set_attributes(sediment_attrs)
>>> snow_ice.set_attributes(snow_ice_attrs)
>>> wq_setup.set_attributes(wq_setup_attrs)
Initialise the GLMNML class and pass in the consolidated dictionaries (
returned by the call method of block classes).
>>> nml_file = glm_nml.GLMNML(
... glm_setup=glm_setup(),
... morphometry=morphometry(),
... time=time(),
... init_profiles=init_profiles(),
... mixing=mixing(),
... output=output(),
... meteorology=meteorology(),
... light=light(),
... bird_model=bird_model(),
... inflow=inflow(),
... outflow=outflow(),
... sediment=sediment(),
... snow_ice=snow_ice(),
... wq_setup=wq_setup()
... )
Write the .nml file with the write_nml() method.
write_nml(nml_file_path='glm3.nml')
¶
InflowBlock
¶
Bases: _BaseBlock
Return the &inflow parameter dictionary.
The &inflow parameters define river inflows and submerged inflows.
InflowBlock provides the means to construct a dictionary containing these
parameters for use in the glm_nml.GLMNML class. Model parameters are set
as attributes upon initialising an instance of the class or using the
set_attributes() method. The get_params() method returns the parameter
dictionary and performs optional error checking to ensure compliant
parameters.
Attributes:
| Name | Type | Description |
|---|---|---|
num_inflows |
Union[int, None]
|
Number of inflows to be simulated in this simulation. Default is
|
names_of_strms |
Union[List[str], str, None]
|
Names of each inflow. A list if |
subm_flag |
Union[List[bool], bool, None]
|
Switch indicating if the inflow is entering as a submerged input. A
list if |
strm_hf_angle |
Union[List[float], float, None]
|
Angle describing the width of an inflow river channel ("half angle"). A
list if |
strmbd_slope |
Union[List[float], float, None]
|
Slope of the streambed / river thalweg for each river (degrees). A
list if |
strmbd_drag |
Union[List[float], float, None]
|
Drag coefficient of the river inflow thalweg, to calculate entrainment
during insertion. A list if |
coef_inf_entrain |
Union[List[float], float, None]
|
Undocumented parameter. A list if |
inflow_factor |
Union[List[float], float, None]
|
Scaling factor that can be applied to adjust the provided input data.
A list if |
inflow_fl |
Union[List[str], str, None]
|
Filename(s) of the inflow CSV boundary condition files. A list if
|
inflow_varnum |
Union[int, None]
|
Number of variables being listed in the columns of |
inflow_vars |
Union[List[str], str, None]
|
Names of the variables in the |
time_fmt |
Union[str, None]
|
Time format of the 1st column in the |
Examples:
>>> from glmpy.nml import glm_nml
>>> inflow = glm_nml.InflowBlock(
... num_inflows=5,
... names_of_strms= ['Inflow1','Inflow2','Inflow3','Inflow4','Inflow5']
... )
>>> inflow_attrs = {
... "num_inflows": 6,
... "names_of_strms": [
... 'Inflow1','Inflow2','Inflow3','Inflow4','Inflow5','Inflow6'
... ],
... "subm_flag": [False, False, False, True, False, False],
... "strm_hf_angle": [85.0, 85.0, 85.0, 85.0, 85.0, 85.0],
... "strmbd_slope": [4.0, 4.0, 4.0, 4.0, 4.0, 4.0],
... "strmbd_drag": [0.0160, 0.0160, 0.0160, 0.0160, 0.0160, 0.0160],
... "inflow_factor": [1.0, 1.0, 1.0, 1.0, 1.0, 1.0],
... "inflow_fl": [
... 'bcs/inflow_1.csv', 'bcs/inflow_2.csv', 'bcs/inflow_3.csv',
... 'bcs/inflow_4.csv', 'bcs/inflow_5.csv', 'bcs/inflow_6.csv'
... ],
... "inflow_varnum": 3,
... "inflow_vars": ['FLOW', 'TEMP', 'SALT'],
... "coef_inf_entrain": 0.0,
... "time_fmt": 'YYYY-MM-DD hh:mm:ss'
... }
>>> inflow.set_attributes(inflow_attrs)
get_params(check_params=False)
¶
Returns a dictionary of model parameters.
Consolidate the model parameters set during class instance
initialisation, or updated through set_attributes(), into a
dictionary suitable for use with the glm_nml.GLMNML class.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
check_params |
bool
|
If |
False
|
Returns:
| Type | Description |
|---|---|
dict[str, Any]
|
A dictionary containing the configuration block parameters. |
set_attrs(attrs_dict)
¶
Set attributes for an instance of a configuration block class.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
attrs_dict |
dict
|
A dictionary of GLM parameters to set the respective attributes in the configuration block class instance. |
required |
Examples:
>>> from glmpy.nml import glm_nml
>>> glm_setup_attrs = {
... "sim_name": "Example Simulation #1",
... "max_layers": 500,
... "min_layer_thick": 0.15,
... "max_layer_thick": 1.50,
... "min_layer_vol": 0.025,
... "density_model": 1,
... "non_avg": False
... }
>>> glm_setup = glm_nml.SetupBlock()
>>> glm_setup.set_attrs(glm_setup_attrs)
InitProfilesBlock
¶
Bases: _BaseBlock
Construct the &init_profiles model parameters.
The &init_profiles parameters define the initial conditions at specific
depths in the water body. InitProfilesBlock provides the means to
construct a dictionary containing these parameters for use in the
glm_nml.GLMNML class. Model parameters are set as attributes upon
initialising an instance of the class or using the set_attributes()
method. The get_params() method returns the parameter dictionary and
performs optional error checking to ensure compliant parameters.
Attributes:
| Name | Type | Description |
|---|---|---|
lake_depth |
Union[float, None]
|
Initial lake height/depth (m). Default is |
num_depths |
Union[int, None]
|
Number of depths provided for initial profiles. Default is |
the_depths |
Union[List[float], float, None]
|
The depths of the initial profile points (m). Default is |
the_temps |
Union[List[float], float, None]
|
The temperature (°C) at each of the initial profile points. Default is
|
the_sals |
Union[List[float], float, None]
|
The salinity (ppt) at each of the initial profile points. Default is
|
num_wq_vars |
Union[int, None]
|
Number of non-GLM (i.e., FABM or AED2) variables to be initialised.
Default is |
wq_names |
Union[List[str], str, None]
|
Names of non-GLM (i.e., FABM or AED2) variables to be initialised.
Default is |
wq_init_vals |
Union[List[float], float, None]
|
Array of water quality variable initial data
(rows = vars; cols = depths). Default is |
Examples:
>>> from glmpy.nml import glm_nml
>>> init_profiles = glm_nml.InitProfilesBlock(
... lake_depth=43,
... num_depths=2
... )
>>> init_profiles_attrs = {
... "num_depths": 3,
... "the_depths": [1, 20, 40],
... "the_temps": [18.0, 18.0, 18.0],
... "the_sals": [ 0.5, 0.5, 0.5],
... "num_wq_vars": 6,
... "wq_names": [
... 'OGM_don','OGM_pon','OGM_dop','OGM_pop','OGM_doc','OGM_poc'
... ],
... "wq_init_vals": [
... 1.1, 1.2, 1.3, 1.2, 1.3,
... 2.1, 2.2, 2.3, 1.2, 1.3,
... 3.1, 3.2, 3.3, 1.2, 1.3,
... 4.1, 4.2, 4.3, 1.2, 1.3,
... 5.1, 5.2, 5.3, 1.2, 1.3,
... 6.1, 6.2, 6.3, 1.2, 1.3
... ]
... }
>>> init_profiles.set_attributes(init_profiles_attrs)
get_params(check_params=False)
¶
Returns a dictionary of model parameters.
Consolidate the model parameters set during class instance
initialisation, or updated through set_attributes(), into a
dictionary suitable for use with the glm_nml.GLMNML class.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
check_params |
bool
|
If |
False
|
Returns:
| Type | Description |
|---|---|
dict[str, Any]
|
A dictionary containing the configuration block parameters. |
set_attrs(attrs_dict)
¶
Set attributes for an instance of a configuration block class.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
attrs_dict |
dict
|
A dictionary of GLM parameters to set the respective attributes in the configuration block class instance. |
required |
Examples:
>>> from glmpy.nml import glm_nml
>>> glm_setup_attrs = {
... "sim_name": "Example Simulation #1",
... "max_layers": 500,
... "min_layer_thick": 0.15,
... "max_layer_thick": 1.50,
... "min_layer_vol": 0.025,
... "density_model": 1,
... "non_avg": False
... }
>>> glm_setup = glm_nml.SetupBlock()
>>> glm_setup.set_attrs(glm_setup_attrs)
LightBlock
¶
Bases: _BaseBlock
Construct the &light model parameters.
The &light parameters define light penertration into the water body.
LightBlock provides the means to construct a dictionary containing these
parameters for use in the glm_nml.GLMNML class. Model parameters are set
as attributes upon initialising an instance of the class or using the
set_attributes() method. The get_params() method returns the parameter
dictionary andperforms optional error checking to ensure compliant
parameters.
Attributes:
| Name | Type | Description |
|---|---|---|
light_mode |
Union[int, None]
|
Switch to configure the approach to light penetration. Options are |
Kw |
Union[float, None]
|
Light extinction coefficient (m^{-1}). Used when |
Kw_file |
Union[str, None]
|
Name of file with Kw time-series included. Default is |
n_bands |
Union[int, None]
|
Number of light bandwidths to simulate. Used when |
light_extc |
Union[List[float], float, None]
|
Comma-separated list of light extinction coefficients for each
waveband. Default is |
energy_frac |
Union[List[float], float, None]
|
Comma-separated list of energy fraction captured by each waveband. Default is None. |
Benthic_Imin |
Union[float, None]
|
Critical fraction of incident light reaching the benthos. Default is
|
Examples:
>>> from glmpy.nml import glm_nml
>>> light = glm_nml.LightBlock(
... light_mode=0,
... Kw=0.5
... )
>>> light_attrs = {
... "n_bands": 4,
... "light_extc": [1.0, 0.5, 2.0, 4.0],
... "energy_frac": [0.51, 0.45, 0.035, 0.005],
... "Benthic_Imin": 10
... }
>>> light.set_attributes(light_attrs)
get_params(check_params=False)
¶
Returns a dictionary of model parameters.
Consolidate the model parameters set during class instance
initialisation, or updated through set_attributes(), into a
dictionary suitable for use with the glm_nml.GLMNML class.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
check_params |
bool
|
If |
False
|
Returns:
| Type | Description |
|---|---|
dict[str, Any]
|
A dictionary containing the configuration block parameters. |
set_attrs(attrs_dict)
¶
Set attributes for an instance of a configuration block class.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
attrs_dict |
dict
|
A dictionary of GLM parameters to set the respective attributes in the configuration block class instance. |
required |
Examples:
>>> from glmpy.nml import glm_nml
>>> glm_setup_attrs = {
... "sim_name": "Example Simulation #1",
... "max_layers": 500,
... "min_layer_thick": 0.15,
... "max_layer_thick": 1.50,
... "min_layer_vol": 0.025,
... "density_model": 1,
... "non_avg": False
... }
>>> glm_setup = glm_nml.SetupBlock()
>>> glm_setup.set_attrs(glm_setup_attrs)
MeteorologyBlock
¶
Bases: _BaseBlock
Construct the &meteorology model parameters.
The &meteorology parameters define a variety of meteorological
dynamics, e.g., rainfall, air temperature, radiation, wind, and cloud
cover. MeteorologyBlock provides the means to construct a dictionary
containing these parameters for use in the glm_nml.GLMNML class. Model
parameters are set as attributes upon initialising an instance of the
class or using the set_attributes() method. The get_params() method
returns the parameter dictionary and performs optional error checking to
ensure compliant parameters.
Attributes:
| Name | Type | Description |
|---|---|---|
met_sw |
Union[bool, None]
|
Switch to enable the surface heating module. Default is |
meteo_fl |
Union[str, None]
|
Filename of the meterological file. Include path and filename. Default
is |
subdaily |
Union[bool, None]
|
Switch to indicate the meteorological data is provided with sub-daily
resolution, at an interval equivalent to |
time_fmt |
Union[str, None]
|
Time format of the 1st column in the inflow_fl. For example,
'YYYY-MM-DD hh |
rad_mode |
Union[int, None]
|
Switch to configure which incoming radiation option to use. Options are
|
albedo_mode |
Union[int, None]
|
Switch to configure which albedo calculation option is used. Options
are |
sw_factor |
Union[float, None]
|
Scaling factor to adjust the shortwave radiation data provided
in the |
lw_type |
Union[str, None]
|
Switch to configure which input approach is being used for
longwave/cloud data in the |
cloud_mode |
Union[int, None]
|
Switch to configure which atmospheric emmissivity calculation
option is used. Options are |
lw_factor |
Union[float, None]
|
Scaling factor to adjust the longwave (or cloud) data provided in the
|
atm_stab |
Union[int, None]
|
Switch to configure which approach to atmospheric stability is used.
|
rh_factor |
Union[float, None]
|
Scaling factor to adjust the relative humidity data provided in the
|
at_factor |
Union[float, None]
|
Scaling factor to adjust the air temperature data provided in the
|
ce |
Union[float, None]
|
Bulk aerodynamic transfer coefficient for latent heat flux. Default is
|
ch |
Union[float, None]
|
Bulk aerodynamic transfer coefficient for sensible heat flux. Default
is |
rain_sw |
Union[bool, None]
|
Switch to configure rainfall input concentrations. Default is |
rain_factor |
Union[float, None]
|
Scaling factor to adjust the rainfall data provided in the |
catchrain |
Union[bool, None]
|
Switch that configures runoff from exposed banks of lake area. Default
is |
rain_threshold |
Union[float, None]
|
Daily rainfall amount (m) required before runoff from exposed banks
occurs. Default is |
runoff_coef |
Union[float, None]
|
Conversion fraction of infiltration excess rainfall to runoff in
exposed lake banks. Default is |
cd |
Union[float, None]
|
Bulk aerodynamic transfer coefficient for momentum. Default is |
wind_factor |
Union[float, None]
|
Scaling factor to adjust the windspeed data provided in the |
fetch_mode |
Union[int, None]
|
Switch to configure which wind-sheltering/fetch option to use. Options
are |
Aws |
Union[float, None]
|
Undocumented parameter. Required if |
Xws |
Union[float, None]
|
Undocumented parameter. Required if |
num_dir |
Union[int, None]
|
Number of wind direction reference points being read in. Required if
|
wind_dir |
Union[float, None]
|
Wind directions used for wind-sheltering effects. Required if
|
fetch_scale |
Union[float, None]
|
Direction specific wind-sheltering scaling factors. Required if
|
ss'. Default is Examples:
>>> from glmpy.nml import glm_nml
>>> meteorology = glm_nml.MeteorologyBlock(
... met_sw=True,
... lw_type='LW_NET'
... )
>>> meteorology_attrs = {
... "lw_type": "LW_IN",
... "rain_sw": False,
... "atm_stab": 0,
... "fetch_mode": 0,
... "rad_mode": 1,
... "albedo_mode": 1,
... "cloud_mode": 4,
... "subdaily": True,
... "meteo_fl": 'bcs/met_hourly.csv',
... "wind_factor": 0.9,
... "ce": 0.0013,
... "ch": 0.0013,
... "cd": 0.0013,
... "catchrain": True,
... "rain_threshold": 0.001,
... "runoff_coef": 0.0
... }
>>> meteorology.set_attributes(meteorology_attrs)
get_params(check_params=False)
¶
Returns a dictionary of model parameters.
Consolidate the model parameters set during class instance
initialisation, or updated through set_attributes(), into a
dictionary suitable for use with the glm_nml.GLMNML class.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
check_params |
bool
|
If |
False
|
Returns:
| Type | Description |
|---|---|
dict[str, Any]
|
A dictionary containing the configuration block parameters. |
set_attrs(attrs_dict)
¶
Set attributes for an instance of a configuration block class.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
attrs_dict |
dict
|
A dictionary of GLM parameters to set the respective attributes in the configuration block class instance. |
required |
Examples:
>>> from glmpy.nml import glm_nml
>>> glm_setup_attrs = {
... "sim_name": "Example Simulation #1",
... "max_layers": 500,
... "min_layer_thick": 0.15,
... "max_layer_thick": 1.50,
... "min_layer_vol": 0.025,
... "density_model": 1,
... "non_avg": False
... }
>>> glm_setup = glm_nml.SetupBlock()
>>> glm_setup.set_attrs(glm_setup_attrs)
MixingBlock
¶
Bases: _BaseBlock
Construct the &mixing model parameters.
The &mixing parameters define the dynamics of layer mixing in the
modelled water body. MixingBlock provides the means to construct a
dictionary containing these parameters for use in the glm_nml.GLMNML
class. Model parameters are set as attributes upon initialising an instance
of the class or using the set_attributes() method. The get_params()
method returns the parameter dictionary and performs optional error
checking to ensure compliant parameters.
Attributes:
| Name | Type | Description |
|---|---|---|
surface_mixing |
Union[int, None]
|
Switch to select the options of the surface mixing model. Options are
|
coef_mix_conv |
Union[float, None]
|
Mixing efficiency - convective overturn. Default is |
coef_wind_stir |
Union[float, None]
|
Mixing efficiency - wind stirring. Default is |
coef_mix_shear |
Union[float, None]
|
Mixing efficiency - shear production. Default is |
coef_mix_turb |
Union[float, None]
|
Mixing efficiency - unsteady turbulence effects. Default is |
coef_mix_KH |
Union[float, None]
|
Mixing efficiency - Kelvin-Helmholtz billowing. Default is |
deep_mixing |
Union[int, None]
|
Switch to select the options of the deep (hypolimnetic) mixing model.
Options are |
coef_mix_hyp |
Union[float, None]
|
Mixing efficiency - hypolimnetic turbulence. Default is |
diff |
Union[float, None]
|
Background (molecular) diffusivity in the hypolimnion. Default is
|
Examples:
>>> from glmpy.nml import glm_nml
>>> mixing = glm_nml.MixingBlock(
... surface_mixing=1,
... coef_mix_conv=0.1,
... )
>>> mixing_attrs = {
... "coef_mix_conv": 0.125,
... "coef_wind_stir": 0.23,
... "coef_mix_shear":0.2,
... "coef_mix_turb": 0.51,
... "coef_mix_KH": 0.3,
... "deep_mixing": 2,
... "coef_mix_hyp": 0.5,
... "diff": 0.0
... }
>>> mixing.set_attributes(mixing_attrs)
get_params(check_params=False)
¶
Returns a dictionary of model parameters.
Consolidate the model parameters set during class instance
initialisation, or updated through set_attributes(), into a
dictionary suitable for use with the glm_nml.GLMNML class.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
check_params |
bool
|
If |
False
|
Returns:
| Type | Description |
|---|---|
dict[str, Any]
|
A dictionary containing the configuration block parameters. |
set_attrs(attrs_dict)
¶
Set attributes for an instance of a configuration block class.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
attrs_dict |
dict
|
A dictionary of GLM parameters to set the respective attributes in the configuration block class instance. |
required |
Examples:
>>> from glmpy.nml import glm_nml
>>> glm_setup_attrs = {
... "sim_name": "Example Simulation #1",
... "max_layers": 500,
... "min_layer_thick": 0.15,
... "max_layer_thick": 1.50,
... "min_layer_vol": 0.025,
... "density_model": 1,
... "non_avg": False
... }
>>> glm_setup = glm_nml.SetupBlock()
>>> glm_setup.set_attrs(glm_setup_attrs)
MorphometryBlock
¶
Bases: _BaseBlock
Construct the &morphometry model parameters.
The &morphometry parameters define the physical dimensions and location
of the water body. MorphometryBlock provides the means to construct a
dictionary containing these parameters for use in the glm_nml.GLMNML
class. Model parameters are set as attributes upon initialising an instance
of the class or using the set_attributes() method. The get_params()
method returns the parameter dictionary and performs optional error
checking to ensure compliant parameters.
Attributes:
| Name | Type | Description |
|---|---|---|
lake_name |
Union[str, None]
|
Site name. Default is |
latitude |
Union[float, None]
|
Latitude, positive North (°N). Default is |
longitude |
Union[float, None]
|
Longitude, positive East (°E). Default is |
base_elev |
Union[float, None]
|
Elevation of the bottom-most point of the lake (m above datum). Default
is |
crest_elev |
Union[float, None]
|
Elevation of a weir crest, where overflow begins (m above datum).
Default is |
bsn_len |
Union[float, None]
|
Length of the lake basin, at crest height (m). Default is |
bsn_wid |
Union[float, None]
|
Width of the lake basin, at crest height (m). Default is |
bsn_vals |
Union[float, None]
|
Number of points being provided to described the hyposgraphic details.
Default is |
H |
Union[List[float], None]
|
Comma-separated list of lake elevations (m above datum). Default is
|
A |
Union[List[float], None]
|
Comma-separated list of lake areas (m^2). Default is |
Examples:
>>> from glmpy.nml import glm_nml
>>> morphometry = glm_nml.MorphometryBlock(
... lake_name='Example Lake',
... latitude=30.0
... )
>>> morphometry_attrs = {
... "latitude": 32.0,
... "longitude": 35.0,
... "base_elev": -252.9,
... "crest_elev": -203.9,
... "bsn_len": 21000.0,
... "bsn_wid": 13000.0,
... "bsn_vals": 45,
... "H": [
... -252.9, -251.9, -250.9, -249.9, -248.9, -247.9, -246.9, -245.9,
... -244.9, -243.9, -242.9, -241.9, -240.9, -239.9, -238.9, -237.9,
... -236.9, -235.9, -234.9, -233.9, -232.9, -231.9, -230.9, -229.9,
... -228.9, -227.9, -226.9, -225.9, -224.9, -223.9, -222.9, -221.9,
... -220.9, -219.9, -218.9, -217.9, -216.9, -215.9, -214.9, -213.9,
... -212.9, -211.9, -208.9, -207.9, -203.9
... ],
... "A": [
... 0, 9250000, 15200000, 17875000, 21975000, 26625000, 31700000,
... 33950000, 38250000, 41100000, 46800000, 51675000, 55725000,
... 60200000, 64675000, 69600000, 74475000, 79850000, 85400000,
... 90975000, 96400000, 102000000, 107000000, 113000000, 118000000,
... 123000000, 128000000, 132000000, 136000000, 139000000,
... 143000000, 146000000, 148000000, 150000000, 151000000,
... 153000000, 155000000, 157000000, 158000000, 160000000,
... 161000000, 162000000, 167000000, 170000000, 173000000
... ]
... }
>>> morphometry.set_attributes(morphometry_attrs)
get_params(check_params=False)
¶
Returns a dictionary of model parameters.
Consolidate the model parameters set during class instance
initialisation, or updated through set_attributes(), into a
dictionary suitable for use with the glm_nml.GLMNML class.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
check_params |
bool
|
If |
False
|
Returns:
| Type | Description |
|---|---|
dict[str, Any]
|
A dictionary containing the configuration block parameters. |
set_attrs(attrs_dict)
¶
Set attributes for an instance of a configuration block class.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
attrs_dict |
dict
|
A dictionary of GLM parameters to set the respective attributes in the configuration block class instance. |
required |
Examples:
>>> from glmpy.nml import glm_nml
>>> glm_setup_attrs = {
... "sim_name": "Example Simulation #1",
... "max_layers": 500,
... "min_layer_thick": 0.15,
... "max_layer_thick": 1.50,
... "min_layer_vol": 0.025,
... "density_model": 1,
... "non_avg": False
... }
>>> glm_setup = glm_nml.SetupBlock()
>>> glm_setup.set_attrs(glm_setup_attrs)
OutflowBlock
¶
Bases: _BaseBlock
Construct the &outflow model parameters.
The &outflow parameters define withdrawals, outlets, offtakes, and
seepage. OutflowBlock provides the means to construct a dictionary
containing these parameters for use in the glm_nml.GLMNML class. Model
parameters are set as attributes upon initialising an instance of the class
or using the set_attributes() method. The get_params() method returns
the parameter dictionary and performs optional error checking to ensure
compliant parameters.
Attributes:
| Name | Type | Description |
|---|---|---|
num_outlet |
Union[int, None]
|
Number of outflows (including withdrawals, outlets or offtakes) to be
included in this simulation. Default is |
outflow_fl |
Union[List[str], str, None]
|
Filename of the file containing the outflow time-series.
A list if |
time_fmt |
Union[str, None]
|
Time format of the 1st column in the |
outflow_factor |
Union[List[float], float, None]
|
Scaling factor used as a multiplier for outflows. A list if
|
outflow_thick_limit |
Union[List[float], float, None]
|
Maximum vertical limit of withdrawal entrainment. A list if
|
single_layer_draw |
Union[List[bool], bool, None]
|
Switch to only limit withdrawal entrainment and force outflows from
layer at the outlet elevation height. A list if |
flt_off_sw |
Union[List[bool], bool, None]
|
Switch to indicate if the outflows are floating offtakes (taking water
from near the surface). A list if |
outlet_type |
Union[List[int], int, None]
|
Switch to configure approach of each withdrawal. Options are |
outl_elvs |
Union[List[float], float, None]
|
Outlet elevations (m). A list if |
bsn_len_outl |
Union[List[float], float, None]
|
Basin length at the outlet height(s) (m). A list if |
bsn_wid_outl |
Union[List[float], float, None]
|
Basin width at the outlet heights (m). A list if |
crit_O2 |
Union[int, None]
|
Undocumented parameter. Default is |
crit_O2_dep |
Union[int, None]
|
Undocumented parameter. Default is |
crit_O2_days |
Union[int, None]
|
Undocumented parameter. Default is |
outlet_crit |
Union[int, None]
|
Undocumented parameter. Default is |
O2name |
Union[str, None]
|
Undocumented parameter. Default is |
O2idx |
Union[str, None]
|
Undocumented parameter. Default is |
target_temp |
Union[float, None]
|
Undocumented parameter. Default is |
min_lake_temp |
Union[float, None]
|
Undocumented parameter. Default is |
fac_range_upper |
Union[float, None]
|
Undocumented parameter. Default is |
fac_range_lower |
Union[float, None
|
Undocumented parameter. Default is |
mix_withdraw |
Union[bool, None]
|
Undocumented parameter. Default is |
coupl_oxy_sw |
Union[bool, None]
|
Undocumented parameter. Default is |
withdrTemp_fl |
Union[str, None]
|
Filename of the file containing the temperature time-series the
adaptive withdrawal is targeting. Required if |
seepage |
Union[bool, None]
|
Switch to enable the seepage of water from the lake bottom. Default is
|
seepage_rate |
Union[float, None]
|
Seepage rate of water, or, soil hydraulic conductivity (m day^{-1}).
Default is |
crest_width |
Union[float, None]
|
Width of weir (at crest height) where lake overflows (m). Default is
|
crest_factor |
Union[float, None]
|
Drag coefficient associated with the weir crest, used to compute the
overflow discharge rate. Applies only when the crest elevation is
configured to be less than the maximum elevation of the domain. Default
is |
Examples:
>>> from glmpy.nml import glm_nml
>>> outflow = glm_nml.OutflowBlock(
... num_outlet=1,
... flt_off_sw=True
... )
>>> outflow_attrs = {
... "flt_off_sw": False,
... "outlet_type": 1,
... "outl_elvs": -215.5,
... "bsn_len_outl": 18000,
... "bsn_wid_outl": 11000,
... "outflow_fl" : 'bcs/outflow.csv',
... "outflow_factor": 1.0,
... "seepage": True,
... "seepage_rate": 0.01
... }
>>> outflow.set_attributes(outflow_attrs)
get_params(check_params=False)
¶
Returns a dictionary of model parameters.
Consolidate the model parameters set during class instance
initialisation, or updated through set_attributes(), into a
dictionary suitable for use with the glm_nml.GLMNML class.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
check_params |
bool
|
If |
False
|
Returns:
| Type | Description |
|---|---|
dict[str, Any]
|
A dictionary containing the configuration block parameters. |
set_attrs(attrs_dict)
¶
Set attributes for an instance of a configuration block class.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
attrs_dict |
dict
|
A dictionary of GLM parameters to set the respective attributes in the configuration block class instance. |
required |
Examples:
>>> from glmpy.nml import glm_nml
>>> glm_setup_attrs = {
... "sim_name": "Example Simulation #1",
... "max_layers": 500,
... "min_layer_thick": 0.15,
... "max_layer_thick": 1.50,
... "min_layer_vol": 0.025,
... "density_model": 1,
... "non_avg": False
... }
>>> glm_setup = glm_nml.SetupBlock()
>>> glm_setup.set_attrs(glm_setup_attrs)
OutputBlock
¶
Bases: _BaseBlock
Construct the &output model parameters.
The &output parameters define the contents and location of GLM output
files. OutputBlock provides the means to construct a dictionary
containing these parameters for use in the glm_nml.GLMNML class. Model
parameters are set as attributes upon initialising an instance of the class
or using the set_attributes() method. The get_params() method returns
the parameter dictionary and performs optional error checking to ensure
compliant parameters.
Attributes:
| Name | Type | Description |
|---|---|---|
out_dir |
Union[str, None]
|
Directory to write the output files. Default is |
out_fn |
Union[str, None]
|
Filename of the main NetCDF output file. Default is |
nsave |
Union[int, None]
|
Frequency to write to the NetCDF and CSV point files. Default is
|
csv_lake_fname |
Union[str, None]
|
Filename for the daily summary file. Default is |
csv_point_nlevs |
Union[float, None]
|
Number of specific level/depth CSV files to be created. Default is
|
csv_point_fname |
Union[str, None]
|
Name to be appended to specified depth CSV files. Default is |
csv_point_frombot |
Union[List[float], float, None]
|
Comma separated list identify whether each output point listed in
csv_point_at is relative to the bottom (i.e., heights) or the surface
(i.e., depths). Default is |
csv_point_at |
Union[List[float], float, None]
|
Height or Depth of points to output at (comma-separated list). Default
is |
csv_point_nvars |
Union[int, None]
|
Number of variables to output into the csv files. Default is |
csv_point_vars |
Union[List[str], str, None]
|
Comma separated list of variable names. Default is |
csv_outlet_allinone |
Union[bool, None]
|
Switch to create an optional outlet file combining all outlets. Default
is |
csv_outlet_fname |
Union[str, None]
|
Name to be appended to each of the outlet CSV files. Default is |
csv_outlet_nvars |
Union[int, None]
|
Number of variables to be written into the outlet file(s). Default is
|
csv_outlet_vars |
Union[List[str], str, None]
|
Comma separated list of variable names to be included in the output
file(s). Default is |
csv_ovrflw_fname |
Union[str, None]
|
Filename to be used for recording the overflow details. Default is
|
Examples:
>>> from glmpy.nml import glm_nml
>>> output = glm_nml.OutputBlock(
... out_dir="output",
... out_fn="output_file"
... )
>>> output_attrs = {
... 'out_fn': 'output',
... 'nsave': 6,
... 'csv_lake_fname': 'lake',
... 'csv_point_nlevs': 2,
... 'csv_point_fname': 'WQ_' ,
... 'csv_point_at': [5, 30],
... 'csv_point_nvars': 7,
... 'csv_point_vars': [
... 'temp', 'salt', 'OXY_oxy', 'SIL_rsi',
... 'NIT_amm', 'NIT_nit', 'PHS_frp'
... ],
... 'csv_outlet_allinone': False,
... 'csv_outlet_fname': 'outlet_',
... 'csv_outlet_nvars': 4,
... 'csv_outlet_vars': ['flow', 'temp', 'salt', 'OXY_oxy'],
... 'csv_ovrflw_fname': "overflow"
... }
>>> output.set_attributes(output_attrs)
get_params(check_params=False)
¶
Returns a dictionary of model parameters.
Consolidate the model parameters set during class instance
initialisation, or updated through set_attributes(), into a
dictionary suitable for use with the glm_nml.GLMNML class.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
check_params |
bool
|
If |
False
|
Returns:
| Type | Description |
|---|---|
dict[str, Any]
|
A dictionary containing the configuration block parameters. |
set_attrs(attrs_dict)
¶
Set attributes for an instance of a configuration block class.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
attrs_dict |
dict
|
A dictionary of GLM parameters to set the respective attributes in the configuration block class instance. |
required |
Examples:
>>> from glmpy.nml import glm_nml
>>> glm_setup_attrs = {
... "sim_name": "Example Simulation #1",
... "max_layers": 500,
... "min_layer_thick": 0.15,
... "max_layer_thick": 1.50,
... "min_layer_vol": 0.025,
... "density_model": 1,
... "non_avg": False
... }
>>> glm_setup = glm_nml.SetupBlock()
>>> glm_setup.set_attrs(glm_setup_attrs)
SedimentBlock
¶
Bases: _BaseBlock
Construct the &sediment model parameters.
The &sediment parameters define the thermal properties of the
soil-sediment. SedimentBlock provides the means to construct a dictionary
containing these parameters for use in the glm_nml.GLMNML class. Model
parameters are set as attributes upon initialising an instance of the class
or using the set_attributes() method. The get_params() method returns
the parameter dictionary and performs optional error checking to ensure
compliant parameters.
Attributes:
| Name | Type | Description |
|---|---|---|
sed_heat_Ksoil |
Union[float, None]
|
Heat conductivity of soil/sediment. Default is |
sed_temp_depth |
Union[float, None]
|
Depth of soil/sediment layer below the lake bottom, used for heat flux
calculation. Default is |
sed_temp_mean |
Union[List[float], float, None]
|
Annual mean sediment temperature. A list if |
sed_temp_amplitude |
Union[List[float], float, None]
|
Amplitude of temperature variation experienced in the sediment over one
year. A list if |
sed_temp_peak_doy |
Union[List[int], int, None]
|
Day of the year where the sediment temperature peaks. A list if
|
benthic_mode |
Union[int, None]
|
Switch to configure which mode of benthic interaction to apply. Options
are |
n_zones |
Union[int, None]
|
Number of sediment zones to simulate. Required if |
zone_heights |
Union[List[float], float, None]
|
Upper height of zone boundary. Required if |
sed_reflectivity |
Union[List[float], float, None]
|
Sediment reflectivity. Default is |
sed_roughness |
Union[List[float], float, None]
|
Undocumented parameter. Default is |
Examples:
>>> from glmpy.nml import glm_nml
>>> sediment = glm_nml.SedimentBlock(
... sed_heat_Ksoil=0.0,
... sed_temp_depth=0.1
... )
>>> sediment_attrs = {
... "sed_temp_depth": 0.2,
... "sed_temp_mean": [5, 10, 20],
... "sed_temp_amplitude": [6, 8, 10],
... "sed_temp_peak_doy": [80, 70, 60],
... "benthic_mode": 1,
... "n_zones": 3,
... "zone_heights": [10.0, 20.0, 50.0],
... "sed_reflectivity": [0.1, 0.01, 0.01],
... "sed_roughness": [0.1, 0.01, 0.01]
... }
>>> sediment.set_attributes(sediment_attrs)
get_params(check_params=False)
¶
Returns a dictionary of model parameters.
Consolidate the model parameters set during class instance
initialisation, or updated through set_attributes(), into a
dictionary suitable for use with the glm_nml.GLMNML class.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
check_params |
bool
|
If |
False
|
Returns:
| Type | Description |
|---|---|
dict[str, Any]
|
A dictionary containing the configuration block parameters. |
set_attrs(attrs_dict)
¶
Set attributes for an instance of a configuration block class.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
attrs_dict |
dict
|
A dictionary of GLM parameters to set the respective attributes in the configuration block class instance. |
required |
Examples:
>>> from glmpy.nml import glm_nml
>>> glm_setup_attrs = {
... "sim_name": "Example Simulation #1",
... "max_layers": 500,
... "min_layer_thick": 0.15,
... "max_layer_thick": 1.50,
... "min_layer_vol": 0.025,
... "density_model": 1,
... "non_avg": False
... }
>>> glm_setup = glm_nml.SetupBlock()
>>> glm_setup.set_attrs(glm_setup_attrs)
SetupBlock
¶
Bases: _BaseBlock
Construct the &glm_setup model parameters.
The &glm_setup parameters define the vertical series of layers that GLM
resolves when modelling a water body. SetupBlock provides the means to
construct a dictionary containing these parameters for use in the
glm_nml.GLMNML class. Model parameters are set as attributes upon
initialising an instance of the class or using the set_attributes()
method. The get_params() method returns the parameter dictionary and
performs optional error checking to ensure compliant parameters.
Attributes:
| Name | Type | Description |
|---|---|---|
sim_name |
Union[str, None]
|
Title of simulation. Default is |
max_layers |
Union[int, None]
|
Maximum number of layers. Default is |
min_layer_vol |
Union[float, None]
|
Minimum layer volume (m^3). Default is |
min_layer_thick |
Union[float, None]
|
Minimum thickness of a layer (m). Default is |
max_layer_thick |
Union[float, None]
|
Maximum thickness of a layer (m). Default is |
density_model |
Union[int, None]
|
Switch to set the density equation. Options are |
non_avg |
Union[bool, None]
|
Switch to configure flow boundary condition temporal interpolation.
Default is |
Examples:
>>> from glmpy.nml import glm_nml
>>> glm_setup = glm_nml.SetupBlock(
... sim_name="Example Simulation #1",
... max_layers=250
... )
>>> glm_setup_attrs = {
... "max_layers": 500,
... "min_layer_thick": 0.15,
... "max_layer_thick": 1.50,
... "min_layer_vol": 0.025,
... "density_model": 1,
... "non_avg": False
... }
>>> glm_setup.set_attributes(glm_setup_attrs)
get_params(check_params=False)
¶
Returns a dictionary of model parameters.
Consolidate the model parameters set during class instance
initialisation, or updated through set_attributes(), into a
dictionary suitable for use with the glm_nml.GLMNML class.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
check_params |
bool
|
If |
False
|
Returns:
| Type | Description |
|---|---|
dict[str, Any]
|
A dictionary containing the configuration block parameters. |
set_attrs(attrs_dict)
¶
Set attributes for an instance of a configuration block class.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
attrs_dict |
dict
|
A dictionary of GLM parameters to set the respective attributes in the configuration block class instance. |
required |
Examples:
>>> from glmpy.nml import glm_nml
>>> glm_setup_attrs = {
... "sim_name": "Example Simulation #1",
... "max_layers": 500,
... "min_layer_thick": 0.15,
... "max_layer_thick": 1.50,
... "min_layer_vol": 0.025,
... "density_model": 1,
... "non_avg": False
... }
>>> glm_setup = glm_nml.SetupBlock()
>>> glm_setup.set_attrs(glm_setup_attrs)
SnowIceBlock
¶
Bases: _BaseBlock
Construct the &snowice model parameters.
The &snowice parameters define the formation of snow and ice cover on the
water body. SetupBlock provides the means to construct a dictionary
containing these parameters for use in the glm_nml.GLMNML class. Model
parameters are set as attributes upon initialising an instance of the
class or using the set_attributes() method. The get_params() method
returns the parameter dictionary and performs optional error checking to
ensure compliant parameters.
Attributes:
| Name | Type | Description |
|---|---|---|
snow_albedo_factor |
Union[float, None]
|
Scaling factor used to as a multiplier to scale the snow/ice albedo
estimate. Default is |
snow_rho_max |
Union[float, None]
|
Minimum snow density allowable (kg m^{-3}). Default is |
snow_rho_min |
Union[float, None]
|
Maximum snow density allowable (kg m^{-3}). Default is |
Examples:
>>> from glmpy.nml import glm_nml
>>> snow_ice = glm_nml.SnowIceBlock(
... snow_albedo_factor=1.0,
... snow_rho_min=40
... )
>>> snow_ice_attrs = {
... "snow_rho_min": 50,
... "snow_rho_max": 300
... }
>>> snow_ice.set_attributes(snow_ice_attrs)
get_params(check_params=False)
¶
Returns a dictionary of model parameters.
Consolidate the model parameters set during class instance
initialisation, or updated through set_attributes(), into a
dictionary suitable for use with the glm_nml.GLMNML class.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
check_params |
bool
|
If |
False
|
Returns:
| Type | Description |
|---|---|
dict[str, Any]
|
A dictionary containing the configuration block parameters. |
set_attrs(attrs_dict)
¶
Set attributes for an instance of a configuration block class.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
attrs_dict |
dict
|
A dictionary of GLM parameters to set the respective attributes in the configuration block class instance. |
required |
Examples:
>>> from glmpy.nml import glm_nml
>>> glm_setup_attrs = {
... "sim_name": "Example Simulation #1",
... "max_layers": 500,
... "min_layer_thick": 0.15,
... "max_layer_thick": 1.50,
... "min_layer_vol": 0.025,
... "density_model": 1,
... "non_avg": False
... }
>>> glm_setup = glm_nml.SetupBlock()
>>> glm_setup.set_attrs(glm_setup_attrs)
TimeBlock
¶
Bases: _BaseBlock
Construct the &time model parameters.
The &time parameters define the duration and timestep of a GLM
simulation. TimeBlock provides the means to construct a dictionary
containing these parameters for use in the glm_nml.GLMNML class. Model
parameters are set as attributes upon initialising an instance of the class
or using the set_attributes() method. The get_params() method returns
the parameter dictionary and performs optional error checking to ensure
compliant parameters.
Attributes:
| Name | Type | Description |
|---|---|---|
timefmt |
Union[int, None]
|
Time configuration switch. Options are |
start |
Union[str, None]
|
Start time/date of simulation in format 'yyyy-mm-dd hh |
stop |
Union[str, None]
|
End time/date of simulation in format 'yyyy-mm-dd hh |
dt |
Union[float, None]
|
Time step (seconds). Default is |
num_days |
Union[int, None]
|
Number of days to simulate. Used when |
timezone |
Union[float, None]
|
UTC time zone. Default is |
Examples:
>>> from glmpy.nml import glm_nml
>>> time = glm_nml.TimeBlock(
... timefmt=3,
... start="1998-01-01 00:00:00"
... )
>>> time_attrs = {
... "start": "1997-01-01 00:00:00",
... "stop": "1999-01-01 00:00:00",
... "dt": 3600.0,
... "num_days": 730,
... "timezone": 7.0
... }
>>> time.set_attributes(time_attrs)
get_params(check_params=False)
¶
Returns a dictionary of model parameters.
Consolidate the model parameters set during class instance
initialisation, or updated through set_attributes(), into a
dictionary suitable for use with the glm_nml.GLMNML class.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
check_params |
bool
|
If |
False
|
Returns:
| Type | Description |
|---|---|
dict[str, Any]
|
A dictionary containing the configuration block parameters. |
set_attrs(attrs_dict)
¶
Set attributes for an instance of a configuration block class.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
attrs_dict |
dict
|
A dictionary of GLM parameters to set the respective attributes in the configuration block class instance. |
required |
Examples:
>>> from glmpy.nml import glm_nml
>>> glm_setup_attrs = {
... "sim_name": "Example Simulation #1",
... "max_layers": 500,
... "min_layer_thick": 0.15,
... "max_layer_thick": 1.50,
... "min_layer_vol": 0.025,
... "density_model": 1,
... "non_avg": False
... }
>>> glm_setup = glm_nml.SetupBlock()
>>> glm_setup.set_attrs(glm_setup_attrs)
WQSetupBlock
¶
Bases: _BaseBlock
Construct the &wq_setup model parameters.
The &wq_setup parameters define the coupling of GLM with water quality
and biogeochemical model libraries, e.g., AED2. WQSetupBlock provides the
means to construct a dictionary containing these parameters for use in the
glm_nml.GLMNML class. Model parameters are set as attributes upon
initialising an instance of the class or using the set_attributes()
method. The get_params() method returns the parameter dictionary and
performs optional error checking to ensure compliant parameters.
wq_lib : Union[str, None]
Water quality model selection. Options are "aed2" and "fabm".
Default is None.
wq_nml_file : Union[str, None]
Filename of water quality configuration file, e.g., "./aed2.nml".
Default is None.
bioshade_feedback : Union[bool, None]
Switch to enable K_{w} to be updated by the WQ model. Default is
None.
mobility_off : Union[bool, None]
Switch to enable settling within the WQ model. Default is None.
ode_method : Union[int, None]
Method to use for ODE solution of water quality module. Default is
None.
split_factor : Union[float, None]
Factor weighting implicit vs explicit numerical solution of the WQ
model. split_factor has a valid range between 0.0 and 1.0.
Default is None.
repair_state : Union[bool, None]
Switch to correct negative or out of range WQ variables. Default is
None.
Examples:
>>> from glmpy.nml import glm_nml
>>> wq_setup = glm_nml.WQSetupBlock(
... wq_lib="aed2",
... wq_nml_file = "aed2/aed2.nml"
... )
>>> wq_setup_attrs = {
... "wq_nml_file": "aed2/aed2.nml",
... "ode_method": 1,
... "split_factor": 1,
... "bioshade_feedback": True,
... "repair_state": True,
... "mobility_off": False
... }
>>> wq_setup.set_attributes(wq_setup_attrs)
get_params(check_params=False)
¶
Returns a dictionary of model parameters.
Consolidate the model parameters set during class instance
initialisation, or updated through set_attributes(), into a
dictionary suitable for use with the glm_nml.GLMNML class.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
check_params |
bool
|
If |
False
|
Returns:
| Type | Description |
|---|---|
dict[str, Any]
|
A dictionary containing the configuration block parameters. |
set_attrs(attrs_dict)
¶
Set attributes for an instance of a configuration block class.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
attrs_dict |
dict
|
A dictionary of GLM parameters to set the respective attributes in the configuration block class instance. |
required |
Examples:
>>> from glmpy.nml import glm_nml
>>> glm_setup_attrs = {
... "sim_name": "Example Simulation #1",
... "max_layers": 500,
... "min_layer_thick": 0.15,
... "max_layer_thick": 1.50,
... "min_layer_vol": 0.025,
... "density_model": 1,
... "non_avg": False
... }
>>> glm_setup = glm_nml.SetupBlock()
>>> glm_setup.set_attrs(glm_setup_attrs)
nml
¶
NMLReader
¶
Bases: _NML
Read NML files.
Read a NML file and return a dictionary of parameters that have been
converted to Python data types. By default, NMLReader can parse
parameters from the standard GLM NML configuration blocks. This
functionality can expanded to read other non-standard blocks, or overwrite
exisiting parameter conversion methods, using the converters
argument. The converted NML dictionary can be returned in its entirety with
get_nml(), or by block with get_block(), or saved directly to a JSON
file with write_json().
Unexpected behaviour will occur if:
-
Exclamation marks (
!) are used within a string parameter, e.g.,sim_name = 'A very important sim!'. Exclamation marks are used to declare comments in NML files. -
You terminate a comma-separated list with a comma, e.g.,
A = 100, 3600, 5600,. Remove the final comma:A = 100, 3600, 5600.
NMLReader provides the following static methods to convert from NML
syntax to Python syntax:
-
read_nml_int: NML integer to Python integer. -
read_nml_float: NML float to Python float. -
read_nml_bool: NML boolean to Python boolean. -
read_nml_str: NML string to Python string. -
read_nml_list: NML list (comma-separated values) to Python list. -
read_nml_array: NML array to Python array.
Attributes:
| Name | Type | Description |
|---|---|---|
nml_file |
Union[str, PathLike]
|
Path to the NML file. |
Examples:
Fetch an individual block of parameters with the get_block() method:
>>> my_nml = nml.NMLReader(nml_file="glm3.nml")
>>> setup = my_nml.get_block("glm_setup")
>>> print(setup)
{
"sim_name": "GLM Simulation",
"max_layers": 60,
"min_layer_vol": 0.0005,
"min_layer_thick": 0.05,
"max_layer_thick": 0.1,
"non_avg": True
}
>>> glm_setup = nml.NMLGLMSetup()
>>> glm_setup.set_attributes(setup)
Expand the functionality of NMLReader to read in a non-standard block:
>>> debugging_types = {
... "debugging": {
... "disable_evap": nml.NMLReader.read_nml_bool
... }
>>> my_nml = nml.NMLReader(
... nml_file="glm3.nml", converters=debugging_types
... )
>>> debugging = my_nml.get_block("debugging")
>>> print(debugging)
{
"disable_evap": False
}
Convert the NML file directly to a JSON file with write_json():
get_block(block)
¶
Get a block of parameters.
Returns a dictionary of model parameters for a specified block. Useful
for setting the attributes of the corresponding nml.NML* class.
Parameters block block_name: str Name of the block to fetch the parameter dictionary for.
Examples:
get_converters(block=None)
¶
Get the current dictionary of methods for reading/writing NML parameters.
Returns a dictionary of the syntax conversion methods used in the
instance of NMLReaderor NMLWriter.
get_nml()
¶
read_nml_array(nml_array, converter_func)
staticmethod
¶
NML array to Python nested list.
Converts a NML array of comma-separated values to a nested Python list. Applies a defined syntax function to each element of the array. Returns a nested Python list where each row of the array is a list.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
nml_array |
List[str]
|
A Python list of strings of comma-separated values. |
required |
converter_func |
Callable
|
|
required |
array |
|
required | |
e |
|
required |
Examples:
Converting an array of floats of size 1x3:
>>> from glmpy.nml import nml
>>> my_nml_array = ["1.1, 1.2, 1.3"]
>>> python_arary = nml.NMLReader.read_nml_array(
... my_nml_array,
... converter_func=nml.NMLReader.read_nml_float
... )
>>> print(python_arary)
>>> print(type(python_arary))
Converting an array of floats of size 2x3:
read_nml_bool(nml_bool)
staticmethod
¶
NML bool to Python bool.
Converts a string containing a NML-like boolean to a Python boolean.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
nml_bool |
str
|
A string representing a NML boolean. Valid booleans are |
required |
Examples:
read_nml_float(nml_float)
staticmethod
¶
NML float to Python float.
Converts a string containing a NML-like float to a Python float.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
nml_float |
str
|
A string representing a NML float. |
required |
Examples:
read_nml_int(nml_int)
staticmethod
¶
NML int to Python int.
Converts a string containing a NML-like integer to a Python integer.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
nml_int |
str
|
A string representing a NML integer. |
required |
Examples:
read_nml_list(nml_list, converter_func)
staticmethod
¶
NML list to Python list.
Converts a NML comma-separated list to a Python list. Applies a defined syntax function to each element of the list.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
nml_list |
Union[str, List[str]]
|
A string of comma-separated values or a Python list of strings of comma-separated values. |
required |
converter_func |
Callable
|
|
required |
comma |
|
required |
Examples:
Converting a comma-separated list of strings:
>>> from glmpy.nml import nml
>>> my_nml_list = "'foo', 'bar', 'baz'"
>>> python_list = nml.NMLReader.read_nml_list(
... my_nml_list,
... converter_func=nml.NMLReader.read_nml_str
... )
>>> print(python_list)
['foo', 'bar', 'baz']
>>> print(type(python_list))
<class 'list'>
Converting a list of comma-separated NML booleans:
>>> my_nml_list = [
... ".true., .false., .true.,", ".false., .true., .false."
... ]
>>> python_list = nml.NMLReader.read_nml_list(
... my_nml_list,
... converter_func=nml.NMLReader.read_nml_bool
... )
>>> print(python_list)
[True, False, True, False, True, False]
>>> print(type(python_list))
<class 'list'>
read_nml_str(nml_str)
staticmethod
¶
NML str to Python str.
Converts a string containing a NML-like string to a Python string.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
nml_str |
str
|
A string representing a NML string, i.e., characters enclosed in
|
required |
Examples:
set_converters(converters)
¶
Update methods for reading/writing NML parameters.
Updates or overwrites the default methods that NMLReader and
NMLWriter use to convert parameter values from Python to NML and
vice versa.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
converters |
Dict[str, Dict[str, Callable]]
|
A nested dictionary where the keys are the NML block names and the
values are a dictionary of parameter names (keys) and syntax
conversion methods (values, e.g., |
required |
Examples:
Use in NMLWriter:
Consider an example where we have an unsupported configuration block that we wish to write to a NML file:
>>> from glmpy.nml import nml
>>> nml_dict = {
... "glm_setup": {
... "sim_name": "Sparkling Lake",
... "max_layers": 500,
... "min_layer_vol": 0.5,
... "min_layer_thick": 0.15,
... "max_layer_thick": 0.5,
... "density_model": 1,
... "non_avg": True,
... },
... "custom_block": {
... "custom_param": True
... }
... }
To write custom_block, we create a similarly structured dictionary
where the value for "custom_param" is the appropriate
NMLWriter.write_nml_* static method:
>>> converters = {
... "custom_block": {
... "custom_block": nml.NMLWriter.write_nml_bool
... }
... }
After initialising NMLWriter, pass converters to the
set_converters() method and write the NML file:
>>> my_nml = nml.NMLWriter(nml_dict=nml_dict)
>>> my_nml.set_converters(converters)
>>> my_nml.write_nml("glm3.nml")
Use in NMLReader:
Consider an example where we have an unsupported configuration block
that we wish to read from the following glm3.nml file:
&glm_setup
sim_name = 'GLM Simulation'
max_layers = 60
min_layer_vol = 0.0005
min_layer_thick = 0.05
max_layer_thick = 0.1
non_avg = .true.
/
&custom_block
custom_param = .true.
/
Define a nested dictionary where the block name is the key and the
block value is a dictionary of parameter name and the appropriate
NMLReader.read_nml_* static method:
>>> converters = {
... "custom_block": {
... "custom_block": nml.NMLReader.read_nml_bool
... }
... }
After initialising NMLReader, pass converters to the
set_converters() method and read the NML file:
write_json(json_file)
¶
Write a JSON file of model parameters.
Converts paramters in a NML file to valid JSON syntax and writes to file.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
json_file |
Union[str, PathLike]
|
Output path of the JSON file. |
required |
Examples:
NMLWriter
¶
Bases: _NML
Write NML files.
Write a NML file from a nested dictionary of block names (keys) and
parameter dictionaries (values). By default, NMLWriter will automatically
determine the which syntax conversion methods should be used to write the
NML file. This functionality can be expicitly controlled using the
set_converters method.
NMLWriter provides the following static methods to convert from Python
syntax to NML syntax:
-
write_nml_str: Python string to NML string. -
write_nml_bool: Python bool to NML bool. -
write_nml_list: Python list to NML list (comma-separated values). -
write_nml_array: Nested Python list to NML array.
Attributes:
| Name | Type | Description |
|---|---|---|
nml_dict |
Dict[str, Dict[str, Any]]
|
A dictionary where the keys are the block names and the values are dictionaries of parameter names (keys) and parameter values (values). |
detect_types |
bool
|
Let |
Examples:
Create a nested dictionary of blocks (keys) and parameters (values) to write:
>>> my_nml_dict = {
... "glm_setup": {
... "sim_name": "Sparkling Lake",
... "max_layers": 500,
... "min_layer_vol": 0.5,
... "min_layer_thick": 0.15,
... "max_layer_thick": 0.5,
... "density_model": 1,
... "non_avg": True,
... },
... "mixing": {
... "surface_mixing": 1,
... "coef_mix_conv": 0.2,
... "coef_wind_stir": 0.402,
... "coef_mix_shear": 0.2,
... "coef_mix_turb": 0.51,
... "coef_mix_KH": 0.3,
... "deep_mixing": 2,
... "coef_mix_hyp": 0.5,
... "diff": 0.0,
... }
... }
Initialise NMLWriter and set the nml_dict attribute:
Write the NML to file by calling the write_nml method:
get_converters(block=None)
¶
Get the current dictionary of methods for reading/writing NML parameters.
Returns a dictionary of the syntax conversion methods used in the
instance of NMLReaderor NMLWriter.
set_converters(converters)
¶
Update methods for reading/writing NML parameters.
Updates or overwrites the default methods that NMLReader and
NMLWriter use to convert parameter values from Python to NML and
vice versa.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
converters |
Dict[str, Dict[str, Callable]]
|
A nested dictionary where the keys are the NML block names and the
values are a dictionary of parameter names (keys) and syntax
conversion methods (values, e.g., |
required |
Examples:
Use in NMLWriter:
Consider an example where we have an unsupported configuration block that we wish to write to a NML file:
>>> from glmpy.nml import nml
>>> nml_dict = {
... "glm_setup": {
... "sim_name": "Sparkling Lake",
... "max_layers": 500,
... "min_layer_vol": 0.5,
... "min_layer_thick": 0.15,
... "max_layer_thick": 0.5,
... "density_model": 1,
... "non_avg": True,
... },
... "custom_block": {
... "custom_param": True
... }
... }
To write custom_block, we create a similarly structured dictionary
where the value for "custom_param" is the appropriate
NMLWriter.write_nml_* static method:
>>> converters = {
... "custom_block": {
... "custom_block": nml.NMLWriter.write_nml_bool
... }
... }
After initialising NMLWriter, pass converters to the
set_converters() method and write the NML file:
>>> my_nml = nml.NMLWriter(nml_dict=nml_dict)
>>> my_nml.set_converters(converters)
>>> my_nml.write_nml("glm3.nml")
Use in NMLReader:
Consider an example where we have an unsupported configuration block
that we wish to read from the following glm3.nml file:
&glm_setup
sim_name = 'GLM Simulation'
max_layers = 60
min_layer_vol = 0.0005
min_layer_thick = 0.05
max_layer_thick = 0.1
non_avg = .true.
/
&custom_block
custom_param = .true.
/
Define a nested dictionary where the block name is the key and the
block value is a dictionary of parameter name and the appropriate
NMLReader.read_nml_* static method:
>>> converters = {
... "custom_block": {
... "custom_block": nml.NMLReader.read_nml_bool
... }
... }
After initialising NMLReader, pass converters to the
set_converters() method and read the NML file:
write_nml(nml_file='glm3.nml')
¶
write_nml_array(python_array, converter_func=None)
staticmethod
¶
Python array to NML array
Convert a 2D Python array to NML syntax. The Python array is
constructed as a nested list - similarly to 2D arrays in the numpy
package. The number of inner lists equals the array rows and the length
of each list equals the array columns. A function can be
optionally passed to the converter_func parameter to format the syntax
of each array element, e.g., write_nml_str() and write_nml_bool().
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
python_array |
List[List[Any]]
|
A list of lists. The number of inner lists equals the array rows and the length of each list equals the array columns. |
required |
converter_func |
Union[Callable, None]
|
A function used to format each list item. Default is |
None
|
row_indent |
int
|
The number of spaces to indent consecutive array rows by. Default
is |
required |
Examples:
>>> from glmpy.nml import nml
>>> wq_init_vals = [
... [1.1, 1.2, 1.3, 1.2, 1.3],
... [2.1, 2.2, 2.3, 1.2, 1.3],
... [3.1, 3.2, 3.3, 1.2, 1.3],
... [4.1, 4.2, 4.3, 1.2, 1.3],
... [5.1, 5.2, 5.3, 1.2, 1.3],
... [6.1, 6.2, 6.3, 1.2, 1.3]
... ]
>>> wq_init_vals = nml.NMLWriter.write_nml_array(
... python_array=wq_init_vals
... )
>>> print(wq_init_vals)
1.1,1.2,1.3,1.2,1.3,
2.1,2.2,2.3,1.2,1.3,
3.1,3.2,3.3,1.2,1.3,
4.1,4.2,4.3,1.2,1.3,
5.1,5.2,5.3,1.2,1.3,
6.1,6.2,6.3,1.2,1.3
>>> bool_array = [
... [True, True, True, True, True],
... [False, False, False, False, False],
... [False, True, False, True, False]
... ]
>>> bool_array = nml.NMLWriter.write_nml_array(
... python_array=bool_array,
... converter_func=nml.NMLWriter.write_nml_bool
... )
>>> print(bool_array)
.true.,.true.,.true.,.true.,.true.,
.false.,.false.,.false.,.false.,.false.,
.false.,.true.,.false.,.true.,.false.
write_nml_bool(python_bool)
staticmethod
¶
write_nml_list(python_list, converter_func=None)
staticmethod
¶
Python list to NML comma-separated list.
Convert a Python list to a comma-separated list. A function can be
optionally passed to the converter_func parameter to format the syntax
of each list item, e.g., write_nml_str() and write_nml_bool().
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
python_list |
List[Any]
|
A Python list |
required |
converter_func |
Union[Callable, None]
|
A function used to format each list item. Default is |
None
|
Examples:
write_nml_param(param_name, param_value, converter_func=None)
staticmethod
¶
GLM parameter/value string.
Construct a string containing a GLM parameter and value with the
correct.nml syntax formatting.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
param_dict |
A dictionary containing GLM parameters (keys) and values, e.g.,
from the |
required | |
param |
The dictionary key, i.e., GLM parameter, to construct the string for. |
required | |
converter_func |
Union[Callable, None]
|
A function used to format the syntax of the value. Default is
|
None
|
Examples: