sweep module

This module provides a high-level API for running biosnicar across ranges of input parameters. It is designed for sensitivity analysis, parameter exploration and lookup table generation.

The sweep module handles the Cartesian product of parameter values, object mutation, recalculation of derived quantities, and collection of results into a pandas DataFrame.

parameter_sweep

Runs biosnicar over the Cartesian product of parameter values and returns structured results.

Args

• params: dict mapping parameter names to lists of values (see supported keys below)
• solver: "adding-doubling" (default) or "toon"
• input_file: path to YAML config or "default"
• return_spectral: if True, include an albedo column with 480-element numpy arrays
• progress: if True, display a tqdm progress bar

Returns

• pd.DataFrame with one row per parameter combination, containing all swept parameter columns plus output columns: BBA, BBAVIS, BBANIR, abs_slr_tot, abs_vis_tot, abs_nir_tot, abs_slr_btm, total_insolation, and optionally albedo

Raises

• ValueError if an unrecognised parameter key is supplied
• ValueError if an unknown solver name is given

Supported parameter keys

Example

from biosnicar.drivers.sweep import parameter_sweep
 
# Sweep SZA x grain radius -> 20 model runs
df = parameter_sweep(
    params={
        "solzen": [30, 40, 50, 60, 70],
        "rds": [100, 200, 500, 1000],
    }
)
 
# Pivot table of broadband albedo
print(df.pivot_table(values="BBA", index="solzen", columns="rds"))
 
# Black carbon concentration sweep
df_bc = parameter_sweep(
    params={"impurity.0.conc": [0, 100, 1000, 10000]},
)
 
# Include spectral albedo in output
df_spec = parameter_sweep(
    params={"solzen": [50]},
    return_spectral=True,
)
albedo_array = df_spec.iloc[0]["albedo"]  # 480-element numpy array

A complete demo script is provided at scripts/sweep_demo.py in the biosnicar repository.