How-to: nml module¶
Understanding the nml Module Structure¶
The nml module provides a structured, object-oriented approach to 
working with GLM and AED configuration files. It's built with three 
levels of abstraction:
- NMLParamobjects: Individual parameters with type checking, validation, and units.
- NMLBlocksubclasses: Collections of related parameters representing configuration blocks.
- NMLsubclasses: Complete configuration files containing multiple blocks.
Stores parameter 
value, units, and       
validation rules.       
┌────────────────┐  
│    NMLParam    │       
│name: "sim_name"│       Contains multiple related
│type: str       │──┐    parameters with block-level
│value: "my_sim" │  │    validation rules.
│units: None     │  │    ┌─────────────────────────┐
└────────────────┘  │    │ GLMSetupBlock(NMLBlock) │
┌────────────────┐  ├───▶│nml_name: "glm"          │──┐
│    NMLParam    │  │    │block_name: "glm_setup"  │  │    Contains multiple
│name: "non_avg" │  │    └─────────────────────────┘  │    blocks with 
│type: bool      │──┘                                 │    cross-block 
│value: True     │                                    │    validation.
│units: None     │                                    │    ┌───────────────┐
└────────────────┘                                    │    │  GLMNML(NML)  │
                                                      │───▶│nml_name: "glm"│
┌────────────────┐                                    │    └───────────────┘
│    NMLParam    │                                    │       
│name: "kw"      │                                    │
│type: float     │──┐                                 │
│value: 0.57     │  │                                 │
│units: "m^{-1}" │  │    ┌─────────────────────────┐  │
└────────────────┘  │    │   LightBlock(NMLBlock)  │  │
┌────────────────┐  ├───▶│nml_name: "glm"          │──┘
│    NMLParam    │  │    │block_name: "light"      │
│name: "n_bands" │  │    └─────────────────────────┘  
│type: int       │──┘   
│value: 2        │
│units: None     │  
└────────────────┘  
Working with NMLBlock subclasses¶
The glm_nml and aed_nml modules contain numerous NMLBlock 
subclasses that correspond directly to parameter 'blocks' in the 
glm.nml and aed.nml files. These classes handle parameter validation 
and provide a consistent interface for accessing and modifying values.
Initialising NMLBlock subclasses¶
Instances of NMLBlock subclasses are constructed by calling the 
__init__ method and providing parameter values as arguments. 
Parameters with no value set will default to None.
Note
All GLM and AED parameter names in glm-py have been converted to 
lower-case, e.g., Fsed_oxy becomes fsed_oxy.
from glmpy.nml import glm_nml
glm_setup = glm_nml.GLMSetupBlock(
    sim_name='my_sim',
    max_layers=500,
    min_layer_vol=0.5,
    min_layer_thick=0.15,
    max_layer_thick=0.5,
    density_model=1,
)
Returning a list of parameter names¶
A list of all parameter names in the block can be return using the 
get_param_names method.
from glmpy.nml import glm_nml
glm_setup = glm_nml.GLMSetupBlock(
    sim_name='my_sim',
    max_layers=500,
    min_layer_vol=0.5,
    min_layer_thick=0.15,
    max_layer_thick=0.5,
    density_model=1,
)
print(glm_setup.get_param_names())
['sim_name', 'max_layers', 'min_layer_vol', 'min_layer_thick', 'max_layer_thick', 'density_model', 'non_avg']
Returning a parameter value¶
Return a parameter value by calling get_param_value and providing the 
paramter name:
from glmpy.nml import glm_nml
glm_setup = glm_nml.GLMSetupBlock(
    sim_name='my_sim',
    max_layers=500,
    min_layer_vol=0.5,
    min_layer_thick=0.15,
    max_layer_thick=0.5,
    density_model=1,
)
print(glm_setup.get_param_value('non_avg'))
Setting a parameter value¶
Set a paramter value after initialisation by calling set_param_value 
and providing the parameter name and it's value.
from glmpy.nml import glm_nml
glm_setup = glm_nml.GLMSetupBlock(
    sim_name='my_sim',
    max_layers=500,
    min_layer_vol=0.5,
    min_layer_thick=0.15,
    max_layer_thick=0.5,
    density_model=1,
)
glm_setup.set_param_value('non_avg', True)
Returning a parameter's units¶
Return a parameter's units by calling get_param_value and providing 
the paramter name:
from glmpy.nml import glm_nml
glm_setup = glm_nml.GLMSetupBlock(
    sim_name='my_sim',
    max_layers=500,
    min_layer_vol=0.5,
    min_layer_thick=0.15,
    max_layer_thick=0.5,
    density_model=1,
)
print(glm_setup.get_param_units('min_layer_thick'))
Returning a dictionary of parameter names and values¶
The to_dict method returns an ordered dictionary of the parameter 
names (keys) and values.
from glmpy.nml import glm_nml
glm_setup = glm_nml.GLMSetupBlock(
    sim_name='my_sim',
    max_layers=500,
    min_layer_vol=0.5,
    min_layer_thick=0.15,
    max_layer_thick=0.5,
    density_model=1,
)
print(glm_setup.to_dict())
OrderedDict([('sim_name', 'my_sim'), ('max_layers', 500), ('min_layer_vol', 0.5), ('min_layer_thick', 0.15), ('max_layer_thick', 0.5), ('density_model', 1), ('non_avg', None)])
Iterating through parameters¶
The iter_params method returns a generator of the NMLParam objects 
in the NMLBlock subclass.
from glmpy.nml import glm_nml
glm_setup = glm_nml.GLMSetupBlock(
    sim_name='my_sim',
    max_layers=500,
    min_layer_vol=0.5,
    min_layer_thick=0.15,
    max_layer_thick=0.5,
    density_model=1,
)
for nml_param in glm_setup.iter_params():
    print(nml_param.name, nml_param.value, nml_param.units)
sim_name my_sim None
max_layers 500 None
min_layer_vol 0.5 m^3
min_layer_thick 0.15 m
max_layer_thick 0.5 m
density_model 1 None
non_avg None None
Validating parameters¶
The validate method¶
Call the validate method to raise errors for invalid parameter values.
from glmpy.nml import glm_nml
glm_setup = glm_nml.GLMSetupBlock(
    sim_name=123456789, #<— invalid data type
    max_layers=500,
    min_layer_vol=0.5,
    min_layer_thick=0.15,
    max_layer_thick=0.5,
    density_model=1,
)
glm_setup.validate()
Overriding validation with strict¶
validate is called when preparing a GLMSim to run. 
In situations where you need to override validate from raising errors,
set the strict attribute to False.