API Reference

Main Classes

class DisortOptions
accur(*args, **kwargs)

Overloaded function.

  1. accur(self: disort.DisortOptions) -> float

Set or get accuracy for disort

Parameters:

accur (float, optional) – accuracy for disort

Returns:

class object if argument is not empty, otherwise the accuracy

Return type:

pydisort.DisortOptions | float

Examples:

>>> import pydisort
>>> op = pydisort.DisortOptions().accur(1.e-6)
>>> print(op)

  1. accur(self: disort.DisortOptions, arg0: float) -> disort.DisortOptions

Set or get accuracy for disort

Parameters:

accur (float, optional) – accuracy for disort

Returns:

class object if argument is not empty, otherwise the accuracy

Return type:

pydisort.DisortOptions | float

Examples:

>>> import pydisort
>>> op = pydisort.DisortOptions().accur(1.e-6)
>>> print(op)
ds(*args, **kwargs)

Overloaded function.

  1. ds(self: disort.DisortOptions) -> disort.disort_state

Set disort state for disort

Parameters:

ds (pydisort.disort_state, optional) – disort state for disort

Returns:

class object if argument is not empty, otherwise the disort state

Return type:

pydisort.DisortOptions | pydisort.disort_state

Examples:

>>> import pydisort
>>> op = pydisort.DisortOptions()
>>> op.ds().nlyr, op.ds().nstr, op.ds().nmom = 10, 4, 4
>>> print(op)

  1. ds(self: disort.DisortOptions, arg0: disort.disort_state) -> disort.DisortOptions

Set disort state for disort

Parameters:

ds (pydisort.disort_state, optional) – disort state for disort

Returns:

class object if argument is not empty, otherwise the disort state

Return type:

pydisort.DisortOptions | pydisort.disort_state

Examples:

>>> import pydisort
>>> op = pydisort.DisortOptions()
>>> op.ds().nlyr, op.ds().nstr, op.ds().nmom = 10, 4, 4
>>> print(op)
flags(*args, **kwargs)

Overloaded function.

  1. flags(self: disort.DisortOptions) -> str

Set or get radiation flags for disort

Parameters:

flags (str, optional) – radiation flags for disort

Returns:

class object if argument is not empty, otherwise the flags

Return type:

pydisort.DisortOptions | str

Examples:

>>> import pydisort
>>> op = pydisort.DisortOptions().flags('onlyfl')
>>> print(op)

  1. flags(self: disort.DisortOptions, arg0: str) -> disort.DisortOptions

Set or get radiation flags for disort

Parameters:

flags (str, optional) – radiation flags for disort

Returns:

class object if argument is not empty, otherwise the flags

Return type:

pydisort.DisortOptions | str

Examples:

>>> import pydisort
>>> op = pydisort.DisortOptions().flags('onlyfl')
>>> print(op)
header(*args, **kwargs)

Overloaded function.

  1. header(self: disort.DisortOptions) -> str

Set or get header for disort

Parameters:

header (str, optional) – header for disort

Returns:

class object if argument is not empty, otherwise the header

Return type:

pydisort.DisortOptions | str

Examples:

>>> import pydisort
>>> op = pydisort.DisortOptions().header('Test run')
>>> print(op)

  1. header(self: disort.DisortOptions, arg0: str) -> disort.DisortOptions

Set or get header for disort

Parameters:

header (str, optional) – header for disort

Returns:

class object if argument is not empty, otherwise the header

Return type:

pydisort.DisortOptions | str

Examples:

>>> import pydisort
>>> op = pydisort.DisortOptions().header('Test run')
>>> print(op)
ncol(*args, **kwargs)

Overloaded function.

  1. ncol(self: disort.DisortOptions) -> int

Set or get number of columns for disort

Usage:

  • ncol() -> int

  • ncol(ncol: int) -> DisortOptions

Parameters:

ncol (int, optional) – number of columns for disort

Returns:

class object if argument is not empty, otherwise the number of columns

Return type:

pydisort.DisortOptions | int

Examples:

>>> import pydisort
>>> op = pydisort.DisortOptions().ncol(10)
>>> print(op)

  1. ncol(self: disort.DisortOptions, arg0: int) -> disort.DisortOptions

Set or get number of columns for disort

Usage:

  • ncol() -> int

  • ncol(ncol: int) -> DisortOptions

Parameters:

ncol (int, optional) – number of columns for disort

Returns:

class object if argument is not empty, otherwise the number of columns

Return type:

pydisort.DisortOptions | int

Examples:

>>> import pydisort
>>> op = pydisort.DisortOptions().ncol(10)
>>> print(op)
nwave(*args, **kwargs)

Overloaded function.

  1. nwave(self: disort.DisortOptions) -> int

Set or get number of wavelengths for disort

Parameters:

nwave (int, optional) – number of wavelengths for disort

Returns:

class object if argument is not empty, otherwise the number of wavelengths

Return type:

pydisort.DisortOptions | int

Examples:

>>> import pydisort
>>> op = pydisort.DisortOptions().nwave(10)
>>> print(op)

  1. nwave(self: disort.DisortOptions, arg0: int) -> disort.DisortOptions

Set or get number of wavelengths for disort

Parameters:

nwave (int, optional) – number of wavelengths for disort

Returns:

class object if argument is not empty, otherwise the number of wavelengths

Return type:

pydisort.DisortOptions | int

Examples:

>>> import pydisort
>>> op = pydisort.DisortOptions().nwave(10)
>>> print(op)
upward(*args, **kwargs)

Overloaded function.

  1. upward(self: disort.DisortOptions) -> int

Set or get direction for disort

Parameters:

upward (int, optional) – direction for disort

Returns:

class object if argument is not empty, otherwise the direction

Return type:

pydisort.DisortOptions | int

Examples:

>>> import pydisort
>>> op = pydisort.DisortOptions().upward(true)
>>> print(op)

  1. upward(self: disort.DisortOptions, arg0: int) -> disort.DisortOptions

Set or get direction for disort

Parameters:

upward (int, optional) – direction for disort

Returns:

class object if argument is not empty, otherwise the direction

Return type:

pydisort.DisortOptions | int

Examples:

>>> import pydisort
>>> op = pydisort.DisortOptions().upward(true)
>>> print(op)
user_mu(*args, **kwargs)

Overloaded function.

  1. user_mu(self: disort.DisortOptions) -> list[float]

Set or get user zenith angles for disort

Parameters:

user_mu (list[float], optional) – user zenith angles for disort

Returns:

class object if argument is not empty, otherwise the user zenith angles

Return type:

pydisort.DisortOptions | list[float]

Examples:

>>> import pydisort
>>> op = pydisort.DisortOptions().user_mu([0.1, 0.2, 0.3])
>>> print(op)

  1. user_mu(self: disort.DisortOptions, arg0: list[float]) -> disort.DisortOptions

Set or get user zenith angles for disort

Parameters:

user_mu (list[float], optional) – user zenith angles for disort

Returns:

class object if argument is not empty, otherwise the user zenith angles

Return type:

pydisort.DisortOptions | list[float]

Examples:

>>> import pydisort
>>> op = pydisort.DisortOptions().user_mu([0.1, 0.2, 0.3])
>>> print(op)
user_phi(*args, **kwargs)

Overloaded function.

  1. user_phi(self: disort.DisortOptions) -> list[float]

Set or get user azimuthal angles for disort

Parameters:

user_phi (list[float], optional) – user azimuthal angles for disort

Returns:

object

Return type:

pydisort.DisortOptions | list[float]

Examples:

>>> import pydisort
>>> op = pydisort.DisortOptions().user_phi([0.1, 0.2, 0.3])
>>> print(op)

  1. user_phi(self: disort.DisortOptions, arg0: list[float]) -> disort.DisortOptions

Set or get user azimuthal angles for disort

Parameters:

user_phi (list[float], optional) – user azimuthal angles for disort

Returns:

object

Return type:

pydisort.DisortOptions | list[float]

Examples:

>>> import pydisort
>>> op = pydisort.DisortOptions().user_phi([0.1, 0.2, 0.3])
>>> print(op)
user_tau(*args, **kwargs)

Overloaded function.

  1. user_tau(self: disort.DisortOptions) -> list[float]

Set or get user optical depths for disort

Parameters:

user_tau (list[float], optional) – user optical depths for disort

Returns:

class object if argument is not empty, otherwise the user optical depths

Return type:

pydisort.DisortOptions | list[float]

Examples:

>>> import pydisort
>>> op = pydisort.DisortOptions().user_tau([0.1, 0.2, 0.3])
>>> print(op)

  1. user_tau(self: disort.DisortOptions, arg0: list[float]) -> disort.DisortOptions

Set or get user optical depths for disort

Parameters:

user_tau (list[float], optional) – user optical depths for disort

Returns:

class object if argument is not empty, otherwise the user optical depths

Return type:

pydisort.DisortOptions | list[float]

Examples:

>>> import pydisort
>>> op = pydisort.DisortOptions().user_tau([0.1, 0.2, 0.3])
>>> print(op)
wave_lower(*args, **kwargs)

Overloaded function.

  1. wave_lower(self: disort.DisortOptions) -> list[float]

Set or get lower wavenumber(length) at each bin for disort

Parameters:

wave_lower (list[float], optional) – lower wavenumber(length) at each bin for disort

Returns:

class object if argument is not empty, otherwise the lower wavenumber(length) at each bin

Return type:

pydisort.DisortOptions | list[float]

Examples:

>>> import pydisort
>>> op = pydisort.DisortOptions().wave_lower([0.1, 0.2, 0.3])
>>> print(op)

  1. wave_lower(self: disort.DisortOptions, arg0: list[float]) -> disort.DisortOptions

Set or get lower wavenumber(length) at each bin for disort

Parameters:

wave_lower (list[float], optional) – lower wavenumber(length) at each bin for disort

Returns:

class object if argument is not empty, otherwise the lower wavenumber(length) at each bin

Return type:

pydisort.DisortOptions | list[float]

Examples:

>>> import pydisort
>>> op = pydisort.DisortOptions().wave_lower([0.1, 0.2, 0.3])
>>> print(op)
wave_upper(*args, **kwargs)

Overloaded function.

  1. wave_upper(self: disort.DisortOptions) -> list[float]

Set or get upper wavenumber(length) at each bin for disort

Parameters:

wave_upper (list[float], optional) – upper wavenumber(length) at each bin for disort

Returns:

class object if argument is not empty, otherwise the upper wavenumber(length) at each bin

Return type:

pydisort.DisortOptions | list[float]

Examples:

>>> import pydisort
>>> op = pydisort.DisortOptions().wave_upper([0.1, 0.2, 0.3])
>>> print(op)

  1. wave_upper(self: disort.DisortOptions, arg0: list[float]) -> disort.DisortOptions

Set or get upper wavenumber(length) at each bin for disort

Parameters:

wave_upper (list[float], optional) – upper wavenumber(length) at each bin for disort

Returns:

class object if argument is not empty, otherwise the upper wavenumber(length) at each bin

Return type:

pydisort.DisortOptions | list[float]

Examples:

>>> import pydisort
>>> op = pydisort.DisortOptions().wave_upper([0.1, 0.2, 0.3])
>>> print(op)
class Disort
forward(*args, **kwargs)

Overloaded function.

  1. forward(self: disort.cpp.Disort, arg0: torch.Tensor, arg1: dict[str, torch.Tensor], arg2: str, arg3: Optional[torch.Tensor]) -> torch.Tensor

  2. forward(self: disort.cpp.Disort, prop: torch.Tensor, bname: str = ‘’, temf: Optional[torch.Tensor] = None, **kwargs) -> torch.Tensor

Calculate radiative flux or intensity

The dimensions of each recognized key in kwargs are:

Key

Shape

Description

<band> + “umu0”

(ncol,)

cosine of solar zenith angle

<band> + “phi0”

(ncol,)

azimuthal angle of solar beam

<band> + “fbeam”

(nwave, ncol)

solar beam flux

<band> + “albedo”

(nwave, ncol)

surface albedo

<band> + “fluor”

(nwave, ncol)

isotropic bottom illumination

<band> + “fisot”

(nwave, ncol)

isotropic top illumination

<band> + “temis”

(nwave, ncol)

top emissivity

“btemp”

(ncol,)

bottom temperature

“ttemp”

(ncol,)

top temperature

Some keys can have a prefix band name, <band>. If the prefix is an non-empty string, a slash “/” is automatically appended to it, such that the key looks like B1/umu0. btemp and ttemp do not have a band name prefix. If the values are short of wave or column dimensions, they are automatically broadcasted to be the shape of 1.

Parameters:

  • prop (torch.Tensor) – Optical properties at each level (nwave, ncol, nlyr, nprop)

  • bname (str) – Name of the radiation band, default is empty string. If the name is not empty, a slash “/” is automatically appended to it.

  • temf (Optional[torch.Tensor]) – Temperature at each level (ncol, nlvl = nlyr + 1), default is None. If not None, the temperature is used to calculate the Planck function.

  • kwargs (Dict[str, torch.Tensor]) – keyword arguments of disort boundary conditions, see keys listed above

Returns:

Radiative flux or intensity, shape (nwave, ncol, nlvl, nrad)

Return type:

torch.Tensor

Examples

>>> import torch
>>> from pydisort import DisortOptions, Disort
>>> op = DisortOptions().flags("onlyfl,lamber")
>>> op.ds().nlyr = 4
>>> op.ds().nstr = 4
>>> op.ds().nmom = 4
>>> op.ds().nphase = 4
>>> ds = Disort(op)
>>> tau = torch.tensor([0.1, 0.2, 0.3, 0.4]).unsqueeze(-1)
>>> flx = ds.forward(tau, fbeam=torch.tensor([3.14159]))
>>> flx
tensor([[[[0.0000, 3.1416],
        [0.0000, 2.8426],
        [0.0000, 2.3273],
        [0.0000, 1.7241],
        [0.0000, 1.1557]]]])
gather_flx(self: disort.cpp.Disort) → torch.Tensor

Gather all disort flux outputs

Returns:

Disort flux outputs (nwave, ncol, nlvl = nlyr + 1, 8)

Return type:

torch.Tensor

Examples

>>> import torch
>>> from pydisort import DisortOptions, Disort
>>> op = DisortOptions().flags("onlyfl,lamber")
>>> op.ds().nlyr = 4
>>> op.ds().nstr = 4
>>> op.ds().nmom = 4
>>> op.ds().nphase = 4
>>> ds = Disort(op)
>>> tau = torch.tensor([0.1, 0.2, 0.3, 0.4]).unsqueeze(-1)
>>> flx = ds.forward(tau, fbeam=torch.tensor([3.14159]))
>>> ds.gather_flx()
gather_rad(self: disort.cpp.Disort) → torch.Tensor

Gather all disort radiation outputs

Returns:

Disort radiation outputs (nwave, ncol, nlvl = nlyr + 1, 6)

Return type:

torch.Tensor

Examples

>>> import torch
>>> import numpy as np
>>> from pydisort import DisortOptions, Disort, scattering_moments
>>> op = DisortOptions().flags("usrtau,usrang,lamber,print-input")
>>> op.ds().nlyr = 1
>>> op.ds().nstr = 16
>>> op.ds().nmom = 16
>>> op.ds().nphase = 16
>>> op.user_tau(np.array([0.0, 0.03125]))
>>> op.user_mu(np.array([-1.0, -0.5, -0.1, 0.1, 0.5, 1.0]))
>>> op.user_phi(np.array([0.0]))
>>> nwave, ncol, nprop = 1, 1, 2 + op.ds().nmom
>>> ds = Disort(op)
>>> tau = torch.tensor([0.1, 0.2, 0.3, 0.4]).reshape((4,1))
>>> bc = {
>>>   "umu0": torch.tensor([0.1]),
>>>   "phi0": torch.tensor([0.0]),
>>>   "albedo": torch.tensor([0.0]),
>>>   "fluor": torch.tensor([0.0]),
>>>   "fisot": torch.tensor([0.0]),
>>> }
>>> bc["fbeam"] = np.pi / bc["umu0"]
>>> tau = torch.zeros((ncol, nprop))
>>> tau[0, 0] = ds.options.user_tau()[-1]
>>> tau[0, 1] = 0.2
>>> tau[0, 2:] = scattering_moments(nprop - 2, "isotropic")
>>> flx = ds.forward(tau, **bc)
>>> ds.gather_rad()
tensor([[[[[0.0000, 0.0000, 0.0000, 0.1178, 0.0264, 0.0134],
           [0.0134, 0.0263, 0.1159, 0.0000, 0.0000, 0.0000]]]]])
class disort_state

This is a wrapper for the disort_state object in the C DISORT library. The only important variables are:

  • nlyr: number of layers

  • nstr: number of streams

  • nmom: number of phase function moments

  • nphase: number of azimuthal angles

The result of the variables will be transferred from the pydisort.DisortOptions object when the pydisort.Disort object is created.

property nlyr

Number of layers

property nmom

Number of phase functions moments

property nphase

Number of azimuthal angles

property nstr

Number of streams

Main Functions

scattering_moments(nmom: int, type: str, gg1: float = 0.0, gg2: float = 0.0, ff: float = 0.0) → torch.Tensor

Get phase function moments based on a phase function model

The following phase function models are supported:

Model

Description

‘isotropic’

Isotropic phase function, [0, 0, 0, …]

‘rayleigh’

Rayleigh scattering phase function, [0, 0.1, 0, …]

‘henyey-greenstein’

Henyey-Greenstein phase function, [gg, gg^2, gg^3, …]

‘double-henyey-greenstein’

Double Henyey-Greenstein phase function, [gg1, gg2, gg1^2, gg2^2, …]

‘haze-garcia-siewert’

Tabulated haze phase function by Garcia/Siewert

‘cloud-garcia-siewert’

Tabulated cloud phase function by Garcia/Siewert
Parameters:

  • nmom (int) – Number of phase function moments

  • type (str) – Phase function model

  • gg1 (float) – First Henyey-Greenstein parameter

  • gg2 (float) – Second Henyey-Greenstein parameter

  • ff (float) – Weighting factor for double Henyey-Greenstein

Returns:

Phase function moments, shape (nmom,)

Return type:

torch.Tensor

Examples

Example 1: Isotropic phase function

>>> import pydisort
>>> pydisort.scattering_moments(4, 'isotropic')
tensor([0., 0., 0., 0.], dtype=torch.float64)

Example 2: Henyey-Greenstein phase function

>>> import pydisort
>>> pydisort.scattering_moments(4, 'henyey-greenstein', 0.85)
tensor([0.8500, 0.7225, 0.6141, 0.5220], dtype=torch.float64)

Example 3: Double Henyey-Greenstein phase function

>>> import pydisort
>>> pydisort.scattering_moments(4, 'double-henyey-greenstein', 0.85, 0.5, 0.5)
tensor([0.6750, 0.4862, 0.3696, 0.2923], dtype=torch.float64)