The SKIRT project
advanced radiative transfer for astrophysics
Classes | Public Member Functions | Static Public Member Functions | Private Attributes | List of all members
PhotonPacket Class Reference

#include <PhotonPacket.hpp>

Inheritance diagram for PhotonPacket:
Inheritance graph
[legend]

Classes

class  ScatteringInfo
 

Public Member Functions

 PhotonPacket ()
 
void applyBias (double w)
 
int compIndex () const
 
ScatteringInfogetScatteringInfo ()
 
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
 

Detailed Description

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.

Implementation notes

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.

Constructor & Destructor Documentation

◆ PhotonPacket()

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.

Member Function Documentation

◆ applyBias()

void PhotonPacket::applyBias ( double  w)

This function applies the given weight bias given as a multiplication factor.

◆ compIndex()

int PhotonPacket::compIndex ( ) const
inline

This function returns the index of the source or medium component that originally emitted the photon packet.

◆ getScatteringInfo()

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.

◆ hasObservedOpticalDepth()

bool PhotonPacket::hasObservedOpticalDepth ( ) const
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.

◆ hasPrimaryOrigin()

bool PhotonPacket::hasPrimaryOrigin ( ) const
inline

This function returns true if the photon packet originated from a primary source, false otherwise.

◆ hasSecondaryOrigin()

bool PhotonPacket::hasSecondaryOrigin ( ) const
inline

This function returns true if the photon packet originated from a medium, false otherwise.

◆ historyIndex()

size_t PhotonPacket::historyIndex ( ) const
inline

This function returns the index of the source or medium component that originally emitted the photon packet.

◆ launch()

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.

◆ launchEmissionPeelOff()

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.

◆ launchScatteringPeelOff()

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.

◆ luminosity()

double PhotonPacket::luminosity ( ) const
inline

This function returns the luminosity \(L\) represented by the photon packet, calculated from its current wavelength and weight.

◆ numScatt()

int PhotonPacket::numScatt ( ) const
inline

This function returns the number of scattering events the photon packet has experienced.

◆ observedOpticalDepth()

double PhotonPacket::observedOpticalDepth ( ) const
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.

◆ perceivedLuminosity()

double PhotonPacket::perceivedLuminosity ( double  lambda) const
inline

This function returns the luminosity \(L\) represented by the photon packet, calculated from its current weight and the specified perceived wavelength.

◆ perceivedWavelength()

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.

◆ propagate()

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.

◆ scatter()

void PhotonPacket::scatter ( Direction  bfk,
Vec  bfv,
double  lambda 
)

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.

◆ setObservedOpticalDepth()

void PhotonPacket::setObservedOpticalDepth ( double  tau)
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.

◆ setPrimaryOrigin()

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.

◆ setScatteringComponent()

void PhotonPacket::setScatteringComponent ( int  h)
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.

◆ setSecondaryOrigin()

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.

◆ shiftedEmissionWavelength()

static double PhotonPacket::shiftedEmissionWavelength ( double  sourceWavelength,
Direction  photonDirection,
Vec  sourceVelocity 
)
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.

◆ shiftedReceptionWavelength()

static double PhotonPacket::shiftedReceptionWavelength ( double  photonWavelength,
Direction  photonDirection,
Vec  receiverVelocity,
double  expansionVelocity = 0. 
)
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.

◆ sourceRestFrameWavelength()

double PhotonPacket::sourceRestFrameWavelength ( ) const
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.

◆ wavelength()

double PhotonPacket::wavelength ( ) const
inline

This function returns the current wavelength \(\lambda\) of the photon packet relative to the model coordinate system.


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