#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 SpatialGrid * | grid () const |
bool | isVector () const |
int | numValues () const |
string | prefix () const |
const SimulationItem * | probe () const |
string | projectedDescription () const |
string | projectedPrefix () const |
string | projectedUnit () const |
string | unit () const |
const Units * | units () 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 |
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.
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.
using ProbeFormBridge::CompoundValueAlongPath = std::function<Array(Position bfr, Direction bfk)> |
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.
using ProbeFormBridge::CompoundValueAtPosition = std::function<Array(Position bfr)> |
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.
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
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.
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.
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
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
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.
using ProbeFormBridge::VectorValueAtPosition = std::function<Vec(Position bfr)> |
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.
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
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
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
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
The sole constructor accepts and retains pointers to the probe and form to be associated with this bridge.
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().
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().
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().
string ProbeFormBridge::description | ( | ) | const |
This function returns the user description of the straight quantity, as set by the most recent call to writeQuantity().
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.
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.
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().
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().
const SimulationItem * ProbeFormBridge::probe | ( | ) | const |
This function returns the probe associated with this bridge upon construction.
string ProbeFormBridge::projectedDescription | ( | ) | const |
This function returns the user description of the projected quantity, as set by the most recent call to writeQuantity().
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().
string ProbeFormBridge::projectedUnit | ( | ) | const |
This function returns the unit string of the projected quantity, as set by the most recent call to writeQuantity().
string ProbeFormBridge::unit | ( | ) | const |
This function returns the unit string of the straight quantity, as set by the most recent call to writeQuantity().
const Units * ProbeFormBridge::units | ( | ) | const |
This function returns the simulation's unit system.
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
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.
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
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.