The SKIRT project
advanced radiative transfer for astrophysics
Public Types | Public Member Functions | Protected Member Functions | Private Types | Private Attributes | Friends | List of all members
MaterialMix Class Referenceabstract

#include <MaterialMix.hpp>

Inheritance diagram for MaterialMix:
Inheritance graph
[legend]

Public Types

enum class  DynamicStateType { None , Primary , Secondary , PrimaryIfMergedIterations }
 
enum class  MaterialType { Dust , Electrons , Gas }
 

Public Member Functions

virtual double asymmpar (double lambda) const
 
virtual Array emissionSpectrum (const MaterialState *state, const Array &Jv) const
 
virtual DisjointWavelengthGridemissionWavelengthGrid () const
 
virtual Array emissivity (const Array &Jv) const
 
virtual bool hasContinuumEmission () const
 
virtual DynamicStateType hasDynamicMediumState () const
 
virtual bool hasExtraSpecificState () const
 
virtual bool hasLineEmission () const
 
virtual bool hasNegativeExtinction () const
 
virtual bool hasPolarizedAbsorption () const
 
virtual bool hasPolarizedEmission () const
 
virtual bool hasPolarizedScattering () const
 
virtual bool hasResonantScattering () const
 
virtual bool hasScatteringDispersion () const
 
virtual bool hasStochasticDustEmission () const
 
virtual double indicativeTemperature (const MaterialState *state, const Array &Jv) const
 
virtual void initializeSpecificState (MaterialState *state, double metallicity, double temperature, const Array &params) const
 
bool isDust () const
 
bool isElectrons () const
 
bool isGas () const
 
virtual bool isSpecificStateConverged (int numCells, int numUpdated, int numNotConverged, MaterialState *currentAggregate, MaterialState *previousAggregate) const
 
virtual Array lineEmissionCenters () const
 
virtual Array lineEmissionMasses () const
 
virtual Array lineEmissionSpectrum (const MaterialState *state, const Array &Jv) const
 
virtual double mass () const =0
 
virtual MaterialType materialType () const =0
 
virtual double opacityAbs (double lambda, const MaterialState *state, const PhotonPacket *pp) const =0
 
virtual double opacityExt (double lambda, const MaterialState *state, const PhotonPacket *pp) const =0
 
virtual double opacitySca (double lambda, const MaterialState *state, const PhotonPacket *pp) const =0
 
virtual vector< SnapshotParameterparameterInfo () const
 
virtual void peeloffScattering (double &I, double &Q, double &U, double &V, double &lambda, Direction bfkobs, Direction bfky, const MaterialState *state, const PhotonPacket *pp) const =0
 
virtual void performScattering (double lambda, const MaterialState *state, PhotonPacket *pp) const =0
 
virtual double sectionAbs (double lambda) const =0
 
virtual double sectionExt (double lambda) const =0
 
virtual const ArraysectionsAbs (double lambda) const
 
virtual const ArraysectionsAbspol (double lambda) const
 
virtual double sectionSca (double lambda) const =0
 
virtual vector< StateVariablespecificStateVariableInfo () const =0
 
virtual const ArraythetaGrid () const
 
virtual UpdateStatus updateSpecificState (MaterialState *state, const Array &Jv) 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 ItemgetItemProperty (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)
 
Itemoperator= (const Item &)=delete
 
Itemparent () 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

 MaterialMix ()
 
Configurationconfig () const
 
Randomrandom () const
 
void setupSelfBefore () 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 = MaterialMix
 

Private Attributes

Configuration_config
 
Random_random
 

Friends

class ItemRegistry
 

Detailed Description

MaterialMix is the abstract base class for all classes representing the concrete material properties of a specific transfer medium. The MaterialMix class hierarchy allows fundamentally different material types (e.g. dust, electrons, and hydrogen-dominated gas) to be implemented as part of a single framework.

Instances of MaterialMix subclasses are immutable after setup has been completed, so the same instance can be reused in multiple contexts.

Material properties

The medium state maintained by a simulation for each cell and medium component includes a pointer to a MaterialMix instance defining the properties of the material, and a number density value defining the amount of material present in the cell per unit of volume. The kind of physical entity being counted by the number density and the conversion from number density to mass density depend on the type of material, as indicated in the table below.

Material type Entity counted Mass conversion
Dust hydrogen atom dust mass per hydrogen atom
Electrons electron electron mass
Gas hydrogen atom gas mass per hydrogen atom

The following table lists some relevant physical quantities including cell properties that may be traced by a simulation, material properties defined by material mixes, and properties that can be derived from these.

Symbol Units Description
\(\Delta s\) \(m\) Distance along a path
\(V\) \(\text{m}^3\) Volume
\(v\) \(\text{m}\,\text{s}^{-1}\) Bulk velocity
\(\bf{B}\) \(\text{T}\) Magnetic field vector
\(T\) \(\text{K}\) Temperature
\(n\) \(\#\,\text{m}^{-3}\) Number density (of entities)
\(\mu\) \(\text{kg}\,\#^{-1}\) Mass per entity
\(\varsigma\) \(\text{m}^2\,\#^{-1}\) Cross section per entity
\(\mathcal{N}=n\Delta s\) \(\#\,\text{m}^{-2}\) Number column density
\(N=nV\) \(\#\) Number (of entities)
\(\rho=n\mu\) \(\text{kg}\,\text{m}^{-3}\) Mass density
\(\Sigma=n\mu\Delta s\) \(\text{kg}\,\text{m}^{-2}\) Mass column density
\(M=n\mu V\) \(\text{kg}\) Mass
\(\kappa=\varsigma/\mu\) \(\text{m}^2\,\text{kg}^{-1}\) Mass coefficient
\(k=n\varsigma\) \(\text{m}^{-1}\) Opacity
\(\tau=n\varsigma\Delta s\) \(1\) Optical depth

Capabilities functions

The abstract interface defined by the MaterialMix base class allows handling essentially all aspects of the simulation with respect to a material of a given type, including absorption, scattering, and secondary emission of photon packets. The base class does not provide any functionality, so everything must be implemented in subclasses.

Because not all physical processes are relevant for (or supported by) all material types, the MaterialMix interface includes a set of functions to define the capabilities of a given concrete material mix. On a basic level, the materialType() function returns the overall material category (dust, gas, or electrons). In addition, there are a number of Boolean functions that indicate whether a certain physical process is supported.

This approach allows fine-grained run-time discovery of capabilities. The functions can be used, for example, during setup to ensure that the configuration is valid (e.g., all material mixes support stochastic heating when enabled in the configuration), to enable or disable optimizations (e.g., when calculating optical depth), and to enable probing of the appropriate information (e.g., producing separate density cuts for dust, gas, and electrons).

Most MaterialMix subclasses implement no public functions outside of those defined in this base class. However, sometimes specific features require external access to additional information offered by a material mix. For example, MultiGrainDustMix subclasses offer access to individual grain populations for use in probes or dust destruction recipes. In those contexts, it is acceptable to apply a dynamic cast to discover whether a given material mix offers the relevant extended interface.

Medium state setup functions

The MaterialMix class hierarchy offers a number of functions that advertise the required medium state variables and assist with initializing their values during setup. For example, the specificStateVariableInfo() function returns a list of medium state variable descriptors specifying the specific state variables used by the material mix. This allows the medium system to allocate storage for the appropriate set of state variables.

All common state variables and the number density (part of the specific state) are initialized by the medium system. Additional specific state variables must be initialized in the initializeSpecificState() material mix function, which is invoked by the medium system for each spatial cell just after the common state variables and the number density have been initialized. If the material mix is configured as part of an imported medium component, extra data fields imported from the snapshot based on the information returned by the parameterInfo() function are passed to this function.

Medium state update functions

As described in the documentation for the MonteCarloSimulation class, the simulation execution flow supports a dynamic medium state (DMS). Specifically, a material mix can provide an algorithm for updating its specific state at the end of a primary or secondary emission segment based on the radiation field calculated during that segment. The hasDynamicMediumState() function indicates if and when the state for this material mix should be updated, and the updateSpecificState() function actually performs such an update.

Low-level material properties functions

The MaterialMix class hierarchy offers functions for retrieving some basic material properties as a function of wavelength, including the absorption cross section, the scattering cross section, and the scattering asymmetry parameter. These functions return default property values, assuming fixed, predefined values for any quantities other than wavelength (e.g., a default temperature, no polarization, no kinematics).

In principle, the values returned by these low-level functions may be used only during setup and for probing. However, some portions of the photon life cycle code might be optimized to use these functions directly in cases where the optical properties are known to depend solely on the photon packet’s wavelength.

High-level functions for photon life cycle

Most importantly, the MaterialMix class hierarchy offers a set of functions that help implement the photon life cycle on a high, generic level. These functions receive at least two arguments: an object representing the medium state for a spatial cell and for a medium component configured with the receiving material mix, and an incoming photon packet. Extra arguments may override information that is also available as part of the state or photon packet, or they may simply provide additional information.

For example, the opacityAbs() and opacitySca() functions return the absorption and scattering opacity \(k=n\varsigma\). They are given a wavelength that overrides the photon packet wavelength. Providing a photon packet is in fact optional so that these functions can be used in situations where there is no photon packet involved, such as when calculating the luminosity absorbed by the dust in a cell.

The propagate() function adjusts the photon packet for any effects caused by propagation over a given distance through the cell. This may include, for example, changes to the polarization state caused by dichroism. The function also returns the total (possibly dichroic) optical depth for the photon packet intensity over the given distance.

The performScattering() function handles a complete random-walk scattering interaction with the medium component of the receiving material mix, including the effects of bulk velocity, polarization, and so forth. The peelOffScattering() function similarly calculates the contribution to a scattering peel-off event for this material, given the instrument reference frame and the relative weight of this medium component.

Functions for secondary continuum emission

The emissivity() function returns the emissivity spectrum of a material mix when it would be embedded in a given radiation field, assuming default values for any specific state variables and assuming isotropic, unpolarized emission. For regular dust mixes that don't vary spatially and that represent spherical grains, the emissivity tells the full story. For other material mixes, it provides just a default.

The emissionSpectrum() function returns the emission spectrum in the spatial cell and medium component represented by the specified material state and the receiving material mix when it would be embedded in the specified radiation field. The returned spectrum takes into account the values of any relevant specific or common state variables, including the number density of the dust in the specified cell.

The remaining functions in this section provide additional optical properties intended for use with the SpheroidalPolarization mode.

Functions for secondary line emission

The lineEmissionSpectrum() function returns the luminosities that will be emitted at the line centers defined by the lineEmissionCenters() function for a material mix with a given material state and embedded in a given radiation field. The caller handling secondary emission will add a Doppler shift corresponding to random thermal motion with particle masses given by the lineEmissionCenters() function. The intrinsic line widths are ignored because they are usually much smaller than the thermal dispersion.

Indicative temperature function

The indicativeTemperature() function returns an indicative temperature with an interpretation depending on the material type. For dust mixes it returns the averaged equilibrium temperature of the grain population given the specified radiation field and assuming local thermal equilibrium conditions. Other materials may return a temperature determined based on the radiation field, the specific state, a default value, or zero if none of the above apply.

Member Enumeration Documentation

◆ DynamicStateType

enum class MaterialMix::DynamicStateType
strong

This enumeration is used to indicate whether a dynamic medium state (DMS) update algorithm is provided, and if so, when it should be executed:

  • None: no DMS update algorithm is provided.
  • Primary: the DMS update affects the opacity for primary emission (PDMS).
  • Secondary: the DMS update affects the secondary emission only (SDMS).
  • PrimaryIfMergedIterations: Primary if the simulation has merged iterations (iterateSecondaryEmission and includePrimaryEmission are both true), and Secondary otherwise.

◆ MaterialType

enum class MaterialMix::MaterialType
strong

This enumeration lists the fundamental material types supported by the MaterialMix class hierarchy.

Constructor & Destructor Documentation

◆ MaterialMix()

MaterialMix::MaterialMix ( )
inlineprotected

Default constructor for abstract Item subclass MaterialMix : "a material mix" .

Member Function Documentation

◆ asymmpar()

virtual double MaterialMix::asymmpar ( double  lambda) const
virtual

This function returns the default scattering asymmetry parameter \(g_\lambda = \left<\cos\theta\right>\) at wavelength \(\lambda\). This value serves as a parameter for the Henyey-Greenstein phase function. The default implementation in this base class returns zero, indicating isotropic scattering.

Reimplemented in DustMix, FragmentDustMixDecorator, and TrivialGasMix.

◆ config()

Configuration * MaterialMix::config ( ) const
inlineprotected

This function returns the simulation's configuration object as a service to subclasses.

◆ emissionSpectrum()

virtual Array MaterialMix::emissionSpectrum ( const MaterialState state,
const Array Jv 
) const
virtual

This function returns the continuum emission spectrum (radiated power per unit of solid angle) in the spatial cell and medium component represented by the specified material state and the receiving material mix when it would be embedded in the specified radiation field. The returned spectrum takes into account the values of any specific and common state variables, including the number density of the material in the specified cell. As a result, the spectra returned for multiple media components of the same material type can be aggregated through simple summation. However, the caller is responsible for final normalization after such aggregation has taken place.

The input radiation field must be discretized on the simulation's radiation field wavelength grid as returned by the Configuration::radiationFieldWLG() function. The output emissivity spectrum is discretized on the wavelength grid returned by the emissionWavelengthGrid() function. For more information, refer to the documentation of this function for each material type. The default implementation in this base class throws a fatal error.

Reimplemented in DustMix, and FragmentDustMixDecorator.

◆ emissionWavelengthGrid()

virtual DisjointWavelengthGrid * MaterialMix::emissionWavelengthGrid ( ) const
virtual

If this material mix supports secondary continuum emission, this function returns the wavelength grid on which this emission is discretized. For more information, refer to the documentation of this function for each material type. The default implementation in this base class throws a fatal error.

Reimplemented in DustMix, and FragmentDustMixDecorator.

◆ emissivity()

virtual Array MaterialMix::emissivity ( const Array Jv) const
virtual

This function returns the continuum emissivity spectrum \(\varepsilon_{\ell'}\) (radiated power per unit of solid angle and per material entity) of the material mix when it would be embedded in the radiation field specified by the mean intensities \((J_\lambda)_\ell\), assuming default values for any specific state variables and assuming isotropic, unpolarized emission. For regular dust mixes that don't vary spatially and that represent spherical grains, the emissivity tells the full story. For other material mixes, it provides just a default or it is not implemented.

The input radiation field must be discretized on the simulation's radiation field wavelength grid as returned by the Configuration::radiationFieldWLG() function. The output emissivity spectrum is discretized on the wavelength grid returned by the emissionWavelengthGrid() function. For more information, refer to the documentation of this function for each material type. The default implementation in this base class throws a fatal error.

Reimplemented in DustMix, FragmentDustMixDecorator, and MultiGrainDustMix.

◆ hasContinuumEmission()

virtual bool MaterialMix::hasContinuumEmission ( ) const
virtual

This function returns true if this material mix supports secondary continuum emission, i.e. with an emission spectrum discretized over a wavelength grid with adjacent bins. The default implementation in this base class returns false.

Reimplemented in DustMix, and FragmentDustMixDecorator.

◆ hasDynamicMediumState()

virtual DynamicStateType MaterialMix::hasDynamicMediumState ( ) const
virtual

This function returns an enumeration indicating whether the material mix offers an algorithm to update its specific medium state, and if so, when the updateSpecificState() function should be called. Refer to the documentation of the MonteCarloSimulation class for more information on dynamic medium state (DMS) support.

The default implementation in this base class returns DynamicStateType::None.

Reimplemented in NonLTELineGasMix, and SpinFlipHydrogenGasMix.

◆ hasExtraSpecificState()

virtual bool MaterialMix::hasExtraSpecificState ( ) const
virtual

This function returns true if the cross sections returned by this material mix may depend on the values of specific state variables other than the number density, and false otherwise. The default implementation in this base class returns false.

Reimplemented in FragmentDustMixDecorator, LyaNeutralHydrogenGasMix, NonLTELineGasMix, SpinFlipAbsorptionMix, and SpinFlipHydrogenGasMix.

◆ hasLineEmission()

virtual bool MaterialMix::hasLineEmission ( ) const
virtual

This function returns true if this material mix supports secondary line emission, i.e. emission at discrete wavelengths. The default implementation in this base class returns false.

Reimplemented in NonLTELineGasMix, and SpinFlipHydrogenGasMix.

◆ hasNegativeExtinction()

virtual bool MaterialMix::hasNegativeExtinction ( ) const
virtual

This function returns true if the extinction cross section (the sum of the absorption and scattering cross section) for this material mix can be negative, and false otherwise. The default implementation in this base class returns false.

For all material mixes, the scattering cross section must always be positive or zero for all wavelengths and material properties. The absorption cross section at a given wavelength can be negative if the material exhibits stimulated emission at that wavelength. As long as the magnitude of the absorption cross section is guaranteed to be smaller than the scattering cross section, the extinction cross section (the sum of both cross sections) always remains positive, and this function can safely return false. As soon as the magnitude of the negative absorption cross section can be larger than the scattering cross section for some wavelengths and material properties, this function must return true. This allows the photon cycle machinery to properly handle negative extinction cross sections and the corresponding negative optical depths.

Reimplemented in NonLTELineGasMix, and TrivialGasMix.

◆ hasPolarizedAbsorption()

virtual bool MaterialMix::hasPolarizedAbsorption ( ) const
virtual

This function returns true if the absorption of radiation for this material mix is dichroic (i.e. the absorption cross section depends on the polarization state of incoming photon and the polarization state is adjusted during absorption), and false otherwise. If hasPolarizedAbsorption() returns true, hasPolarizedScattering() must return true as well. The default implementation in this base class returns false.

◆ hasPolarizedEmission()

virtual bool MaterialMix::hasPolarizedEmission ( ) const
virtual

This function returns true if the secondary emission for this material mix is or may be polarized and anisotropic, and false otherwise. If hasPolarizedEmission() returns true, hasPolarizedScattering() must return true as well. The default implementation in this base class returns false.

Reimplemented in ConfigurableDustMix.

◆ hasPolarizedScattering()

virtual bool MaterialMix::hasPolarizedScattering ( ) const
virtual

This function returns true if this material mix supports polarization during scattering events, and false otherwise. The default implementation in this base class returns false.

Reimplemented in ConfigurableDustMix, ElectronMix, FragmentDustMixDecorator, LyaNeutralHydrogenGasMix, MeanPinteBenchmarkDustMix, MeanTrustBenchmarkDustMix, and XRayAtomicGasMix.

◆ hasResonantScattering()

virtual bool MaterialMix::hasResonantScattering ( ) const
virtual

This function returns true if scattering for this material mix is resonant (such as for Lyman-alpha), and false otherwise. The default implementation in this base class returns false.

Reimplemented in LyaNeutralHydrogenGasMix.

◆ hasScatteringDispersion()

virtual bool MaterialMix::hasScatteringDispersion ( ) const
virtual

This function returns true if a scattering interaction for this material mix may adjust the wavelength of the interacting photon packet, and false otherwise. The default implementation in this base class returns false.

Reimplemented in ElectronMix, LyaNeutralHydrogenGasMix, and XRayAtomicGasMix.

◆ hasStochasticDustEmission()

virtual bool MaterialMix::hasStochasticDustEmission ( ) const
virtual

This function returns true if this material mix represents dust and supports stochastic heating of dust grains for the calculation of secondary emission, and false otherwise. The default implementation in this base class returns false.

Reimplemented in FragmentDustMixDecorator, and MultiGrainDustMix.

◆ indicativeTemperature()

virtual double MaterialMix::indicativeTemperature ( const MaterialState state,
const Array Jv 
) const
virtual

This function returns an indicative temperature for the material represented by the specified material state and the receiving material mix, assuming an embedding radiation field specified by the mean intensities \((J_\lambda)_\ell\), if available.

If the simulation tracks the radiation field, the specified Jv array is discretized on the simulation's radiation field wavelength grid as returned by the Configuration::radiationFieldWLG() function. If the simulation does not track the radiation field, the Jv array passed to this function is empty.

The interpretation of the indicative temperature depends heavily on the material type. For dust mixes, the function returns the averaged equilibrium temperature of the grain population given the specified radiation field and assuming local thermal equilibrium conditions. Other materials may return a temperature determined based on the radiation field and/or the material state, a default value, or zero if none of the above apply. Refer to the description for this function in the various subclasses for more information. The default implementation in this base class throws a fatal error.

Reimplemented in DustMix, ElectronMix, FragmentDustMixDecorator, LyaNeutralHydrogenGasMix, NonLTELineGasMix, SpinFlipAbsorptionMix, SpinFlipHydrogenGasMix, TrivialGasMix, and XRayAtomicGasMix.

◆ initializeSpecificState()

virtual void MaterialMix::initializeSpecificState ( MaterialState state,
double  metallicity,
double  temperature,
const Array params 
) const
virtual

This function initializes any specific state variables requested by this material mix through the specificStateVariableInfo() function except for the number density. The function is invoked by the medium system for each spatial cell after the common state variables and the number density have been initialized to their proper values, and the specific state variables have been initialized to a default value of zero.

If the material mix is configured as part of an imported medium component, the imported metallicity and temperature, if any, and extra parameter fields imported from the snapshot as requested by the parameterInfo() function are passed to this function. If the material mix is configured in a geometric medium component, or if (part of) the information has not been imported, this is indicated for the metallicity and temperature by a negative value and for the custom parameters by an empty array.

The default implementation in this base class does nothing.

Reimplemented in ElectronMix, FragmentDustMixDecorator, LyaNeutralHydrogenGasMix, NonLTELineGasMix, SpinFlipAbsorptionMix, and SpinFlipHydrogenGasMix.

◆ isDust()

bool MaterialMix::isDust ( ) const
inline

This convenience function returns true if the fundamental material type represented by this material mix is Dust, and false otherwise.

◆ isElectrons()

bool MaterialMix::isElectrons ( ) const
inline

This convenience function returns true if the fundamental material type represented by this material mix is Electrons, and false otherwise.

◆ isGas()

bool MaterialMix::isGas ( ) const
inline

This convenience function returns true if the fundamental material type represented by this material mix is Gas, and false otherwise.

◆ isSpecificStateConverged()

virtual bool MaterialMix::isSpecificStateConverged ( int  numCells,
int  numUpdated,
int  numNotConverged,
MaterialState currentAggregate,
MaterialState previousAggregate 
) const
virtual

If this material mix has a dynamic medium state, i.e. if the hasDynamicMediumState() function returns anything other than None, this function is invoked (once) after updateSpecificState() has been called for all spatial cells. The numCells, numUpdated and numNotConverged arguments specify respectively the number of spatial cells in the simulation, the number of cells updated during this update cycle, and the number of updated cells that have not yet converged. The currentAggregate and previousAggregate arguments provide the current and previous aggregate material states for this material mix (for more information, see the section on aggregation in the MediumState class header). Based on this information and any relevant user configuration options, the function returns true if the medium state is considered to be converged and false if not. The default implementation in this base class always returns true.

Reimplemented in NonLTELineGasMix.

◆ lineEmissionCenters()

virtual Array MaterialMix::lineEmissionCenters ( ) const
virtual

If this material mix supports secondary line emission, this function returns a list of the line centers at which this emission occurs. The default implementation in this base class throws a fatal error.

Reimplemented in NonLTELineGasMix, and SpinFlipHydrogenGasMix.

◆ lineEmissionMasses()

virtual Array MaterialMix::lineEmissionMasses ( ) const
virtual

If this material mix supports secondary line emission, this function returns a list of the particle masses for each of the lines returned by the lineEmissionCenters() function. These masses can be used by a caller in conjunction with the temperature stored in the medium state to determine the thermal velocity distribution of emitting particles and assign a corresponding random Doppler shift to the wavelength of emitted photon packets. The default implementation in this base class throws a fatal error.

Reimplemented in NonLTELineGasMix, and SpinFlipHydrogenGasMix.

◆ lineEmissionSpectrum()

virtual Array MaterialMix::lineEmissionSpectrum ( const MaterialState state,
const Array Jv 
) const
virtual

This function returns the line emission spectrum (radiated power per unit of solid angle) in the spatial cell and medium component represented by the specified material state and the receiving material mix when it would be embedded in the specified radiation field. The returned spectrum takes into account the values of any specific and common state variables, including the number density of the material in the specified cell. The returned values correspond to each of the lines returned by the lineEmissionCenters() function. The default implementation in this base class throws a fatal error.

Reimplemented in NonLTELineGasMix, and SpinFlipHydrogenGasMix.

◆ mass()

virtual double MaterialMix::mass ( ) const
pure virtual

This function returns the mass per entity \(\mu\) for this material. The table below indicates the precise meaning of this number depending on the type of material being represented.

Material type Interpretation of mass() return value
Dust dust mass per hydrogen atom
Electrons electron mass
Gas gas mass per hydrogen atom

Implemented in DustMix, ElectronMix, FragmentDustMixDecorator, LyaNeutralHydrogenGasMix, NonLTELineGasMix, SpinFlipAbsorptionMix, SpinFlipHydrogenGasMix, TrivialGasMix, and XRayAtomicGasMix.

◆ materialType()

virtual MaterialType MaterialMix::materialType ( ) const
pure virtual

This function returns the fundamental material type represented by this material mix. See the documentation of the MaterialMix class for more information.

Implemented in DustMix, ElectronMix, EmittingGasMix, FragmentDustMixDecorator, LyaNeutralHydrogenGasMix, SpinFlipAbsorptionMix, TrivialGasMix, and XRayAtomicGasMix.

◆ opacityAbs()

virtual double MaterialMix::opacityAbs ( double  lambda,
const MaterialState state,
const PhotonPacket pp 
) const
pure virtual

This function returns the absorption opacity \(k^\text{abs}=n\varsigma^\text{abs}\) for the given wavelength, material state, and photon properties (optional; may be nullptr).

Implemented in DustMix, ElectronMix, FragmentDustMixDecorator, LyaNeutralHydrogenGasMix, NonLTELineGasMix, SpinFlipAbsorptionMix, SpinFlipHydrogenGasMix, TrivialGasMix, and XRayAtomicGasMix.

◆ opacityExt()

virtual double MaterialMix::opacityExt ( double  lambda,
const MaterialState state,
const PhotonPacket pp 
) const
pure virtual

This function returns the extinction opacity \(k^\text{ext}=k^\text{abs}+k^\text{sca}\) for the given wavelength, material state, and photon properties (optional; may be nullptr).

Implemented in DustMix, ElectronMix, FragmentDustMixDecorator, LyaNeutralHydrogenGasMix, NonLTELineGasMix, SpinFlipAbsorptionMix, SpinFlipHydrogenGasMix, TrivialGasMix, and XRayAtomicGasMix.

◆ opacitySca()

virtual double MaterialMix::opacitySca ( double  lambda,
const MaterialState state,
const PhotonPacket pp 
) const
pure virtual

This function returns the scattering opacity \(k^\text{sca}=n\varsigma^\text{sca}\) for the given wavelength, material state, and photon properties (optional; may be nullptr).

Implemented in DustMix, ElectronMix, FragmentDustMixDecorator, LyaNeutralHydrogenGasMix, NonLTELineGasMix, SpinFlipAbsorptionMix, SpinFlipHydrogenGasMix, TrivialGasMix, and XRayAtomicGasMix.

◆ parameterInfo()

virtual vector< SnapshotParameter > MaterialMix::parameterInfo ( ) const
virtual

This function returns the number and type of import parameters required by this particular material mix as a list of SnapshotParameter objects. Each of these objects specifies unit information and a human-readable descripton for the parameter. The default implementation in this base class returns an empty list.

Important note: for historical reasons, a metallicity and/or temperature import column can be configured explicitly by the user. If so, these values are made available to the material mix seperately from and in addition to the parameters requested here; see the initializeSpecificState() function. Consequently, it is not allowed for a material mix to request an additional metallicity and/or temperature parameter with the parameterInfo() function.

Reimplemented in FragmentDustMixDecorator, NonLTELineGasMix, and SpinFlipHydrogenGasMix.

◆ peeloffScattering()

virtual void MaterialMix::peeloffScattering ( double &  I,
double &  Q,
double &  U,
double &  V,
double &  lambda,
Direction  bfkobs,
Direction  bfky,
const MaterialState state,
const PhotonPacket pp 
) const
pure virtual

This function calculates the contribution of the medium component associated with this material mix to the peel-off photon luminosity, polarization state, and wavelength shift for the given wavelength, geometry, material state, and photon properties. The contributions to the Stokes vector components are stored in the I, Q, U, V arguments, which are guaranteed to be initialized to zero by the caller. If there is a wavelength shift, the new wavelength value replaces the incoming value of the lambda argument.

Since we force the peel-off photon packet to be scattered from the direction \({\bf{k}}\) into the direction \({\bf{k}}_{\text{obs}}\), the corresponding biasing factor is given by the probability that a photon packet would be scattered into the direction \({\bf{k}}_{\text{obs}}\) if its original propagation direction was \({\bf{k}}\). For a given medium component, this biasing factor is equal to the value of the scattering phase function \(\Phi({\bf{k}},{\bf{k}}_{\text{obs}})\) for that medium component.

Implemented in DustMix, ElectronMix, FragmentDustMixDecorator, LyaNeutralHydrogenGasMix, NonLTELineGasMix, SpinFlipAbsorptionMix, SpinFlipHydrogenGasMix, TrivialGasMix, and XRayAtomicGasMix.

◆ performScattering()

virtual void MaterialMix::performScattering ( double  lambda,
const MaterialState state,
PhotonPacket pp 
) const
pure virtual

This function performs a scattering event on the specified photon packet in the spatial cell and medium component represented by the specified material state and the receiving material mix. 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.

The calculation takes all physical processes into account, including the bulk velocity and Hubble expansion velocity in the cell, any relevant material state variables such as the temperature of a gas medium, and any relevant properties of the incoming photon packet such as the polarization state. The first argument specifies the perceived wavelength of the photon packet at the scattering location so that this value does not need to be recalculated within the function.

Implemented in DustMix, ElectronMix, FragmentDustMixDecorator, LyaNeutralHydrogenGasMix, NonLTELineGasMix, SpinFlipAbsorptionMix, SpinFlipHydrogenGasMix, TrivialGasMix, and XRayAtomicGasMix.

◆ random()

Random * MaterialMix::random ( ) const
inlineprotected

This function returns the simulation's random generator as a service to subclasses.

◆ sectionAbs()

virtual double MaterialMix::sectionAbs ( double  lambda) const
pure virtual

This function returns the default absorption cross section per entity \(\varsigma^{\text{abs}}_{\lambda}\) at wavelength \(\lambda\).

Implemented in DustMix, ElectronMix, FragmentDustMixDecorator, LyaNeutralHydrogenGasMix, NonLTELineGasMix, SpinFlipAbsorptionMix, SpinFlipHydrogenGasMix, TrivialGasMix, and XRayAtomicGasMix.

◆ sectionExt()

virtual double MaterialMix::sectionExt ( double  lambda) const
pure virtual

This function returns the default extinction cross section per entity \(\varsigma^{\text{ext}}_{\lambda} = \varsigma^{\text{abs}}_{\lambda} + \varsigma^{\text{sca}}_{\lambda}\) at wavelength \(\lambda\).

Implemented in DustMix, ElectronMix, FragmentDustMixDecorator, LyaNeutralHydrogenGasMix, NonLTELineGasMix, SpinFlipAbsorptionMix, SpinFlipHydrogenGasMix, TrivialGasMix, and XRayAtomicGasMix.

◆ sectionsAbs()

virtual const Array & MaterialMix::sectionsAbs ( double  lambda) const
virtual

This function is intended for use with the SpheroidalPolarization mode. It returns the absorption cross sections per entity \(\varsigma ^{\text{abs}} _{\lambda} (\theta)\) at wavelength \(\lambda\) as a function of the emission angle \(\theta\), discretized on the grid returned by the thetaGrid() function. The default implementation in this base class throws a fatal error.

Reimplemented in DustMix.

◆ sectionsAbspol()

virtual const Array & MaterialMix::sectionsAbspol ( double  lambda) const
virtual

This function is intended for use with the SpheroidalPolarization mode. It returns the linear polarization absorption cross sections per entity \(\varsigma ^{\text{abspol}} _{\lambda} (\theta)\) at wavelength \(\lambda\) as a function of the emission angle \(\theta\), discretized on the grid returned by the thetaGrid() function. The default implementation in this base class throws a fatal error.

Reimplemented in DustMix.

◆ sectionSca()

virtual double MaterialMix::sectionSca ( double  lambda) const
pure virtual

This function returns the default scattering cross section per entity \(\varsigma^{\text{sca}}_{\lambda}\) at wavelength \(\lambda\).

Implemented in DustMix, ElectronMix, FragmentDustMixDecorator, LyaNeutralHydrogenGasMix, NonLTELineGasMix, SpinFlipAbsorptionMix, SpinFlipHydrogenGasMix, TrivialGasMix, and XRayAtomicGasMix.

◆ setupSelfBefore()

void MaterialMix::setupSelfBefore ( )
overrideprotectedvirtual

This function caches the simulation's random generator for use by subclasses.

Reimplemented from SimulationItem.

Reimplemented in MRNDustMix, NonLTELineGasMix, SpinFlipHydrogenGasMix, ThemisDustMix, TrustBenchmarkDustMix, WeingartnerDraineDustMix, XRayAtomicGasMix, and ZubkoDustMix.

◆ specificStateVariableInfo()

virtual vector< StateVariable > MaterialMix::specificStateVariableInfo ( ) const
pure virtual

This function returns a list of StateVariable objects describing the specific state variables used by the receiving material mix. This allows the MediumSystem class to allocate storage for the appropriate set of state variables, and it allows probing the relevant medium state variables for output. See the StateVariable class for more info.

Common state variables should not be listed; their presence is derived from other aspects of the configured medium components. On the other hand, all specific state variables used by the material mix must be listed, including those that should always present. Variables of type Custom must be listed last. Multiple variables of type Custom can be requested by supplying indices in the range \( 0 \le k < K\), where K is the total number of custom variables. Each of these indices must occur in the list exactly once in increasing order.

Implemented in DustMix, ElectronMix, FragmentDustMixDecorator, LyaNeutralHydrogenGasMix, NonLTELineGasMix, SpinFlipAbsorptionMix, SpinFlipHydrogenGasMix, TrivialGasMix, and XRayAtomicGasMix.

◆ thetaGrid()

virtual const Array & MaterialMix::thetaGrid ( ) const
virtual

This function is intended for use with the SpheroidalPolarization mode. It returns the grid used for discretizing quantities that are a function of the scattering/emission angle \(\theta\). The same grid is returned by all material mixes that have SpheroidalPolarization mode. The default implementation in this base class throws a fatal error.

Reimplemented in DustMix.

◆ updateSpecificState()

virtual UpdateStatus MaterialMix::updateSpecificState ( MaterialState state,
const Array Jv 
) const
virtual

If this material mix has a dynamic medium state, i.e. if the hasDynamicMediumState() function returns anything other than None, this function is invoked for each spatial cell at the end of each relevant primary or secondary emission segment. Based on the specified radiation field, if needed, the function updates any values in the specific material state for this cell and medium component that may inform the local emission and/or extinction properties of the material. The function returns the update status as described for the UpdateStatus class. This information is used to optimize the synchronization of changes across multiple processes and to determine whether an iterative update has converged, if applicable.

This function may be called in parallel across multiple threads and processes. It should not update any information outside the specific medium state of the given cell and medium component. The default implementation in this base class throws a fatal error.

Reimplemented in NonLTELineGasMix, and SpinFlipHydrogenGasMix.


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