pyradtran.interface.PyRadtranAccessor

pyradtran.interface.PyRadtranAccessor#

class pyradtran.interface.PyRadtranAccessor(xarray_obj)[source]#

Bases: object

xarray accessor for running libRadtran simulations.

Registered as ds.pyradtran. The primary method is run(), which parallelises uvspec over every point in the dataset.

Examples

>>> result = ds.pyradtran.run(
...     config_path="config/my_config.yaml",
...     era5_atmosphere=era5_ds,
...     params={"albedo": 0.85},
... )

See also

execute_simulation_batch

The underlying parallel driver.

__init__(xarray_obj)[source]#
explain(point: Dict[str, Any] | None = None, params: Dict[str, Any] | None = None, config_path: str | Path | None = None, config: SimulationConfig | None = None, time_var: str = 'time', lat_var: str = 'latitude', lon_var: str = 'longitude') → str[source]#

Preview the annotated uvspec input file for one point.

No simulation is run. Each line is tagged with the layer that produced it (config / params-literal / dataset-var / unvalidated).

Parameters:

  • point (dict, optional) – Dataset.sel()-style selector (nearest match). Defaults to the first element along every dimension.

  • params (dict, optional) – Same mapping accepted by run().

  • config_path – Configuration source, same as run().

  • config – Configuration source, same as run().

Return type:

str

inspect_cloud_file(selector: Dict[str, Any] | None = None, params: Dict[str, Any] | None = None, parameter_overrides: Dict[str, Any] | None = None, cloud_wc_var: str | None = None, cloud_ic_var: str | None = None, cloud_reff_var: str | None = None, cloud_ic_reff_var: str | None = None, cloud_top_var: str | None = None, cloud_bottom_var: str | None = None) → str[source]#

Preview the cloud-profile file that would be generated.

Parameters:

  • selector (dict, optional) – Passed to Dataset.sel() to pick a single point. Defaults to the first element along every dimension.

  • params (dict, optional) – Unified parameter mapping (same as run()); Var entries resolve from the selected point.

  • parameter_overrides (dict, optional) – Deprecated — use params instead.

  • cloud_wc_var (str, optional)

  • cloud_ic_var (str, optional)

  • cloud_reff_var (str, optional)

  • cloud_ic_reff_var (str, optional)

  • cloud_top_var (str, optional)

  • cloud_bottom_var (str, optional)

Returns:

Column-formatted cloud profile, or an explanatory message when no cloud can be constructed.

Return type:

str

jacobian(param: str, delta: float, params: Dict[str, Any] | None = None, config_path: str | Path | None = None, config: SimulationConfig | None = None, **run_kwargs) → Dataset[source]#

Finite-difference sensitivity kernel for one scalar parameter.

Runs the batch twice (base and param + delta) and returns (perturbed - base) / delta with the same dimensions.

Parameters:

  • param (str) – Registry parameter to perturb (must resolve to a scalar: a params literal or a config default — not a Var).

  • delta (float) – Perturbation size in the parameter’s units.

  • params (dict, optional) – Base parameter mapping (same as run()).

  • config_path – Configuration source, same as run().

  • config – Configuration source, same as run().

  • **run_kwargs – Forwarded to run() (e.g. show_progress=False).

Returns:

Kernel dataset; attrs jacobian_param, jacobian_delta.

Return type:

xarray.Dataset

Raises:

ValidationError – If param is a Var reference or no base value exists.

run(config_path: str | Path | None = None, config: SimulationConfig | None = None, params: Dict[str, Any] | None = None, parameter_overrides: Dict[str, Any] | None = None, time_var: str = 'time', lat_var: str = 'latitude', lon_var: str = 'longitude', albedo_var: str | None = None, surface_temperature_var: str | None = None, surface_type_var: str | None = None, era5_atmosphere: Dataset | None = None, era5_clouds: bool | Dict[str, Any] = False, return_dataset: bool = True, save_to_file: bool = True, output_path: str | Path | None = None, progress_callback: callable | None = None, cloud_wc_var: str | None = None, cloud_ic_var: str | None = None, cloud_reff_var: str | None = None, cloud_ic_reff_var: str | None = None, cloud_top_var: str | None = None, cloud_bottom_var: str | None = None, show_progress: bool = True, channels: DataArray | None = None, keep_spectral: bool = False) → Dataset | Path[source]#

Run uvspec for every point in the dataset.

Parameters:

  • config_path (str or pathlib.Path, optional) – YAML configuration file.

  • config (SimulationConfig, optional) – Pre-built config (overrides config_path).

  • params (dict, optional) – Unified parameter mapping: registry keys / raw uvspec keywords / dotted config paths to literal values or Var per-point dataset references. Preferred over the deprecated *_var and parameter_overrides kwargs below.

  • parameter_overrides (dict, optional) – Deprecated — use params instead.

  • time_var (str) – Coordinate variable names.

  • lat_var (str) – Coordinate variable names.

  • lon_var (str) – Coordinate variable names.

  • albedo_var (str, optional) – Deprecated — use params={"albedo": Var(...)}.

  • surface_temperature_var (str, optional) – Deprecated — use params={"sur_temperature": Var(...)}.

  • surface_type_var (str, optional) – Deprecated — use params={"brdf_rpv_type": Var(...)}.

  • era5_atmosphere (xarray.Dataset, optional) – ERA5 dataset for custom atmosphere profiles. Raw CDS or ARCO-ERA5 naming is accepted and normalised automatically; an o3 field adds an ozone profile to the radiosonde file (and disables the config ozone_du scaling).

  • era5_clouds (bool or dict, default False) – Also derive per-point cloud profiles (wc_file / ic_file) from the ERA5 clwc / ciwc fields. A dict is forwarded to pyradtran.era5.cloud_profiles() (e.g. {"reff_water_um": 8.0}). Explicit cloud settings via params or cloud_*_var win over ERA5 clouds.

  • return_dataset (bool, default True) – Return results as an xarray Dataset.

  • save_to_file (bool, default True) – Write results to NetCDF.

  • output_path (str or pathlib.Path, optional) – Destination file (auto-generated when None).

  • progress_callback (callable, optional) – callback(current, total).

  • show_progress (bool, default True) – Show a tqdm progress bar. Pass False to suppress it (useful when the output will be rendered as HTML).

  • cloud_wc_var (str, optional) – LWC / IWC dataset variables.

  • cloud_ic_var (str, optional) – LWC / IWC dataset variables.

  • cloud_reff_var (str, optional) – Effective-radius variables.

  • cloud_ic_reff_var (str, optional) – Effective-radius variables.

  • cloud_top_var (str, optional) – Cloud geometry variables (km).

  • cloud_bottom_var (str, optional) – Cloud geometry variables (km).

  • channels (xarray.DataArray, optional) – Instrument spectral response functions, dims (channel, wavelength). When given and the result is spectral, every spectral variable is SRF-averaged onto a channel dimension via convolve_channels(); the returned (and saved) dataset is channel-space.

  • keep_spectral (bool, default False) – With channels, also keep the original spectral variables under <name>_spectral.

Returns:

Results dataset when return_dataset is True, otherwise the output file path.

Return type:

xarray.Dataset or pathlib.Path

Raises:

PyRadtranError – If no valid results are produced.

run_uvspec(config_path: str | Path | None = None, config: SimulationConfig | None = None, params: Dict[str, Any] | None = None, parameter_overrides: Dict[str, Any] | None = None, time_var: str = 'time', lat_var: str = 'latitude', lon_var: str = 'longitude', albedo_var: str | None = None, surface_temperature_var: str | None = None, surface_type_var: str | None = None, era5_atmosphere: Dataset | None = None, era5_clouds: bool | Dict[str, Any] = False, return_dataset: bool = True, save_to_file: bool = True, output_path: str | Path | None = None, progress_callback: callable | None = None, cloud_wc_var: str | None = None, cloud_ic_var: str | None = None, cloud_reff_var: str | None = None, cloud_ic_reff_var: str | None = None, cloud_top_var: str | None = None, cloud_bottom_var: str | None = None, show_progress: bool = True, channels: DataArray | None = None, keep_spectral: bool = False) → Dataset | Path#

Alias for run() — kept for backwards compatibility with older notebooks that call ds.pyradtran.run_uvspec(...).

Contents