MediumSystem Class Reference

#include <MediumSystem.hpp>

Inheritance diagram for MediumSystem:

Public Member Functions
double	albedoForScattering (const PhotonPacket *pp) const
void	beginDynamicMediumStateIteration ()
Vec	bulkVelocity (int m) const
double	callWithMaterialState (std::function< double(const MaterialState *mst)> callback, int m, int h) const
void	clearRadiationField (bool primary)
void	communicateRadiationField (bool primary)
Array	continuumEmissionSpectrum (int m, int h) const
double	custom (int m, int h, int i) const
int	dimension () const
DustEmissionOptions *	dustEmissionOptions () const
Array	dustEmissionSpectrum (int m) const
double	dustLuminosity (int m) const
double	dustMassDensity (int m) const
double	dustMassDensity (Position bfr) const
const vector< int > &	dustMediumIndices () const
DynamicStateOptions *	dynamicStateOptions () const
const vector< int > &	electronMediumIndices () const
double	electronNumberDensity (int m) const
double	electronNumberDensity (Position bfr) const
const vector< int > &	gasMediumIndices () const
double	gasNumberDensity (int m) const
double	gasNumberDensity (Position bfr) const
double	getExtinctionOpticalDepth (const PhotonPacket *pp, double distance) const
double	getExtinctionOpticalDepth (const SpatialGridPath *path, double lambda, MaterialMix::MaterialType type) const
SpatialGrid *	grid () const
int	gridDimension () const
bool	hasDust () const
bool	hasElectrons () const
bool	hasGas () const
bool	hasMaterialType (MaterialMix::MaterialType type) const
double	indicativeDustTemperature (int m) const
double	indicativeElectronTemperature (int m) const
double	indicativeGasTemperature (int m) const
double	indicativeTemperature (int m, int h) const
double	indicativeTemperature (int m, MaterialMix::MaterialType type) const
bool	isDust (int h) const
bool	isElectrons (int h) const
bool	isGas (int h) const
bool	isMaterialType (MaterialMix::MaterialType type, int h) const
IterationOptions *	iterationOptions () const
Array	lineEmissionSpectrum (int m, int h) const
LyaOptions *	lyaOptions () const
Vec	magneticField (int m) const
double	massDensity (int m) const
double	massDensity (int m, int h) const
Array	meanIntensity (int m) const
const vector< Medium * > &	media () const
double	metallicity (int m, int h) const
const MaterialMix *	mix (int m, int h) const
double	numberDensity (int m, int h) const
int	numCells () const
int	numMedia () const
double	opacityAbs (double lambda, int m, int h) const
double	opacityAbs (double lambda, int m, MaterialMix::MaterialType type) const
double	opacityExt (double lambda, int m) const
double	opacityExt (double lambda, int m, int h) const
double	opacityExt (double lambda, int m, MaterialMix::MaterialType type) const
double	opacitySca (double lambda, int m, int h) const
void	peelOffScattering (const ShortArray &wv, double lambda, Direction bfkobs, Direction bfky, PhotonPacket *pp, PhotonPacket *ppp) const
void	peelOffScattering (int h, double w, double lambda, Direction bfkobs, Direction bfky, PhotonPacket *pp, PhotonPacket *ppp) const
double	perceivedWavelengthForScattering (const PhotonPacket *pp) const
PhotonPacketOptions *	photonPacketOptions () const
RadiationFieldOptions *	radiationFieldOptions () const
SamplingOptions *	samplingOptions () const
SecondaryEmissionOptions *	secondaryEmissionOptions () const
void	setExtinctionOpticalDepths (PhotonPacket *pp) const
bool	setInteractionPointUsingExtinction (PhotonPacket *pp, double tauinteract) const
bool	setInteractionPointUsingScatteringAndAbsorption (PhotonPacket *pp, double tauinteract) const
void	setScatteringAndAbsorptionOpticalDepths (PhotonPacket *pp) const
void	simulateScattering (Random *random, PhotonPacket *pp) const
void	storeRadiationField (bool primary, int m, int ell, double Lds)
double	temperature (int m, int h) const
std::pair< double, double >	totalDustAbsorbedLuminosity () const
bool	updatePrimaryDynamicMediumState ()
bool	updateSecondaryDynamicMediumState ()
double	volume (int m) const
bool	weightsForScattering (ShortArray &wv, double lambda, const PhotonPacket *pp) const
Public Member Functions inherited from SimulationItem
template<class T >
T *	find (bool setup=true) const
template<class T >
T *	interface (int levels=-999999, bool setup=true) const
virtual string	itemName () const
void	setup ()
string	typeAndName () const
Public Member Functions inherited from Item
	Item (const Item &)=delete
virtual	~Item ()
void	addChild (Item *child)
const vector< Item * > &	children () const
virtual void	clearItemListProperty (const PropertyDef *property)
void	destroyChild (Item *child)
virtual bool	getBoolProperty (const PropertyDef *property) const
virtual vector< double >	getDoubleListProperty (const PropertyDef *property) const
virtual double	getDoubleProperty (const PropertyDef *property) const
virtual string	getEnumProperty (const PropertyDef *property) const
virtual int	getIntProperty (const PropertyDef *property) const
virtual vector< Item * >	getItemListProperty (const PropertyDef *property) const
virtual Item *	getItemProperty (const PropertyDef *property) const
virtual string	getStringProperty (const PropertyDef *property) const
int	getUtilityProperty (string name) const
virtual void	insertIntoItemListProperty (const PropertyDef *property, int index, Item *item)
Item &	operator= (const Item &)=delete
Item *	parent () const
virtual void	removeFromItemListProperty (const PropertyDef *property, int index)
virtual void	setBoolProperty (const PropertyDef *property, bool value)
virtual void	setDoubleListProperty (const PropertyDef *property, vector< double > value)
virtual void	setDoubleProperty (const PropertyDef *property, double value)
virtual void	setEnumProperty (const PropertyDef *property, string value)
virtual void	setIntProperty (const PropertyDef *property, int value)
virtual void	setItemProperty (const PropertyDef *property, Item *item)
virtual void	setStringProperty (const PropertyDef *property, string value)
void	setUtilityProperty (string name, int value)
virtual string	type () const

Protected Member Functions
	MediumSystem ()
void	setupSelfAfter () override
Protected Member Functions inherited from SimulationItem
	SimulationItem ()
virtual bool	offersInterface (const std::type_info &interfaceTypeInfo) const
virtual void	setupSelfAfter ()
virtual void	setupSelfBefore ()
Protected Member Functions inherited from Item
	Item ()

Private Types
using	BaseType = SimulationItem
using	ItemType = MediumSystem

Private Member Functions
double	opacityAbs (double lambda, int m, const PhotonPacket *pp) const
double	opacityExt (double lambda, int m, const PhotonPacket *pp) const
double	opacitySca (double lambda, int m, const PhotonPacket *pp) const
double	radiationField (int m, int ell) const
bool	updateDynamicStateMedia (bool primary)
bool	updateDynamicStateRecipes ()

Private Attributes
Configuration *	_config
vector< int >	_dust_hv
DustEmissionOptions *	_dustEmissionOptions
DynamicStateOptions *	_dynamicStateOptions
vector< int >	_elec_hv
vector< int >	_gas_hv
SpatialGrid *	_grid
IterationOptions *	_iterationOptions
LyaOptions *	_lyaOptions
vector< Medium * >	_media
bool	_mixPerCell
vector< const MaterialMix * >	_mixv
int	_numCells
int	_numDustEmissionWavelengths
int	_numMedia
vector< int >	_pdms_hv
PhotonPacketOptions *	_photonPacketOptions
RadiationFieldOptions *	_radiationFieldOptions
Table< 2 >	_rf1
Table< 2 >	_rf2
Table< 2 >	_rf2c
SamplingOptions *	_samplingOptions
vector< int >	_sdms_hv
SecondaryEmissionOptions *	_secondaryEmissionOptions
MediumState	_state
WavelengthGrid *	_wavelengthGrid

Friends
class	ItemRegistry

Detailed Description

An instance of the MediumSystem class represents a complete medium system, which is the superposition of one or more transfer media. Each individual medium represents a spatial density distribution and defines the material properties of the medium at each location. While the specific material properties may vary with location, the fundamental material type must be the same throughout the spatial domain for each medium.

In addition to the media input model, the MediumSystem class includes the spatial grid that tessellates the spatial domain of the simulation into cells, and manages the medium state and the radiation field for each spatial cell in this grid. The class therefore plays a central role in the simulation and it offers quite a few different type of functions.

Overall medium configuration

These functions offer basic information on the spatial grid, the medium components, and the material types in the medium system.

Medium state

The medium state for each spatial cell in the simulation includes a set of common state variables shared by all medium components and a set of specific state variables for each individual medium component. See the MediumState class for more information. The functions in this section allow access to the common state variables for a given spatial cell.

Low-level optical properties

These functions allow retrieving absorption, scattering and extinction cross sections for a given spatial cell and material type as a function of wavelength, assuming fixed, predefined values for any quantities other than wavelength (e.g., a default temperature, no polarization, no kinematics). The values returned by these low-level functions may be used only during setup and for probing.

High-level photon life cycle

These functions support the photon life cycle by offering a generic interface for operations including tracing photon paths through the medium and performing scattering events. The functions calculate opacities and other medium properties in a given spatial cell by passing the incoming photon packet and the full medium state to the appropriate material mix for each medium component. This allows proper treatment of polarization and kinematics and supports dependencies on temperature or custom special state variables.

Radiation field

These functions allow storing the radiation field during the photon life cycle and retrieving the results after a set of photon's have been processed. The contribution to the radation field for each spatial cell and for each wavelength in the simulation's radiation field wavelength grid is traced separately for primary and secondary sources. This avoids the need for repeating primary emission during dust-temperature convergence iterations. At all times, the sum of the primary and secondary contributions represents the radiation field to be used as input for calculations. There is a third, temporary table that serves as a target for storing the secondary radiation field so that the "stable" primary and secondary tables remain available for calculating secondary emission spectra while shooting secondary photons through the grid.

Indicative temperature

These functions determine an indicative temperature in a given spatial cell and for a given material type, averaged over medium components if applicable. Depending on the material type, the indicative temperature may be based on the radiation field or it may be derived from a value given in the input model. In any case, it does not reflect a physical quantity and it should be used only for setup and probing purposes.

Emission

These functions support the secondary source system by offering a generic interface for calculating the secondary emission properties in a given spatial cell and for a given material type, including luminosities, spectra and polarization.

This item type is allowed only if the Boolean expression "!NoMedium" evaluates to true after replacing the names by true or false depending on their presence.

Constructor & Destructor Documentation

MediumSystem()

MediumSystem::MediumSystem ( )

inlineprotected

Default constructor for concrete Item subclass MediumSystem : "a medium system" .

Member Function Documentation

albedoForScattering()

double MediumSystem::albedoForScattering

(

const PhotonPacket *

pp

)

const

This function returns the weighted scattering albedo

$$\frac{\sum _h{k}_h^{\text{sca}}}{\sum _h{k}_h^{\text{ext}}}$$

over all medium components at wavelength $\lambda$ in the spatial cell hosting the specified photon packet's scattering event. The opacities are calculated at the wavelength perceived by the medium taking into account the bulk velocity and Hubble expansion velocity in that cell and taking into account any relevant properties of the specified photon packet such as the polarization state.

beginDynamicMediumStateIteration()

void MediumSystem::beginDynamicMediumStateIteration

(

)

This function shifts the current aggregate medium state to the previous aggregate medium state. It should be called at the start of each iteration step.

bulkVelocity()

Vec MediumSystem::bulkVelocity

(

int

m

)

const

This function returns the aggregate bulk velocity $\mathit{v}$ of the medium in spatial cell with index $m$. If there are multiple media components, the aggregate bulk velocity $\mathit{v}$ is determined by averaging the respective bulk velocities over the corresponding number densities,

$$\mathit{v}=\frac{\sum _h{n}_h{\mathit{v}}_h}{\sum _h{n}_h}.$$

If no medium component specifies a bulk velocity, this function returns the null vector.

callWithMaterialState()

double MediumSystem::callWithMaterialState	(	std::function< double(const MaterialState *mst)>	callback,
		int	m,
		int	h
	)		const

This function invokes the given callback function with the material state for the specified cell and medium component as a single argument, and returns the resulting floating point value. The function is intended for specialty probing and should be used with restraint.

clearRadiationField()

void MediumSystem::clearRadiationField

(

bool

primary

)

This function initializes all values of the primary and/or secondary radiation field info tables to zero. In simulation modes that record the radiation field, the function should be called before starting a simulation segment (i.e. before a set of photon packets is launched). If the primary flag is true, the function clears both the primary table and the stable secondary table (if present). The stable secondary table is cleared as well so that we can use its contents even if no secondary of photon packet segment has been launched yet. If the flag is false, the function clears just the temporary secondary table, so that the stable secondary table remains available for calculating secondary emission spectra.

communicateRadiationField()

void MediumSystem::communicateRadiationField

(

bool

primary

)

This function accumulates the radiation field between multiple processes. In simulation modes that record the radiation field, the function should be called in serial code after finishing a simulation segment (i.e. after a before set of photon packets has been launched) and before querying the radiation field's contents. If the primary flag is true, the primary table is synchronized; otherwise the temporary secondary table is synchronized and its contents is copied into the stable secondary table.

continuumEmissionSpectrum()

Array MediumSystem::continuumEmissionSpectrum	(	int	m,
		int	h
	)		const

This function returns the continuum emission spectrum in the spatial cell with index $m$ for the medium component with index $h$. It is intended for use with gas medium components that support secondary continuum emission. When invoked for other medium components, the behavior of the function is undefined. The returned spectrum is discretized on the wavelength grid returned by the MaterialMix::emissionWavelengthGrid() function of the material mix associated with the specified medium component. It contains absolute (specific) luminosity values that do not need further normalization.

custom()

double MediumSystem::custom	(	int	m,
		int	h,
		int	i
	)		const

This function returns the value of the custom specific state variable with index $i$ of the medium component with index $h$ in the spatial cell with index $m$. If the specified medium component does not have a custom variable with the specified index, the behavior of this function is undefined.

dimension()

int MediumSystem::dimension

(

)

const

This function returns the dimension of the medium system, which depends on the (lack of) symmetry in the geometries of the media it contains (not including the spatial grid). A value of 1 means spherical symmetry, 2 means axial symmetry and 3 means none of these symmetries. The medium with the least symmetry (i.e. the highest dimension) determines the result for the whole system.

dustEmissionOptions()

MediumSystem::dustEmissionOptions ( ) const

inline

This function returns the value of the discoverable item property dustEmissionOptions : "the dust emission options" .

The default value for this property is given by the conditional value expression "DustEmissionOptions" .

This property is relevant only if the Boolean expression "DustEmission" evaluates to true after replacing the names by true or false depending on their presence.

dustEmissionSpectrum()

Array MediumSystem::dustEmissionSpectrum

(

int

m

)

const

This function returns the combined emission spectrum for all dust media in the spatial cell with index $m$. Depending on a simulation-wide configuration option, the spectrum is calculated under the assumption of local thermal equilibrium (LTE) or taking into account the effect of stochastically heated dust grains (NLTE). The returned spectrum is discretized on the wavelength grid returned by the Configuration::dustEmissionWLG() function and has arbitrary normalization. The caller is responsible for properly normalizing the spectrum based on the value returned by the dustLuminosity() function.

dustLuminosity()

double MediumSystem::dustLuminosity

(

int

m

)

const

This function returns the bolometric luminosity $L_{\text{bol},m}^{\text{abs}}$ that has been absorbed by dust media in the spatial cell with index $m$.

The bolometric luminosity is calculated using

$$L_{\text{bol},m}^{\text{abs}}=\sum _{\ell }(k_{\text{type}}^{\text{abs}}{)}_{\ell ,m}(L\mathrm{\Delta }s{)}_{\ell ,m}$$

where $\ell$ runs over the wavelengths in the simulation's radiation field wavelength grid, $m$ is the spatial cell index, $(k_{\text{dust}}^{\text{abs}}{)}_{\ell ,m}$ is the absorption opacity of the dust in the cell, and $(L\mathrm{\Delta }s{)}_{\ell ,m}$ has been accumulated over all photon packets contributing to the bin.

dustMassDensity() [1/2]

double MediumSystem::dustMassDensity

(

int

m

)

const

This function returns the total mass density of all dust medium components in spatial cell with index $m$.

dustMassDensity() [2/2]

double MediumSystem::dustMassDensity

(

Position

bfr

)

const

This function returns the total mass density of all dust medium components at the specified position in the input model (i.e. directly querying the medium components rather than the gridded medium state).

dustMediumIndices()

const vector< int > & MediumSystem::dustMediumIndices ( ) const

inline

This function returns a list of indices $h$ for media components that contain dust.

dynamicStateOptions()

MediumSystem::dynamicStateOptions ( ) const

inline

This function returns the value of the discoverable item property dynamicStateOptions : "the dynamic medium state options" .

The default value for this property is given by the conditional value expression "DynamicStateOptions" .

This property is relevant only if the Boolean expression "IteratePrimary" evaluates to true after replacing the names by true or false depending on their presence.

electronMediumIndices()

const vector< int > & MediumSystem::electronMediumIndices ( ) const

inline

This function returns a list of indices $h$ for media components that contain electrons.

electronNumberDensity() [1/2]

double MediumSystem::electronNumberDensity

(

int

m

)

const

This function returns the total number density of all electron medium components in spatial cell with index $m$.

electronNumberDensity() [2/2]

double MediumSystem::electronNumberDensity

(

Position

bfr

)

const

This function returns the total number density of all electron medium components at the specified position in the input model (i.e. directly querying the medium components rather than the gridded medium state).

gasMediumIndices()

const vector< int > & MediumSystem::gasMediumIndices ( ) const

inline

This function returns a list of indices $h$ for media components that contain gas.

gasNumberDensity() [1/2]

double MediumSystem::gasNumberDensity

(

int

m

)

const

This function returns the total number density of all gas medium components in spatial cell with index $m$.

gasNumberDensity() [2/2]

double MediumSystem::gasNumberDensity

(

Position

bfr

)

const

This function returns the total number density of all gas medium components at the specified position in the input model (i.e. directly querying the medium components rather than the gridded medium state).

getExtinctionOpticalDepth() [1/2]

double MediumSystem::getExtinctionOpticalDepth	(	const PhotonPacket *	pp,
		double	distance
	)		const

This function calculates and returns the extinction optical depth along a path through the medium system defined by the initial position and direction of the specified PhotonPacket object and up to the specified distance.

This function is intended for handling peel-off photon packets during the photon life cycle. Because it is at the heart of the photon life cycle, performance is important. Hence the function implements optimized versions for media with spatially constant cross sections. Furthermore, the calculation is limited to the specified distance along the path. More precisely, all path segments with an entry boundary at a cumulative distance along the path smaller than the specified distance are included in the calculation, and any remaining segments are skipped.

The optical depth for each traversed path segment is calculated as described for the setExtinctionOpticalDepths() function, i.e. at the wavelength perceived by the medium in the cell being crossed and taking into account any relevant properties of the incoming photon packet.

High optical depth

Assuming that the extinction cross section is always positive, we know that the observable weight of a peel-off photon packet will be numerically zero as soon as the cumulative optical depth along its path is higher than ${\tau }_{\mathrm{m}\mathrm{a}\mathrm{x}}=\ln (L/L_{\mathrm{m}\mathrm{i}\mathrm{n}})$, where $L$ is the weight at the peel-off interaction site, and $L_{\mathrm{m}\mathrm{i}\mathrm{n}}$ is the smallest representable positive double-precision floating point number. Hence this function aborts the calculation and returns positive infinity when this happens.

If the extinction cross section can be negative, this optimization cannot be applied because the cumulative optical depth could decrease again further along the path.

getExtinctionOpticalDepth() [2/2]

double MediumSystem::getExtinctionOpticalDepth	(	const SpatialGridPath *	path,
		double	lambda,
		MaterialMix::MaterialType	type
	)		const

This function returns the extinction optical depth at the specified wavelength along a path through the medium system, taking into account only medium components with the specified material type. The starting position and the direction of the path are taken from the specified SpatialGridPath object. This function is intended for use from probes and hence is not performance-sensitive.

The function determines the segments of the path $(\mathrm{\Delta }s{)}_m$ as it crosses the cells with indices $m$ in the spatial grid and calculates the optical depth along the path as

$${\tau }_{\text{path}}=\sum _m(\mathrm{\Delta }s{)}_m\sum _h{k}_{m,h}^{\text{ext}},$$

where $k_{m,h}^{\text{ext}}$ is the extinction opacity corresponding to the $h$'th medium component in the cell with index $m$ at the specified wavelength $\lambda$ and the sum over $h$ runs only over the medium components with the specified material type.

Because no photon packet is available, the calculation ignores kinematic effects as well as any other photon packet properties such as polarization.

grid()

MediumSystem::grid ( ) const

inline

This function returns the value of the discoverable item property grid : "the spatial grid" .

The default value for this property is given by the conditional value expression "Dimension3:PolicyTreeSpatialGrid;Dimension2:Cylinder2DSpatialGrid;Sphere1DSpatialGrid" .

gridDimension()

int MediumSystem::gridDimension

(

)

const

This function returns the dimension of the spatial grid held by the medium system. A value of 1 means spherical symmetry, 2 means axial symmetry and 3 means none of these symmetries.

hasDust()

bool MediumSystem::hasDust ( ) const

inline

This function returns true if at least one of the media in the medium system contains dust.

hasElectrons()

bool MediumSystem::hasElectrons ( ) const

inline

This function returns true if at least one of the media in the medium system contains electrons.

hasGas()

bool MediumSystem::hasGas ( ) const

inline

This function returns true if at least one of the media in the medium system contains gas.

hasMaterialType()

bool MediumSystem::hasMaterialType

(

MaterialMix::MaterialType

type

)

const

This function returns true if at least one of the media in the medium system has the specified fundamental material type (i.e. dust, electrons, or gas).

indicativeDustTemperature()

double MediumSystem::indicativeDustTemperature

(

int

m

)

const

This function returns an indicative dust temperature for the spatial cell with index $m$, or zero if the simulation does not track the radiation field. Also see the indicativeTemperature() function for more information.

An indicative temperature for each dust component is obtained by solving the energy balance equation under LTE (local thermal equilibrium) assumptions for a single representative grain for each dust mix. The resulting temperatures are averaged over the dust components present in the spatial cell, weighed by relative mass in the cell. If the cell does not contain any dust, the function returns zero.

Note that the indicative dust temperature does not correspond to a physical temperature. The LTE assumption is almost certainly unjustified for a relevant portion of the dust grains (depending on the embedding radiation field), and even when ignoring this problem, averaging temperatures over the dust components and over the various grain material types and grain sizes within a particular dust mix has no clear-cut physical justification nor interpretation.

indicativeElectronTemperature()

double MediumSystem::indicativeElectronTemperature

(

int

m

)

const

This function returns an indicative electron temperature in the spatial cell with index $m$. This temperature is obtained by averaging the temperature over the electron medium components present in the spatial cell, weighed by relative mass in each component. If no medium component specifies an electron temperature, this function returns zero. Also see the indicativeTemperature() function for more information.

indicativeGasTemperature()

double MediumSystem::indicativeGasTemperature

(

int

m

)

const

This function returns an indicative gas temperature in the spatial cell with index $m$. This temperature is obtained by averaging the temperature over the gas medium components present in the spatial cell, weighed by relative mass in each component. If no medium component specifies a gas temperature, this function returns zero. Also see the indicativeTemperature() function for more information.

indicativeTemperature() [1/2]

double MediumSystem::indicativeTemperature	(	int	m,
		int	h
	)		const

This function returns an indicative temperature ${\overline{T}}_{m,h}$ for the material in the medium component with index $h$ in the spatial cell with index $m$. If the cell does not contain any material for the medium component, the function returns zero.

The interpretation of the indicative temperature depends heavily on the material type. Refer to the description for the MaterialMix::indicativeTemperature() function in the various MaterialMix subclasses for more information. Note that, in any case, the indicative temperature usually does not correspond to a physical temperature.

The calculation of the indicative temperature may depend on the radiation field embedding the material in the specified spatial cell, it may simply reflect the medium state for the cell as defined in the input model during setup, or it may somehow depend on both. If the radiation field is not being tracked in the simulation, and the indicative temperature for the requested material type depends on it, the function will return zero. If the radiation field is being tracked, this function assumes that the radiation field information has been accumulated and the communicateRadiationField() function has been called before invoking this function; see the meanIntensity() function. If this is not the case, the behavior is undefined.

indicativeTemperature() [2/2]

double MediumSystem::indicativeTemperature	(	int	m,
		MaterialMix::MaterialType	type
	)		const

This function returns an indicative temperature for the material of the specified type in the spatial cell with index $m$. It obtains an indicative temperature for each component with a material mix of the specified type, and averages these temperatures over the medium components weighed by their relative mass in the cell. In formula form, for a spatial cell $m$ with components $h$ of the specified type, the indicative dust temperature is defined as

$${\overline{T}}_m=\frac{\sum _h{\rho }_{m,h}{\overline{T}}_{m,h}}{\sum _h{\rho }_{m,h}}$$

where ${\overline{T}}_{m,h}$ is the indicative temperature for each component $h$. If the cell does not contain any material of the requested type, the function returns zero.

The interpretation of the indicative temperature depends heavily on the material type. Refer to the description for the MaterialMix::indicativeTemperature() function in the various MaterialMix subclasses for more information. Note that, in any case, the indicative temperature usually does not correspond to a physical temperature.

The calculation of the indicative temperature may depend on the radiation field embedding the material in the specified spatial cell, it may simply reflect the medium state for the cell as defined in the input model during setup, or it may somehow depend on both. If the radiation field is not being tracked in the simulation, and the indicative temperature for the requested material type depends on it, the function will return zero. If the radiation field is being tracked, this function assumes that the radiation field information has been accumulated and the communicateRadiationField() function has been called before invoking this function; see the meanIntensity() function. If this is not the case, the behavior is undefined.

isDust()

bool MediumSystem::isDust ( int  h ) const

inline

This function returns true if the medium component with index $h$ contains dust.

isElectrons()

bool MediumSystem::isElectrons ( int  h ) const

inline

This function returns true if the medium component with index $h$ contains electrons.

isGas()

bool MediumSystem::isGas ( int  h ) const

inline

This function returns true if the medium component with index $h$ contains gas.

isMaterialType()

bool MediumSystem::isMaterialType	(	MaterialMix::MaterialType	type,
		int	h
	)		const

This function returns true if the medium component with index $h$ has the specified fundamental material type (i.e. dust, electrons, or gas).

iterationOptions()

MediumSystem::iterationOptions ( ) const

inline

This function returns the value of the discoverable item property iterationOptions : "the primary and/or secondary emission iteration options" .

The default value for this property is given by the conditional value expression "IterationOptions" .

This property is relevant only if the Boolean expression "IteratePrimary|IterateSecondary" evaluates to true after replacing the names by true or false depending on their presence.

lineEmissionSpectrum()

Array MediumSystem::lineEmissionSpectrum	(	int	m,
		int	h
	)		const

This function returns the line emission spectrum in the spatial cell with index $m$ for the medium component with index $h$. It is intended for use with gas medium components that support secondary line emission. When invoked for other medium components, the behavior of the function is undefined. The returned values correspond to each of the lines returned by the MaterialMix::lineEmissionCenters() function of the material mix associated with the specified medium component. The values represent absolute line luminosities that do not need further normalization.

lyaOptions()

MediumSystem::lyaOptions ( ) const

inline

This function returns the value of the discoverable item property lyaOptions : "the Lyman-alpha line transfer options" .

The default value for this property is given by the conditional value expression "LyaOptions" .

This property is relevant only if the Boolean expression "Lya" evaluates to true after replacing the names by true or false depending on their presence.

magneticField()

Vec MediumSystem::magneticField

(

int

m

)

const

This function returns the magnetic field $\mathit{B}$ in the spatial cell with index $m$. At most one medium component is allowed to specify a magnetic field. If no medium component specifies a magnetic field, this function returns the null vector.

massDensity() [1/2]

double MediumSystem::massDensity

(

int

m

)

const

This function returns the total mass density of all medium components in spatial cell with index $m$.

massDensity() [2/2]

double MediumSystem::massDensity	(	int	m,
		int	h
	)		const

This function returns the mass density of the medium component with index $h$ in spatial cell with index $m$.

meanIntensity()

Array MediumSystem::meanIntensity

(

int

m

)

const

This function returns an array with the mean radiation field intensity $(J_{\lambda }{)}_{\ell ,m}$ in the spatial cell with index $m$ at each of the wavelength bins $\ell$ defined by the wavelength grid returned by the Configuration::radiationFieldWLG() function.

The mean intensity is calculated using

$$(J_{\lambda }{)}_{\ell ,m}=\frac{(L\mathrm{\Delta }s{)}_{\ell ,m}}{4\pi V_m(\mathrm{\Delta }\lambda {)}_{\ell }}$$

where $\ell$ is the index of the wavelength bin, $(\mathrm{\Delta }\lambda {)}_{\ell }$ is the wavelength bin width, $m$ is the spatial cell index, $V_m$ is the volume of the cell, and $(L\mathrm{\Delta }s{)}_{\ell ,m}$ has been accumulated over all photon packets contributing to the bin. The resulting mean intensity $J_{\lambda }$ is expressed as an amount of energy per unit of time, per unit of area, per unit of wavelength, and per unit of solid angle.

media()

MediumSystem::media ( ) const

inline

This function returns the value of the discoverable item list property media : "the transfer media" .

This property is relevant only if the Boolean expression "!NoMedium" evaluates to true after replacing the names by true or false depending on their presence.

The default value for this property is given by the conditional value expression "GeometricMedium" .

This property is required only if the Boolean expression "!NoMedium" evaluates to true after replacing the names by true or false depending on their presence.

metallicity()

double MediumSystem::metallicity	(	int	m,
		int	h
	)		const

This function returns the metallicity $Z$ of the medium component with index $h$ in spatial cell with index $m$. If the specified medium component does not have the metallicity specific state variable, the behavior of this function is undefined.

mix()

const MaterialMix * MediumSystem::mix	(	int	m,
		int	h
	)		const

This function returns the material mix corresponding to the medium component with index $h$ in spatial cell with index $m$.

numberDensity()

double MediumSystem::numberDensity	(	int	m,
		int	h
	)		const

This function returns the number density of the medium component with index $h$ in spatial cell with index $m$.

numCells()

int MediumSystem::numCells

(

)

const

This function returns the number of cells in the spatial grid held by the medium system. The returned value is valid only after setup has been performed.

numMedia()

int MediumSystem::numMedia

(

)

const

This function returns the number of media in the medium system. The returned value is valid only after setup has been performed.

opacityAbs() [1/3]

double MediumSystem::opacityAbs ( double  lambda, int  m, const PhotonPacket *  pp  ) const

private

This function returns the absorption opacity $k^{\text{abs}}=\sum _h{k}_h^{\text{abs}}$ summed over all medium components at wavelength $\lambda$ in spatial cell with index $m$, where applicable taking into account the properties of the specified incoming photon packet (for example, its polarization state).

opacityAbs() [2/3]

double MediumSystem::opacityAbs	(	double	lambda,
		int	m,
		int	h
	)		const

This function returns the absorption opacity $k_h^{\text{abs}}$ at wavelength $\lambda$ of the medium component with index $h$ in spatial cell with index $m$. Because no photon packet is provided, default values are used for any relevant incoming photon packet properties. For example, the radiation is assumed to be unpolarized.

opacityAbs() [3/3]

double MediumSystem::opacityAbs	(	double	lambda,
		int	m,
		MaterialMix::MaterialType	type
	)		const

This function returns the absorption opacity $k^{\text{abs}}=\sum _h{k}_h^{\text{abs}}$ summed over all medium components with the specified material type at wavelength $\lambda$ in spatial cell with index $m$. Because no photon packet is provided, default values are used for any relevant incoming photon packet properties. For example, the radiation is assumed to be unpolarized.

opacityExt() [1/4]

double MediumSystem::opacityExt	(	double	lambda,
		int	m
	)		const

This function returns the extinction opacity $k^{\text{ext}}=\sum _h{k}_h^{\text{ext}}$ summed over all medium components at wavelength $\lambda$ in spatial cell with index $m$. Because no photon packet is provided, default values are used for any relevant incoming photon packet properties. For example, the radiation is assumed to be unpolarized.

opacityExt() [2/4]

double MediumSystem::opacityExt ( double  lambda, int  m, const PhotonPacket *  pp  ) const

private

This function returns the extinction opacity $k^{\text{ext}}=\sum _h{k}_h^{\text{ext}}$ summed over all medium components at wavelength $\lambda$ in spatial cell with index $m$, where applicable taking into account the properties of the specified incoming photon packet (for example, its polarization state).

opacityExt() [3/4]

double MediumSystem::opacityExt	(	double	lambda,
		int	m,
		int	h
	)		const

This function returns the extinction opacity $k_h^{\text{ext}}$ at wavelength $\lambda$ of the medium component with index $h$ in spatial cell with index $m$. Because no photon packet is provided, default values are used for any relevant incoming photon packet properties. For example, the radiation is assumed to be unpolarized.

opacityExt() [4/4]

double MediumSystem::opacityExt	(	double	lambda,
		int	m,
		MaterialMix::MaterialType	type
	)		const

This function returns the extinction opacity $k^{\text{ext}}=\sum _h{k}_h^{\text{ext}}$ summed over all medium components with the specified material type at wavelength $\lambda$ in spatial cell with index $m$. Because no photon packet is provided, default values are used for any relevant incoming photon packet properties. For example, the radiation is assumed to be unpolarized.

opacitySca() [1/2]

double MediumSystem::opacitySca ( double  lambda, int  m, const PhotonPacket *  pp  ) const

private

This function returns the scattering opacity $k^{\text{sca}}=\sum _h{k}_h^{\text{sca}}$ summed over all medium components at wavelength $\lambda$ in spatial cell with index $m$, where applicable taking into account the properties of the specified incoming photon packet (for example, its polarization state).

opacitySca() [2/2]

double MediumSystem::opacitySca	(	double	lambda,
		int	m,
		int	h
	)		const

This function returns the scattering opacity $k_h^{\text{sca}}$ at wavelength $\lambda$ of the medium component with index $h$ in spatial cell with index $m$. Because no photon packet is provided, default values are used for any relevant incoming photon packet properties. For example, the radiation is assumed to be unpolarized.

peelOffScattering() [1/2]

void MediumSystem::peelOffScattering	(	const ShortArray &	wv,
		double	lambda,
		Direction	bfkobs,
		Direction	bfky,
		PhotonPacket *	pp,
		PhotonPacket *	ppp
	)		const

This function calculates the consolidated peel-off photon luminosity and polarization state for all medium components with the specified opacity weights and for the given perceived wavelength, geometry, and incoming photon packet. The specified placeholder peel-off photon packet is then launched using this information so that it is ready for detection by instruments. If there are multiple medium components, the contributions to the luminosity (and if polarization is enabled, to the other components of the Stokes vector) are weighted by the specified relative opacities of the various medium components.

This function should be called only when scattering events cannot change the wavelength, i.e. the hasScatteringDispersion() function returns false for all material mixes in the simulation. In this case, a single consolidated peel-off photon packet can be sent to each intrument.

peelOffScattering() [2/2]

void MediumSystem::peelOffScattering	(	int	h,
		double	w,
		double	lambda,
		Direction	bfkobs,
		Direction	bfky,
		PhotonPacket *	pp,
		PhotonPacket *	ppp
	)		const

This function calculates the peel-off photon luminosity, polarization state, and wavelength for the specified medium component with the specified opacity weight and for the given perceived wavelength, geometry, and incoming photon packet. The specified placeholder peel-off photon packet is then launched using this information so that it is ready for detection by instruments.

This function should be used when scattering events may change the wavelength, i.e. the hasScatteringDispersion() function returns true for one or more material mixes in the simulation. In this case, a seperate peel-off photon packet for each medium component must be sent to each intrument.

perceivedWavelengthForScattering()

double MediumSystem::perceivedWavelengthForScattering

(

const PhotonPacket *

pp

)

const

This function returns the perceived wavelength of the photon packet at the scattering interaction distance, taking into account the bulk velocity and Hubble expansion velocity in that cell.

photonPacketOptions()

MediumSystem::photonPacketOptions ( ) const

inline

This function returns the value of the discoverable item property photonPacketOptions : "the photon packet options" .

The default value for this property is given by the conditional value expression "PhotonPacketOptions" .

radiationField()

double MediumSystem::radiationField ( int  m, int  ell  ) const

private

This function returns the sum of the values in both the primary and the stable secondary radiation field tables at the specified cell and wavelength indices. If a table is not present, the value for that table is assumed to be zero.

radiationFieldOptions()

MediumSystem::radiationFieldOptions ( ) const

inline

This function returns the value of the discoverable item property radiationFieldOptions : "the radiation field options" .

The default value for this property is given by the conditional value expression "RadiationFieldOptions" .

This property is relevant only if the Boolean expression "!NoMedium" evaluates to true after replacing the names by true or false depending on their presence.

samplingOptions()

MediumSystem::samplingOptions ( ) const

inline

This function returns the value of the discoverable item property samplingOptions : "the spatial grid sampling options" .

The default value for this property is given by the conditional value expression "SamplingOptions" .

secondaryEmissionOptions()

MediumSystem::secondaryEmissionOptions ( ) const

inline

This function returns the value of the discoverable item property secondaryEmissionOptions : "the secondary emission options" .

The default value for this property is given by the conditional value expression "SecondaryEmissionOptions" .

This property is relevant only if the Boolean expression "Emission" evaluates to true after replacing the names by true or false depending on their presence.

setExtinctionOpticalDepths()

void MediumSystem::setExtinctionOpticalDepths

(

PhotonPacket *

pp

)

const

This function calculates the cumulative extinction optical depth at the end of each path segment along a path through the medium system defined by the initial position and direction of the specified PhotonPacket object, and stores the results of the calculation into the same PhotonPacket object.

This function is intended for handling random-walk photon packet paths during a photon life cycle that does use forced-scattering, requiring the optical depth to be calculated for the full path until it reaches the model boundary. Moreover, the function is intended for a photon life cycle that does not use explicit absorption, so it suffices to consider the extinction optical depth (without discriminating between scattering and absorption).

Because the function is at the heart of the photon life cycle, performance is important. Firstly, separating the geometric and optical depth calculations seems to be faster, probably due to memory access and caching issues. So the function first determines and stores the path segments and then calculates and stores the cumulative optical depth at the end of each segment. Secondly, the function implements optimized versions for media with spatially constant cross sections.

With the geometric path information given, the function calculates the extinction optical depth for each path segment $(\mathrm{\Delta }s{)}_m$ as it crosses the spatial cell with index $m$ as

$${\tau }_m^{\text{ext}}=(\mathrm{\Delta }s{)}_m\sum _h{k}_{m,h}^{\text{ext}},$$

where $k_{m,h}^{\text{ext}}$ is the extinction opacity corresponding to the $h$'th medium component in the cell with index $m$ and the sum over $h$ runs over all medium components. The opacities $k_{m,h}^{\text{ext}}$ are calculated at the wavelength perceived by the medium in cell $m$ taking into account the bulk velocity and Hubble expansion velocity in that cell, and taking into account any relevant properties of the incoming photon packet such as the polarization state.

Using these optical depth values per segment, the function determines the cumulative optical depths at the segment exit boundaries and stores them into the specified photon packet object. Note that the optical depth at entry of the initial segment is equal to zero by definition.

setInteractionPointUsingExtinction()

bool MediumSystem::setInteractionPointUsingExtinction	(	PhotonPacket *	pp,
		double	tauinteract
	)		const

This function calculates the cumulative extinction optical depth and distance at the end of path segments along a path through the medium system defined by the initial position and direction of the specified PhotonPacket object until the specified interaction optical depth has been reached. The function then interpolates the extinction optical depth and distance at the interaction point, stores these values in the photon packet, and returns true. If the specified interaction optical depth is never reached within the path, the function returns false.

This function is intended for handling random-walk photon packet paths during a photon life cycle that does not use forced-scattering. In that case there is no need to calculate the complete path, substantially boosting performance in high-optical depth media. Moreover, the function is intended for a photon life cycle that does not use explicit absorption, so it suffices to consider the extinction optical depth (without discriminating between scattering and absorption). Because the function is at the heart of the photon life cycle, performance is important. Hence it implements optimized versions for media with spatially constant cross sections.

The optical depth for each traversed path segment is calculated as described for the setExtinctionOpticalDepths() function, i.e. at the wavelength perceived by the medium in the cell being crossed and taking into account any relevant properties of the incoming photon packet.

setInteractionPointUsingScatteringAndAbsorption()

bool MediumSystem::setInteractionPointUsingScatteringAndAbsorption	(	PhotonPacket *	pp,
		double	tauinteract
	)		const

This function calculates the cumulative scattering optical depth, the cumulative absorption optical depth, and the distance at the end of each of the path segments along a path through the medium system defined by the initial position and direction of the specified PhotonPacket object. The calculation proceeds until the scattering optical depth reaches the specified interaction optical depth. The function then interpolates the scattering optical depth, the cumulative absorption optical depth, and the distance at the interaction point, stores these values in the photon packet, and returns true. If the specified interaction optical depth is never reached within the path, the function returns false.

This function is intended for handling random-walk photon packet paths during a photon life cycle that does not use forced-scattering. In that case there is no need to calculate the complete path, substantially boosting performance in high-optical depth media. Moreover, the function is intended for a photon life cycle that does use explicit absorption, requiring the separate treatment of scattering and absorption optical depth. Because the function is at the heart of the photon life cycle, performance is important. Hence it implements optimized versions for media with spatially constant cross sections.

The optical depth for each traversed path segment is calculated as described for the setScatteringAndAbsorptionOpticalDepths() function, i.e. at the wavelength perceived by the medium in the cell being crossed and taking into account any relevant properties of the incoming photon packet.

setScatteringAndAbsorptionOpticalDepths()

void MediumSystem::setScatteringAndAbsorptionOpticalDepths

(

PhotonPacket *

pp

)

const

This function calculates the cumulative scattering and absorption optical depths at the end of each path segment along a path through the medium system defined by the initial position and direction of the specified PhotonPacket object, and stores the results of the calculation into the same PhotonPacket object.

This function is intended for handling random-walk photon packet paths during a photon life cycle that does use forced-scattering, requiring the optical depths to be calculated for the full path until it reaches the model boundary. Moreover, the function is intended for a photon life cycle that does use explicit absorption. In this case, the next interaction point is determined based on the scattering optical depth (as opposed to the total extinction optical depth), so we need to calculate and store the scattering and absorption optical depths separately.

Because it is at the heart of the photon life cycle, performance is important. Firstly, separating the geometric and optical depth calculations seems to be faster, probably due to memory access and caching issues. So the function first determines and stores the path segments and then calculates and stores the cumulative optical depths at the end of each segment. Secondly, the function implements optimized versions for media with spatially constant cross sections.

With the geometric path information given, the function calculates the scattering and absorption optical depths for each path segment $(\mathrm{\Delta }s{)}_m$ as it crosses the spatial cell with index $m$ as

$${\tau }_m^{\text{sca,abs}}=(\mathrm{\Delta }s{)}_m\sum _h{k}_{m,h}^{\text{sca,abs}},$$

where $k_{m,h}^{\text{sca,abs}}$ represent the scattering and absorption opacities corresponding to the $h$'th medium component in the cell with index $m$ and the sum over $h$ runs over all medium components. The opacities $k_{m,h}^{\text{sca,abs}}$ are calculated at the wavelength perceived by the medium in cell $m$ taking into account the bulk velocity and Hubble expansion velocity in that cell, and taking into account any relevant properties of the incoming photon packet such as the polarization state.

Using these optical depth values per segment, the function determines the cumulative optical depths at the segment exit boundaries and stores them into the specified photon packet object. Note that the optical depth at entry of the initial segment is equal to zero by definition.

setupSelfAfter()

void MediumSystem::setupSelfAfter ( )

overrideprotectedvirtual

This function calculates and stores initial state information for each spatial cell, including the cell volume and the number density for each medium as defined by the input model. If needed for the simulation's configuration, it also allocates one or two radiation field data tables that have a bin for each spatial cell in the simulation and for each bin in the wavelength grid returned by the Configuration::radiationFieldWLG() function.

Reimplemented from SimulationItem.

simulateScattering()

void MediumSystem::simulateScattering	(	Random *	random,
		PhotonPacket *	pp
	)		const

This function simulates a random walk scattering event of a photon packet. Most of the properties of the photon packet remain unaltered, including the position and the luminosity. The properties that change include the number of scattering events experienced by the photon packet, which is increased by one, the propagation direction, which is generated randomly, the wavelength, which is properly Doppler-shifted for the bulk velocity of the medium, and the polarization state, which may be affected by the scattering process.

If there is only one medium component, the scattering event is governed by the corresponding material mix. If there are several components, the function first randomly selects a medium component from the list, where the relative weight of each component $h$ is determined by the scattering opacity $k_{m,h}^{\text{sca}}$ of the medium component in the scattering interaction cell $m$ obtained from the specified photon packet. These opacities are calculated at the wavelength perceived by the medium in cell $m$ taking into account the bulk velocity and Hubble expansion velocity in that cell, and taking into account any relevant properties of the incoming photon packet such as the polarization state.

Performing the actual scattering event is delegated to the material mix corresponding to the selected medium component in the interaction cell. Refer to the MaterialMix::performScattering() function for more information.

storeRadiationField()

void MediumSystem::storeRadiationField	(	bool	primary,
		int	m,
		int	ell,
		double	Lds
	)

This function adds the specified value of $L\mathrm{\Delta }s$ to the radiation field bin corresponding to the spatial cell index $m$ and the wavelength index $\ell$. If the primary flag is true, the value is added to the primary table; otherwise it is added to the temporary secondary table.

The addition happens in a thread-safe way, so that this function can be called from multiple parallel threads, even for the same spatial/wavelength bin. If any of the indices are out of range, undefined behavior results.

temperature()

double MediumSystem::temperature	(	int	m,
		int	h
	)		const

This function returns the temperature $T$ of the medium component with index $h$ in spatial cell with index $m$. If the specified medium component does not have the temperature specific state variable, the behavior of this function is undefined.

totalDustAbsorbedLuminosity()

std::pair< double, double > MediumSystem::totalDustAbsorbedLuminosity

(

)

const

This function returns a pair of values specifying the bolometric luminosity absorbed by dust media across the complete domain of the spatial grid, respectively using the partial radiation field stored in the primary table and the stable secondary table. The bolometric absorbed luminosity in each cell is calculated as described for the dustLuminosity() function.

updateDynamicStateMedia()

bool MediumSystem::updateDynamicStateMedia ( bool  primary )

private

This function updates the medium state for any media in the simulation with an associated material mix that supports a primary or secondary dynamic medium state, depending on the value of the specified flag. The function returns true if all updates have converged, and false otherwise. It assumes that the radiation field has been calculated and that at least one medium component in the simulation supports a dynamic medium state of the requested type.

updateDynamicStateRecipes()

bool MediumSystem::updateDynamicStateRecipes ( )

private

This function invokes the dynamic medium state recipes configured for this simulation to update the medium state. The function returns true if all recipes have converged, and false otherwise. It assumes that the radiation field has been calculated and that at least one dynamic medium state recipe has been configured for the simulation.

updatePrimaryDynamicMediumState()

bool MediumSystem::updatePrimaryDynamicMediumState

(

)

This function updates the primary dynamic medium state (PDMS) for all spatial cells and medium components based on the currently established radiation field. It invokes any dynamic medium state recipes (instances of a DynamicStateRecipe subclass) configured for this simulation and updates the medium state for any media in the simulation with an associated material mix (instances of a MaterialMix subclass) that supports a PDMS. The function returns true if all updates have converged, and false otherwise.

This function assumes that the radiation field has been calculated.

updateSecondaryDynamicMediumState()

bool MediumSystem::updateSecondaryDynamicMediumState

(

)

This function updates the secondary dynamic medium state (SDMS) for all spatial cells and medium components based on the currently established radiation field. It updates the medium state for any media in the simulation with an associated material mix (instances of a MaterialMix subclass) that supports a SDMS. The function returns true if all updates have converged, and false otherwise.

This function assumes that the radiation field has been calculated.

volume()

double MediumSystem::volume

(

int

m

)

const

This function returns the volume of the spatial cell with index $m$.

weightsForScattering()

bool MediumSystem::weightsForScattering	(	ShortArray &	wv,
		double	lambda,
		const PhotonPacket *	pp
	)		const

This function calculates the relative weights of the medium components in a scattering event, determined by the scattering opacity $k_{m,h}^{\text{sca}}$ of the medium component $h$ in the scattering interaction cell $m$ obtained from the specified photon packet. These opacities are calculated at the specified wavelength (which is assumed to be the wavelength perceived by the medium in cell $m$ taking into account the bulk velocity and Hubble expansion velocity in that cell) and taking into account any relevant properties of the specified photon packet such as the polarization state.

The resulting weights are normalized to a total of unity and stored in the target array. The array is resized appropriately (i.e. to the number of medium components in the simulation). The function returns true if normalized weights have been successfully calculated, and false if all of the weights are zero (i.e. the photon packet does not scatter in this cell).

---

The documentation for this class was generated from the following file:

• MediumSystem.hpp