 |
The SKIRT project
advanced radiative transfer for astrophysics
|
|
The SKIRT project
advanced radiative transfer for astrophysics
|
#include <PhotonPacket.hpp>
Classes | |
| class | ScatteringInfo |
Public Member Functions | |
| PhotonPacket () | |
| void | applyBias (double w) |
| int | compIndex () const |
| ScatteringInfo * | getScatteringInfo () |
| bool | hasObservedOpticalDepth () const |
| bool | hasPrimaryOrigin () const |
| bool | hasSecondaryOrigin () const |
| size_t | historyIndex () const |
| void | launch (size_t historyIndex, double lambda, double L, Position bfr, Direction bfk, VelocityInterface *bvi=nullptr, AngularDistributionInterface *adi=nullptr, PolarizationProfileInterface *ppi=nullptr) |
| void | launchEmissionPeelOff (const PhotonPacket *pp, Direction bfk) |
| void | launchScatteringPeelOff (const PhotonPacket *pp, Direction bfk, Vec bfv, double lambda, double w) |
| double | luminosity () const |
| int | numScatt () const |
| double | observedOpticalDepth () const |
| double | perceivedLuminosity (double lambda) const |
| double | perceivedWavelength (Vec receiverVelocity, double expansionVelocity) const |
| void | propagate (double s) |
| void | scatter (Direction bfk, Vec bfv, double lambda) |
| void | setObservedOpticalDepth (double tau) |
| void | setPrimaryOrigin (int sourceCompIndex) |
| void | setScatteringComponent (int h) |
| void | setSecondaryOrigin (int mediumCompIndex) |
| double | sourceRestFrameWavelength () const |
| double | wavelength () const |
 Public Member Functions inherited from SpatialGridPath | |
| SpatialGridPath () | |
| SpatialGridPath (const Position &bfr, const Direction &bfk) | |
| void | addSegment (int m, double ds) |
| void | clear () |
| Direction | direction () const |
| void | findInteractionPoint (double tauinteract) |
| int | interactionCellIndex () const |
| double | interactionDistance () const |
| double | interactionOpticalDepth () const |
| Position | moveInside (const Box &box, double eps) |
| Position | position () const |
| void | propagatePosition (double s) |
| vector< Segment > & | segments () |
| const vector< Segment > & | segments () const |
| void | setDirection (const Direction &bfk) |
| void | setInteractionPoint (int m, double s, double tauAbs=0.) |
| void | setPosition (const Position &bfr) |
| double | totalOpticalDepth () const |
| Public Member Functions inherited from StokesVector | |
| StokesVector () | |
| StokesVector (double I, double Q, double U, double V, Direction n) | |
| void | applyMueller (double S11, double S12, double S22, double S33, double S34, double S44) |
| void | applyMueller (double S11, double S12, double S33, double S34) |
| bool | isPolarized () const |
| double | linearPolarizationDegree () const |
| Direction | normal () const |
| double | polarizationAngle () const |
| double | rotateIntoPlane (Direction k, Direction knew) |
| void | rotateStokes (double phi, Direction k) |
| void | setPolarized (const StokesVector &polarization) |
| void | setPolarized (double I, double Q, double U, double V) |
| void | setPolarized (double I, double Q, double U, double V, Direction n) |
| void | setUnpolarized () |
| void | stokes (double &I, double &Q, double &U, double &V) |
| double | stokesI () const |
| double | stokesQ () const |
| double | stokesU () const |
| double | stokesV () const |
| double | totalPolarizationDegree () const |
Static Public Member Functions | |
| static double | shiftedEmissionWavelength (double sourceWavelength, Direction photonDirection, Vec sourceVelocity) |
| static double | shiftedReceptionWavelength (double photonWavelength, Direction photonDirection, Vec receiverVelocity, double expansionVelocity=0.) |
Private Attributes | |
| AngularDistributionInterface * | _adi |
| VelocityInterface * | _bvi |
| int | _compIndex |
| int | _h |
| bool | _hasObservedOpticalDepth |
| size_t | _historyIndex |
| double | _lambda |
| double | _lambda0 |
| int | _nscatt |
| double | _observedOpticalDepth |
| PolarizationProfileInterface * | _ppi |
| vector< ScatteringInfo > | _scatteringInfo |
| double | _W |
The PhotonPacket class is used to describe monochromatic photon packets, the basic entities that are transported during a radiative transfer simulation. The fundamental properties of a photon packet include its wavelength and its weight. The wavelength property specifies the wavelength (or equivalenty, the frequency) of all photons in the packet. The weight property specifies the number of photons carried by the packet, or more precisely the number of photons per unit of time. Indeed, because we consider time-independent models, a photon packet actually represents a photon stream, consisting of a number of photons per unit of time. The weight can be fractional because it is derived from some arbitrary luminosity, and because it can be adjusted by arbitrary biasing factors during the photon packet's lifetime.
Note that adjusting a photon packet's wavelength (perhaps because of a Doppler shift) indirectly affects the luminosity represented by the packet, because the latter is directly proportional to the frequency and thus inversely proportional to the wavelength.
Apart from its wavelength and weight, a photon packet carries information about its polarization state, about its origin (e.g. emission by a primary or secondary source), about the interactions it experienced since its emission (e.g. the number of scattering events), and about its current path (e.g. starting position, propagation direction, spatial grid cells being crossed). A photon packet also carries a unique identifier (within the current emission segment) for the history it is part of, i.e. the collection of scattered and peeled-off packets derived from the same originally launched packet (emitted by a primary or secondary source). This history index can be used by instruments to group the fluxes of all photon packets belonging to the same history.
For a given luminosity \(L\) (representing the amount of energy carried by the photon packet per unit of time) and wavelength \(\lambda=c/\nu\), the weight of the photon packet (i.e. the number of photons it carries per unit time) can be written as
\[ W = \frac{L}{h\nu} = \frac{L\lambda}{hc}. \]
To avoid multiplying and dividing by the constant factor \(hc\), the weight tracked by a photon packet is instead simply defined as \(W'=L\lambda\).
The current path and the polarization state are handled by publicly inheriting repectively the SpatialGridPath class and the StokesVector class. For performance reasons, a PhotonPacket object is usually constructed once at the start of a loop and then reused in the loop body for many consecutive launches; this allows the vectors with path information to remain allocated. Also, several trivial functions are implemented inline in the header.
The PhotonPacket class offers auxiliary facilities for caching "technical" information related to a photon packet's state during its lifecycle. This optional information is managed by the clients invoking the corresponding store and retrieve functions. Examples include the observed optical depth, used to avoid recalculating the optical depth for consecutive instruments with the same viewing direction, and extra scattering information, used by some material mixes to ensure that peel-off and random-walk operations for a given scattering interaction are treated consistently.
| PhotonPacket::PhotonPacket | ( | ) |
The constructor initializes an empty photon packet object. After construction, the photon packet is ready to be launched through one of the launch() functions. The other functions in this class should be invoked only after the photon packet has been launched. The same photon packet object can be re-launched multiple times.
| void PhotonPacket::applyBias | ( | double | w | ) |
This function applies the given weight bias given as a multiplication factor.
|
inline |
This function returns the index of the source or medium component that originally emitted the photon packet.
| ScatteringInfo * PhotonPacket::getScatteringInfo | ( | ) |
This function returns a pointer to the (writable) scattering information record maintained for the current medium component as previously set through the setScatteringComponent() function. When this function is called for the first time for a new scattering event, the information record will be freshly initialized as described for the ScatteringInfo class. Specifically, the valid flag will be false. Subsequent invocations for the same scattering event will return the same information record with field values as updated by the client code.
Material mixes that need to store scattering information should call this function for each peel-off and random-walk scattering operation. If valid is false, the material mix should update the relevant fields and set valid to true. If valid is already true, the previously stored field values can be retrieved.
|
inline |
This function returns true if an "observed" optical depth value has been stored and the packet has not since been relaunched. Otherwise the function returns false.
|
inline |
This function returns true if the photon packet originated from a primary source, false otherwise.
|
inline |
This function returns true if the photon packet originated from a medium, false otherwise.
|
inline |
This function returns the index of the source or medium component that originally emitted the photon packet.
| void PhotonPacket::launch | ( | size_t | historyIndex, |
| double | lambda, | ||
| double | L, | ||
| Position | bfr, | ||
| Direction | bfk, | ||
| VelocityInterface * | bvi = nullptr, |
||
| AngularDistributionInterface * | adi = nullptr, |
||
| PolarizationProfileInterface * | ppi = nullptr |
||
| ) |
This function initializes the photon packet for a new life cycle. The arguments specify the packet's history index, the wavelength of its photons, the source luminosity represented by the packet, its starting position, and its propagation direction. The function calculates the weight corresponding to the specified luminosity and wavelength, copies the remaining arguments to the corresponding data members and initializes the other data members as described below.
If the VelocityInterface is specified (i.e. it is not the null pointer), then the packet's wavelength is Doppler shifted corresponding to its emission direction. If the PolarizationStateInterface is specified, the packet's polarization state is set according to its emission direction; otherwise the polarization state is set to unpolarized. The AngularDistributionInterface is not used by this function, but pointers to all three interfaces are stored in data members for use by the launchEmissionPeelOff() function.
The emission origin is set to an invalid value, which should be overridden by calling the setPrimaryOrigin() or the setSecondaryOrigin() function. The number of scattering events is set to zero. The current path is invalidated, and all information about the previous life cycle is lost.
| void PhotonPacket::launchEmissionPeelOff | ( | const PhotonPacket * | pp, |
| Direction | bfk | ||
| ) |
This function initializes a peel off photon packet being sent to an instrument for an emission event. The arguments specify the base photon packet from which the peel off derives and the direction towards the instrument. The function copies the relevant values from the base photon packet to the peel off photon packet, updates the peel off direction, and honors some extra source properties tracked by the base photon packet as follows.
If the base packet has a VelocityInterface (i.e. if it is not the null pointer), then the peel-off packet's wavelength is Doppler shifted corresponding to its propagation direction. If the base packet has an AngularDistributionInterface, a bias for the probability of the peel-off propagation direction is applied to the peel-off packet's weight. If the base packet has a PolarizationStateInterface, the peel-off packet's polarization state is set according to its propagation direction; otherwise its polarization state is set to unpolarized.
The current path of the peel off photon packet is invalidated, and all information about its previous life cycle is lost. The base photon packet remains unchanged.
| void PhotonPacket::launchScatteringPeelOff | ( | const PhotonPacket * | pp, |
| Direction | bfk, | ||
| Vec | bfv, | ||
| double | lambda, | ||
| double | w | ||
| ) |
This function initializes a peel off photon packet being sent to an instrument for a scattering event. The arguments specify the base photon packet from which the peel off derives, the direction towards the instrument, the new wavelength measured in a local frame with bulk velocity \({\bf{v}}\), and the weight bias (as a multiplication factor). The function copies the relevant values from the base photon packet to the peel off photon packet, updates the peel off direction, the wavelength and weight, and increments the scattering counter.
The peel off photon packet is initialized to an unpolarized state; the polarization state should be properly updated after the launch through the StokesVector class functions. The current path of the peel off photon packet is invalidated, and all information about its previous life cycle is lost. The base photon packet remains unchanged.
|
inline |
This function returns the luminosity \(L\) represented by the photon packet, calculated from its current wavelength and weight.
|
inline |
This function returns the number of scattering events the photon packet has experienced.
|
inline |
If hasObservedOpticalDepth() returns true, this function returns the most recently stored "observed" optical depth. Otherwise, it returns some meaningless value. This capability is offered so that consecutive instruments with the same observer type, position and viewing direction can avoid recalculating the optical depth.
|
inline |
This function returns the luminosity \(L\) represented by the photon packet, calculated from its current weight and the specified perceived wavelength.
| double PhotonPacket::perceivedWavelength | ( | Vec | receiverVelocity, |
| double | expansionVelocity | ||
| ) | const |
This function returns the Doppler-shifted wavelength perceived for this photon packet by a moving receiver (with non-relativistic velocity). The arguments specify the velocity of the receiver \({\bf{v}}_\text{rec}\) relative to the model coordinate frame and the expansion velocity \(\Delta v_\mathrm{h}\) of the universe relative to the starting position of the photon packet's current path (or zero if cosmological expansion is not taken into account). See the shiftedReceptionWavelength() function for more details.
| void PhotonPacket::propagate | ( | double | s | ) |
This function causes the propagation of the photon packet over a physical distance \(s\). It updates the position from \({\bf{r}}\) to \({\bf{r}}+s\,{\bf{k}}\), where \({\bf{k}}\) is the propagation direction of the photon packet, invalidating the current path.
This function scatters the photon packet into the new direction \({\bf{k}}\) with the new wavelength \(\lambda\) measured in a local frame with bulk velocity \({\bf{v}}\). It increments the counter that keeps track of scattering events, updates the direction, invalidating the current path, and updates the wavelength. The polarization remains unchanged; it should be properly updated through the StokesVector class functions.
|
inline |
This function stores the most recently "observed" optical depth, calculated externally, in a data member. This capability is offered so that consecutive instruments with the same observer type, position and viewing direction can avoid recalculating the optical depth.
| void PhotonPacket::setPrimaryOrigin | ( | int | sourceCompIndex | ) |
This function establishes that the photon packet has been emitted by a primary source and registers the index of the emitting source component. This information is used by some instruments to record fluxes seperately based on their origin. This function should be called just after launch.
|
inline |
This function sets the index of the medium component participating in the next peel-off or random-walk scattering operation. It should be called by the photon cycle machinery just before the material mix corresponding to the specified medium component is requested to determine its contribution to a peel-off or to perform a random-walk scattering operation. This mechanism allows the photon packet to maintain a seperate scattering information record for each medium component.
| void PhotonPacket::setSecondaryOrigin | ( | int | mediumCompIndex | ) |
This function establishes that the photon packet has been emitted by a medium and registers the index of the emitting medium component. This information is used by some instruments to record fluxes seperately based on their origin. This function should be called just after launch.
|
static |
This function returns the Doppler-shifted wavelength that should be assigned to a photon packet (i.e. the wavelength relative to the model coordinate frame) when the packet is emitted from a moving source (with non-relativistic velocity). The arguments specify the emitted wavelength \(\lambda_\text{src}\) in the source rest frame, the direction \({\bf{k}}_\text{ph}\) of the emitted photon packet, and the velocity of the source \({\bf{v}}_\text{src}\) relative to the model coordinate frame. The photon packet wavelength \(\lambda_\text{ph}\) can then be written as
\[ \lambda_\text{ph} = \lambda_\text{src} \left(1 - \frac{{\bf{k}}_\text{ph} \cdot {\bf{v}}_\text{src}}{c} \right) \]
where \(c\) is the speed of light in vacuum.
|
static |
This function returns the Doppler-shifted wavelength perceived by a moving receiver (with non-relativistic velocity) for an incoming photon packet. The arguments specify the photon packet wavelength \(\lambda_\text{ph}\) in the model coordinate frame, the direction \({\bf{k}}_\text{ph}\) of the incoming photon packet, the velocity of the receiver \({\bf{v}}_\text{rec}\) relative to the model coordinate frame, and the expansion velocity \(\Delta v_\mathrm{h}\) of the universe relative to the starting position of the photon packet's current path (or zero if cosmological expansion is not taken into account).
The wavelength \(\lambda_\text{rec}\) perceived by the receiver can then be written as
\[ \left. \lambda_\text{rec} = \lambda_\text{ph} \middle/ \left(1 - \frac{{\bf{k}}_\text{ph} \cdot {\bf{v}}_\text{rec} + \Delta v_\mathrm{h}}{c} \right) \right. \]
where \(c\) is the speed of light in vacuum.
|
inline |
This function returns the wavelength \(\lambda_0\) of the photon packet when it was launched, relative to the rest frame of the original source.
|
inline |
This function returns the current wavelength \(\lambda\) of the photon packet relative to the model coordinate system.