eradiate.scenes.atmosphere.ParticleLayer

eradiate.scenes.atmosphere.ParticleLayer#

class eradiate.scenes.atmosphere.ParticleLayer(id='atmosphere', geometry='plane_parallel', bottom=<Quantity(0.0, 'kilometer')>, top=<Quantity(1.0, 'kilometer')>, distribution='uniform', w_ref=<Quantity(550, 'nanometer')>, tau_ref=<Quantity(0.2, 'dimensionless')>, dataset='govaerts_2021-continental', has_absorption=True, has_scattering=True, force_polarized_phase=False, *, scale=None, force_majorant=False, particle_shape='spherical')[source]#

Bases: AbstractHeterogeneousAtmosphere

Particle layer scene element [particle_layer].

The particle layer has a vertical extension specified by a bottom altitude (set by bottom) and a top altitude (set by top). Inside the layer, the particles number is distributed according to a distribution (set by distribution). See particle_dist for the available distribution types and corresponding parameters. The particle layer is itself divided into a number of (sub-)layers (n_layers) to allow to describe the variations of the particles number with altitude. The particle density in the layer is adjusted so that the particle layer’s optical thickness at a specified reference wavelength (w_ref) meets a specified value (tau_ref). The particles radiative properties are specified by a data set (dataset).

Parameters:

id (str, optional, default: "atmosphere") – Identifier of the current scene element.
geometry (SceneGeometry or dict or str, optional, default: "plane_parallel") – Parameters defining the basic geometry of the scene. Note if the atmosphere is used in a simulation, the experiment has all control over the atmosphere’s geometry and is going to set it. Therefore, in such a case it is best to define the geometry at the experiment level. When the atmosphere is used standalone, care must be taken to ensure that the geometry is consistent with the vertical extent of the atmosphere.
scale (float, optional) – If set, the extinction coefficient is scaled by the corresponding amount during computation.
force_majorant (bool, optional) – If set to true, uses heterogeneous medium, which is compatible with all integrators except PiecewiseVolpathIntegrator. Otherwise, uses a piecewise medium which is compatible with PiecewiseVolPathIntegrator and other integrators. This setting only affects PlaneParallelGeometry, other geometries use heterogeneous mediums.
bottom (float or quantity, default: 0 km) – Bottom altitude of the particle layer.

Unit-enabled field (default: ucc[length])
top (float or quantity, default: 1 km.) – Top altitude of the particle layer.

Unit-enabled field (default: ucc[length]).
distribution (ParticleDistribution or dict or {"uniform", "gaussian", "exponential"}, optional, default: "uniform") – Particle distribution. Simple defaults can be set using a string: "uniform" (resp. "gaussian", "exponential") is converted to UniformParticleDistribution() (resp. GaussianParticleDistribution(), ExponentialParticleDistribution()).
w_ref (quantity or float, default: 550.0) – Reference wavelength at which the extinction optical thickness is specified.

Unit-enabled field (default: ucc[‘wavelength’]).
tau_ref (quantity or float, default: 0.2) – Extinction optical thickness at the reference wavelength.

Unit-enabled field (default: ucc[dimensionless]).
dataset (Dataset or path-like or str, default: "govaerts_2021-continental") – Particle radiative property data set.If an xarray dataset is passed, the dataset is used as is (refer to the data guide for the format requirements of this dataset).If a path is passed, the converter tries to open the corresponding file on the hard drive; should that fail, it queries the Eradiate datastore with that path.If a string is passed, it is interpreted as an identifier for a particle radiative property dataset in the Eradiate data store.
has_absorption (bool, default: True) – Absorption bypass switch. If True, the absorption coefficient is computed. Else, the absorption coefficient is not computed and instead set to zero.
has_scattering (bool, default: True) – Scattering bypass switch. If True, the scattering coefficient is computed. Else, the scattering coefficient is not computed and instead set to zero.
force_polarized_phase (bool, default: False) – Force the use of a polarized phase function implementation, evenwhen no polarization information is available.
particle_shape ({"spherical", "spheroidal"}, default: "spherical") – Defines the shape of the particle. Only used in polarized mode.
- "spherical": 4 coefficients considered [m11, m12, m33, m34].
- "spheroidal": 6 coefficients considered [m11, m12, m22, m33, m34, m44].

Fields:

id (str or None) – Identifier of the current scene element.
geometry (SceneGeometry) – Parameters defining the basic geometry of the scene.
scale (float or None) – If set, the extinction coefficient is scaled by the corresponding amount during computation.
force_majorant (bool) – If set to true, uses heterogeneous medium, which is compatible with all integrators except PiecewiseVolpathIntegrator.
bottom (quantity) – Bottom altitude of the particle layer.
top (quantity) – Top altitude of the particle layer.
distribution (ParticleDistribution) – Particle distribution.
w_ref (quantity) – Reference wavelength at which the extinction optical thickness is specified.
tau_ref (quantity) – Extinction optical thickness at the reference wavelength.
dataset (Dataset) – Particle radiative property data set.If an xarray dataset is passed, the dataset is used as is (refer to the data guide for the format requirements of this dataset).If a path is passed, the converter tries to open the corresponding file on the hard drive; should that fail, it queries the Eradiate datastore with that path.If a string is passed, it is interpreted as an identifier for a particle radiative property dataset in the Eradiate data store.
has_absorption (bool) – Absorption bypass switch.
has_scattering (bool) – Scattering bypass switch.
force_polarized_phase (bool) – Force the use of a polarized phase function implementation, evenwhen no polarization information is available.
particle_shape (str) – Defines the shape of the particle.

eval_albedo(si, zgrid=None)[source]#

eval_albedo(si, zgrid=None)

Evaluate albedo spectrum based on a spectral context. This method dispatches evaluation to specialized methods depending on the active mode.

Parameters:

si (SpectralIndex) – Spectral index.
zgrid (ZGrid, optional) – Altitude grid on which evaluation is performed. If unset, an instance-specific default is used (see zgrid).

Returns:

quantity – Evaluated spectrum as an array with length equal to the number of layers.

eval_fractions(zgrid)[source]#

Compute the particle number fraction in the particle layer.

Returns:: ndarray – Particle number fractions as a (n_layers,)-shaped array.

eval_mfp(ctx)[source]#

Compute a typical scattering mean free path. This rough estimate can be used e.g. to compute a distance guaranteeing that the medium can be considered optically thick.

Parameters:: ctx (KernelContext) – A context data structure containing parameters relevant for kernel dictionary generation.
Returns:: mfp (quantity) – Mean free path estimate.

eval_radprops(si, zgrid=None, optional_fields=False)#

Evaluate the extinction coefficients and albedo profiles.

Parameters:

si (SpectralIndex) – Spectral index.
zgrid (ZGrid, optional) – Altitude grid on which evaluation is performed. If unset, an instance-specific default is used (see zgrid).
optional_fields (bool, optional, default: False) – If True, also output the absorption and scattering coefficients, not required for scene setup but useful for analysis and debugging.

Returns:

Dataset – A dataset with the following variables:

sigma_t: extinction coefficient;
albedo: albedo;
sigma_a: absorption coefficient (optional);
sigma_s: scattering coefficient (optional).

and coordinates:

z: altitude.

eval_sigma_a(si, zgrid=None)[source]#

eval_sigma_a(si, zgrid=None)

Evaluate absorption coefficient given a spectral context.

Parameters:

si (SpectralIndex) – Spectral index.
zgrid (ZGrid, optional) – Altitude grid on which evaluation is performed. If unset, an instance-specific default is used (see zgrid).

Returns:

quantity – Particle layer extinction coefficient.

eval_sigma_s(si, zgrid=None)[source]#

eval_sigma_s(si, zgrid=None)

Evaluate scattering coefficient given a spectral context.

Parameters:

si (SpectralIndex) – Spectral index.
zgrid (ZGrid, optional) – Altitude grid on which evaluation is performed. If unset, an instance-specific default is used (see zgrid).

Returns:

quantity – Particle layer scattering coefficient.

eval_sigma_t(si, zgrid=None)[source]#

eval_sigma_t(si, zgrid=None)

Evaluate extinction coefficient given a spectral context.

Parameters:

si (SpectralIndex) – Spectral index.
zgrid (ZGrid, optional) – Altitude grid on which evaluation is performed. If unset, an instance-specific default is used (see zgrid).

Returns:

quantity – Particle layer extinction coefficient.

eval_transmittance(si, interaction='extinction')#

Evaluate the atmosphere’s transmittance with respect to specific interaction.

Parameters:

si (SpectralIndex) – Spectral index.
interaction ({"extinction", "absorption", "scattering"}, optional, default: "extinction") – Interaction type.

Returns:

quantity – Total atmosphere transmittance.

traverse(callback)#

Traverse this scene element and collect kernel dictionary template and parameter update map contributions.

Parameters:: callback (SceneTraversal) – Callback data structure storing the collected data.

update()[source]#: Update internal state.

property absorption_data#

Returns:: AbsorptionDatabase or None – If relevant, the molecular absorption database associated with this atmosphere.

property bottom_altitude#

Returns:: quantity – Atmosphere bottom altitude.

property height#

Returns:: quantity – Atmosphere height.

property medium_id#

Returns:: str – ID of the medium associated with the atmosphere in the Mitsuba scene tree.

property objects#

Map of child objects associated with this scene element.

Returns:: dict – A dictionary mapping object names to a corresponding object to be inserted in the Eradiate scene graph.

property params#

Returns:: dict[str, UpdateParameter] or None – A dictionary mapping parameter paths, consisting of dot-separated strings, to a corresponding update protocol.

eradiate.scenes.atmosphere.ParticleLayer

Contents

eradiate.scenes.atmosphere.ParticleLayer#