API Reference

Main Classes

class DisortOptions

Set radiation flags and dimension for disort

This is usually the first step in setting up a disort run. Some disort options can be set directly in the disort_state object, such as the dimensions and the flags. Others, such as the polarj and azimuthal angles requires allocating the internal arrays of disort_state. The DisortOptions object holds those arrays temporarily until the disort_state object is initialized when a Disort object is created based on the DisortOptions object.

Note

When the DisortOptions object is printed, it may not truly reflect the state of the disort_state object. This is because the DisortOptions object holds temporary arrays that are not yet transferred to the disort_state object. Transferring happens when the Disort object is created by calling:

>>> disort = pydisort.Disort(op)

where op is the DisortOptions object.

Returns:: DisortOption object

Examples:

>>> import pydisort
>>> op = pydisort.DisortOptions().flags('onlyfl').nwave(10).ncol(10)
>>> op.ds().nlyr, op.ds().nstr, op.ds().nmom = 10, 4, 4
>>> print(op)
DisortOptions(flags = onlyfl; nwave = 10; ncol = 10; disort_state = (nlyr = 10; nstr = 4; nmom = 4; ibcnd = 0; usrtau = 0; usrang = 0; lamber = 0; planck = 0; spher = 0; onlyfl = 0); wave = ())

The following flags are supported:

Flag

Description

‘ibcnd’

General or Specific boundary condition

‘usrtau’

use user optical depths

‘usrang’

use user azimuthal angles

‘lamber’

turn on lambertian reflection surface

‘plank’

turn on plank source (thermal emission)

‘spher’

turn on spherical correction

‘onlyfl’

only compute radiative fluxes

‘quiet’

turn on disort internal printout

‘intensity_correction’

turn on intensity correction

‘old_intensity_correction’

turn on old intensity correction

‘general_source’

turn on general source

‘output_uum’

output azimuthal components of the intensity

‘print-input’

print input parameters

‘print-fluxes’

print fluxes

‘print-intensity’

print intensity

‘print-transmissivity’

print transmissivity

‘print-phase-function’

print phase function

A General boundary condition is invoked when ‘ibcnd’ is unspecified (False). This allows:

beam illumination from the top

isotropic illumination from the top

thermal emission from the top

internal thermal emission

reflection at the bottom

thermal emission from the bottom

A Special boundary condition is invoked when ‘ibcnd’ is specified (True). Special boundary condition only returns albedo and transmissivity of the entire medium.

Warning

current version of pydisort has limited support for this option.

consult the documentation of DISORT for more details on this option.

accur(*args, **kwargs)

Overloaded function.

accur(self: disort.DisortOptions) -> float
Set or get accuracy for disort
Usage:
accur() -> float

accur(accur: float) -> DisortOptions
Args:
accur (float, optional): accuracy for disort

Returns:
DisortOptions: object
Examples:
>>> import pydisort >>> op = pydisort.DisortOptions().accur(1.e-6) >>> print(op)
accur(self: disort.DisortOptions, arg0: float) -> disort.DisortOptions
Set or get accuracy for disort
Usage:
accur() -> float

accur(accur: float) -> DisortOptions
Args:
accur (float, optional): accuracy for disort

Returns:
DisortOptions: object
Examples:
>>> import pydisort >>> op = pydisort.DisortOptions().accur(1.e-6) >>> print(op)

ds(*args, **kwargs)

Overloaded function.

ds(self: disort.DisortOptions) -> disort_state
Set disort state for disort

Args:
ds (disort_state): disort state for disort

Returns:
DisortOptions: object

Examples:
>>> import pydisort >>> op = pydisort.DisortOptions() >>> op.ds().nlyr, op.ds().nstr, op.ds().nmom = 10, 4, 4 >>> print(op)
ds(self: disort.DisortOptions, arg0: disort_state) -> disort.DisortOptions
Set disort state for disort

Args:
ds (disort_state): disort state for disort

Returns:
DisortOptions: object

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.

flags(self: disort.DisortOptions) -> str
Set or get radiation flags for disort
Usage:
flags() -> str

flags(key: str) -> DisortOptions
Args:
flags (str, optional): radiation flags for disort

Returns:
DisortOptions: object
Examples:
>>> import pydisort >>> op = pydisort.DisortOptions().flags('onlyfl') >>> print(op)
flags(self: disort.DisortOptions, arg0: str) -> disort.DisortOptions
Set or get radiation flags for disort
Usage:
flags() -> str

flags(key: str) -> DisortOptions
Args:
flags (str, optional): radiation flags for disort

Returns:
DisortOptions: object
Examples:
>>> import pydisort >>> op = pydisort.DisortOptions().flags('onlyfl') >>> print(op)

header(*args, **kwargs)

Overloaded function.

header(self: disort.DisortOptions) -> str
Set or get header for disort
Usage:
header() -> str

header(header: str) -> DisortOptions
Args:
header (str, optional): header for disort

Returns:
DisortOptions: object
Examples:
>>> import pydisort >>> op = pydisort.DisortOptions().header('Test run') >>> print(op)
header(self: disort.DisortOptions, arg0: str) -> disort.DisortOptions
Set or get header for disort
Usage:
header() -> str

header(header: str) -> DisortOptions
Args:
header (str, optional): header for disort

Returns:
DisortOptions: object
Examples:
>>> import pydisort >>> op = pydisort.DisortOptions().header('Test run') >>> print(op)

ncol(*args, **kwargs)

Overloaded function.

ncol(self: disort.DisortOptions) -> int
Set or get number of columns for disort
Usage:
ncol() -> int

ncol(ncol: int) -> DisortOptions
Args:
ncol (int, optional): number of columns for disort

Returns:
DisortOptions: object
Examples:
>>> import pydisort >>> op = pydisort.DisortOptions().ncol(10) >>> print(op)
ncol(self: disort.DisortOptions, arg0: int) -> disort.DisortOptions
Set or get number of columns for disort
Usage:
ncol() -> int

ncol(ncol: int) -> DisortOptions
Args:
ncol (int, optional): number of columns for disort

Returns:
DisortOptions: object
Examples:
>>> import pydisort >>> op = pydisort.DisortOptions().ncol(10) >>> print(op)

nwave(*args, **kwargs)

Overloaded function.

nwave(self: disort.DisortOptions) -> int
Set or get number of wavelengths for disort
Usage:
nwave() -> int

nwave(nwave: int) -> DisortOptions
Args:
nwave (int, optional): number of wavelengths for disort

Returns:
DisortOptions: object
Examples:
>>> import pydisort >>> op = pydisort.DisortOptions().nwave(10) >>> print(op)
nwave(self: disort.DisortOptions, arg0: int) -> disort.DisortOptions
Set or get number of wavelengths for disort
Usage:
nwave() -> int

nwave(nwave: int) -> DisortOptions
Args:
nwave (int, optional): number of wavelengths for disort

Returns:
DisortOptions: object
Examples:
>>> import pydisort >>> op = pydisort.DisortOptions().nwave(10) >>> print(op)

upward(*args, **kwargs)

Overloaded function.

upward(self: disort.DisortOptions) -> int
Set or get direction for disort
Usage:
upward() -> int

upward(upward: int) -> DisortOptions
Args:
upward (int): direction for disort

Returns:
DisortOptions: object
Examples:
>>> import pydisort >>> op = pydisort.DisortOptions().upward(true) >>> print(op)
upward(self: disort.DisortOptions, arg0: int) -> disort.DisortOptions
Set or get direction for disort
Usage:
upward() -> int

upward(upward: int) -> DisortOptions
Args:
upward (int): direction for disort

Returns:
DisortOptions: object
Examples:
>>> import pydisort >>> op = pydisort.DisortOptions().upward(true) >>> print(op)

user_mu(*args, **kwargs)

Overloaded function.

user_mu(self: disort.DisortOptions) -> list[float]
Set or get user zenith angles for disort
Usage:
user_mu() -> list

user_mu(user_mu: list) -> DisortOptions
Args:
user_mu (list): user zenith angles for disort

Returns:
DisortOptions: object
Examples:
>>> import pydisort >>> op = pydisort.DisortOptions().user_mu([0.1, 0.2, 0.3]) >>> print(op)
user_mu(self: disort.DisortOptions, arg0: list[float]) -> disort.DisortOptions
Set or get user zenith angles for disort
Usage:
user_mu() -> list

user_mu(user_mu: list) -> DisortOptions
Args:
user_mu (list): user zenith angles for disort

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

user_phi(*args, **kwargs)

Overloaded function.

user_phi(self: disort.DisortOptions) -> list[float]
Set or get user azimuthal angles for disort
Usage:
user_phi() -> list

user_phi(user_phi: list) -> DisortOptions
Args:
user_phi (list): user azimuthal angles for disort

Returns:
DisortOptions: object
Examples:
>>> import pydisort >>> op = pydisort.DisortOptions().user_phi([0.1, 0.2, 0.3]) >>> print(op)
user_phi(self: disort.DisortOptions, arg0: list[float]) -> disort.DisortOptions
Set or get user azimuthal angles for disort
Usage:
user_phi() -> list

user_phi(user_phi: list) -> DisortOptions
Args:
user_phi (list): user azimuthal angles for disort

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

user_tau(*args, **kwargs)

Overloaded function.

user_tau(self: disort.DisortOptions) -> list[float]
Set or get user optical depths for disort
Usage:
user_tau() -> list

user_tau(user_tau: list) -> DisortOptions
Args:
user_tau (list): user optical depths for disort

Returns:
DisortOptions: object
Examples:
>>> import pydisort >>> op = pydisort.DisortOptions().user_tau([0.1, 0.2, 0.3]) >>> print(op)
user_tau(self: disort.DisortOptions, arg0: list[float]) -> disort.DisortOptions
Set or get user optical depths for disort
Usage:
user_tau() -> list

user_tau(user_tau: list) -> DisortOptions
Args:
user_tau (list): user optical depths for disort

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

wave_lower(*args, **kwargs)

Overloaded function.

wave_lower(self: disort.DisortOptions) -> list[float]
Set or get lower wavenumber(length) at each bin for disort
Usage:
wave_lower() -> list

wave_lower(wave_lower: list) -> DisortOptions
Args:
wave_lower (list): lower wavenumber(length) at each bin for disort

Returns:
DisortOptions: object
Examples:
>>> import pydisort >>> op = pydisort.DisortOptions().wave_lower([0.1, 0.2, 0.3]) >>> print(op)
wave_lower(self: disort.DisortOptions, arg0: list[float]) -> disort.DisortOptions
Set or get lower wavenumber(length) at each bin for disort
Usage:
wave_lower() -> list

wave_lower(wave_lower: list) -> DisortOptions
Args:
wave_lower (list): lower wavenumber(length) at each bin for disort

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

wave_upper(*args, **kwargs)

Overloaded function.

wave_upper(self: disort.DisortOptions) -> list[float]
Set or get upper wavenumber(length) at each bin for disort
Usage:
wave_upper() -> list

wave_upper(wave_upper: list) -> DisortOptions
Args:
wave_upper (list): upper wavenumber(length) at each bin for disort

Returns:
DisortOptions: object
Examples:
>>> import pydisort >>> op = pydisort.DisortOptions().wave_upper([0.1, 0.2, 0.3]) >>> print(op)
wave_upper(self: disort.DisortOptions, arg0: list[float]) -> disort.DisortOptions
Set or get upper wavenumber(length) at each bin for disort
Usage:
wave_upper() -> list

wave_upper(wave_upper: list) -> DisortOptions
Args:
wave_upper (list): upper wavenumber(length) at each bin for disort

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

class Disort

forward(*args, **kwargs)

Overloaded function.

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

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

Calculate radiative flux or intensity

The dimensions of each recognized key in bc 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.
Args:
prop (torch.Tensor): Optical properties at each level (nwave, ncol, nlyr, nprop)

bc (Dict[str, torch.Tensor]): Dictionary of disort boundary conditions.

bname (str): Name of the radiation band

temf (Optional[torch.Tensor]): Temperature at each level (ncol, nlvl = nlyr + 1)

Returns:
torch.Tensor: Radiative flux or intensity, shape (nwave, ncol, nlvl, nrad)

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]).reshape((4,1))
>>> bc = {"fbeam" : torch.tensor([3.14159]).reshape((1,1))}
>>> flx = ds.forward(tau, bc)
>>> 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]).reshape((4,1))
>>> bc = {"fbeam" : torch.tensor([3.14159]).reshape((1,1))}
>>> flx = ds.forward(tau, bc)
>>> 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.zeros((1, 1)),
>>>   "fluor": torch.zeros((1, 1)),
>>>   "fisot": torch.zeros((1, 1)),
>>> }
>>> bc["fbeam"] = np.pi / bc["umu0"].reshape((nwave, ncol))
>>> 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 angles (grid points)

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

Returns:: disort_state object

Examples

>>> import pydisort
>>> ds = pydisort.disort_state()
>>> ds.nlyr, ds.nstr, ds.nphase = 10, 4, 4
>>> print(ds)
disort_state(nlyr = 10; nstr = 4; nmom = 0; ibcnd = 0; usrtau = 0; usrang = 0; lamber = 0; planck = 0; spher = 0; onlyfl = 0)

property nlyr: Number of layers

property nmom: Number of phase functions moments

property nphase: Number of angles (grid points)

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)