API Reference

Package Interface

pyRadtran — A complete Python wrapper for libRadtran radiative transfer.

class pyradtran.AerosolModel(*, set_tau_at_wvl: tuple[float, float] | None=None, king_byrne: tuple[float, float, float] | None=None, modify: list[AerosolModifyEntry] = <factory>)[source]

Bases: UvspecOption

Abstract base class for all aerosol configurations.

Subclasses implement mode-specific to_uvspec_lines(). Common capabilities (set_tau_at_wvl, king_byrne, modify) are handled here.

king_byrne: tuple[float, float, float] | None

model_config = {'extra': 'forbid', 'frozen': True, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

modify: list[AerosolModifyEntry]

set_tau_at_wvl: tuple[float, float] | None

to_uvspec_items() → list[tuple[int, str]][source]

Return (phase, keyword_line) pairs for priority-sorted output.

Subclasses may override to assign different phases to different keywords. Default phase is 9 (output section).

abstractmethod to_uvspec_lines() → list[str][source]

Serialize this configuration to uvspec input file lines.

Returns:: List of strings, each being one line of a uvspec input file.

class pyradtran.AerosolModifyEntry(*, variable: str, action: str, value: float)[source]

Bases: UvspecOption

A single aerosol_modify directive.

variable

Property to modify (gg, ssa, tau, tau550).

Type:: str

action

How to modify (scale or set).

Type:: str

value

Numeric value.

Type:: float

action: str

model_config = {'extra': 'forbid', 'frozen': True, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

validate_entry() → AerosolModifyEntry[source]

value: float

variable: str

class pyradtran.CompositeAerosol(*, set_tau_at_wvl: tuple[float, float] | None = None, king_byrne: tuple[float, float, float] | None = None, modify: list[~pyradtran.models.aerosol.AerosolModifyEntry] = <factory>, sources: ~typing.Annotated[list, ~annotated_types.MinLen(min_length=1)], wavelength_grid_um: ~typing.Annotated[list[float], ~annotated_types.MinLen(min_length=1)], altitude_grid_km: ~typing.Annotated[list[float], ~annotated_types.MinLen(min_length=2)], n_legendre: int = 32, output_dir: ~pathlib.Path | None = None)[source]

Bases: AerosolModel

Tier 4: composite aerosol scene mixing multiple sources.

altitude_grid_km: list[float]

model_config = {'extra': 'forbid', 'frozen': True, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

n_legendre: int

output_dir: Path | None

sources: list

to_uvspec_lines() → list[str][source]

Generate aerosol_file explicit <master> line.

For single preset/external sources, delegates directly to their to_uvspec_lines() to avoid the explicit-file overhead.

validate_grids() → CompositeAerosol[source]

wavelength_grid_um: list[float]

pyradtran.ExternalAerosol: alias of ExternalFile

class pyradtran.ExternalFile(*, set_tau_at_wvl: tuple[float, float] | None = None, king_byrne: tuple[float, float, float] | None = None, modify: list[~pyradtran.models.aerosol.AerosolModifyEntry] = <factory>, files: ~typing.Annotated[list[tuple[str, str]], ~annotated_types.MinLen(min_length=1)])[source]

Bases: AerosolModel

External aerosol optical property files.

files

List of (file_type, file_path) tuples. Types: “gg”, “ssa”, “tau”, “explicit”, “moments”, “ref”, “siz”.

Type:: list[tuple[str, str]]

files: list[tuple[str, str]]

model_config = {'extra': 'forbid', 'frozen': True, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

to_uvspec_lines() → list[str][source]

Serialize this configuration to uvspec input file lines.

Returns:: List of strings, each being one line of a uvspec input file.

validate_files() → ExternalFile[source]

class pyradtran.IntegrationConfig(*, n_radius_grid: int = 200, radius_min_um: float = 0.001, radius_max_um: float = 100.0)[source]

Bases: BaseModel

Configuration for size-distribution numerical integration.

model_config = {'extra': 'forbid', 'frozen': True, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

n_radius_grid: int

radius_max_um: float

radius_min_um: float

class pyradtran.LayerOptics(tau: ndarray[tuple[Any, ...], dtype[_ScalarT]], ssa: ndarray[tuple[Any, ...], dtype[_ScalarT]], g: ndarray[tuple[Any, ...], dtype[_ScalarT]], legendre_moments: ndarray[tuple[Any, ...], dtype[_ScalarT]])[source]

Bases: object

Extensive optical properties per layer.

g: ndarray[tuple[Any, ...], dtype[_ScalarT]]

legendre_moments: ndarray[tuple[Any, ...], dtype[_ScalarT]]

ssa: ndarray[tuple[Any, ...], dtype[_ScalarT]]

tau: ndarray[tuple[Any, ...], dtype[_ScalarT]]

class pyradtran.LoadedSpecies(*, species: MieSpecies | PrecomputedSpecies | OPACSpecies, mass_profile_kg_m3: Annotated[list[float], MinLen(min_length=1)], altitude_km: Annotated[list[float], MinLen(min_length=2)], rh_profile: list[float] | None = None)[source]

Bases: BaseModel

Tier 3: extensive in-atmosphere optical properties.

altitude_km: list[float]

evaluate(wl_um: ndarray, z_km: ndarray, n_legendre: int = 32) → LayerOptics[source]

Evaluate optical properties on (wavelength, altitude) grid.

Parameters:

wl_um – Wavelength grid in um, strictly ascending.
z_km – Altitude grid in km, strictly descending (layer centers or boundaries).
n_legendre – Number of Legendre moments.

Returns:

LayerOptics with shape (n_wl, n_layer).

mass_profile_kg_m3: list[float]

model_config = {'extra': 'forbid', 'frozen': True, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

rh_profile: list[float] | None

species: MieSpecies | PrecomputedSpecies | OPACSpecies

validate_profiles() → LoadedSpecies[source]

class pyradtran.MieSpecies(*, refractive_index: ~pyradtran.models.aerosol_composite.RefractiveIndex, size_distribution: ~pyradtran.models.aerosol_composite.SizeDistribution, particle_density_kg_m3: ~typing.Annotated[float, ~annotated_types.Gt(gt=0)], integration_config: ~pyradtran.models.aerosol_composite.IntegrationConfig = <factory>)[source]

Bases: BaseModel

Mie-computed species from refractive index + size distribution.

integration_config: IntegrationConfig

intensive(wl_um: ndarray, n_legendre: int = 32) → SpeciesOptics[source]

Compute mass-normalized intensive optical properties.

Parameters:

wl_um – Wavelengths in micrometers.
n_legendre – Number of Legendre moments to generate. Because the bhmie() path does not compute angular scattering by default, moments are derived from the Henyey-Greenstein phase function rather than a full Mie phase function.

Returns:

SpeciesOptics with beta_ext_per_mass, ssa, g, and legendre_moments.

model_config = {'extra': 'forbid', 'frozen': True, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

particle_density_kg_m3: float

refractive_index: RefractiveIndex

size_distribution: SizeDistribution

class pyradtran.OPACSpecies(*, netcdf_path: Annotated[str, MinLen(min_length=1)], wavelength_nm: float | None = None)[source]

Bases: BaseModel

OPAC species from a pre-computed libRadtran netCDF optical-property file.

The netCDF file is expected to contain output_dtauc, output_ssalb, and output_pmom variables (libRadtran write_optical_properties format).

intensive(wl_um: ndarray, n_legendre: int = 32) → SpeciesOptics[source]

Read netCDF and return intensive properties.

For a netCDF with nlyr layers, the returned beta_ext_per_mass assumes the optical depth is distributed uniformly across layers for the purpose of SpeciesOptics (the actual layer geometry is applied later in LoadedSpecies).

model_config = {'extra': 'forbid', 'frozen': True, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

netcdf_path: str

wavelength_nm: float | None

class pyradtran.OpacCustom(*, set_tau_at_wvl: tuple[float, float] | None = None, king_byrne: tuple[float, float, float] | None = None, modify: list[~pyradtran.models.aerosol.AerosolModifyEntry] = <factory>, species_file: ~typing.Annotated[str, ~annotated_types.MinLen(min_length=1)], species_names: list[str] | None = None, library: str = 'OPAC')[source]

Bases: AerosolModel

OPAC custom species profile aerosol.

Uses a user-provided mass concentration profile file with the OPAC library.

species_file

Path to an ASCII profile file.

Type:: str

library

OPAC library path or “OPAC” for default resolution.

Type:: str

species_names

Optional species filter.

Type:: list[str] | None

library: str

model_config = {'extra': 'forbid', 'frozen': True, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

species_file: str

species_names: list[str] | None

to_uvspec_lines() → list[str][source]

Serialize this configuration to uvspec input file lines.

Returns:: List of strings, each being one line of a uvspec input file.

validate_species() → OpacCustom[source]

class pyradtran.OpacPreset(*, set_tau_at_wvl: tuple[float, float] | None=None, king_byrne: tuple[float, float, float] | None=None, modify: list[AerosolModifyEntry] = <factory>, name: OpacPresetName, library: str = 'OPAC', species_names: list[str] | None = None)[source]

Bases: AerosolModel

OPAC preset mixture profile aerosol.

Uses pre-defined aerosol species mixture profiles from the OPAC library. The name selects from 10 predefined mixture profiles. Optionally filter to specific species via species_names.

name

Preset mixture profile name.

Type:: pyradtran.models.aerosol.OpacPresetName

library

OPAC library path or “OPAC” for uvspec default resolution.

Type:: str

species_names

Optional species filter (e.g. [“inso”, “soot”]).

Type:: list[str] | None

library: str

model_config = {'extra': 'forbid', 'frozen': True, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

name: OpacPresetName

species_names: list[str] | None

to_uvspec_lines() → list[str][source]

Serialize this configuration to uvspec input file lines.

Returns:: List of strings, each being one line of a uvspec input file.

validate_species() → OpacPreset[source]

class pyradtran.OpacPresetName(value)[source]

Bases: str, Enum

OPAC preset mixture profile names.

These correspond to files in data/aerosol/OPAC/standard_aerosol_files/.

ANTARCTIC = 'antarctic'

CONTINENTAL_AVERAGE = 'continental_average'

CONTINENTAL_CLEAN = 'continental_clean'

CONTINENTAL_POLLUTED = 'continental_polluted'

DESERT = 'desert'

DESERT_SPHEROIDS = 'desert_spheroids'

MARITIME_CLEAN = 'maritime_clean'

MARITIME_POLLUTED = 'maritime_polluted'

MARITIME_TROPICAL = 'maritime_tropical'

URBAN = 'urban'

class pyradtran.ParticleOptics(*, wavelength_um: Annotated[list[float], MinLen(min_length=1)], radius_um: Annotated[list[float], MinLen(min_length=1)], Qext: ndarray[tuple[Any, ...], dtype[_ScalarT]], Qsca: ndarray[tuple[Any, ...], dtype[_ScalarT]], g: ndarray[tuple[Any, ...], dtype[_ScalarT]], legendre_moments: ndarray[tuple[Any, ...], dtype[_ScalarT]] | None = None)[source]

Bases: BaseModel

Single-particle optical properties vs wavelength and radius.

Qext: NDArray

Qsca: NDArray

classmethod from_aerosol3d(data) → ParticleOptics[source]

Create ParticleOptics from Aerosol3D AerosolOpticsData.

Handles unit conversion (nm -> um, nm^2 -> um^2) and Legendre convention (prefers beta_l, falls back to k_l conversion).

Parameters:: data – Object with wavelength_nm, C_ext, C_sca, g, r_eff_nm, n_legendre, legendre_moments_beta, legendre_moments fields.
Returns:: ParticleOptics ready for use in PrecomputedSpecies.

classmethod from_cross_sections(*, wavelength_um: list[float], radius_um: list[float], Cext_um2: ndarray[tuple[Any, ...], dtype[_ScalarT]], Csca_um2: ndarray[tuple[Any, ...], dtype[_ScalarT]], g: ndarray[tuple[Any, ...], dtype[_ScalarT]], legendre_moments: ndarray[tuple[Any, ...], dtype[_ScalarT]] | None = None) → ParticleOptics[source]: Build from cross-sections (convert to Q-factors).

g: NDArray

legendre_moments: NDArray | None

model_config = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'frozen': True, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

radius_um: list[float]

validate_shapes() → ParticleOptics[source]

wavelength_um: list[float]

class pyradtran.PrecomputedSpecies(*, particle_optics: ~pyradtran.models.aerosol_composite.ParticleOptics, size_distribution: ~pyradtran.models.aerosol_composite.SizeDistribution, particle_density_kg_m3: ~typing.Annotated[float, ~annotated_types.Gt(gt=0)], integration_config: ~pyradtran.models.aerosol_composite.IntegrationConfig = <factory>)[source]

Bases: BaseModel

Species from precomputed ParticleOptics + size distribution.

integration_config: IntegrationConfig

intensive(wl_um: ndarray, n_legendre: int = 32) → SpeciesOptics[source]: Integrate precomputed Q-factors over size distribution.

model_config = {'extra': 'forbid', 'frozen': True, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

particle_density_kg_m3: float

particle_optics: ParticleOptics

size_distribution: SizeDistribution

class pyradtran.RefractiveIndex(*, wavelength_um: Annotated[list[float], MinLen(min_length=2)], n_real: list[float], k_imag: Annotated[list[float], MinLen(min_length=1)])[source]

Bases: BaseModel

Wavelength-dependent complex refractive index.

Interpolation is log-linear in wavelength.

at(wl_um: ndarray) → ndarray[source]: Interpolate refractive index to requested wavelengths.

k_imag: list[float]

model_config = {'extra': 'forbid', 'frozen': True, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

n_real: list[float]

validate_lengths_and_sorted() → RefractiveIndex[source]

wavelength_um: list[float]

class pyradtran.Runner[source]

Bases: object

Execute uvspec simulations.

Usage:

result = Runner.execute(scene, data_path="/path/to/data")
results = Runner.execute_many(scenes, max_workers=4)

Global defaults may be set once via configure() so that uvspec_exe and data_path do not need to be repeated on every call:

Runner.configure(uvspec_exe="/opt/libRadtran/bin/uvspec",
                 data_path="/opt/libRadtran/data")
result = Runner.execute(scene)

classmethod configure(config: RunnerConfig | None = None, **kwargs) → RunnerConfig[source]

Set global default configuration for all Runner executions.

Parameters:

config – A complete RunnerConfig instance, or None.
**kwargs – Individual fields (e.g. uvspec_exe=..., data_path=...).

Returns:

The newly set configuration.

Execute a single uvspec simulation.

Parameters:

scene – Configured Scene object.
uvspec_exe – Path to uvspec binary. Auto-detected if None.
data_path – Path to libRadtran data directory. Auto-detected if None.
keep_temp – Keep temporary files after execution.
timeout – Maximum execution time in seconds.
config – Optional RunnerConfig overriding global defaults for this call only.

Returns:

xarray.Dataset with simulation results.

Execute multiple uvspec simulations in parallel.

Parameters:

scenes – List of configured Scene objects.
uvspec_exe – Path to uvspec binary. Auto-detected if None.
data_path – Path to libRadtran data directory. Auto-detected if None.
max_workers – Maximum parallel workers.
keep_temp – Keep temporary files after execution.
timeout – Maximum execution time in seconds per scene.
config – Optional RunnerConfig overriding global defaults.

Returns:

List of xarray.Dataset results, one per scene.

class pyradtran.RunnerConfig(uvspec_exe: str | None = None, data_path: str | None = None, max_workers: int = 4, keep_temp: bool = False, timeout: int | None = None)[source]

Bases: object

Configuration for uvspec execution.

uvspec_exe

Path to uvspec binary. Auto-detected via PATH if None.

Type:: str | None

data_path

Path to libRadtran data directory. Uses env vars if None.

Type:: str | None

max_workers

Maximum parallel workers for execute_many().

Type:: int

keep_temp

Keep temporary files after execution (for debugging).

Type:: bool

timeout

Maximum uvspec execution time in seconds. None = no timeout.

Type:: int | None

data_path: str | None = None

keep_temp: bool = False

max_workers: int = 4

timeout: int | None = None

uvspec_exe: str | None = None

Bases: object

Immutable scene builder composing all uvspec configuration models.

Each set_*() method returns a new Scene via deepcopy. Use .clone() for an explicit copy.

Usage:

scene = (
    Scene()
    .set_atmosphere(profile="us", altitude=2.663)
    .set_source_solar(sza=30.0)
    .set_wavelength(250.0, 1200.0)
    .set_solver(method="disort", streams=16)
    .set_output(quantities=["lambda", "edir"])
)

add_raw_keyword(key: str, value: str = '') → Scene[source]

build_input(data_files_path: str | None = None) → str[source]

Build complete uvspec input text from this Scene.

Raises:: ValueError – If required components are missing.

clone() → Scene[source]: Create a deep copy of this Scene.

set_advanced(**kwargs) → Scene[source]

set_aerosol(aerosol: AerosolModel) → Scene[source]: Set aerosol configuration from an AerosolModel instance.

set_aerosol_modify(variable: str, action: str, value: float) → Scene[source]

Add an aerosol modification directive.

Parameters:

variable – Property to modify (gg, ssa, tau, tau550).
action – Modification type (scale or set).
value – Numeric value.

set_atmosphere(**kwargs) → Scene[source]

set_cloud(**kwargs) → Scene[source]

set_dynamic(method: str = 'dynamic_tenstream', iterations: int | None = None, **kwargs) → Scene[source]

set_mc(**kwargs) → Scene[source]

set_mol_modify(species: str, value: float, unit: str) → Scene[source]

set_output(**kwargs) → Scene[source]

set_satellite(geometry: str | None = None, pixel: tuple[int, int] | None = None, **source_kwargs) → Scene[source]

set_solver(method: str = 'disort', streams: int = 16, **kwargs) → Scene[source]

set_source_solar(sza: float, **kwargs) → Scene[source]

set_source_thermal(**kwargs) → Scene[source]

set_special(**kwargs) → Scene[source]

set_sslidar(**kwargs) → Scene[source]

set_surface(**kwargs) → Scene[source]

set_three_d(**kwargs) → Scene[source]

set_wavelength(wl_min: float, wl_max: float | None = None, **kwargs) → Scene[source]

class pyradtran.SizeDistribution(*, kind: Literal['lognormal', 'modified_gamma', 'discrete', 'monodisperse'], params: dict, number_density_per_m3: float = 1.0)[source]

Bases: BaseModel

Aerosol particle size distribution.

evaluate(r_grid_um: ndarray) → ndarray[source]

kind: Literal['lognormal', 'modified_gamma', 'discrete', 'monodisperse']

model_config = {'extra': 'forbid', 'frozen': True, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

number_density_per_m3: float

params: dict

validate_params() → SizeDistribution[source]

class pyradtran.SpeciesOptics(beta_ext_per_mass: ndarray[tuple[Any, ...], dtype[_ScalarT]], ssa: ndarray[tuple[Any, ...], dtype[_ScalarT]], g: ndarray[tuple[Any, ...], dtype[_ScalarT]], legendre_moments: ndarray[tuple[Any, ...], dtype[_ScalarT]] | None = None)[source]

Bases: object

Mass-normalized intensive optical properties of an aerosol species.

beta_ext_per_mass: ndarray[tuple[Any, ...], dtype[_ScalarT]]

g: ndarray[tuple[Any, ...], dtype[_ScalarT]]

legendre_moments: ndarray[tuple[Any, ...], dtype[_ScalarT]] | None = None

ssa: ndarray[tuple[Any, ...], dtype[_ScalarT]]

class pyradtran.ThreeDConfig(*, atmosphere_file: str | None = None)[source]

Bases: UvspecOption

3D atmospheric field configuration.

Configures 3D atmospheric input fields for MYSTIC and dynamic tenstream solvers.

atmosphere_file

Path to 3D atmospheric field NetCDF file.

Type:: str | None

Note

3D cloud fields are specified through CloudConfig: scene.set_cloud(wc_file=(“3D”, “/path/to/cloud3d.nc”)) or scene.set_cloud(ic_file=(“3D”, “/path/to/ic3d.nc”)).

The ipa (independent pixel approximation) for 3D is enabled via McConfig.ipa=True or McConfig.tipa=”dir”/”dir3d”.

atmosphere_file: str | None

model_config = {'extra': 'forbid', 'frozen': True, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

to_uvspec_items() → list[tuple[int, str]][source]

Return (phase, keyword_line) pairs for priority-sorted output.

Subclasses may override to assign different phases to different keywords. Default phase is 9 (output section).

to_uvspec_lines() → list[str][source]

Serialize this configuration to uvspec input file lines.

Returns:: List of strings, each being one line of a uvspec input file.

pyradtran.run_3d(atmosphere_file: str | None = None, profile: str = 'us', altitude: float = 0.0, sza: float = 30.0, wl_min: float = 300.0, wl_max: float = 2500.0, photons: int = 100000, ipa: bool = False, uvspec_exe: str | None = None, data_path: str | None = None) → Dataset[source]

Run 3D Monte Carlo radiative transfer simulation.

Parameters:

atmosphere_file – Path to 3D atmospheric field file.
profile – Standard atmosphere profile (for 1D fallback).
altitude – Surface altitude in km.
sza – Solar zenith angle in degrees.
wl_min – Minimum wavelength in nm.
wl_max – Maximum wavelength in nm.
photons – Number of Monte Carlo photons.
ipa – Use independent pixel approximation.
uvspec_exe – Path to uvspec binary.
data_path – Path to libRadtran data directory.

Returns:

xarray.Dataset with 3D radiative transfer results.

pyradtran.run_cloudy_scene(ic_properties: str = 'fu', ic_tau: float | None = None, ic_habit: str | None = None, wc_properties: str | None = None, wc_tau: float | None = None, sza: float = 30.0, profile: str = 'us', altitude: float | str = 0.0, pwv: float = 5.0, ozone: float = 300.0, wl_min: float = 300.0, wl_max: float = 2500.0, albedo: float = 0.2, streams: int = 16, uvspec_exe: str | None = None, data_path: str | None = None) → Dataset[source]

Run uvspec with cloud layer.

Parameters:

ic_properties – Ice cloud parameterization (fu, yang, key, baum, etc.).
ic_tau – Ice cloud optical thickness (set via ic_modify).
ic_habit – Ice crystal habit type.
wc_properties – Water cloud parameterization (hu, echam4).
wc_tau – Water cloud optical thickness.
sza – Solar zenith angle in degrees.
profile – Atmospheric profile name.
altitude – Surface altitude in km.
pwv – Precipitable water vapor in mm.
ozone – Ozone column in DU.
wl_min – Minimum wavelength in nm.
wl_max – Maximum wavelength in nm.
albedo – Surface albedo.
streams – Number of DISORT streams.
uvspec_exe – Path to uvspec binary.
data_path – Path to libRadtran data directory.

Returns:

xarray.Dataset with irradiance vs wavelength.

pyradtran.run_lidar(area: float = 1.0, E0: float = 0.1, efficiency: float = 0.5, position: float = 0.0, range_bin: float = 0.1, n_ranges: int = 100, profile: str = 'us', altitude: float = 0.0, wl_min: float = 300.0, wl_max: float = 1100.0, streams: int = 16, uvspec_exe: str | None = None, data_path: str | None = None) → Dataset[source]

Run single scattering lidar simulation.

Parameters:

area – Telescope area in m^2.
E0 – Pulse energy in Joules.
efficiency – Detector efficiency.
position – Lidar position in km.
range_bin – Range bin width in km.
n_ranges – Number of range bins.
profile – Atmospheric profile.
altitude – Surface altitude in km.
wl_min – Minimum wavelength in nm.
wl_max – Maximum wavelength in nm.
streams – Number of DISORT streams.
uvspec_exe – Path to uvspec binary.
data_path – Path to libRadtran data directory.

Returns:

xarray.Dataset with lidar signal vs range.

pyradtran.run_polarized(profile: str = 'us', altitude: float = 0.0, sza: float = 30.0, wl_min: float = 250.0, wl_max: float = 1200.0, photons: int = 100000, streams: int = 16, uvspec_exe: str | None = None, data_path: str | None = None) → Dataset[source]

Run polarized Monte Carlo simulation.

Parameters:

profile – Atmospheric profile.
altitude – Surface altitude in km.
sza – Solar zenith angle in degrees.
wl_min – Minimum wavelength in nm.
wl_max – Maximum wavelength in nm.
photons – Number of Monte Carlo photons.
streams – Number of streams (for correlated-k).
uvspec_exe – Path to uvspec binary.
data_path – Path to libRadtran data directory.

Returns:

xarray.Dataset with polarized radiance.

pyradtran.run_satellite(geometry: str = 'MPS', pixel: tuple[int, int] | None = None, profile: str = 'us', sza: float = 60.0, wl_min: float = 300.0, wl_max: float = 2500.0, solver: str = 'disort', streams: int = 16, uvspec_exe: str | None = None, data_path: str | None = None) → Dataset[source]

Run satellite-viewing radiative transfer simulation.

Parameters:

geometry – Satellite geometry name (e.g., MPS, SENTINEL2A).
pixel – Optional (x, y) pixel coordinates for satellite_geometry file.
profile – Standard atmosphere profile.
sza – Solar zenith angle in degrees.
wl_min – Minimum wavelength in nm.
wl_max – Maximum wavelength in nm.
solver – RTE solver name.
streams – Number of angular streams.
uvspec_exe – Path to uvspec binary.
data_path – Path to libRadtran data directory.

Returns:

xarray.Dataset with satellite-view radiance/irradiance.

pyradtran.run_solar_radiance(sza: float = 30.0, airmass: float | None = None, profile: str = 'us', altitude: float | str = 0.0, pwv: float = 5.0, ozone: float = 300.0, wl_min: float = 250.0, wl_max: float = 2500.0, albedo: float = 0.2, streams: int = 16, solver: str = 'disort', uvspec_exe: str | None = None, data_path: str | None = None) → Dataset[source]

Calculate solar spectral radiance (direct + diffuse irradiance).

Parameters:

sza – Solar zenith angle in degrees. Ignored if airmass is set.
airmass – Relative airmass. Overrides sza if provided.
profile – Atmospheric profile name.
altitude – Surface altitude in km, or a preset name.
pwv – Precipitable water vapor in mm.
ozone – Ozone column in DU.
wl_min – Minimum wavelength in nm.
wl_max – Maximum wavelength in nm.
albedo – Surface albedo.
streams – Number of DISORT streams.
solver – RTE solver name.
uvspec_exe – Path to uvspec binary.
data_path – Path to libRadtran data directory.

Returns:

xarray.Dataset with irradiance vs wavelength at TOA and surface.

pyradtran.run_solar_transmittance(airmass: float = 1.0, pwv: float = 5.0, ozone: float = 300.0, profile: str = 'us', altitude: float | str = 0.0, wl_min: float = 250.0, wl_max: float = 1200.0, albedo: float = 0.0, streams: int = 16, uvspec_exe: str | None = None, data_path: str | None = None) → Dataset[source]

Calculate solar spectral transmittance.

Parameters:

airmass – Relative airmass (1.0 = zenith).
pwv – Precipitable water vapor in mm (mol_modify H2O).
ozone – Ozone column in DU (mol_modify O3).
profile – Atmospheric profile name (us, ms, mw, tp, ss, sw).
altitude – Surface altitude in km, or a preset name (“LSST”, “CTIO”).
wl_min – Minimum wavelength in nm.
wl_max – Maximum wavelength in nm.
albedo – Surface albedo.
streams – Number of DISORT streams.
uvspec_exe – Path to uvspec binary.
data_path – Path to libRadtran data directory.

Returns:

xarray.Dataset with transmittance vs wavelength.

pyradtran.run_thermal_brightness(pwv: float = 10.0, profile: str = 'ms', altitude: float = 0.0, wl_min: float = 2500.0, wl_max: float = 50000.0, sur_temperature: float | None = None, streams: int = 16, uvspec_exe: str | None = None, data_path: str | None = None) → Dataset[source]: Calculate thermal infrared brightness temperature.

pyradtran.run_with_aerosol(aerosol_file_type: str = 'explicit', aerosol_file_path: str | None = None, sza: float = 30.0, profile: str = 'us', altitude: float | str = 0.0, pwv: float = 5.0, ozone: float = 300.0, wl_min: float = 300.0, wl_max: float = 2500.0, albedo: float = 0.2, streams: int = 16, uvspec_exe: str | None = None, data_path: str | None = None) → Dataset[source]

Run uvspec with external aerosol optical property file.

Parameters:

aerosol_file_type – Type of aerosol file (explicit, gg, ssa, tau, moments).
aerosol_file_path – Path to the aerosol file.
sza – Solar zenith angle in degrees.
profile – Atmospheric profile name.
altitude – Surface altitude in km.
pwv – Precipitable water vapor in mm.
ozone – Ozone column in DU.
wl_min – Minimum wavelength in nm.
wl_max – Maximum wavelength in nm.
albedo – Surface albedo.
streams – Number of DISORT streams.
uvspec_exe – Path to uvspec binary.
data_path – Path to libRadtran data directory.

Returns:

xarray.Dataset with irradiance vs wavelength.

pyradtran.run_with_opac_custom(species_file: str, library: str = 'OPAC', species_names: list[str] | None = None, sza: float = 30.0, profile: str = 'us', altitude: float | str = 0.0, pwv: float = 5.0, ozone: float = 300.0, wl_min: float = 300.0, wl_max: float = 2500.0, albedo: float = 0.2, streams: int = 16, uvspec_exe: str | None = None, data_path: str | None = None) → Dataset[source]

Run uvspec with OPAC custom species profile.

Parameters:

species_file – Path to an ASCII species mass concentration profile file.
library – OPAC library path or “OPAC” for default resolution.
species_names – Optional species filter.
sza – Solar zenith angle in degrees.
profile – Atmospheric profile name.
altitude – Surface altitude in km.
pwv – Precipitable water vapor in mm.
ozone – Ozone column in DU.
wl_min – Minimum wavelength in nm.
wl_max – Maximum wavelength in nm.
albedo – Surface albedo.
streams – Number of DISORT streams.
uvspec_exe – Path to uvspec binary.
data_path – Path to libRadtran data directory.

Returns:

xarray.Dataset with irradiance vs wavelength.

pyradtran.run_with_opac_preset(preset: str | OpacPresetName, library: str = 'OPAC', species_names: list[str] | None = None, sza: float = 30.0, profile: str = 'us', altitude: float | str = 0.0, pwv: float = 5.0, ozone: float = 300.0, wl_min: float = 300.0, wl_max: float = 2500.0, albedo: float = 0.2, streams: int = 16, uvspec_exe: str | None = None, data_path: str | None = None) → Dataset[source]

Run uvspec with OPAC preset mixture profile.

Parameters:

preset – OPAC preset name (e.g. “continental_average”) or OpacPresetName enum.
library – OPAC library path or “OPAC” for default resolution.
species_names – Optional species filter (e.g. [“inso”, “soot”]).
sza – Solar zenith angle in degrees.
profile – Atmospheric profile name.
altitude – Surface altitude in km.
pwv – Precipitable water vapor in mm.
ozone – Ozone column in DU.
wl_min – Minimum wavelength in nm.
wl_max – Maximum wavelength in nm.
albedo – Surface albedo.
streams – Number of DISORT streams.
uvspec_exe – Path to uvspec binary.
data_path – Path to libRadtran data directory.

Returns:

xarray.Dataset with irradiance vs wavelength.

Scene

Scene builder with immutable chain API.

Scene composes all Pydantic models into a complete uvspec configuration. Each set_*() method returns a NEW Scene via copy.deepcopy() to avoid mutability traps.

Bases: object

Immutable scene builder composing all uvspec configuration models.

Each set_*() method returns a new Scene via deepcopy. Use .clone() for an explicit copy.

Usage:

scene = (
    Scene()
    .set_atmosphere(profile="us", altitude=2.663)
    .set_source_solar(sza=30.0)
    .set_wavelength(250.0, 1200.0)
    .set_solver(method="disort", streams=16)
    .set_output(quantities=["lambda", "edir"])
)

add_raw_keyword(key: str, value: str = '') → Scene[source]

build_input(data_files_path: str | None = None) → str[source]

Build complete uvspec input text from this Scene.

Raises:: ValueError – If required components are missing.

clone() → Scene[source]: Create a deep copy of this Scene.

set_advanced(**kwargs) → Scene[source]

set_aerosol(aerosol: AerosolModel) → Scene[source]: Set aerosol configuration from an AerosolModel instance.

set_aerosol_modify(variable: str, action: str, value: float) → Scene[source]

Add an aerosol modification directive.

Parameters:

variable – Property to modify (gg, ssa, tau, tau550).
action – Modification type (scale or set).
value – Numeric value.

set_atmosphere(**kwargs) → Scene[source]

set_cloud(**kwargs) → Scene[source]

set_dynamic(method: str = 'dynamic_tenstream', iterations: int | None = None, **kwargs) → Scene[source]

set_mc(**kwargs) → Scene[source]

set_mol_modify(species: str, value: float, unit: str) → Scene[source]

set_output(**kwargs) → Scene[source]

set_satellite(geometry: str | None = None, pixel: tuple[int, int] | None = None, **source_kwargs) → Scene[source]

set_solver(method: str = 'disort', streams: int = 16, **kwargs) → Scene[source]

set_source_solar(sza: float, **kwargs) → Scene[source]

set_source_thermal(**kwargs) → Scene[source]

set_special(**kwargs) → Scene[source]

set_sslidar(**kwargs) → Scene[source]

set_surface(**kwargs) → Scene[source]

set_three_d(**kwargs) → Scene[source]

set_wavelength(wl_min: float, wl_max: float | None = None, **kwargs) → Scene[source]

Runner

Subprocess execution engine for uvspec.

Runner is decoupled from Scene. Scene holds configuration; Runner executes it by building input, running uvspec, and parsing output.

class pyradtran.core.runner.Runner[source]

Bases: object

Execute uvspec simulations.

Usage:

result = Runner.execute(scene, data_path="/path/to/data")
results = Runner.execute_many(scenes, max_workers=4)

Global defaults may be set once via configure() so that uvspec_exe and data_path do not need to be repeated on every call:

Runner.configure(uvspec_exe="/opt/libRadtran/bin/uvspec",
                 data_path="/opt/libRadtran/data")
result = Runner.execute(scene)

classmethod configure(config: RunnerConfig | None = None, **kwargs) → RunnerConfig[source]

Set global default configuration for all Runner executions.

Parameters:

config – A complete RunnerConfig instance, or None.
**kwargs – Individual fields (e.g. uvspec_exe=..., data_path=...).

Returns:

The newly set configuration.

Execute a single uvspec simulation.

Parameters:

scene – Configured Scene object.
uvspec_exe – Path to uvspec binary. Auto-detected if None.
data_path – Path to libRadtran data directory. Auto-detected if None.
keep_temp – Keep temporary files after execution.
timeout – Maximum execution time in seconds.
config – Optional RunnerConfig overriding global defaults for this call only.

Returns:

xarray.Dataset with simulation results.

Execute multiple uvspec simulations in parallel.

Parameters:

scenes – List of configured Scene objects.
uvspec_exe – Path to uvspec binary. Auto-detected if None.
data_path – Path to libRadtran data directory. Auto-detected if None.
max_workers – Maximum parallel workers.
keep_temp – Keep temporary files after execution.
timeout – Maximum execution time in seconds per scene.
config – Optional RunnerConfig overriding global defaults.

Returns:

List of xarray.Dataset results, one per scene.

class pyradtran.core.runner.RunnerConfig(uvspec_exe: str | None = None, data_path: str | None = None, max_workers: int = 4, keep_temp: bool = False, timeout: int | None = None)[source]

Bases: object

Configuration for uvspec execution.

uvspec_exe

Path to uvspec binary. Auto-detected via PATH if None.

Type:: str | None

data_path

Path to libRadtran data directory. Uses env vars if None.

Type:: str | None

max_workers

Maximum parallel workers for execute_many().

Type:: int

keep_temp

Keep temporary files after execution (for debugging).

Type:: bool

timeout

Maximum uvspec execution time in seconds. None = no timeout.

Type:: int | None

data_path: str | None = None

keep_temp: bool = False

max_workers: int = 4

timeout: int | None = None

uvspec_exe: str | None = None

Core Utilities

Serialize Scene configuration to uvspec input text.

pyradtran.core.input_builder.build_input_text(atmosphere: AtmosphereConfig, source: SourceConfig, wavelength: WavelengthConfig, solver: SolverConfig, output: OutputConfig, surface: SurfaceConfig | None = None, aerosol: AerosolModel | None = None, cloud: CloudConfig | None = None, mc: McConfig | None = None, sslidar: SslidarConfig | None = None, advanced: AdvancedConfig | None = None, three_d: ThreeDConfig | None = None, raw_keywords: list[tuple[str, str]] | None = None, data_files_path: str | None = None, special: SpecialConfig | None = None) → str[source]

Build a complete uvspec input string from configuration models.

Keywords are collected as (phase, line) pairs from each model’s to_uvspec_items() method, then sorted by phase to guarantee correct uvspec keyword ordering.

Phase assignments:: 0 - data_files_path, include directives 1 - atmosphere 2 - source 3 - wavelength 4 - scattering/absorption switches (no_absorption, no_scattering) 5 - aerosol 6 - cloud 7 - surface 8 - solver 9 - output 10 - mc, sslidar 11 - three_d 12 - advanced 13 - raw_keywords (user-supplied, always last)

Parse uvspec output files into xarray.Dataset.

Supports both ASCII (default DISORT 7-column and output_user custom) and NetCDF output formats.

pyradtran.core.output_parser.parse_output(output_path: str | Path, format: str = 'netcdf', n_zout: int = 1, column_names: list[str] | None = None) → Dataset[source]

Parse uvspec output file into xarray.Dataset.

Parameters:

output_path – Path to uvspec output file.
format – Output format — “netcdf” or “ascii”.
n_zout – Number of zout levels in output (for ASCII multi-level).
column_names – Custom column names for output_user ASCII output.

Returns:

xarray.Dataset with wavelength (and optionally zout) as coordinates.

Temporary file lifecycle management for uvspec data files.

class pyradtran.core.tempfile_manager.TempFileManager(temp_dir: str | None = None, keep_temp: bool = False)[source]

Bases: object

Manage temporary data files for uvspec execution.

Parameters:

temp_dir – Directory for temporary files. Defaults to system temp.
keep_temp – If True, don’t delete files on cleanup (for debugging).

Usage:

with TempFileManager() as mgr:
    path = mgr.write_array("extinction.dat", extinction_data)
# files cleaned up on exit

cleanup() → None[source]: Delete all tracked temporary files.

property files: list[str]: List of tracked temporary file paths.

write_array(name: str, data: ndarray) → str[source]: Write numpy array to a temporary file, return the path.

write_text(name: str, content: str) → str[source]: Write text content to a temporary file, return the path.

Convenience Functions

High-level convenience functions for common radiative transfer tasks.

pyradtran.convenience.run_3d(atmosphere_file: str | None = None, profile: str = 'us', altitude: float = 0.0, sza: float = 30.0, wl_min: float = 300.0, wl_max: float = 2500.0, photons: int = 100000, ipa: bool = False, uvspec_exe: str | None = None, data_path: str | None = None) → Dataset[source]

Run 3D Monte Carlo radiative transfer simulation.

Parameters:

atmosphere_file – Path to 3D atmospheric field file.
profile – Standard atmosphere profile (for 1D fallback).
altitude – Surface altitude in km.
sza – Solar zenith angle in degrees.
wl_min – Minimum wavelength in nm.
wl_max – Maximum wavelength in nm.
photons – Number of Monte Carlo photons.
ipa – Use independent pixel approximation.
uvspec_exe – Path to uvspec binary.
data_path – Path to libRadtran data directory.

Returns:

xarray.Dataset with 3D radiative transfer results.

pyradtran.convenience.run_cloudy_scene(ic_properties: str = 'fu', ic_tau: float | None = None, ic_habit: str | None = None, wc_properties: str | None = None, wc_tau: float | None = None, sza: float = 30.0, profile: str = 'us', altitude: float | str = 0.0, pwv: float = 5.0, ozone: float = 300.0, wl_min: float = 300.0, wl_max: float = 2500.0, albedo: float = 0.2, streams: int = 16, uvspec_exe: str | None = None, data_path: str | None = None) → Dataset[source]

Run uvspec with cloud layer.

Parameters:

ic_properties – Ice cloud parameterization (fu, yang, key, baum, etc.).
ic_tau – Ice cloud optical thickness (set via ic_modify).
ic_habit – Ice crystal habit type.
wc_properties – Water cloud parameterization (hu, echam4).
wc_tau – Water cloud optical thickness.
sza – Solar zenith angle in degrees.
profile – Atmospheric profile name.
altitude – Surface altitude in km.
pwv – Precipitable water vapor in mm.
ozone – Ozone column in DU.
wl_min – Minimum wavelength in nm.
wl_max – Maximum wavelength in nm.
albedo – Surface albedo.
streams – Number of DISORT streams.
uvspec_exe – Path to uvspec binary.
data_path – Path to libRadtran data directory.

Returns:

xarray.Dataset with irradiance vs wavelength.

pyradtran.convenience.run_lidar(area: float = 1.0, E0: float = 0.1, efficiency: float = 0.5, position: float = 0.0, range_bin: float = 0.1, n_ranges: int = 100, profile: str = 'us', altitude: float = 0.0, wl_min: float = 300.0, wl_max: float = 1100.0, streams: int = 16, uvspec_exe: str | None = None, data_path: str | None = None) → Dataset[source]

Run single scattering lidar simulation.

Parameters:

area – Telescope area in m^2.
E0 – Pulse energy in Joules.
efficiency – Detector efficiency.
position – Lidar position in km.
range_bin – Range bin width in km.
n_ranges – Number of range bins.
profile – Atmospheric profile.
altitude – Surface altitude in km.
wl_min – Minimum wavelength in nm.
wl_max – Maximum wavelength in nm.
streams – Number of DISORT streams.
uvspec_exe – Path to uvspec binary.
data_path – Path to libRadtran data directory.

Returns:

xarray.Dataset with lidar signal vs range.

pyradtran.convenience.run_polarized(profile: str = 'us', altitude: float = 0.0, sza: float = 30.0, wl_min: float = 250.0, wl_max: float = 1200.0, photons: int = 100000, streams: int = 16, uvspec_exe: str | None = None, data_path: str | None = None) → Dataset[source]

Run polarized Monte Carlo simulation.

Parameters:

profile – Atmospheric profile.
altitude – Surface altitude in km.
sza – Solar zenith angle in degrees.
wl_min – Minimum wavelength in nm.
wl_max – Maximum wavelength in nm.
photons – Number of Monte Carlo photons.
streams – Number of streams (for correlated-k).
uvspec_exe – Path to uvspec binary.
data_path – Path to libRadtran data directory.

Returns:

xarray.Dataset with polarized radiance.

pyradtran.convenience.run_satellite(geometry: str = 'MPS', pixel: tuple[int, int] | None = None, profile: str = 'us', sza: float = 60.0, wl_min: float = 300.0, wl_max: float = 2500.0, solver: str = 'disort', streams: int = 16, uvspec_exe: str | None = None, data_path: str | None = None) → Dataset[source]

Run satellite-viewing radiative transfer simulation.

Parameters:

geometry – Satellite geometry name (e.g., MPS, SENTINEL2A).
pixel – Optional (x, y) pixel coordinates for satellite_geometry file.
profile – Standard atmosphere profile.
sza – Solar zenith angle in degrees.
wl_min – Minimum wavelength in nm.
wl_max – Maximum wavelength in nm.
solver – RTE solver name.
streams – Number of angular streams.
uvspec_exe – Path to uvspec binary.
data_path – Path to libRadtran data directory.

Returns:

xarray.Dataset with satellite-view radiance/irradiance.

pyradtran.convenience.run_solar_radiance(sza: float = 30.0, airmass: float | None = None, profile: str = 'us', altitude: float | str = 0.0, pwv: float = 5.0, ozone: float = 300.0, wl_min: float = 250.0, wl_max: float = 2500.0, albedo: float = 0.2, streams: int = 16, solver: str = 'disort', uvspec_exe: str | None = None, data_path: str | None = None) → Dataset[source]

Calculate solar spectral radiance (direct + diffuse irradiance).

Parameters:

sza – Solar zenith angle in degrees. Ignored if airmass is set.
airmass – Relative airmass. Overrides sza if provided.
profile – Atmospheric profile name.
altitude – Surface altitude in km, or a preset name.
pwv – Precipitable water vapor in mm.
ozone – Ozone column in DU.
wl_min – Minimum wavelength in nm.
wl_max – Maximum wavelength in nm.
albedo – Surface albedo.
streams – Number of DISORT streams.
solver – RTE solver name.
uvspec_exe – Path to uvspec binary.
data_path – Path to libRadtran data directory.

Returns:

xarray.Dataset with irradiance vs wavelength at TOA and surface.

pyradtran.convenience.run_solar_transmittance(airmass: float = 1.0, pwv: float = 5.0, ozone: float = 300.0, profile: str = 'us', altitude: float | str = 0.0, wl_min: float = 250.0, wl_max: float = 1200.0, albedo: float = 0.0, streams: int = 16, uvspec_exe: str | None = None, data_path: str | None = None) → Dataset[source]

Calculate solar spectral transmittance.

Parameters:

airmass – Relative airmass (1.0 = zenith).
pwv – Precipitable water vapor in mm (mol_modify H2O).
ozone – Ozone column in DU (mol_modify O3).
profile – Atmospheric profile name (us, ms, mw, tp, ss, sw).
altitude – Surface altitude in km, or a preset name (“LSST”, “CTIO”).
wl_min – Minimum wavelength in nm.
wl_max – Maximum wavelength in nm.
albedo – Surface albedo.
streams – Number of DISORT streams.
uvspec_exe – Path to uvspec binary.
data_path – Path to libRadtran data directory.

Returns:

xarray.Dataset with transmittance vs wavelength.

pyradtran.convenience.run_thermal_brightness(pwv: float = 10.0, profile: str = 'ms', altitude: float = 0.0, wl_min: float = 2500.0, wl_max: float = 50000.0, sur_temperature: float | None = None, streams: int = 16, uvspec_exe: str | None = None, data_path: str | None = None) → Dataset[source]: Calculate thermal infrared brightness temperature.

pyradtran.convenience.run_with_aerosol(aerosol_file_type: str = 'explicit', aerosol_file_path: str | None = None, sza: float = 30.0, profile: str = 'us', altitude: float | str = 0.0, pwv: float = 5.0, ozone: float = 300.0, wl_min: float = 300.0, wl_max: float = 2500.0, albedo: float = 0.2, streams: int = 16, uvspec_exe: str | None = None, data_path: str | None = None) → Dataset[source]

Run uvspec with external aerosol optical property file.

Parameters:

aerosol_file_type – Type of aerosol file (explicit, gg, ssa, tau, moments).
aerosol_file_path – Path to the aerosol file.
sza – Solar zenith angle in degrees.
profile – Atmospheric profile name.
altitude – Surface altitude in km.
pwv – Precipitable water vapor in mm.
ozone – Ozone column in DU.
wl_min – Minimum wavelength in nm.
wl_max – Maximum wavelength in nm.
albedo – Surface albedo.
streams – Number of DISORT streams.
uvspec_exe – Path to uvspec binary.
data_path – Path to libRadtran data directory.

Returns:

xarray.Dataset with irradiance vs wavelength.

pyradtran.convenience.run_with_opac_custom(species_file: str, library: str = 'OPAC', species_names: list[str] | None = None, sza: float = 30.0, profile: str = 'us', altitude: float | str = 0.0, pwv: float = 5.0, ozone: float = 300.0, wl_min: float = 300.0, wl_max: float = 2500.0, albedo: float = 0.2, streams: int = 16, uvspec_exe: str | None = None, data_path: str | None = None) → Dataset[source]

Run uvspec with OPAC custom species profile.

Parameters:

species_file – Path to an ASCII species mass concentration profile file.
library – OPAC library path or “OPAC” for default resolution.
species_names – Optional species filter.
sza – Solar zenith angle in degrees.
profile – Atmospheric profile name.
altitude – Surface altitude in km.
pwv – Precipitable water vapor in mm.
ozone – Ozone column in DU.
wl_min – Minimum wavelength in nm.
wl_max – Maximum wavelength in nm.
albedo – Surface albedo.
streams – Number of DISORT streams.
uvspec_exe – Path to uvspec binary.
data_path – Path to libRadtran data directory.

Returns:

xarray.Dataset with irradiance vs wavelength.

pyradtran.convenience.run_with_opac_preset(preset: str | OpacPresetName, library: str = 'OPAC', species_names: list[str] | None = None, sza: float = 30.0, profile: str = 'us', altitude: float | str = 0.0, pwv: float = 5.0, ozone: float = 300.0, wl_min: float = 300.0, wl_max: float = 2500.0, albedo: float = 0.2, streams: int = 16, uvspec_exe: str | None = None, data_path: str | None = None) → Dataset[source]

Run uvspec with OPAC preset mixture profile.

Parameters:

preset – OPAC preset name (e.g. “continental_average”) or OpacPresetName enum.
library – OPAC library path or “OPAC” for default resolution.
species_names – Optional species filter (e.g. [“inso”, “soot”]).
sza – Solar zenith angle in degrees.
profile – Atmospheric profile name.
altitude – Surface altitude in km.
pwv – Precipitable water vapor in mm.
ozone – Ozone column in DU.
wl_min – Minimum wavelength in nm.
wl_max – Maximum wavelength in nm.
albedo – Surface albedo.
streams – Number of DISORT streams.
uvspec_exe – Path to uvspec binary.
data_path – Path to libRadtran data directory.

Returns:

xarray.Dataset with irradiance vs wavelength.

Configuration Models

Base

Base class for all uvspec option models.

class pyradtran.models.base.UvspecOption[source]

Bases: BaseModel

Base class for uvspec keyword group models.

All models are frozen (immutable) and reject extra fields to catch typos at the Python level rather than at uvspec runtime.

Subclasses must implement to_uvspec_lines() to serialize their configuration to uvspec input file format.

model_config = {'extra': 'forbid', 'frozen': True, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

to_uvspec_items() → list[tuple[int, str]][source]

Return (phase, keyword_line) pairs for priority-sorted output.

Subclasses may override to assign different phases to different keywords. Default phase is 9 (output section).

to_uvspec_lines() → list[str][source]

Serialize this configuration to uvspec input file lines.

Returns:: List of strings, each being one line of a uvspec input file.

Atmosphere

Atmosphere configuration model.

Maps to uvspec keywords: atmosphere_file, altitude, pressure, mol_modify, mol_abs_param.

Reference: libRadtran src_py/molecular_options.py, src_py/surface_options.py

class pyradtran.models.atmosphere.AtmosphereConfig(*, profile: ~typing.Annotated[str, ~annotated_types.MinLen(min_length=1)], altitude: ~typing.Annotated[float, ~annotated_types.Ge(ge=-1000000.0), ~annotated_types.Le(le=1000000.0)] = 0.0, pressure: ~types.Annotated[float | None, ~annotated_types.Ge(ge=0), ~annotated_types.Le(le=1000000.0)] = None, mol_modify: list[tuple[str, float, str]] = <factory>, mol_abs_param: str | None = None, crs_model: dict[str, str] | list[dict[str, str]] | None = None, atm_z_grid: list[float] | None = None, radiosonde: bool = False, radiosonde_levels_only: bool = False, mol_file: list[dict[str, str]] | None = None, mol_tau_file: tuple[str, str] | None = None, rayleigh_depol: ~types.Annotated[float | None, ~annotated_types.Ge(ge=0.0), ~annotated_types.Le(le=1.0)] = None, raman: bool = False)[source]

Bases: UvspecOption

Atmospheric profile and molecular absorption configuration.

profile

Named AFGL atmosphere or path to custom atmosphere file. Shorthands: us, ms, mw, tp, ss, sw. Full names: US-standard, midlatitude_summer, midlatitude_winter, tropics, subarctic_summer, subarctic_winter.

Type:: str

altitude

Surface altitude above sea level in km. Default: 0.0.

Type:: float

pressure

Surface pressure in hPa. Scales pressure, air, O2, CO2 profiles.

Type:: float | None

mol_modify

List of (species, column_value, unit) tuples. Species: O3, O2, H2O, CO2, NO2, BRO, OCLO, HCHO, O4, SO2, CH4, N2O, CO, N2. Units: DU, CM_2, MM.

Type:: list[tuple[str, float, str]]

mol_abs_param

Molecular absorption parameterization scheme string. Default is reptran coarse (handled by uvspec internally).

Type:: str | None

atm_z_grid

Custom altitude grid in km.

Type:: list[float] | None

radiosonde

Use radiosonde profile data.

Type:: bool

radiosonde_levels_only

Use only radiosonde levels (requires radiosonde=True).

Type:: bool

mol_file

List of molecular VMR profile files, each a dict with keys “species”, “file”, and optional “unit”.

Type:: list[dict[str, str]] | None

mol_tau_file

Molecular optical thickness file as (kind, filepath) tuple.

Type:: tuple[str, str] | None

rayleigh_depol

Rayleigh scattering depolarization factor.

Type:: float | None

raman

Enable Raman scattering.

Type:: bool

altitude: float

atm_z_grid: list[float] | None

crs_model: dict[str, str] | list[dict[str, str]] | None

model_config = {'extra': 'forbid', 'frozen': True, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(context: Any, /) → None

This function is meant to behave like a BaseModel method to initialize private attributes.

It takes context as an argument since that’s what pydantic-core passes when calling it.

Parameters:

self – The BaseModel instance.
context – The context.

mol_abs_param: str | None

mol_file: list[dict[str, str]] | None

mol_modify: list[tuple[str, float, str]]

mol_tau_file: tuple[str, str] | None

pressure: float | None

profile: str

radiosonde: bool

radiosonde_levels_only: bool

raman: bool

rayleigh_depol: float | None

to_uvspec_items() → list[tuple[int, str]][source]

Return (phase, keyword_line) pairs for priority-sorted output.

Subclasses may override to assign different phases to different keywords. Default phase is 9 (output section).

to_uvspec_lines() → list[str][source]

Serialize this configuration to uvspec input file lines.

Returns:: List of strings, each being one line of a uvspec input file.

validate_crs_model() → AtmosphereConfig[source]

validate_mol_modify_entries() → AtmosphereConfig[source]

validate_radiosonde() → AtmosphereConfig[source]

Source

Source configuration model.

Maps to uvspec keywords: source, sza, phi0, day_of_year, solar_flux_file, umu, phi, latitude, longitude, time, time_interpolate, time_interval, earth_radius, sza_file, isotropic_source_toa.

Reference: libRadtran src_py/geometry_options.py, src_py/spectral_options.py

class pyradtran.models.source.SourceConfig(*, source: ~typing.Annotated[str, _PydanticGeneralMetadata(pattern='^(solar|thermal)$')], sza: ~types.Annotated[float | None, ~annotated_types.Ge(ge=0.0), ~annotated_types.Le(le=180.0)] = None, phi0: ~types.Annotated[float | None, ~annotated_types.Ge(ge=-360.0), ~annotated_types.Le(le=360.0)] = None, day_of_year: ~types.Annotated[int | None, ~annotated_types.Ge(ge=1), ~annotated_types.Le(le=366)] = None, solar_flux_file: str | None = None, umu: list[float] = <factory>, phi: list[float] = <factory>, satellite_geometry: str | None = None, satellite_pixel: tuple[int, int] | None = None, latitude: tuple[str, int, int, int] | None = None, longitude: tuple[str, int, int, int] | None = None, time: str | None = None, time_interpolate: bool = False, time_interval: tuple[str, str] | None = None, earth_radius: ~types.Annotated[float | None, ~annotated_types.Ge(ge=0.0)] = None, sza_file: str | None = None, isotropic_source_toa: bool = False)[source]

Bases: UvspecOption

Solar or thermal radiation source configuration.

source

Radiation source type – “solar” or “thermal”.

Type:: str

sza

Solar zenith angle in degrees [0, 180]. Required for solar source (unless sza_file or isotropic_source_toa is set).

Type:: float | None

phi0

Solar azimuth angle in degrees [-360, 360].

Type:: float | None

day_of_year

Day of year [1, 366].

Type:: int | None

solar_flux_file

Path to solar flux file (e.g. kurudz_0.1nm.dat).

Type:: str | None

umu

Viewing zenith angles (cosines). Positive = upward, negative = downward.

Type:: list[float]

phi

Viewing azimuth angles in degrees.

Type:: list[float]

satellite_geometry

Satellite geometry specification (e.g., SENTINEL2A, MPS).

Type:: str | None

satellite_pixel

Pixel coordinates (x, y) for satellite pixel-based geometry.

Type:: tuple[int, int] | None

latitude

Geographic latitude as (hemisphere, degrees, minutes, seconds).

Type:: tuple[str, int, int, int] | None

longitude

Geographic longitude as (hemisphere, degrees, minutes, seconds).

Type:: tuple[str, int, int, int] | None

time

Time of day string (e.g. “10:30:00”).

Type:: str | None

time_interpolate

Enable time interpolation.

Type:: bool

time_interval

Tuple of (start_time, end_time) for time range.

Type:: tuple[str, str] | None

earth_radius

Earth radius in km.

Type:: float | None

sza_file

Path to file containing solar zenith angle data.

Type:: str | None

isotropic_source_toa

Use isotropic source at top of atmosphere.

Type:: bool

check_satellite_consistency() → SourceConfig[source]

check_sza_for_solar() → SourceConfig[source]

check_sza_mutual_exclusion() → SourceConfig[source]

day_of_year: int | None

earth_radius: float | None

isotropic_source_toa: bool

latitude: tuple[str, int, int, int] | None

longitude: tuple[str, int, int, int] | None

model_config = {'extra': 'forbid', 'frozen': True, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

phi: list[float]

phi0: float | None

satellite_geometry: str | None

satellite_pixel: tuple[int, int] | None

solar_flux_file: str | None

source: str

sza: float | None

sza_file: str | None

time: str | None

time_interpolate: bool

time_interval: tuple[str, str] | None

to_uvspec_items() → list[tuple[int, str]][source]

Return (phase, keyword_line) pairs for priority-sorted output.

Subclasses may override to assign different phases to different keywords. Default phase is 9 (output section).

to_uvspec_lines() → list[str][source]

Serialize this configuration to uvspec input file lines.

Returns:: List of strings, each being one line of a uvspec input file.

umu: list[float]

Wavelength

Wavelength configuration model.

Maps to uvspec keywords: wavelength, spline, filter_function_file, wavelength_grid_file, wavelength_index, slit_function_file, spline_file, fluorescence, fluorescence_file, thermal_bands_file, thermal_bandwidth.

Reference: libRadtran src_py/spectral_options.py

class pyradtran.models.wavelength.WavelengthConfig(*, wavelength_min: Annotated[float | None, Ge(ge=0), Le(le=1000000.0)] = None, wavelength_max: Annotated[float | None, Ge(ge=0), Le(le=1000000.0)] = None, unit: Annotated[str, _PydanticGeneralMetadata(pattern='^(nm|cm-1)$')] = 'nm', spline: str | None = None, filter_function_file: str | None = None, wavelength_grid_file: str | None = None, wavelength_index: tuple[int, int] | None = None, slit_function_file: str | None = None, spline_file: str | None = None, fluorescence: bool = False, fluorescence_file: str | None = None, thermal_bands_file: str | None = None, thermal_bandwidth: tuple[float, str] | None = None)[source]

Bases: UvspecOption

Spectral range configuration.

wavelength_min

Shortest wavelength (nm or cm-1), or single wavelength when wavelength_max is not set.

Type:: float | None

wavelength_max

Longest wavelength (nm or cm-1). Optional; when None, wavelength_min is treated as a single wavelength value.

Type:: float | None

unit

Wavelength unit – “nm” (default) or “cm-1” for wavenumbers.

Type:: str

spline

Spline smoothing arguments string (3 floats).

Type:: str | None

filter_function_file

Path to filter function file.

Type:: str | None

wavelength_grid_file

Path to wavelength grid file (alternative to wavelength_min).

Type:: str | None

wavelength_index

Tuple of (start_index, end_index) for wavelength subset.

Type:: tuple[int, int] | None

slit_function_file

Path to slit function file.

Type:: str | None

spline_file

Path to spline file.

Type:: str | None

fluorescence

Enable fluorescence calculation.

Type:: bool

fluorescence_file

Path to fluorescence data file.

Type:: str | None

thermal_bands_file

Path to thermal bands file.

Type:: str | None

thermal_bandwidth

Tuple of (width, unit) for thermal bandwidth.

Type:: tuple[float, str] | None

filter_function_file: str | None

fluorescence: bool

fluorescence_file: str | None

model_config = {'extra': 'forbid', 'frozen': True, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

slit_function_file: str | None

spline: str | None

spline_file: str | None

thermal_bands_file: str | None

thermal_bandwidth: tuple[float, str] | None

to_uvspec_items() → list[tuple[int, str]][source]

Return (phase, keyword_line) pairs for priority-sorted output.

Subclasses may override to assign different phases to different keywords. Default phase is 9 (output section).

to_uvspec_lines() → list[str][source]

Serialize this configuration to uvspec input file lines.

Returns:: List of strings, each being one line of a uvspec input file.

unit: str

validate_wavelength_set() → WavelengthConfig[source]

wavelength_grid_file: str | None

wavelength_index: tuple[int, int] | None

wavelength_max: float | None

wavelength_min: float | None

Solver

Solver configuration model.

Maps to uvspec keywords: rte_solver, number_of_streams, pseudospherical, deltam.

Reference: libRadtran src_py/solver_options.py

class pyradtran.models.solver.SolverConfig(*, method: str, streams: Annotated[int, Ge(ge=1)] = 6, pseudospherical: bool = False, deltam: bool = False, dynamic_iterations: Annotated[int | None, Ge(ge=0)] = None, dynamic_history: bool = False, dynamic_heat_unit: str | None = None, disort_intcor: str | None = None, disort_spherical_albedo: bool = False, schwarzschild_streams: Annotated[int | None, Ge(ge=1)] = None)[source]

Bases: UvspecOption

Radiative transfer solver configuration.

method

Solver name (disort, twostr, mystic, etc.).

Type:: str

streams

Number of streams for discrete ordinates solvers. Default: 6.

Type:: int

pseudospherical

Enable pseudo-spherical correction (disort/twostr only).

Type:: bool

deltam

Enable delta-M scaling.

Type:: bool

dynamic_iterations

Number of iterations for dynamic solvers.

Type:: int | None

dynamic_history

Enable history tracking for dynamic solvers.

Type:: bool

dynamic_heat_unit

Heat unit for dynamic solvers.

Type:: str | None

deltam: bool

disort_intcor: str | None

disort_spherical_albedo: bool

dynamic_heat_unit: str | None

dynamic_history: bool

dynamic_iterations: int | None

method: str

model_config = {'extra': 'forbid', 'frozen': True, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

pseudospherical: bool

schwarzschild_streams: int | None

streams: int

to_uvspec_items() → list[tuple[int, str]][source]

Return (phase, keyword_line) pairs for priority-sorted output.

Subclasses may override to assign different phases to different keywords. Default phase is 9 (output section).

to_uvspec_lines() → list[str][source]

Serialize this configuration to uvspec input file lines.

Returns:: List of strings, each being one line of a uvspec input file.

validate_solver() → SolverConfig[source]

Output

Output configuration model.

Maps to uvspec keywords: output_user, output_quantity, output_process, output_format, quiet, verbose, zout, output_file.

Reference: libRadtran src_py/output_options.py

class pyradtran.models.output.OutputConfig(*, quantities: list[str] = <factory>, quantity: str | None = None, process: str | None = None, format: str = 'netcdf', quiet: bool = True, verbose: bool = False, zout: list[float | str] = <factory>, output_file: str | None = None, heating_rate: str | None = None, write_optical_properties: bool = False)[source]

Bases: UvspecOption

Output format and content configuration.

quantities

Output column quantities (e.g. [“lambda”, “edir”, “edn”, “eup”]).

Type:: list[str]

quantity

Output quantity type (transmittance, reflectivity, brightness).

Type:: str | None

process

Output processing (e.g. ‘integrate’, ‘per_nm’, ‘sum’).

Type:: str | None

format

Output file format – “netcdf” (default), “ascii”, “flexstor”.

Type:: str

quiet

Suppress uvspec stdout messages. Default: True.

Type:: bool

verbose

Enable verbose uvspec output.

Type:: bool

zout

Output altitudes in km above ground level. Supports float values and special strings like “toa” and “boa”.

Type:: list[float | str]

output_file

Path for output file (overrides auto-generated name).

Type:: str | None

heating_rate

Heating rate calculation mode (e.g. ‘local’, ‘layer_fd’).

Type:: str | None

write_optical_properties

Write optical properties to output file.

Type:: bool

format: str

heating_rate: str | None

model_config = {'extra': 'forbid', 'frozen': True, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

output_file: str | None

process: str | None

quantities: list[str]

quantity: str | None

quiet: bool

to_uvspec_items() → list[tuple[int, str]][source]

Return (phase, keyword_line) pairs for priority-sorted output.

Subclasses may override to assign different phases to different keywords. Default phase is 9 (output section).

to_uvspec_lines() → list[str][source]

Serialize this configuration to uvspec input file lines.

Returns:: List of strings, each being one line of a uvspec input file.

validate_output() → OutputConfig[source]

verbose: bool

write_optical_properties: bool

zout: list[float | str]

Surface

Surface configuration model.

Maps to uvspec keywords: albedo, albedo_file, albedo_map, albedo_library, sur_temperature, brdf_ambrals, brdf_hapke, brdf_rpv, brdf_cam, bpdf_litvinov, bpdf_maignan, bpdf_tsang_u10.

Reference: libRadtran src/uvspec_lex.l (surface/BRDF options)

class pyradtran.models.surface.SurfaceConfig(*, albedo: Annotated[float | None, Ge(ge=0.0), Le(le=1.0)] = None, albedo_file: str | None = None, albedo_map: str | tuple[str, str] | None = None, albedo_library: str | None = None, sur_temperature: float | None = None, brdf_ambrals: dict[str, float] | None = None, brdf_hapke: dict[str, float] | None = None, brdf_rpv: dict[str, float] | None = None, brdf_cam: dict[str, float] | None = None, bpdf_litvinov: dict[str, float] | None = None, bpdf_maignan: dict[str, float] | None = None, bpdf_tsang_u10: Annotated[float | None, Ge(ge=0.0), Le(le=100.0)] = None, brdf_rossli_file: str | None = None, brdf_rossli_hotspot: bool = False, brdf_rpv_file: str | None = None, surface_type_map: str | None = None, surface_temperature_map: str | tuple[str, str, float] | None = None)[source]

Bases: UvspecOption

Surface reflection and temperature configuration.

albedo

Constant Lambertian albedo [0, 1]. Mutually exclusive with BRDF/BPDF.

Type:: float | None

albedo_file

Path to wavelength-dependent albedo file.

Type:: str | None

albedo_map

Path to spatial albedo map NetCDF file, or tuple (path, variable).

Type:: str | tuple[str, str] | None

albedo_library

Albedo library name or path (“IGBP”).

Type:: str | None

sur_temperature

Surface temperature in Kelvin (for thermal IR).

Type:: float | None

brdf_ambrals

Dict of AMBRALS BRDF parameters (iso, vol, geo).

Type:: dict[str, float] | None

brdf_hapke

Dict of Hapke BRDF parameters (w, b0, h).

Type:: dict[str, float] | None

brdf_rpv

Dict of RPV BRDF parameters (rho0, k, theta, scale).

Type:: dict[str, float] | None

brdf_cam

Dict of CAM BRDF parameters (pcl, sal, u10).

Type:: dict[str, float] | None

bpdf_litvinov

Dict of Litvinov BPDF parameters.

Type:: dict[str, float] | None

bpdf_maignan

Dict of Maignan BPDF parameters.

Type:: dict[str, float] | None

bpdf_tsang_u10

Wind speed for Tsang BPDF (m/s).

Type:: float | None

albedo: float | None

albedo_file: str | None

albedo_library: str | None

albedo_map: str | tuple[str, str] | None

bpdf_litvinov: dict[str, float] | None

bpdf_maignan: dict[str, float] | None

bpdf_tsang_u10: float | None

brdf_ambrals: dict[str, float] | None

brdf_cam: dict[str, float] | None

brdf_hapke: dict[str, float] | None

brdf_rossli_file: str | None

brdf_rossli_hotspot: bool

brdf_rpv: dict[str, float] | None

brdf_rpv_file: str | None

check_mutual_exclusion() → SurfaceConfig[source]

model_config = {'extra': 'forbid', 'frozen': True, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

sur_temperature: float | None

surface_temperature_map: str | tuple[str, str, float] | None

surface_type_map: str | None

to_uvspec_items() → list[tuple[int, str]][source]

Return (phase, keyword_line) pairs for priority-sorted output.

Subclasses may override to assign different phases to different keywords. Default phase is 9 (output section).

to_uvspec_lines() → list[str][source]

Serialize this configuration to uvspec input file lines.

Returns:: List of strings, each being one line of a uvspec input file.

Cloud

Cloud configuration model (Phase 2).

Maps to uvspec keywords: ic_file, ic_properties, ic_habit, ic_habit_yang2013, ic_modify, wc_file, wc_properties, wc_modify, cloudcover, cloud_overlap.

Reference: libRadtran src/uvspec_lex.l (cloud options)

class pyradtran.models.cloud.CloudConfig(*, ic_properties: str | None = None, ic_file: tuple[str, str] | None=None, ic_habit: str | None = None, ic_habit_roughness: str | None = None, ic_modify: list[CloudModifyEntry] = <factory>, wc_properties: str | None = None, wc_file: tuple[str, str] | None=None, wc_modify: list[CloudModifyEntry] = <factory>, modify: list[CloudModifyEntry] = <factory>, cloud_cover_type: str | None = None, cloud_cover: Annotated[float | None, ~annotated_types.Ge(ge=0.0), ~annotated_types.Le(le=1.0)] = None, cloud_overlap: str | None = None, interpolate: bool = False, cloud_fraction_file: str | None = None, cloud_fraction_map: str | tuple[str, str, float] | None=None, wc_saturate: bool = False, ic_saturate: bool = False, wc_ipa: bool = False, wc_layer: Annotated[int | None, ~annotated_types.Ge(ge=0)] = None)[source]

Bases: UvspecOption

Cloud configuration for water and ice clouds.

ic_properties

Ice cloud optical property parameterization.

Type:: str | None

ic_file

Tuple of (dimension, path) for ice cloud external file.

Type:: tuple[str, str] | None

ic_habit

Ice crystal habit type.

Type:: str | None

ic_habit_roughness

Roughness for yang2013 (“smooth”, “moderate”, “severe”).

Type:: str | None

ic_modify

List of ice cloud modification directives.

Type:: list[CloudModifyEntry]

wc_properties

Water cloud optical property parameterization.

Type:: str | None

wc_file

Tuple of (dimension, path) for water cloud external file.

Type:: tuple[str, str] | None

wc_modify

List of water cloud modification directives.

Type:: list[CloudModifyEntry]

cloud_cover_type

Cloud type for cloud cover (“ic” or “wc”).

Type:: str | None

cloud_cover

Cloud cover fraction [0, 1].

Type:: float | None

cloud_overlap

Cloud overlap method.

Type:: str | None

interpolate

Append ‘interpolate’ to ic/wc_properties for spectral mode.

Type:: bool

cloud_cover: float | None

cloud_cover_type: str | None

cloud_fraction_file: str | None

cloud_fraction_map: str | tuple[str, str, float] | None

cloud_overlap: str | None

ic_file: tuple[str, str] | None

ic_habit: str | None

ic_habit_roughness: str | None

ic_modify: list[CloudModifyEntry]

ic_properties: str | None

ic_saturate: bool

interpolate: bool

model_config = {'extra': 'forbid', 'frozen': True, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

modify: list[CloudModifyEntry]

to_uvspec_items() → list[tuple[int, str]][source]

Return (phase, keyword_line) pairs for priority-sorted output.

Subclasses may override to assign different phases to different keywords. Default phase is 9 (output section).

to_uvspec_lines() → list[str][source]

Serialize this configuration to uvspec input file lines.

Returns:: List of strings, each being one line of a uvspec input file.

validate_cloud() → CloudConfig[source]

wc_file: tuple[str, str] | None

wc_ipa: bool

wc_layer: int | None

wc_modify: list[CloudModifyEntry]

wc_properties: str | None

wc_saturate: bool

class pyradtran.models.cloud.CloudModifyEntry(*, variable: str, action: str, value: float)[source]

Bases: UvspecOption

A single cloud modify directive (wc_modify or ic_modify).

action: str

model_config = {'extra': 'forbid', 'frozen': True, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

validate_entry() → CloudModifyEntry[source]

value: float

variable: str

Monte Carlo

Monte Carlo (MYSTIC) configuration model.

Maps to uvspec keywords: mc_photons, mc_backward, mc_escape, mc_vroom, mc_polarisation, mc_randomseed, mc_minphotons, mc_maxscatters, mc_spectral_is, mc_delta_scaling, mc_rad_alpha, mc_backward_output, mc_forward_output, mc_backward_heat, mc_std, mc_jacobian, mc_progressbar, mc_surface_reflectalways, mc_spherical, mc_tenstream, mc_ipa, mc_tipa, mc_sensordirection, mc_sensorposition, mc_spherical3D_scene, mc_basename, mc_minscatters, mc_sun_angular_size.

Reference: libRadtran src_py/mc_options.py

class pyradtran.models.mc.McConfig(*, photons: Annotated[int | None, Ge(ge=0)] = None, min_photons: Annotated[int | None, Ge(ge=0)] = None, backward: bool = False, backward_pixel_range: tuple[int, int, int, int] | None = None, escape: str | None = None, vroom: str | None = None, polarisation: bool = False, polarisation_state: Annotated[int | None, Ge(ge=-3), Le(le=4)] = None, random_seed: Annotated[int | None, Ge(ge=0), Le(le=1000000000000000)] = None, max_scatters: Annotated[int | None, Ge(ge=0)] = None, spectral_is: Annotated[float | None, Ge(ge=0), Le(le=1000000.0)] = None, delta_scaling_mucut: Annotated[float | None, Ge(ge=0.0), Le(le=1.0)] = None, delta_scaling_n_start: Annotated[int | None, Ge(ge=0)] = None, rad_alpha: Annotated[float | None, Ge(ge=0.0), Le(le=90.0)] = None, backward_output: str | None = None, backward_output_unit: str | None = None, forward_output: str | None = None, backward_heat: str | None = None, std: Annotated[float | None, Ge(ge=0.0)] = None, jacobian: str | None = None, jacobian_std: bool = False, progressbar: Annotated[int | None, Ge(ge=0), Le(le=3)] = None, surface_reflect_always: bool = False, photons_file: str | None = None, albedo_file: str | None = None, albedo_spectral_file: str | None = None, rossli_file: str | None = None, ambrals_spectral_file: str | None = None, rpv_spectral_file: str | None = None, bpdf: str | None = None, surface_parallel: bool = False, elevation_file: str | None = None, lidar_file: str | None = None, triangular_surface_file: str | None = None, spherical: str | None = None, tenstream: bool = False, ipa: bool = False, tipa: str | None = None, sensor_direction: tuple[float, float, float] | None = None, sensor_position: tuple[float, float, float] | None = None, spherical3d_scene: tuple[float, float, float, float] | None = None, basename: str | None = None, min_scatters: Annotated[int | None, Ge(ge=0)] = None, sun_angular_size: Annotated[float | None, Ge(ge=0.0), Le(le=10.0)] = None, relerr: Annotated[float | None, Ge(ge=0.0)] = None, coherent_backscatter: bool = False, nca: bool = False, aerosol_is: bool = False, bcond: str | None = None)[source]

Bases: UvspecOption

Monte Carlo (MYSTIC) solver configuration.

photons

Total number of photons to trace. Required for MYSTIC.

Type:: int | None

min_photons

Minimum photons per spectral band (correlated-k).

Type:: int | None

backward

Enable backward photon tracing. Required for most MC output.

Type:: bool

backward_pixel_range

Optional (ix_start, iy_start, ix_end, iy_end).

Type:: tuple[int, int, int, int] | None

escape

Calculate radiances via escape probabilities – “on” or “off”.

Type:: str | None

vroom

Variance Reduction Optimal Options Method – “on” or “off”.

Type:: str | None

polarisation

Enable polarisation calculations.

Type:: bool

polarisation_state

Initial Stokes vector (-3 to 4, default 0).

Type:: int | None

random_seed

Random seed for reproducibility.

Type:: int | None

max_scatters

Maximum scatters before photon destruction (testing).

Type:: int | None

spectral_is

Wavelength for spectral importance sampling.

Type:: float | None

delta_scaling_mucut

Truncation threshold for delta-M scaling.

Type:: float | None

delta_scaling_n_start

Stream number for delta-M scaling start.

Type:: int | None

rad_alpha

Opening angle for all-sky radiance (degrees).

Type:: float | None

backward_output

Output quantity for backward MC (e.g. “edn”).

Type:: str | None

backward_output_unit

Unit for backward MC output.

Type:: str | None

forward_output

Output quantity for forward MC (e.g. “heating”).

Type:: str | None

backward_heat

Thermal heating method – “HYBRID”, “EMABS”, etc.

Type:: str | None

std

Target standard deviation (stop when reached).

Type:: float | None

jacobian

Jacobian calculation mode – “1D” or “3D”.

Type:: str | None

jacobian_std

Calculate Jacobian standard deviation.

Type:: bool

progressbar

MC progress bar mode (0=off, 2, 3).

Type:: int | None

surface_reflect_always

Always reflect at surface, weight via albedo.

Type:: bool

photons_file

Path to photon distribution file.

Type:: str | None

spherical

3D geometry mode - “1D” or “3D”.

Type:: str | None

tenstream

Enable tenstream approximation.

Type:: bool

ipa

Importance photon acceleration.

Type:: bool

tipa

Tracked importance photon acceleration - “dir” or “dir3d”.

Type:: str | None

sensor_direction

Sensor viewing direction (dx, dy, dz).

Type:: tuple[float, float, float] | None

sensor_position

Sensor position (x, y, z).

Type:: tuple[float, float, float] | None

spherical3d_scene

Spherical 3D scene bounds (lon_min, lat_min, lon_max, lat_max).

Type:: tuple[float, float, float, float] | None

basename

Basename for output files.

Type:: str | None

min_scatters

Minimum number of scatters before stopping.

Type:: int | None

sun_angular_size

Sun angular size in degrees.

Type:: float | None

aerosol_is: bool

albedo_file: str | None

albedo_spectral_file: str | None

ambrals_spectral_file: str | None

backward: bool

backward_heat: str | None

backward_output: str | None

backward_output_unit: str | None

backward_pixel_range: tuple[int, int, int, int] | None

basename: str | None

bcond: str | None

bpdf: str | None

coherent_backscatter: bool

delta_scaling_mucut: float | None

delta_scaling_n_start: int | None

elevation_file: str | None

escape: str | None

forward_output: str | None

ipa: bool

jacobian: str | None

jacobian_std: bool

lidar_file: str | None

max_scatters: int | None

min_photons: int | None

min_scatters: int | None

model_config = {'extra': 'forbid', 'frozen': True, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

nca: bool

photons: int | None

photons_file: str | None

polarisation: bool

polarisation_state: int | None

progressbar: int | None

rad_alpha: float | None

random_seed: int | None

relerr: float | None

rossli_file: str | None

rpv_spectral_file: str | None

sensor_direction: tuple[float, float, float] | None

sensor_position: tuple[float, float, float] | None

spectral_is: float | None

spherical: str | None

spherical3d_scene: tuple[float, float, float, float] | None

std: float | None

sun_angular_size: float | None

surface_parallel: bool

surface_reflect_always: bool

tenstream: bool

tipa: str | None

to_uvspec_items() → list[tuple[int, str]][source]

Return (phase, keyword_line) pairs for priority-sorted output.

Subclasses may override to assign different phases to different keywords. Default phase is 9 (output section).

to_uvspec_lines() → list[str][source]

Serialize this configuration to uvspec input file lines.

Returns:: List of strings, each being one line of a uvspec input file.

triangular_surface_file: str | None

validate_mc() → McConfig[source]

vroom: str | None

SSLidar

SSLidar (Single Scattering Lidar) configuration model.

Maps to uvspec keywords: sslidar, sslidar_nranges, sslidar_polarisation.

Reference: libRadtran src_py/geometry_options.py, src_py/solver_options.py

class pyradtran.models.sslidar.SslidarConfig(*, area: Annotated[float | None, Ge(ge=0), Le(le=1000000.0)] = None, E0: Annotated[float | None, Ge(ge=0), Le(le=1000000.0)] = None, efficiency: Annotated[float | None, Ge(ge=0.0), Le(le=1.0)] = None, position: Annotated[float | None, Ge(ge=0), Le(le=1000000.0)] = None, range_bin: Annotated[float | None, Ge(ge=0), Le(le=1000000.0)] = None, n_ranges: Annotated[int | None, Ge(ge=1)] = None, polarisation: bool = False)[source]

Bases: UvspecOption

Single scattering lidar configuration.

Requires rte_solver sslidar.

area

Telescope area in m^2.

Type:: float | None

E0

Pulse energy in Joules.

Type:: float | None

efficiency

Detector efficiency.

Type:: float | None

position

Lidar position above ground in km.

Type:: float | None

range_bin

Range bin width in km.

Type:: float | None

n_ranges

Number of range bins.

Type:: int | None

polarisation

Enable polarisation measurement.

Type:: bool

E0: float | None

area: float | None

efficiency: float | None

model_config = {'extra': 'forbid', 'frozen': True, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

n_ranges: int | None

polarisation: bool

position: float | None

range_bin: float | None

to_uvspec_items() → list[tuple[int, str]][source]

Return (phase, keyword_line) pairs for priority-sorted output.

Subclasses may override to assign different phases to different keywords. Default phase is 9 (output section).

to_uvspec_lines() → list[str][source]

Serialize this configuration to uvspec input file lines.

Returns:: List of strings, each being one line of a uvspec input file.

3D Fields

3D atmosphere and cloud configuration model.

Maps to uvspec keywords: atmosphere_file (3D NetCDF fields).

Note: 3D cloud fields are specified via CloudConfig using wc_file=(“3D”, path) or ic_file=(“3D”, path), not through a separate keyword. The ipa_3d and output3D flags are set automatically by uvspec when tipa or MYSTIC is enabled.

Reference: libRadtran src/uvspec_lex.l (MYSTIC 3D options)

class pyradtran.models.three_d.ThreeDConfig(*, atmosphere_file: str | None = None)[source]

Bases: UvspecOption

3D atmospheric field configuration.

Configures 3D atmospheric input fields for MYSTIC and dynamic tenstream solvers.

atmosphere_file

Path to 3D atmospheric field NetCDF file.

Type:: str | None

Note

3D cloud fields are specified through CloudConfig: scene.set_cloud(wc_file=(“3D”, “/path/to/cloud3d.nc”)) or scene.set_cloud(ic_file=(“3D”, “/path/to/ic3d.nc”)).

The ipa (independent pixel approximation) for 3D is enabled via McConfig.ipa=True or McConfig.tipa=”dir”/”dir3d”.

atmosphere_file: str | None

model_config = {'extra': 'forbid', 'frozen': True, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

to_uvspec_items() → list[tuple[int, str]][source]

Return (phase, keyword_line) pairs for priority-sorted output.

Subclasses may override to assign different phases to different keywords. Default phase is 9 (output section).

to_uvspec_lines() → list[str][source]

Serialize this configuration to uvspec input file lines.

Returns:: List of strings, each being one line of a uvspec input file.

Advanced

Advanced options model.

Maps to uvspec keywords: fluorescence, fluorescence_file, raman.

Phase 3 scope. Phase 4 may add 3D, satellite geometry, dynamic solvers, etc.

Reference: libRadtran src_py/surface_options.py, src_py/solver_options.py

class pyradtran.models.advanced.AdvancedConfig(*, fluorescence: Annotated[float | None, Ge(ge=0.0)] = None, fluorescence_file: str | None = None, raman: bool = False, raman_variant: str | None = None)[source]

Bases: UvspecOption

Advanced radiative transfer options.

fluorescence

Isotropic surface fluorescence emission (W/m^2/nm).

Type:: float | None

fluorescence_file

Path to wavelength-dependent fluorescence file. Mutually exclusive with fluorescence.

Type:: str | None

raman

Enable first-order rotational Raman scattering. Requires rte_solver disort.

Type:: bool

raman_variant

Raman variant – “original” (default: standard).

Type:: str | None

fluorescence: float | None

fluorescence_file: str | None

model_config = {'extra': 'forbid', 'frozen': True, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

raman: bool

raman_variant: str | None

to_uvspec_items() → list[tuple[int, str]][source]

Return (phase, keyword_line) pairs for priority-sorted output.

Subclasses may override to assign different phases to different keywords. Default phase is 9 (output section).

to_uvspec_lines() → list[str][source]

Serialize this configuration to uvspec input file lines.

Returns:: List of strings, each being one line of a uvspec input file.

validate_advanced() → AdvancedConfig[source]

Special

Special options model for scattering/absorption control and file includes.

Maps to uvspec keywords: no_absorption, no_scattering, no_scattering mol, include.

Reference: libRadtran src/uvspec_lex.l

class pyradtran.models.special.SpecialConfig(*, no_absorption: bool = False, no_scattering: bool = False, no_scattering_mol: bool = False, include_files: list[str] = <factory>)[source]

Bases: UvspecOption

Special options: scattering/absorption toggles and include files.

no_absorption

Disable all absorption.

Type:: bool

no_scattering

Disable all scattering.

Type:: bool

no_scattering_mol

Disable molecular scattering only.

Type:: bool

include_files

Paths to additional input files to include (Phase 0).

Type:: list[str]

include_files: list[str]

model_config = {'extra': 'forbid', 'frozen': True, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

no_absorption: bool

no_scattering: bool

no_scattering_mol: bool

to_uvspec_lines() → list[str][source]

Serialize this configuration to uvspec input file lines.

Returns:: List of strings, each being one line of a uvspec input file.

validate_scattering() → SpecialConfig[source]

Aerosol Models

Standard Aerosol

Aerosol configuration models.

Provides a strict class hierarchy for aerosol configuration:

OpacPreset: OPAC preset mixture profiles (continental_average, maritime_clean, etc.)
OpacCustom: OPAC custom species profile files
ExternalAerosol: External optical property files (explicit, gg, ssa, tau, moments)

Reference: libRadtran src/uvspec_lex.l (aerosol options) Reference: Hess et al. (1998), Bull. Amer. Meteor. Soc., 79, 831-844

class pyradtran.models.aerosol.AerosolModel(*, set_tau_at_wvl: tuple[float, float] | None=None, king_byrne: tuple[float, float, float] | None=None, modify: list[AerosolModifyEntry] = <factory>)[source]

Bases: UvspecOption

Abstract base class for all aerosol configurations.

Subclasses implement mode-specific to_uvspec_lines(). Common capabilities (set_tau_at_wvl, king_byrne, modify) are handled here.

king_byrne: tuple[float, float, float] | None

model_config = {'extra': 'forbid', 'frozen': True, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

modify: list[AerosolModifyEntry]

set_tau_at_wvl: tuple[float, float] | None

to_uvspec_items() → list[tuple[int, str]][source]

Return (phase, keyword_line) pairs for priority-sorted output.

Subclasses may override to assign different phases to different keywords. Default phase is 9 (output section).

abstractmethod to_uvspec_lines() → list[str][source]

Serialize this configuration to uvspec input file lines.

Returns:: List of strings, each being one line of a uvspec input file.

class pyradtran.models.aerosol.AerosolModifyEntry(*, variable: str, action: str, value: float)[source]

Bases: UvspecOption

A single aerosol_modify directive.

variable

Property to modify (gg, ssa, tau, tau550).

Type:: str

action

How to modify (scale or set).

Type:: str

value

Numeric value.

Type:: float

action: str

model_config = {'extra': 'forbid', 'frozen': True, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

validate_entry() → AerosolModifyEntry[source]

value: float

variable: str

pyradtran.models.aerosol.ExternalAerosol: alias of ExternalFile

class pyradtran.models.aerosol.ExternalFile(*, set_tau_at_wvl: tuple[float, float] | None = None, king_byrne: tuple[float, float, float] | None = None, modify: list[~pyradtran.models.aerosol.AerosolModifyEntry] = <factory>, files: ~typing.Annotated[list[tuple[str, str]], ~annotated_types.MinLen(min_length=1)])[source]

Bases: AerosolModel

External aerosol optical property files.

files

List of (file_type, file_path) tuples. Types: “gg”, “ssa”, “tau”, “explicit”, “moments”, “ref”, “siz”.

Type:: list[tuple[str, str]]

files: list[tuple[str, str]]

model_config = {'extra': 'forbid', 'frozen': True, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

to_uvspec_lines() → list[str][source]

Serialize this configuration to uvspec input file lines.

Returns:: List of strings, each being one line of a uvspec input file.

validate_files() → ExternalFile[source]

class pyradtran.models.aerosol.OpacCustom(*, set_tau_at_wvl: tuple[float, float] | None = None, king_byrne: tuple[float, float, float] | None = None, modify: list[~pyradtran.models.aerosol.AerosolModifyEntry] = <factory>, species_file: ~typing.Annotated[str, ~annotated_types.MinLen(min_length=1)], species_names: list[str] | None = None, library: str = 'OPAC')[source]

Bases: AerosolModel

OPAC custom species profile aerosol.

Uses a user-provided mass concentration profile file with the OPAC library.

species_file

Path to an ASCII profile file.

Type:: str

library

OPAC library path or “OPAC” for default resolution.

Type:: str

species_names

Optional species filter.

Type:: list[str] | None

library: str

model_config = {'extra': 'forbid', 'frozen': True, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

species_file: str

species_names: list[str] | None

to_uvspec_lines() → list[str][source]

Serialize this configuration to uvspec input file lines.

Returns:: List of strings, each being one line of a uvspec input file.

validate_species() → OpacCustom[source]

class pyradtran.models.aerosol.OpacPreset(*, set_tau_at_wvl: tuple[float, float] | None=None, king_byrne: tuple[float, float, float] | None=None, modify: list[AerosolModifyEntry] = <factory>, name: OpacPresetName, library: str = 'OPAC', species_names: list[str] | None = None)[source]

Bases: AerosolModel

OPAC preset mixture profile aerosol.

Uses pre-defined aerosol species mixture profiles from the OPAC library. The name selects from 10 predefined mixture profiles. Optionally filter to specific species via species_names.

name

Preset mixture profile name.

Type:: OpacPresetName

library

OPAC library path or “OPAC” for uvspec default resolution.

Type:: str

species_names

Optional species filter (e.g. [“inso”, “soot”]).

Type:: list[str] | None

library: str

model_config = {'extra': 'forbid', 'frozen': True, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

name: OpacPresetName

species_names: list[str] | None

to_uvspec_lines() → list[str][source]

Serialize this configuration to uvspec input file lines.

Returns:: List of strings, each being one line of a uvspec input file.

validate_species() → OpacPreset[source]

class pyradtran.models.aerosol.OpacPresetName(value)[source]

Bases: str, Enum

OPAC preset mixture profile names.

These correspond to files in data/aerosol/OPAC/standard_aerosol_files/.

ANTARCTIC = 'antarctic'

CONTINENTAL_AVERAGE = 'continental_average'

CONTINENTAL_CLEAN = 'continental_clean'

CONTINENTAL_POLLUTED = 'continental_polluted'

DESERT = 'desert'

DESERT_SPHEROIDS = 'desert_spheroids'

MARITIME_CLEAN = 'maritime_clean'

MARITIME_POLLUTED = 'maritime_polluted'

MARITIME_TROPICAL = 'maritime_tropical'

URBAN = 'urban'

Composite Aerosol

Composable aerosol optical-property models (Tier 1–4).

See design spec: docs/superpowers/specs/2026-04-27-composite-aerosol-design.md

class pyradtran.models.aerosol_composite.CompositeAerosol(*, set_tau_at_wvl: tuple[float, float] | None = None, king_byrne: tuple[float, float, float] | None = None, modify: list[~pyradtran.models.aerosol.AerosolModifyEntry] = <factory>, sources: ~typing.Annotated[list, ~annotated_types.MinLen(min_length=1)], wavelength_grid_um: ~typing.Annotated[list[float], ~annotated_types.MinLen(min_length=1)], altitude_grid_km: ~typing.Annotated[list[float], ~annotated_types.MinLen(min_length=2)], n_legendre: int = 32, output_dir: ~pathlib.Path | None = None)[source]

Bases: AerosolModel

Tier 4: composite aerosol scene mixing multiple sources.

altitude_grid_km: list[float]

model_config = {'extra': 'forbid', 'frozen': True, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

n_legendre: int

output_dir: Path | None

sources: list

to_uvspec_lines() → list[str][source]

Generate aerosol_file explicit <master> line.

For single preset/external sources, delegates directly to their to_uvspec_lines() to avoid the explicit-file overhead.

validate_grids() → CompositeAerosol[source]

wavelength_grid_um: list[float]

class pyradtran.models.aerosol_composite.IntegrationConfig(*, n_radius_grid: int = 200, radius_min_um: float = 0.001, radius_max_um: float = 100.0)[source]

Bases: BaseModel

Configuration for size-distribution numerical integration.

model_config = {'extra': 'forbid', 'frozen': True, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

n_radius_grid: int

radius_max_um: float

radius_min_um: float

class pyradtran.models.aerosol_composite.LayerOptics(tau: ndarray[tuple[Any, ...], dtype[_ScalarT]], ssa: ndarray[tuple[Any, ...], dtype[_ScalarT]], g: ndarray[tuple[Any, ...], dtype[_ScalarT]], legendre_moments: ndarray[tuple[Any, ...], dtype[_ScalarT]])[source]

Bases: object

Extensive optical properties per layer.

g: ndarray[tuple[Any, ...], dtype[_ScalarT]]

legendre_moments: ndarray[tuple[Any, ...], dtype[_ScalarT]]

ssa: ndarray[tuple[Any, ...], dtype[_ScalarT]]

tau: ndarray[tuple[Any, ...], dtype[_ScalarT]]

class pyradtran.models.aerosol_composite.LoadedSpecies(*, species: MieSpecies | PrecomputedSpecies | OPACSpecies, mass_profile_kg_m3: Annotated[list[float], MinLen(min_length=1)], altitude_km: Annotated[list[float], MinLen(min_length=2)], rh_profile: list[float] | None = None)[source]

Bases: BaseModel

Tier 3: extensive in-atmosphere optical properties.

altitude_km: list[float]

evaluate(wl_um: ndarray, z_km: ndarray, n_legendre: int = 32) → LayerOptics[source]

Evaluate optical properties on (wavelength, altitude) grid.

Parameters:

wl_um – Wavelength grid in um, strictly ascending.
z_km – Altitude grid in km, strictly descending (layer centers or boundaries).
n_legendre – Number of Legendre moments.

Returns:

LayerOptics with shape (n_wl, n_layer).

mass_profile_kg_m3: list[float]

model_config = {'extra': 'forbid', 'frozen': True, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

rh_profile: list[float] | None

species: MieSpecies | PrecomputedSpecies | OPACSpecies

validate_profiles() → LoadedSpecies[source]

class pyradtran.models.aerosol_composite.MieSpecies(*, refractive_index: ~pyradtran.models.aerosol_composite.RefractiveIndex, size_distribution: ~pyradtran.models.aerosol_composite.SizeDistribution, particle_density_kg_m3: ~typing.Annotated[float, ~annotated_types.Gt(gt=0)], integration_config: ~pyradtran.models.aerosol_composite.IntegrationConfig = <factory>)[source]

Bases: BaseModel

Mie-computed species from refractive index + size distribution.

integration_config: IntegrationConfig

intensive(wl_um: ndarray, n_legendre: int = 32) → SpeciesOptics[source]

Compute mass-normalized intensive optical properties.

Parameters:

wl_um – Wavelengths in micrometers.
n_legendre – Number of Legendre moments to generate. Because the bhmie() path does not compute angular scattering by default, moments are derived from the Henyey-Greenstein phase function rather than a full Mie phase function.

Returns:

SpeciesOptics with beta_ext_per_mass, ssa, g, and legendre_moments.

model_config = {'extra': 'forbid', 'frozen': True, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

particle_density_kg_m3: float

refractive_index: RefractiveIndex

size_distribution: SizeDistribution

class pyradtran.models.aerosol_composite.OPACSpecies(*, netcdf_path: Annotated[str, MinLen(min_length=1)], wavelength_nm: float | None = None)[source]

Bases: BaseModel

OPAC species from a pre-computed libRadtran netCDF optical-property file.

The netCDF file is expected to contain output_dtauc, output_ssalb, and output_pmom variables (libRadtran write_optical_properties format).

intensive(wl_um: ndarray, n_legendre: int = 32) → SpeciesOptics[source]

Read netCDF and return intensive properties.

For a netCDF with nlyr layers, the returned beta_ext_per_mass assumes the optical depth is distributed uniformly across layers for the purpose of SpeciesOptics (the actual layer geometry is applied later in LoadedSpecies).

model_config = {'extra': 'forbid', 'frozen': True, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

netcdf_path: str

wavelength_nm: float | None

class pyradtran.models.aerosol_composite.ParticleOptics(*, wavelength_um: Annotated[list[float], MinLen(min_length=1)], radius_um: Annotated[list[float], MinLen(min_length=1)], Qext: ndarray[tuple[Any, ...], dtype[_ScalarT]], Qsca: ndarray[tuple[Any, ...], dtype[_ScalarT]], g: ndarray[tuple[Any, ...], dtype[_ScalarT]], legendre_moments: ndarray[tuple[Any, ...], dtype[_ScalarT]] | None = None)[source]

Bases: BaseModel

Single-particle optical properties vs wavelength and radius.

Qext: NDArray

Qsca: NDArray

classmethod from_aerosol3d(data) → ParticleOptics[source]

Create ParticleOptics from Aerosol3D AerosolOpticsData.

Handles unit conversion (nm -> um, nm^2 -> um^2) and Legendre convention (prefers beta_l, falls back to k_l conversion).

Parameters:: data – Object with wavelength_nm, C_ext, C_sca, g, r_eff_nm, n_legendre, legendre_moments_beta, legendre_moments fields.
Returns:: ParticleOptics ready for use in PrecomputedSpecies.

classmethod from_cross_sections(*, wavelength_um: list[float], radius_um: list[float], Cext_um2: ndarray[tuple[Any, ...], dtype[_ScalarT]], Csca_um2: ndarray[tuple[Any, ...], dtype[_ScalarT]], g: ndarray[tuple[Any, ...], dtype[_ScalarT]], legendre_moments: ndarray[tuple[Any, ...], dtype[_ScalarT]] | None = None) → ParticleOptics[source]: Build from cross-sections (convert to Q-factors).

g: NDArray

legendre_moments: NDArray | None

model_config = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'frozen': True, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

radius_um: list[float]

validate_shapes() → ParticleOptics[source]

wavelength_um: list[float]

class pyradtran.models.aerosol_composite.PrecomputedSpecies(*, particle_optics: ~pyradtran.models.aerosol_composite.ParticleOptics, size_distribution: ~pyradtran.models.aerosol_composite.SizeDistribution, particle_density_kg_m3: ~typing.Annotated[float, ~annotated_types.Gt(gt=0)], integration_config: ~pyradtran.models.aerosol_composite.IntegrationConfig = <factory>)[source]

Bases: BaseModel

Species from precomputed ParticleOptics + size distribution.

integration_config: IntegrationConfig

intensive(wl_um: ndarray, n_legendre: int = 32) → SpeciesOptics[source]: Integrate precomputed Q-factors over size distribution.

model_config = {'extra': 'forbid', 'frozen': True, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

particle_density_kg_m3: float

particle_optics: ParticleOptics

size_distribution: SizeDistribution

class pyradtran.models.aerosol_composite.RefractiveIndex(*, wavelength_um: Annotated[list[float], MinLen(min_length=2)], n_real: list[float], k_imag: Annotated[list[float], MinLen(min_length=1)])[source]

Bases: BaseModel

Wavelength-dependent complex refractive index.

Interpolation is log-linear in wavelength.

at(wl_um: ndarray) → ndarray[source]: Interpolate refractive index to requested wavelengths.

k_imag: list[float]

model_config = {'extra': 'forbid', 'frozen': True, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

n_real: list[float]

validate_lengths_and_sorted() → RefractiveIndex[source]

wavelength_um: list[float]

class pyradtran.models.aerosol_composite.SizeDistribution(*, kind: Literal['lognormal', 'modified_gamma', 'discrete', 'monodisperse'], params: dict, number_density_per_m3: float = 1.0)[source]

Bases: BaseModel

Aerosol particle size distribution.

evaluate(r_grid_um: ndarray) → ndarray[source]

kind: Literal['lognormal', 'modified_gamma', 'discrete', 'monodisperse']

model_config = {'extra': 'forbid', 'frozen': True, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

number_density_per_m3: float

params: dict

validate_params() → SizeDistribution[source]

class pyradtran.models.aerosol_composite.Species(*args, **kwargs)[source]

Bases: Protocol

Protocol for Tier 2 species classes.

intensive(wl_um: ndarray, n_legendre: int = 32) → SpeciesOptics[source]

class pyradtran.models.aerosol_composite.SpeciesOptics(beta_ext_per_mass: ndarray[tuple[Any, ...], dtype[_ScalarT]], ssa: ndarray[tuple[Any, ...], dtype[_ScalarT]], g: ndarray[tuple[Any, ...], dtype[_ScalarT]], legendre_moments: ndarray[tuple[Any, ...], dtype[_ScalarT]] | None = None)[source]

Bases: object

Mass-normalized intensive optical properties of an aerosol species.

beta_ext_per_mass: ndarray[tuple[Any, ...], dtype[_ScalarT]]

g: ndarray[tuple[Any, ...], dtype[_ScalarT]]

legendre_moments: ndarray[tuple[Any, ...], dtype[_ScalarT]] | None = None

ssa: ndarray[tuple[Any, ...], dtype[_ScalarT]]

Aerosol Optics

Presets

Site altitudes, standard atmosphere profiles, and common configurations.

pyradtran.presets.resolve_altitude(altitude: float | str) → float[source]: Resolve altitude – accepts km float or site preset name.