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

#include <ProbeFormBridge.hpp>

Public Types

using AddColumnDefinitions = std::function< void(TextOutFile &outfile)>
 
using CompoundValueAlongPath = std::function< Array(Position bfr, Direction bfk)>
 
using CompoundValueAtPosition = std::function< Array(Position bfr)>
 
using CompoundValueInCell = std::function< Array(int m)>
 
using ScalarValueAlongPath = std::function< double(Position bfr, Direction bfk)>
 
using ScalarValueAtPosition = std::function< double(Position bfr)>
 
using ScalarValueInCell = std::function< double(int m)>
 
using ScalarValueInEntity = std::function< double(const Snapshot *snapshot, int m)>
 
using VectorValueAlongPath = std::function< Vec(Position bfr, Direction bfk)>
 
using VectorValueAtPosition = std::function< Vec(Position bfr)>
 
using VectorValueInCell = std::function< Vec(int m)>
 
using VectorValueInEntity = std::function< Vec(const Snapshot *snapshot, int m)>
 
using WeightInCell = std::function< double(int m)>
 
using WeightInEntity = std::function< double(const Snapshot *snapshot, int m)>
 

Public Member Functions

 ProbeFormBridge (const Probe *probe, const Form *form)
 
void addColumnDefinitions (TextOutFile &outfile) const
 
Array axis () const
 
string axisUnit () const
 
string description () const
 
const SpatialGridgrid () const
 
bool isVector () const
 
int numValues () const
 
string prefix () const
 
const SimulationItemprobe () const
 
string projectedDescription () const
 
string projectedPrefix () const
 
string projectedUnit () const
 
string unit () const
 
const Unitsunits () const
 
void valuesAlongPath (Position bfr, Direction bfk, Array &values) const
 
void valuesAtPosition (Position bfr, Array &values) const
 
void valuesInCell (int m, Array &values) const
 
void writeQuantity (string fileid, string projectedFileid, string quantity, string projectedQuantity, string description, string projectedDescription, const Array &axis, string axisUnit, AddColumnDefinitions addColumnDefinitions, CompoundValueInCell valueInCell)
 
void writeQuantity (string fileid, string projectedFileid, string quantity, string projectedQuantity, string description, string projectedDescription, const vector< const Snapshot * > &snapshots, ScalarValueInEntity valueInEntity)
 
void writeQuantity (string fileid, string projectedFileid, string quantity, string projectedQuantity, string description, string projectedDescription, ScalarValueAtPosition valueAtPosition, ScalarValueAlongPath valueAlongPath)
 
void writeQuantity (string fileid, string projectedFileid, string quantity, string projectedQuantity, string description, string projectedDescription, ScalarValueInCell valueInCell)
 
void writeQuantity (string fileid, string projectedFileid, string quantity, string projectedQuantity, string description, string projectedDescription, VectorValueAtPosition valueAtPosition, VectorValueAlongPath valueAlongPath)
 
void writeQuantity (string fileid, string projectedFileid, string unit, string projectedUnit, double projectedUnitFactor, string description, string projectedDescription, const Array &axis, string axisUnit, AddColumnDefinitions addColumnDefinitions, CompoundValueInCell valueInCell)
 
void writeQuantity (string fileid, string projectedFileid, string unit, string projectedUnit, string description, string projectedDescription, const Array &axis, string axisUnit, AddColumnDefinitions addColumnDefinitions, CompoundValueAtPosition valueAtPosition, CompoundValueAlongPath valueAlongPath)
 
void writeQuantity (string fileid, string quantity, string description, string projectedDescription, const vector< const Snapshot * > &snapshots, ScalarValueInEntity valueInEntity, WeightInEntity weightInEntity)
 
void writeQuantity (string fileid, string quantity, string description, string projectedDescription, const vector< const Snapshot * > &snapshots, VectorValueInEntity valueInEntity, WeightInEntity weightInEntity)
 
void writeQuantity (string fileid, string quantity, string description, string projectedDescription, ScalarValueInCell valueInCell, WeightInCell weightInCell)
 
void writeQuantity (string fileid, string quantity, string description, string projectedDescription, VectorValueInCell valueInCell, WeightInCell weightInCell)
 
void writeQuantity (string fileid, string unit, string description, string projectedDescription, const Array &axis, string axisUnit, AddColumnDefinitions addColumnDefinitions, CompoundValueInCell valueInCell, WeightInCell weightInCell)
 

Private Types

enum class  Type {
  GridScalarAccumulated , GridScalarAveraged , GridVectorAveraged , GridCompoundAccumulated ,
  GridCompoundAveraged , InputScalar , InputVector , InputCompound
}
 

Private Attributes

AddColumnDefinitions _addColumnDefinitions
 
Array _axis
 
string _axisUnit
 
CompoundValueAlongPath _compoundValueAlongPath
 
CompoundValueAtPosition _compoundValueAtPosition
 
CompoundValueInCell _compoundValueInCell
 
string _description
 
string _fileid
 
const Form_form
 
const SpatialGrid_grid
 
int _numValues
 
const Probe_probe
 
string _projectedDescription
 
string _projectedFileid
 
string _projectedUnit
 
double _projectedUnitFactor
 
ScalarValueAlongPath _scalarValueAlongPath
 
ScalarValueAtPosition _scalarValueAtPosition
 
ScalarValueInCell _scalarValueInCell
 
Type _type
 
string _unit
 
double _unitFactor
 
const Units_units
 
VectorValueAlongPath _vectorValueAlongPath
 
VectorValueAtPosition _vectorValueAtPosition
 
VectorValueInCell _vectorValueInCell
 
WeightInCell _weightInCell
 

Detailed Description

ProbeFormBridge is a helper class that provides a bridge between Probe and Form instances for form-assisted probes. The overall design objectives are described below. Refer to the documentation of the respective classes for more details.

Probes and forms

The idea is to allow combining two orthogonal concepts in an arbitrary fashion. The quantity being probed is specified by a Probe subclass, while the manner in which this quantity is being probed is specified by a Form subclass. Each Probe instance of this type is configured with a single Form instance.

This design does not apply to all probes. It is intended for probing physical quantities that are defined as a scalar, vector or compound field over the spatial domain of the simulation. This includes two categories:

Forms describe how a given quantity should be probed. Generic forms (inheriting the GenericForm class) can be associated with any probe, including both spatial grid and input model probes. Examples include planar and linear cuts through the spatial domain, sampling at a user-specified list of positions, and parallel or all-sky projections. Spatial grid forms (inheriting the SpatialGridForm class) rely on the fact that the probed quantity is discretized on the simulation's spatial grid, and thus can be associated only with spatial grid probes. The prime example is the per-cell form.

The probe-form bridge

As can be deduced from the description above, the various types of probes and forms offer or require different types of primitives for retrieving probed quantity values. The ProbeFormBridge class provides a bridge between these differing capabilities and requirements. When a probe wants to output a file, it constructs a bridge instance and calls one of the bridge's writeQuantity() functions, passing it the appropriate information and local callback functions for retrieving probed quantity values on request. The bridge in turn calls the form's writeQuantity(bridge) function. Each Form subclass offers its own implementation of this function depending on the form's type of output. The form can get all required information through the bridge, including probed quantity values. The bridge passes the latter requests to the probe's call back functions, translating between request types as needed. For example, in the case of a spatial grid probe, a request by the form for a value at a given position is translated to a request for a value in the cell containing the position.

One aspect that needs special care is the conversion from internal units (always SI) to output units (defined by the unit system configured by the user). For each probe-form combination, the bridge handles two different quantity types: the 'straight' quantity, probed at a given position, and the 'projected' quantity, probed along a given path. The projected quantity can be averaged or accumulated over the path. In the first case, the project and straight quantities have the same units; in the second case they don't.

The bridge always supplies output units to the form, simplifying the implementation of a Form subclass. On the probe side, things are more complicated. Probes that handle scalar or vector quantities must specify the type of quantity to the bridge and supply any quantity values in internal units. The bridge will take care of the unit conversions. On the other hand, probes handling compound quantities must always convert quantity values to output units before supplying them to the bridge. This is so because the conversion factor may differ between components in a complicated way (for example, spectral quantities at different wavelengths).

There are several variations of the writeQuantity() function tailored to scalar, vector and compound quantities, and catering to spatial grid or input model probes. Because these functions often expect the same arguments in different combinations, all arguments are described here.

Member Typedef Documentation

◆ AddColumnDefinitions

using ProbeFormBridge::AddColumnDefinitions = std::function<void(TextOutFile& outfile)>

This is the type declaration for the callback function provided by the probe to add column definitions for a straight compound quantity to the specified text output file.

◆ CompoundValueAlongPath

This is the type declaration for the callback function provided by the input model probe to retrieve the compound value (in output units) of the quantity being probed along the path starting at the specified position in the specified direction. The returned array must have the same number of elements as the axis array passed to the writeQuantity() function.

◆ CompoundValueAtPosition

This is the type declaration for the callback function provided by the input model probe to retrieve the compound value (in output units) of the quantity being probed at the specified position. The returned array must have the same number of elements as the axis array passed to the writeQuantity() function.

◆ CompoundValueInCell

using ProbeFormBridge::CompoundValueInCell = std::function<Array(int m)>

This is the type declaration for the callback function provided by the spatial grid probe to retrieve the compound value (in internal or output units) of the quantity being probed in the spatial cell with index \(m\). The returned array must have the same number of elements as the axis array passed to the writeQuantity() function.

◆ ScalarValueAlongPath

using ProbeFormBridge::ScalarValueAlongPath = std::function<double(Position bfr, Direction bfk)>

This is the type declaration for the callback function provided by the input model probe to retrieve the scalar value (in internal units) of the quantity being probed along the path starting at the specified position in the specified direction.

◆ ScalarValueAtPosition

using ProbeFormBridge::ScalarValueAtPosition = std::function<double(Position bfr)>

This is the type declaration for the callback function provided by the input model probe to retrieve the scalar value (in internal units) of the quantity being probed at the specified position.

◆ ScalarValueInCell

using ProbeFormBridge::ScalarValueInCell = std::function<double(int m)>

This is the type declaration for the callback function provided by the spatial grid probe to retrieve the scalar value (in internal units) of the quantity being probed in the spatial cell with index \(m\).

◆ ScalarValueInEntity

using ProbeFormBridge::ScalarValueInEntity = std::function<double(const Snapshot* snapshot, int m)>

This is the type declaration for the callback function provided by the imported model probe to retrieve the scalar value (in internal units) of the quantity being probed in the snapshot entity with index \(m\).

◆ VectorValueAlongPath

using ProbeFormBridge::VectorValueAlongPath = std::function<Vec(Position bfr, Direction bfk)>

This is the type declaration for the callback function provided by the input model probe to retrieve the vector value (in internal units) of the quantity being probed along the path starting at the specified position in the specified direction.

◆ VectorValueAtPosition

This is the type declaration for the callback function provided by the input model probe to retrieve the vector value (in internal units) of the quantity being probed at the specified position.

◆ VectorValueInCell

using ProbeFormBridge::VectorValueInCell = std::function<Vec(int m)>

This is the type declaration for the callback function provided by the spatial grid probe to retrieve the vector value (in internal units) of the quantity being probed in the spatial cell with index \(m\).

◆ VectorValueInEntity

using ProbeFormBridge::VectorValueInEntity = std::function<Vec(const Snapshot* snapshot, int m)>

This is the type declaration for the callback function provided by the imported model probe to retrieve the vector value (in internal units) of the quantity being probed in the snapshot entity with index \(m\).

◆ WeightInCell

using ProbeFormBridge::WeightInCell = std::function<double(int m)>

This is the type declaration for the callback function provided by the spatial grid probe to retrieve the weight (in arbitrary units) of the quantity being probed in the spatial cell with index \(m\).

◆ WeightInEntity

using ProbeFormBridge::WeightInEntity = std::function<double(const Snapshot* snapshot, int m)>

This is the type declaration for the callback function provided by the imported model probe to retrieve the weight (in arbitrary units) of the quantity being probed in the snapshot entity with index \(m\).

Constructor & Destructor Documentation

◆ ProbeFormBridge()

ProbeFormBridge::ProbeFormBridge ( const Probe probe,
const Form form 
)

The sole constructor accepts and retains pointers to the probe and form to be associated with this bridge.

Member Function Documentation

◆ addColumnDefinitions()

void ProbeFormBridge::addColumnDefinitions ( TextOutFile outfile) const

This function adds the column definitions appropriate for the straight quantity being probed to the specified text output file. It should not be called for projected quantities. For scalar and vector quantities, the function adds the appropriate column definitions based on the description and unit information provided to the most recent call to writeQuantity(). For compound quantities, it invokes the addColumnDefinitions callback set by the most recent call to writeQuantity().

◆ axis()

Array ProbeFormBridge::axis ( ) const

This function returns an array with the axis values for the quantity being probed, as set by the most recent call to writeQuantity(). For a scalar quantity, this returns the empty array (as opposed to an array with a single value). For a vector quantity, this returns an array containing {1.,2.,3.}. For a compound quantity, this returns the axis values set by the call to writeQuantity(). In the latter two cases, the number of elements in the returned array equals the return value of numValues().

◆ axisUnit()

string ProbeFormBridge::axisUnit ( ) const

This function returns the unit string of the axis values for the quantity, as set by the most recent call to writeQuantity(). For a scalar or vector quantity, this returns "1". For a compound quantity, this returns the axis unit set by the call to writeQuantity().

◆ description()

string ProbeFormBridge::description ( ) const

This function returns the user description of the straight quantity, as set by the most recent call to writeQuantity().

◆ grid()

const SpatialGrid * ProbeFormBridge::grid ( ) const

This function returns the simulation's spatial grid, or the null pointer if the simulation does not include any media.

◆ isVector()

bool ProbeFormBridge::isVector ( ) const

This function returns if the quantity being probed, as set by the most recent call to writeQuantity(), is a vector quantity, and false if it is a scalar or compound quantity.

◆ numValues()

int ProbeFormBridge::numValues ( ) const

This function returns the number of values in the quantity being probed, as set by the most recent call to writeQuantity(). For a scalar quantity, this returns 1. For a vector quantity, this returns 3. For a compound quantity, this returns the size of the axis array set by the call to writeQuantity().

◆ prefix()

string ProbeFormBridge::prefix ( ) const

This function returns the file name prefix formed by combining the probe name with the file identifier for the straight quantity set by the most recent call to writeQuantity().

◆ probe()

const SimulationItem * ProbeFormBridge::probe ( ) const

This function returns the probe associated with this bridge upon construction.

◆ projectedDescription()

string ProbeFormBridge::projectedDescription ( ) const

This function returns the user description of the projected quantity, as set by the most recent call to writeQuantity().

◆ projectedPrefix()

string ProbeFormBridge::projectedPrefix ( ) const

This function returns the file name prefix formed by combining the probe name with the file identifier for the projected quantity set by the most recent call to writeQuantity().

◆ projectedUnit()

string ProbeFormBridge::projectedUnit ( ) const

This function returns the unit string of the projected quantity, as set by the most recent call to writeQuantity().

◆ unit()

string ProbeFormBridge::unit ( ) const

This function returns the unit string of the straight quantity, as set by the most recent call to writeQuantity().

◆ units()

const Units * ProbeFormBridge::units ( ) const

This function returns the simulation's unit system.

◆ valuesAlongPath()

void ProbeFormBridge::valuesAlongPath ( Position  bfr,
Direction  bfk,
Array values 
) const

This function retrieves the values (in output units) of the quantity being probed along the path starting at the specified position in the specified direction. The provided array must have numValues elements that will be overwritten by this function.

This function should be called only from within the writeQuantity() function of a generic form. Its operation depends on the type of the associated probe, the quantity properties set by the most recent call to writeQuantity(), and the callbacks set by the writeQuantity() function of this bridge that triggered the current file output.

For an input model probe, the function simply invokes the valuesAlongPath callback. For a spatial grid probe, the function accesses the simulation's spatial grid to determine the list of path segments (traversing each cell) corresponding to the specified path, and it calls the valuesInCell callback for each cell in the list. If the straight and projected quantity names differ, the function calculates the accumulated quantity \(\sum_m Q_m \Delta s_m\). If the quantity names are the same, it calculates the weighted average \(\sum_m Q_m w_m \Delta s_m / \sum_m w_m \Delta s_m\), where the weights are retrieved by calling the weightInCell callback for each cell.

◆ valuesAtPosition()

void ProbeFormBridge::valuesAtPosition ( Position  bfr,
Array values 
) const

This function retrieves the values (in output units) of the quantity being probed at the specified position. The provided array must have numValues elements that will be overwritten by this function.

This function should be called only from within the writeQuantity() function of a generic form. Depending on the type of the associated probe, it operates by invoking either the valuesAtPosition or valuesInCell callback set by the writeQuantity() function of this bridge that triggered the current file output. In the latter case, the function accesses the simulation's spatial grid to retrieve the index of the cell containing the specified position.

◆ valuesInCell()

void ProbeFormBridge::valuesInCell ( int  m,
Array values 
) const

This function retrieves the values (in output units) of the quantity being probed in the spatial cell with index \(m\). The provided array must have numValues elements that will be overwritten by this function.

This function should be called only from within the writeQuantity() function of a spatial grid-specific form. It operates by invoking the valuesInCell callback set by the writeQuantity() function of this bridge that triggered the current file output.

◆ writeQuantity() [1/12]

void ProbeFormBridge::writeQuantity ( string  fileid,
string  projectedFileid,
string  quantity,
string  projectedQuantity,
string  description,
string  projectedDescription,
const Array axis,
string  axisUnit,
AddColumnDefinitions  addColumnDefinitions,
CompoundValueInCell  valueInCell 
)

This function causes the form associated with this bridge to output a file for a compound quantity that needs to be accumulated along a path according to the provided information. It should be called only from spatial grid probes. Refer to the class header for more information on the arguments.

◆ writeQuantity() [2/12]

void ProbeFormBridge::writeQuantity ( string  fileid,
string  projectedFileid,
string  quantity,
string  projectedQuantity,
string  description,
string  projectedDescription,
const vector< const Snapshot * > &  snapshots,
ScalarValueInEntity  valueInEntity 
)

This function causes the form associated with this bridge to output a file for a scalar quantity that needs to be accumulated along a path, according to the provided information. It should be called only from input model probes for imported source or media components. Refer to the class header for more information on the arguments.

◆ writeQuantity() [3/12]

void ProbeFormBridge::writeQuantity ( string  fileid,
string  projectedFileid,
string  quantity,
string  projectedQuantity,
string  description,
string  projectedDescription,
ScalarValueAtPosition  valueAtPosition,
ScalarValueAlongPath  valueAlongPath 
)

This function causes the form associated with this bridge to output a file for a scalar quantity according to provided the information. It should be called only from input model probes. Refer to the class header for more information on the arguments.

◆ writeQuantity() [4/12]

void ProbeFormBridge::writeQuantity ( string  fileid,
string  projectedFileid,
string  quantity,
string  projectedQuantity,
string  description,
string  projectedDescription,
ScalarValueInCell  valueInCell 
)

This function causes the form associated with this bridge to output a file for a scalar quantity that needs to be accumulated along a path, according to the provided information. It should be called only from spatial grid probes. Refer to the class header for more information on the arguments.

◆ writeQuantity() [5/12]

void ProbeFormBridge::writeQuantity ( string  fileid,
string  projectedFileid,
string  quantity,
string  projectedQuantity,
string  description,
string  projectedDescription,
VectorValueAtPosition  valueAtPosition,
VectorValueAlongPath  valueAlongPath 
)

This function causes the form associated with this bridge to output a file for a vector quantity according to provided the information. It should be called only from input model probes. Refer to the class header for more information on the arguments.

◆ writeQuantity() [6/12]

void ProbeFormBridge::writeQuantity ( string  fileid,
string  projectedFileid,
string  unit,
string  projectedUnit,
double  projectedUnitFactor,
string  description,
string  projectedDescription,
const Array axis,
string  axisUnit,
AddColumnDefinitions  addColumnDefinitions,
CompoundValueInCell  valueInCell 
)

This function causes the form associated with this bridge to output a file for a compound quantity that needs to be accumulated along a path according to the provided information. It should be called only from spatial grid probes. Refer to the class header for more information on the arguments.

◆ writeQuantity() [7/12]

void ProbeFormBridge::writeQuantity ( string  fileid,
string  projectedFileid,
string  unit,
string  projectedUnit,
string  description,
string  projectedDescription,
const Array axis,
string  axisUnit,
AddColumnDefinitions  addColumnDefinitions,
CompoundValueAtPosition  valueAtPosition,
CompoundValueAlongPath  valueAlongPath 
)

This function causes the form associated with this bridge to output a file for a compound quantity according to provided the information. It should be called only from input model probes. Refer to the class header for more information on the arguments.

◆ writeQuantity() [8/12]

void ProbeFormBridge::writeQuantity ( string  fileid,
string  quantity,
string  description,
string  projectedDescription,
const vector< const Snapshot * > &  snapshots,
ScalarValueInEntity  valueInEntity,
WeightInEntity  weightInEntity 
)

This function causes the form associated with this bridge to output a file for a scalar quantity that needs to be averaged along a path, according to the provided information. It should be called only from input model probes for imported source or media components. Refer to the class header for more information on the arguments.

◆ writeQuantity() [9/12]

void ProbeFormBridge::writeQuantity ( string  fileid,
string  quantity,
string  description,
string  projectedDescription,
const vector< const Snapshot * > &  snapshots,
VectorValueInEntity  valueInEntity,
WeightInEntity  weightInEntity 
)

This function causes the form associated with this bridge to output a file for a vector quantity that needs to be averaged along a path, according to the provided information. It should be called only from input model probes for imported source or media components. Refer to the class header for more information on the arguments.

◆ writeQuantity() [10/12]

void ProbeFormBridge::writeQuantity ( string  fileid,
string  quantity,
string  description,
string  projectedDescription,
ScalarValueInCell  valueInCell,
WeightInCell  weightInCell 
)

This function causes the form associated with this bridge to output a file for a scalar quantity that needs to be averaged along a path, according to the provided information. It should be called only from spatial grid probes. Refer to the class header for more information on the arguments.

◆ writeQuantity() [11/12]

void ProbeFormBridge::writeQuantity ( string  fileid,
string  quantity,
string  description,
string  projectedDescription,
VectorValueInCell  valueInCell,
WeightInCell  weightInCell 
)

This function causes the form associated with this bridge to output a file for a vector quantity (which is always averaged along a path) according to the provided information. It should be called only from spatial grid probes. Refer to the class header for more information on the arguments.

◆ writeQuantity() [12/12]

void ProbeFormBridge::writeQuantity ( string  fileid,
string  unit,
string  description,
string  projectedDescription,
const Array axis,
string  axisUnit,
AddColumnDefinitions  addColumnDefinitions,
CompoundValueInCell  valueInCell,
WeightInCell  weightInCell 
)

This function causes the form associated with this bridge to output a file for a compound quantity that needs to be averaged along a path according to the provided information. It should be called only from spatial grid probes. Refer to the class header for more information on the arguments.


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