#include <ImportedSource.hpp>

Inheritance diagram for ImportedSource:

[legend]

Public Member Functions
int	dimension () const override

string	filename () const

bool	hasVelocity () const override

bool	importBias () const

bool	importCurrentMass () const

bool	importVelocity () const

bool	importVelocityDispersion () const

void	launch (PhotonPacket *pp, size_t historyIndex, double L) const override

double	luminosity () const override

double	meanSpecificLuminosity (const Band *band, int m) const

double	meanSpecificLuminosity (Range wavelengthRange, int m) const

void	prepareForLaunch (double sourceBias, size_t firstIndex, size_t numIndices) override

SEDFamily *	sedFamily () const

const Snapshot *	snapshot () const

double	specificLuminosity (double wavelength) const override

double	specificLuminosity (double wavelength, int m) const

string	useColumns () const

Range	wavelengthRange () const override

Public Member Functions inherited from Source
virtual int	dimension () const =0

virtual bool	hasVelocity () const =0

virtual void	launch (PhotonPacket *pp, size_t historyIndex, double L) const =0

virtual double	luminosity () const =0

virtual void	prepareForLaunch (double sourceBias, size_t firstIndex, size_t numIndices)

double	sourceWeight () const

virtual double	specificLuminosity (double wavelength) const =0

double	wavelengthBias () const

WavelengthDistribution *	wavelengthBiasDistribution () 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

Public Member Functions inherited from WavelengthRangeInterface
virtual	~WavelengthRangeInterface ()

virtual Range	wavelengthRange () const =0

Protected Member Functions
	ImportedSource ()

	~ImportedSource ()

virtual Snapshot *	createAndOpenSnapshot ()=0

void	setupSelfAfter () override

Protected Member Functions inherited from Source
	Source ()

void	informAvailableWavelengthRange (Range available, string itemType)

Random *	random () 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 ()

Protected Member Functions inherited from SourceWavelengthRangeInterface
	SourceWavelengthRangeInterface ()

Protected Member Functions inherited from WavelengthRangeInterface
	WavelengthRangeInterface ()

Private Types
using	BaseType = Source

using	ItemType = ImportedSource

Private Attributes
double	_arbitaryWavelength

WavelengthDistribution *	_biasDistribution

Array	_bv

string	_filename

bool	_importBias

bool	_importCurrentMass

bool	_importVelocity

bool	_importVelocityDispersion

vector< size_t >	_Iv

double	_L

Array	_Lbv

Array	_Lv

bool	_oligochromatic

SEDFamily *	_sedFamily

Snapshot *	_snapshot

string	_useColumns

Range	_wavelengthRange

Array	_Wv

double	_xi

Friends
class	ItemRegistry

Detailed Description

ImportedSource is an abstract class representing a primary radiation source with a spatial and spectral luminosity distribution imported from an input file. The input data is usually derived from a hydrodynamical simulation snapshot. Various types of snapshots are supported by subclasses of this class. Refer to the subclass documentation for information on the file format.

Usually, the input file defines a spatial distribution through smoothed particles, which must be interpolated and summed, or through adjacent cells that partition the spatial domain. At the level of this abstract class, we use the generic term entity for referring to either a particle or a cell.

In addition to spatial information, each entity in the snapshot carries properties that allow selecting a particular SED from a parameterized SED family. The present class requires the user to configure an SEDFamily object for this purpose. The number, type, and order of parameters is defined by the SED family. For each entity, the SED family is requested to select and properly scale a specific SED based on the entity's properties. Combining the spatial and spectral information for an entity yields its contribution to the imported radiation source.

The input file may include additional columns as configured by the importXXX options offered by this base class. Most importantly, it may include a bulk velocity vector with an optional velocity dispersion for each entity. When this option is enabled, the appropriate Doppler shift is taken into account when launching photon packets. Apart from the anisotropy resulting from this optional Doppler shift, the radiation emitted by this primary source is always isotropic. It is also always unpolarized.

Furthermore, the input file may include a separate column listing the current mass. When this option is enabled, the provided current mass can be used for probing the input model. This is relevant because SED families usually do not request the current mass as a parameter (they often use the initial mass instead, or do not include direct mass information at all).

Source biasing

Finally, the input file may include a column specifying a source bias weight for the corresponding entity. These bias weights adjust the (relative) number of photon packets launched from each entity. This can be used to increase sampling in regions of interest, for example to reduce Monte Carlo noise in the low-luminosity outskirts of a galaxy model. Specifically, the number of photon packets $N_{m}$ allocated to entity $m$ is given by

$N_{m} = N_{s} [(1 - ξ) \frac{b_{m} L_{m}}{\sum b_{m} L_{m}} + ξ \frac{b_{m}}{\sum b_{m}}]$

where $N_{s}$ is the total number of photon packets to be launched by this source, $b_{m}$ is imported bias weight for entity $m$ , $L_{m}$ is the luminosity of entity $m$ , and $ξ$ is the value of the sourceBias property offered by the SourceSystem class. If the importBias option for this source is disabled (the default), all bias weights are taken to have a value of $b_{m} = 1$ . The above formule then reduces to

$N_{m} = N_{s} [(1 - ξ) \frac{L_{m}}{L} + ξ \frac{1}{M}]$

where $L$ is the total luminosity for this source and $M$ is the total number of entities in this source. In all cases, the value of $ξ$ shifts between luminosity-weighted ( $ξ = 0$ ) and entity-weighted ( $ξ = 1$ ) or any combination thereof.

When an item of this type is used, the names provided by the conditional value expression "Dimension3" are inserted into the name sets used for evaluating Boolean expressions.

Properties of sub-types of this type are listed in user interfaces somewhere in between the properties of this type.

Constructor & Destructor Documentation

◆ ImportedSource()

ImportedSource::ImportedSource ( )

inlineprotected

Default constructor for abstract Item subclass ImportedSource : "a primary source imported from snapshot data" .

◆ ~ImportedSource()

ImportedSource::~ImportedSource ( )

protected

The destructor deletes the snapshot object, if present.

Member Function Documentation

◆ createAndOpenSnapshot()

virtual Snapshot * ImportedSource::createAndOpenSnapshot ( )

protectedpure virtual

This function constructs a new Snapshot object of the type appropriate for the subclass, calls its open() function, and returns a pointer to the object. Ownership of the Snapshot object is transferred to the caller.

Implemented in AdaptiveMeshSource, CellSource, CylindricalCellSource, ParticleSource, SphericalCellSource, and VoronoiMeshSource.

◆ dimension()

int ImportedSource::dimension ( ) const

overridevirtual

This function returns the dimension of the source, which is always 3 for an imported source.

Implements Source.

◆ filename()

string ImportedSource::filename ( ) const

inline

This function returns the value of the discoverable string property filename : "the name of the file to be imported" .

◆ hasVelocity()

bool ImportedSource::hasVelocity ( ) const

overridevirtual

This function returns true if the importVelocity flag is enabled for the source.

Implements Source.

◆ importBias()

ImportedSource::importBias ( ) const

inline

This function returns the value of the discoverable Boolean property importBias : "import a per-particle/cell source bias weight" .

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

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

◆ importCurrentMass()

ImportedSource::importCurrentMass ( ) const

inline

This function returns the value of the discoverable Boolean property importCurrentMass : "import current mass" .

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

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

When a value is entered for this property, the names provided by the conditional value expression "importCurrentMass:CurrentMass" are inserted into the name sets used for evaluating Boolean expressions.

◆ importVelocity()

ImportedSource::importVelocity ( ) const

inline

This function returns the value of the discoverable Boolean property importVelocity : "import velocity components (3 columns)" .

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

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

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

When a value is entered for this property, the names provided by the conditional value expression "importVelocity:SourceVelocity" are inserted into the name sets used for evaluating Boolean expressions.

◆ importVelocityDispersion()

ImportedSource::importVelocityDispersion ( ) const

inline

This function returns the value of the discoverable Boolean property importVelocityDispersion : "import velocity dispersion (spherically symmetric)" .

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

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

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

◆ launch()

void ImportedSource::launch	(	PhotonPacket *	pp,
		size_t	historyIndex,
		double	L
	)		const

overridevirtual

This function causes the photon packet pp to be launched from the source using the given history index and luminosity contribution. It proceeds as follows.

First, the function finds the entity index that corresponding to the history index using the map constructed by the prepareForLaunch() function. It obtains the normalized spectral distribition (and the corresponding cumulative distribution) for that entity from the SED family configured for this source. In fact, the function sets up a thread-local object that caches the spectral distribution for an entity between consecutive invocations of the launch() function. This works even if there are multiple sources of this type because each thread handles a single photon packet at a time.

Subsequently, the function samples a wavelength from the entity's SED, properly handling the configured wavelength biasing, and asks the Snapshot object to generate a random launch position for the entity. If the importVelocity flag is enabled, the function also constructs an object that serves a RedshiftInterface appropriate for the velocity of the entity. Again, this object is allocated in thread-local storage so that it stays around after being handed to the photon packet.

Finally, the function causes the photon packet to be launched with the information described above and an isotropic launch direction.

Implements Source.

◆ luminosity()

double ImportedSource::luminosity ( ) const

overridevirtual

This function returns the luminosity $L$ (i.e. radiative power) of the source integrated over the wavelength range of primary sources (configured for the source system as a whole) and across its complete spatial domain.

Implements Source.

◆ meanSpecificLuminosity() [1/2]

double ImportedSource::meanSpecificLuminosity	(	const Band *	band,
		int	m
	)		const

This function returns the specific luminosity $L_{λ}$ of the source's snapshot entity with index $m$ convolved over the specified broadband, or zero if the band lies outside the wavelength range of primary sources or if the source does not emit in the band's wavelength range. If the entity index is out of range, the behavior is undefined.

This function is intended to provide InputModelProbe instances with access to the luminosity per snapshot entity, information that is not otherwise made available to the simulation. To preserve proper data encapsulation, this function should not be called from anywhere else in the simulation machinery.

◆ meanSpecificLuminosity() [2/2]

double ImportedSource::meanSpecificLuminosity	(	Range	wavelengthRange,
		int	m
	)		const

This function returns the average specific luminosity $L_{λ}$ of the source's snapshot entity with index $m$ in the specified wavelength range, or zero if the wavelength range is outside the wavelength range of primary sources or if the source does not emit in the wavelength range. If the entity index is out of range, the behavior is undefined.

This function is intended to provide InputModelProbe instances with access to the luminosity per snapshot entity, information that is not otherwise made available to the simulation. To preserve proper data encapsulation, this function should not be called from anywhere else in the simulation machinery.

◆ prepareForLaunch()

void ImportedSource::prepareForLaunch	(	double	sourceBias,
		size_t	firstIndex,
		size_t	numIndices
	)

overridevirtual

This function performs some preparations for launching photon packets. It is called in serial mode before each segment of photon packet launches, providing the history indices mapped by the source system to this particular source. See the description of the SourceSystem class for more background information.

This function distributes the provided range of history indices over the individual entities imported by this source, creating a map for use when actually launching the photon packets. The number of photon packets allocated to each entity is determined following the scheme described in the header documentation of this class.

Reimplemented from Source.

◆ sedFamily()

ImportedSource::sedFamily ( ) const

inline

This function returns the value of the discoverable item property sedFamily : "the SED family for assigning spectra to the imported sources" .

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

◆ setupSelfAfter()

void ImportedSource::setupSelfAfter ( )

overrideprotectedvirtual

This function imports the snapshot data from the input file through a Snapshot object of the appropriate type. Specifically, it first calls the createSnapshot() function, which must be implemented in a subclass, to construct and open a Snapshot object of the appropriate type. It then passes the user-configurable options of this class to the Snapshot object and tells it to import the data.

Finally, the function constructs a vector with the luminosities (integrated over the primary source wavelength range) for all imported entities. This information is used when deciding how many photon packets should be launched from each entity.

Reimplemented from SimulationItem.

◆ snapshot()

const Snapshot * ImportedSource::snapshot ( ) const

This function returns (a pointer to) the snapshot object associated with this imported source. It is intended to provide InputModelProbe instances with direct access to the snapshot for probing imported information that is not otherwise made available to the simulation. To preserve proper data encapsulation, this function should not be called from anywhere else in the simulation machinery.

◆ specificLuminosity() [1/2]

double ImportedSource::specificLuminosity ( double wavelength ) const

overridevirtual

This function returns the specific luminosity $L_{λ}$ (i.e. radiative power per unit of wavelength) of the source at the specified wavelength $λ$ , or zero if the wavelength is outside the wavelength range of primary sources (configured for the source system as a whole) or if the source simply does not emit at the wavelength.

Implements Source.

◆ specificLuminosity() [2/2]

double ImportedSource::specificLuminosity	(	double	wavelength,
		int	m
	)		const

This function returns the specific luminosity $L_{λ}$ of the source's snapshot entity with index $m$ at the specified wavelength $λ$ , or zero if the wavelength is outside the wavelength range of primary sources or if the source does not emit at the wavelength. If the entity index is out of range, the behavior is undefined.

This function is intended to provide InputModelProbe instances with access to the luminosity per snapshot entity, information that is not otherwise made available to the simulation. To preserve proper data encapsulation, this function should not be called from anywhere else in the simulation machinery.

◆ useColumns()

ImportedSource::useColumns ( ) const

inline

This function returns the value of the discoverable string property useColumns : "a list of names corresponding to columns in the file to be imported" .

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

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

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

◆ wavelengthRange()

Range ImportedSource::wavelengthRange ( ) const

overridevirtual

This function returns the wavelength range for this source. Outside this range, all luminosities are zero. This source's wavelength range is determined as the intersection of the simulation's source wavelength range (obtained from the simulation configuration) and the intrinsic wavelength range of the SED family associated with the source.

This function implements the SourceWavelengthRangeInterface interface.

Implements WavelengthRangeInterface.

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

ImportedSource.hpp

Public Member Functions

Protected Member Functions

Private Types

Private Attributes

Friends

Detailed Description

Constructor & Destructor Documentation

◆ ImportedSource()

◆ ~ImportedSource()

Member Function Documentation

◆ createAndOpenSnapshot()

◆ dimension()

◆ filename()

◆ hasVelocity()

◆ importBias()

◆ importCurrentMass()

◆ importVelocity()

◆ importVelocityDispersion()

◆ launch()

◆ luminosity()

◆ meanSpecificLuminosity() [1/2]

◆ meanSpecificLuminosity() [2/2]

◆ prepareForLaunch()

◆ sedFamily()

◆ setupSelfAfter()

◆ snapshot()

◆ specificLuminosity() [1/2]

◆ specificLuminosity() [2/2]

◆ useColumns()

◆ wavelengthRange()