Parameters & Validation

Parameters & Validation#

All runtime parameters go through one mapping: params. Any libRadtran option can be a key; the value decides how it is applied.

The params mapping#

A key can be:

  1. A uvspec option (albedo, sza, zout, wc_modify, ic_properties, … — anything your libRadtran accepts)

  2. A dotted config path (simulation_defaults.wavelength_nm) — applied to the configuration instead of the input file

The value can be:

  • A literal — same value for every simulated point

  • Var("name") — resolved per point from the variable name in your input dataset

from pyradtran import Var

ds_sim = ds.pyradtran.run(
    config_path='config/solar.yaml',
    params={
        'albedo': Var('surface_albedo'),   # per-point from the dataset
        'mol_modify O3': 320.0,            # same for every point
        'wc_modify': ['tau550 set 12'],    # repeatable option: list
        'aerosol_default': True,           # flag option: bare keyword
    },
)

Points where a Var value is NaN simply omit that parameter (the config default applies); NaN coordinates or a missing/NaT time skip the whole point and record status=2 in the result.

Flag options take True (emit the bare keyword) or False (emit nothing — useful to switch a config-supplied flag off for one run). Numeric zout values are sorted and de-duplicated automatically: uvspec hard-errors on unsorted output altitudes.

Validated against your libRadtran#

libRadtran ships a machine-readable description of every option. On first use pyRadtran extracts it from your local installation (cached under ~/.pyradtran/), so every entry is checked against the exact binary you run — before any simulation starts:

params={'albdeo': 0.3}
# ValidationError: 'albdeo' is not a known uvspec option of the local
# libRadtran install; did you mean albedo / albedo_map?

params={'ic_properties': 'granite'}
# ValidationError: 'ic_properties': 'granite' is not one of
# ['baum', 'baum_v36', 'echam4', 'fu', 'hey', 'key', ...]

params={'cloudcover wc': 1.5}
# ValidationError: 'cloudcover wc' value 1.5 outside [0.0, 1.0]

Need an option your schema does not know (patched uvspec build)? Wrap it in Raw to bypass validation:

from pyradtran import Raw
params={'my_custom_option': Raw('anything goes')}

Explore all options from Python#

import pyradtran

print(pyradtran.describe('wc_modify'))
# wc_modify <gg|ssa|tau|tau550> <set|scale> <float>
# group: Water and ice clouds   (repeatable)
# requires: wc_file
# ... full documentation ...

pyradtran.search_options('optical thickness')
# ['aerosol_modify', 'ic_modify', 'wc_modify', ...]

describe() shows the usage signature, valid choices and ranges, option dependencies, and the full documentation text — for the libRadtran version you actually have installed.

Preview before you run#

explain() renders the exact input file for one point — without running anything — and tags every line with the layer that produced it:

print(ds.pyradtran.explain(
    params={'albedo': Var('surface_albedo')},
    config_path='config/solar.yaml',
))
# rte_solver disort          # config
# albedo 0.85                # dataset-var
# mol_modify O3 320.0 DU     # params-literal
# ...

The The Parameter System: A Deep Dive notebook walks through all of this hands-on.

Note

The old parameter_overrides=, albedo_var=, surface_temperature_var=, surface_type_var= and altitude_var= keyword arguments still work but are deprecated: albedo_var="x" → params={"albedo": Var("x")}, parameter_overrides={...} → params={...}.

Contents