#include <MediumState.hpp>

Public Member Functions
Vec	bulkVelocity (int m) const

void	calculateAggregate ()

double	custom (int m, int h, int i) const

size_t	initAllocate ()

void	initCommonStateVariables (const vector< StateVariable > &variables)

void	initCommunicate ()

void	initConfiguration (int numCells, int numMedia, int numAggregateCells)

void	initSpecificStateVariables (const vector< StateVariable > &variables)

Vec	magneticField (int m) const

double	metallicity (int m, int h) const

double	numberDensity (int m, int h) const

void	pushAggregate ()

void	setBulkVelocity (int m, Vec value)

void	setCustom (int m, int h, int i, double value)

void	setMagneticField (int m, Vec value)

void	setMetallicity (int m, int h, double value)

void	setNumberDensity (int m, int h, double value)

void	setTemperature (int m, int h, double value)

void	setVolume (int m, double value)

std::pair< int, int >	synchronize (const vector< UpdateStatus > &cellFlags)

double	temperature (int m, int h) const

double	volume (int m) const

Private Attributes
Array	_data

vector< int >	_densityOffsets

int	_nextComponent

int	_nextOffset

int	_numAggregateCells

int	_numCells

int	_numMedia

int	_numVars

vector< int >	_off_cust

vector< int >	_off_dens

vector< int >	_off_meta

int	_off_mfld

vector< int >	_off_temp

int	_off_velo

int	_off_volu

Detailed Description

An instance of the MediumState class contains the complete medium state for a simulation. The MediumSystem maintains a single (private) instance of this class and provides access to its contents to the rest of the simulation code as needed.

For each spatial cell in the simulation, the medium state includes a set of common state variables shared by all medium components and a set of specific state variables for each individual medium component. The following table lists the variables that may be present in each of these sets.

Identifier	Symbol	Type	Set	Present
Volume	\(V\)	double	Common	always
BulkVelocity	\(v\)	Vec	Common	if needed for any medium component
MagneticField	\(\bf{B}\)	Vec	Common	if needed for any medium component
NumberDensity	\(n\)	double	Specific	always
Metallicity	\(Z\)	double	Specific	if requested by the medium component
Temperature	\(T\)	double	Specific	if requested by the medium component
Custom + k		double	Specific	zero or more as requested by the medium component

The presence or absence of these state variables is communicated to the MediumState class during its construction, so that it can dynamically allocate the appropriate amount of storage and provide an access mechanism for each state variable. This process is described in more detail in the following sections.

Construction

Fully initializing a MediumState object requires calling the following functions in the correct order (after default-constructing the object):

the initConfiguration() function specifies the number of spatial cells and the number of medium components in the simulation.
the initCommonStateVariables() function specifies the set of common state variables.
the initSpecificStateVariables() function must be called once for each medium component, in order of component index, specifying the set of specific state variables for that component.
the initAllocate() function finalizes construction and actually allocates storage; it initializes all variables to a value of zero.
the setXXX() functions set any nonzero initial variable values required to reflect the input model; this may happen in parallel.
the initCommunicate() function communicates the initialized state variable values between processes.

The initCommonStateVariables() and initSpecificStateVariables() functions each receive a list of StateVariable objects to identify the required state variables. All required state variables must be listed, including those that should always present. Variables of type Custom must be listed last. Multiple variables of type Custom can be requested by supplying indices in the range \( 0 \le k < K\), where K is the total number of custom variables. Each of these indices must occur in the list exactly once in increasing order.

Synchronization

A simulation may update the values of medium state variables, often as part of an iterative process to calculate a self-consistent state. These updates may happen in parallel over cells. After a set of updates, usually at the end of each step in the iterative process, the synchronize() function should be called to broadcast the updates between processes.

Aggregation

When a simulation employs an iterative process to calculate a self-consistent medium state, it needs a criterion to determine whether the state has sufficiently converged. Such criterion is often based on aggregate information calculated over all cells in the spatial grid for the current iteration and for one or more previous iterations. This class can calculate and store such aggregate information in the form of "fake" cells that are added at the end of the array of regular cells. The number of stored aggregated states, including current and previous ones, must be specified as the last argument of the initConfiguration() function. If this number is zero, no aggregation is performed.

Information from the aggregate states can be retrieved using the same functions as those for regular cells. Assuming a number of regular spatial cells \(M\), the current (i.e. most recent) aggregate state has cell index \(m=M\), the previous aggregate state has cell index \(m=M+1\), the one before that has cell index \(m=M+2\), and so forth.

The calculateAggregate() function should be called at the end of construction, i.e. after initCommunicate(), and at the end of each dynamic medium state update cycle, i.e. after synchronize(). It recalculates the current aggregate state by accumulating information over all spatial cells. The pushAggregate() function should be called at the end of each step in the iterative process. It shifts the existing aggregate states to the next higher cell index, dropping the least recent aggregate state and making room for a new one.

The current implementation performs the following aggregation. The cell volume is summed over all cells, providing the total volume of the spatial domain: \(V_\mathrm{tot} = \sum V_m\). All variables with quantity type "numbervolumedensity" are summed after multiplication with the cell volume, providing a total number: \(N_\mathrm{tot} = \sum n_m V_m\). Any other variables are not aggregated; i.e. the aggregated values are zero. The aggregated values can be retrieved through the volume(), numberDensity() and custom() functions using the fake cell index corresponding to the desired current or previous state.

Storage

To simplify the storage mechanism, state variables of type Vec are split into their three components, so that all state variables can considered to be of type double. Memory is allocated only for state variables that are actually needed. Given the number of spatial cells \(M\) (possibly increased by the requested number of aggregate cells), the number of medium components \(H\), the number of common state variables \(C\), and the number of specific state variables \(S_h\) for each medium component \(h\), the number of state variables per spatial cell is \(K = C+\sum_h S_h\) and the grand total number of state variables is \(N = M (C+\sum_h S_h)\).

The MediumState class allocates a single one-dimensional data array of this size \(N\) and provides a mapping to locate a particular state variable in this array. This is accomplished by also storing the offset for each variable within the set of variables per spatial cell. To facilitate access, these offsets are stored for all supported variables (by name) and not just for the required variables. The offsets for unused variables remain at zero.

Given the offset \(O_x\) for a particular state variable \(x\), a spatial cell index \(m\) and a medium component index \(h\), the index of the variable in the data array can be calculated as \(i=K \times m + O_x\). This implies that variables are stored contiguously per cell.

Access to undefined variables

In general, an attempt to access (read or write) a variable for which storage has not been requested results in undefined behavior. However, assuming that storage has been requested for the volume (which is always needed anyway), the other variables in the common state can be safely read (not written) even if no storage was requested for them. This allows the bulk velocity and magnetic field vectors to be retrieved without concern for whether they were configured in the input model.

Member Function Documentation

◆ bulkVelocity()

Vec MediumState::bulkVelocity ( int m ) const

inline

This function returns the aggregate bulk velocity \({\boldsymbol{v}}\) of the medium in the spatial cell with index \(m\), or zero if storage was not requested for this variable.

◆ calculateAggregate()

void MediumState::calculateAggregate ( )

If aggregation has been requested when initializing the configuration, this function calculates the current aggregate state. For more information, see the description of aggregation in the class header.

◆ custom()

double MediumState::custom	(	int	m,
		int	h,
		int	i
	)		const

inline

This function returns the value of the custom variable with index \(i\) of the medium component with index \(h\) in the spatial cell with index \(m\).

◆ initAllocate()

size_t MediumState::initAllocate ( )

This function ends the initialization sequence, allocates memory for the state variables, and returns the total number \(N = M (C+\sum_h S_h)\) of state variables. All newly allocated state variables are guaranteed to have a value of zero.

◆ initCommonStateVariables()

void MediumState::initCommonStateVariables ( const vector< StateVariable > & variables )

This function initializes the set of required common state variables.

◆ initCommunicate()

void MediumState::initCommunicate ( )

This function communicates the state variable values between processes after each process has initialized the values for a subset of the spatial cells and left the values for the other cells at zero. (The function uses the ProcessManager::sumToAll() function, so it assumes that the uninitialized variables have a zero value).

◆ initConfiguration()

void MediumState::initConfiguration	(	int	numCells,
		int	numMedia,
		int	numAggregateCells
	)

This function initializes the number of spatial cells and number of medium components. If the specified number of aggregate cells is nonzero, the configuration is also prepared to store that number of aggregate states, as described in the class header.

◆ initSpecificStateVariables()

void MediumState::initSpecificStateVariables ( const vector< StateVariable > & variables )

This function initializes the set of required specific state variables for the next medium component. The function must be called once for each medium component, in order of component index.

◆ magneticField()

Vec MediumState::magneticField ( int m ) const

inline

This function returns the magnetic field \({\boldsymbol{B}}\) in the spatial cell with index \(m\), or zero if storage was not requested for this variable.

◆ metallicity()

double MediumState::metallicity	(	int	m,
		int	h
	)		const

inline

This function returns the metallicity \(Z\) of the medium component with index \(h\) in the spatial cell with index \(m\).

◆ numberDensity()

double MediumState::numberDensity	(	int	m,
		int	h
	)		const

inline

This function returns the number density of the medium component with index \(h\) in the spatial cell with index \(m\).

◆ pushAggregate()

void MediumState::pushAggregate ( )

If aggregation has been requested when initializing the configuration, this function shifts the previously stored aggregate states to make room for a new current aggregate state. For more information, see the description of aggregation in the class header.

◆ setBulkVelocity()

void MediumState::setBulkVelocity	(	int	m,
		Vec	value
	)

This function sets the aggregate bulk velocity \({\boldsymbol{v}}\) of the medium in the spatial cell with index \(m\).

◆ setCustom()

void MediumState::setCustom	(	int	m,
		int	h,
		int	i,
		double	value
	)

This function sets the value of the custom variable with index \(i\) of the medium component with index \(h\) in the spatial cell with index \(m\).

◆ setMagneticField()

void MediumState::setMagneticField	(	int	m,
		Vec	value
	)

This function sets the magnetic field \({\boldsymbol{B}}\) in the spatial cell with index \(m\).

◆ setMetallicity()

void MediumState::setMetallicity	(	int	m,
		int	h,
		double	value
	)

This function sets the metallicity \(Z\) of the medium component with index \(h\) in the spatial cell with index \(m\).

◆ setNumberDensity()

void MediumState::setNumberDensity	(	int	m,
		int	h,
		double	value
	)

This function sets the number density of the medium component with index \(h\) in the spatial cell with index \(m\).

◆ setTemperature()

void MediumState::setTemperature	(	int	m,
		int	h,
		double	value
	)

This function sets the temperature \(T\) of the medium component with index \(h\) in the spatial cell with index \(m\).

◆ setVolume()

void MediumState::setVolume	(	int	m,
		double	value
	)

This function sets the volume \(V\) of the spatial cell with index \(m\).

◆ synchronize()

std::pair< int, int > MediumState::synchronize ( const vector< UpdateStatus > & cellFlags )

This function synchronizes the state variables between processes after each process has possibly updated some of their values. The provided vector indicates the cells for which the calling process has made some changes. The vector must be of length numCells as passed to the initConfiguration() function, where each element in the vector corresponds to the cell with the same index. If the calling process updated the state of a given cell, the corresponding vector element must be UpdatedConverged or UpdatedNotConverged and otherwise it must be NotUpdated. The function returns a pair of integers specifying the total number of updated cells and the total number of not-converged cells, aggregated over all processes.

Only one of the calling processes may have updated the state for any given cell. If two or more processes updated the state of the same cell, the result of the synchronization is undefined.

◆ temperature()

double MediumState::temperature	(	int	m,
		int	h
	)		const

inline

This function returns the temperature \(T\) of the medium component with index \(h\) in the spatial cell with index \(m\).

◆ volume()

double MediumState::volume ( int m ) const

inline

This function returns the volume \(V\) of the spatial cell with index \(m\).

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

MediumState.hpp

Public Member Functions

Private Attributes

Detailed Description

Member Function Documentation

◆ bulkVelocity()

◆ calculateAggregate()

◆ custom()

◆ initAllocate()

◆ initCommonStateVariables()

◆ initCommunicate()

◆ initConfiguration()

◆ initSpecificStateVariables()

◆ magneticField()

◆ metallicity()

◆ numberDensity()

◆ pushAggregate()

◆ setBulkVelocity()

◆ setCustom()

◆ setMagneticField()

◆ setMetallicity()

◆ setNumberDensity()

◆ setTemperature()

◆ setVolume()

◆ synchronize()

◆ temperature()

◆ volume()