#include <AdaptiveMeshSnapshot.hpp>

Inheritance diagram for AdaptiveMeshSnapshot:

Public Member Functions
	AdaptiveMeshSnapshot ()

	~AdaptiveMeshSnapshot ()

void	addNeighbors ()

int	cellIndex (Position bfr) const

std::unique_ptr< PathSegmentGenerator >	createPathSegmentGenerator () const

double	density (int m) const override

double	density (Position bfr) const override

double	diagonal (int m) const

Box	extent () const override

Box	extent (int m) const

Position	generatePosition () const override

Position	generatePosition (int m) const override

void	getEntities (EntityCollection &entities, Position bfr) const override

void	getEntities (EntityCollection &entities, Position bfr, Direction bfk) const override

double	mass () const override

int	numEntities () const override

Position	position (int m) const override

void	readAndClose () override

void	setExtent (const Box &extent)

double	volume (int m) const override

Public Member Functions inherited from Snapshot
	Snapshot ()

virtual	~Snapshot ()

double	age (int m) const

double	age (Position bfr) const

double	currentMass (int m) const

double	currentMass (Position bfr) const

virtual double	density (int m) const =0

virtual double	density (Position bfr) const =0

virtual Box	extent () const =0

virtual Position	generatePosition () const =0

virtual Position	generatePosition (int m) const =0

virtual void	getEntities (EntityCollection &entities, Position bfr) const =0

virtual void	getEntities (EntityCollection &entities, Position bfr, Direction bfk) const =0

bool	hasAge () const

bool	hasCurrentMass () const

bool	hasInitialMass () const

bool	hasMagneticField () const

bool	hasMetallicity () const

bool	hasParameters () const

bool	hasTemperature () const

bool	hasVelocity () const

bool	hasVelocityDispersion () const

bool	holdsNumber () const

void	importBox ()

void	importCurrentMass ()

void	importMagneticField ()

void	importMass ()

void	importMassDensity ()

void	importMetallicity ()

void	importNumber ()

void	importNumberDensity ()

void	importParameters (const vector< SnapshotParameter > &parameters)

void	importPosition ()

void	importSize ()

void	importTemperature ()

void	importVelocity ()

void	importVelocityDispersion ()

double	initialMass (int m) const

double	initialMass (Position bfr) const

Vec	magneticField (int m) const

Vec	magneticField (Position bfr) const

virtual double	mass () const =0

double	metallicity (int m) const

double	metallicity (Position bfr) const

virtual int	numEntities () const =0

void	open (const SimulationItem *item, string filename, string description)

void	parameters (int m, Array &params) const

void	parameters (Position bfr, Array &params) const

virtual Position	position (int m) const =0

virtual void	readAndClose ()

void	setMassDensityPolicy (double multiplier, double maxTemperature, bool useMetallicity)

void	setNeedGetEntities ()

double	SigmaX () const

double	SigmaY () const

double	SigmaZ () const

double	temperature (int m) const

double	temperature (Position bfr) const

void	useColumns (string columns)

Vec	velocity (int m) const

Vec	velocity (Position bfr) const

double	velocityDispersion (int m) const

double	velocityDispersion (Position bfr) const

double	volume () const

virtual double	volume (int m) const =0

Protected Member Functions
int	nearestEntity (Position bfr) const override

const Array &	properties (int m) const override

Protected Member Functions inherited from Snapshot
int	ageIndex () const

int	boxIndex () const

int	currentMassIndex () const

int	densityIndex () const

bool	hasMassDensityPolicy () const

TextInFile *	infile ()

int	initialMassIndex () const

Log *	log () const

void	logMassStatistics (int numIgnored, double totalOriginalMass, double totalMetallicMass, double totalEffectiveMass)

int	magneticFieldIndex () const

int	massIndex () const

double	maxTemperature () const

int	metallicityIndex () const

double	multiplier () const

virtual int	nearestEntity (Position bfr) const =0

bool	needGetEntities () const

int	numParameters () const

int	parametersIndex () const

int	positionIndex () const

virtual const Array &	properties (int m) const =0

Random *	random () const

void	setContext (const SimulationItem *item)

int	sizeIndex () const

int	temperatureIndex () const

Units *	units () const

bool	useMetallicity () const

bool	useTemperatureCutoff () const

int	velocityDispersionIndex () const

int	velocityIndex () const

Private Attributes
vector< Node * >	_cells

Array	_cumrhov

double	_eps

Box	_extent

double	_mass

Array	_rhov

Node *	_root

Friends
class	MySegmentGenerator

Detailed Description

An AdaptiveMeshSnapshot object represents a three-dimensional Adaptive Mesh Refinement (AMR) grid and offers several related interrogation facilities. As implemented by this class, an adaptive mesh recursively partitions a cuboidal spatial domain into cuboidal (sub)cells. In contrast to an octree, which has a fixed 2x2x2 subdivision scheme, an adaptive mesh uses an arbitrary scheme that can (and must) be specified for each subdivision seperately. As a result, an adaptive mesh can provide high resolution (i.e. small cells) in areas where it matters, without consuming memory in areas where the resolution can be lower, in a very flexible manner.

The primary objective of the AdaptiveMeshSnapshot class is to represent snapshot data produced by a hydrodynamical simulation and imported from a column text file, defining a primary source or a transfer medium distribution. To support this use case, the class is based on the Snapshot class; it uses the facilities offered there to configure and help read the snapshot data, and it implements all functions in the general Snapshot public interface. In addition it offers functionality that is specific to this snapshot type, such as, for example, the requirement to configure the spatial extent of the domain. A client should employ the default AdaptiveMeshSnapshot constructor and configure the snapshot object as described in the Snapshot class header.

Additionally, once a snapshot has been imported, the adaptive mesh defined by the snapshot can in some cases also be used to discretize the spatial domain as a basis for the radiative transfer simulation itself. To support this use case, the class offers the capability to trace a linear path through the adaptive mesh.

Once an AdaptiveMeshSnapshot object has been constructed and fully configured, its data is no longer modified. Consequently all getters are re-entrant.

Tree structure, Morton ordering, and file format

The adaptive mesh data structure is organized in a tree. Each tree node represents a cubodial portion of the domain, called its extent. The root node's extent is the complete domain. A nonleaf node distributes its extent over its child nodes using a regular linear grid. The number of subdivisions is defined separately for each node and can differ for each spatial dimension. A leaf node represents a cell in which physical quantities are considered to be constant. Collectively the leaf nodes form a partition of the domain, i.e. their extents cover the complete domain without overlapping one another.

The cells in this three-dimensional data structure can be arranged in a linear sequence using Morton ordering. This ordering is obtained by performing a depth-first traversal of the tree, where each nonleaf node outputs its children in the order x-first, then y, then z.

When reading an adaptive mesh snapshot from a text column input file, each line in the file describes a particular tree node (nonleaf or leaf), and the lines are given in Morton order. Specifically, each line in the file can be one of the following types:

Comment: lines with a crosshatch (#) as the first non-whitespace character, lines containing only whitespace and empty lines are ignored (and do not count in the Morton order).
Nonleaf: a nonleaf line has an exclamation mark (!) as the first non-whitespace character, followed by optional whitespace and then three whitespace-separated positive integer numbers \(N_x,N_y,N_z\). These three numbers specify the number of child nodes carried by this node in each spatial direction. The child nodes are on a regular linear grid as described above.
Leaf: a leaf node contains one or more whitespace-separated floating point numbers reflecting the physical quantities associated with the leaf node, depending on the user configuration settings for the snapshot. The default units for these quantities can be overridden by including columns header info in the file as described in the TextInFile class header.

Note that the input file does not include the physical extent of the domain; this information must be provided as part of the user configuration for the snapshot.

Below is an example of an adaptive mesh import file. For illustrative purposes:

the mesh is assumed to have a single cell in the z direction;
the value in the first colum indicates the Morton order index of the leaf cell;
the values in the remaining two columns indicate the x and y coordinates of the cell's center using a domain of size 4. x 3. with one corner at the origin.

# Example adaptive mesh import data file
#
! 4 3 1
 0 0.50 0.50
 1 1.50 0.50
 2 2.50 0.50
 3 3.50 0.50
 4 0.50 1.50
 5 1.50 1.50
! 2 2 1
 6 2.25 1.25
 7 2.75 1.25
 8 2.25 1.75
! 2 2 1
 9 2.63 1.63
10 2.88 1.63
11 2.63 1.88
12 2.88 1.88
! 2 2 1
13 3.25 1.25
14 3.75 1.25
15 3.25 1.75
16 3.75 1.75
17 0.50 2.50
18 1.50 2.50
! 2 2 1
19 2.25 2.25
20 2.75 2.25
21 2.25 2.75
22 2.75 2.75
! 2 2 1
23 3.25 3.25
24 3.75 3.25
25 3.25 3.75
26 3.75 3.75

Constructor & Destructor Documentation

◆ AdaptiveMeshSnapshot()

AdaptiveMeshSnapshot::AdaptiveMeshSnapshot ( )

The default constructor initializes the snapshot in an invalid state; see the description of the required calling sequence in the Snapshot class header.

◆ ~AdaptiveMeshSnapshot()

AdaptiveMeshSnapshot::~AdaptiveMeshSnapshot ( )

The destructor releases any data structures allocated by this class.

Member Function Documentation

◆ addNeighbors()

void AdaptiveMeshSnapshot::addNeighbors ( )

This function adds neighbor information to all leaf nodes in the adaptive mesh. If should be called after the readAndClose() function has completed its operation, and before the createPathSegmentGenerator() function is invoked. Specifically, the function causes each leaf node to remember its most likely neighbor at each of its six walls. This information, while optional, substantially accelerates path construction.

◆ cellIndex()

int AdaptiveMeshSnapshot::cellIndex ( Position bfr ) const

This function returns the leaf cell index \(0\le m \le N_{cells}-1\) for the cell containing the specified point \({\bf{r}}\). If the point is outside the domain, the function returns -1. The function recursively searches the adaptive mesh tree until it finds the appropriate leaf cell.

◆ createPathSegmentGenerator()

std::unique_ptr< PathSegmentGenerator > AdaptiveMeshSnapshot::createPathSegmentGenerator ( ) const

This function creates and hands over ownership of a path segment generator appropriate for the adaptive mesh spatial grid, implemented as a private PathSegmentGenerator subclass.

The algorithm used to construct the path is fairly straightforward because all cells are cuboids lined up with the coordinate axes. The information added by the addNeighbors() function significantly accelerates path construction.

◆ density() [1/2]

double AdaptiveMeshSnapshot::density ( int m ) const

overridevirtual

This function returns the mass density associated with the leaf cell with index m. If no density policy has been set or no mass information is being imported, or if the index is out of range, the behavior is undefined.

Implements Snapshot.

◆ density() [2/2]

double AdaptiveMeshSnapshot::density ( Position bfr ) const

overridevirtual

This function returns the mass density represented by the snapshot at a given point \({\bf{r}}\), or equivalently, the mass density associated with the leaf cell containing the given point. If the point is outside the domain, the function returns zero. If no density policy has been set or no mass information is being imported, the behavior is undefined.

Implements Snapshot.

◆ diagonal()

double AdaptiveMeshSnapshot::diagonal ( int m ) const

This function returns the diagonal of the leaf cell with index m. If the index is out of range, the behavior is undefined.

◆ extent() [1/2]

Box AdaptiveMeshSnapshot::extent ( ) const

overridevirtual

This function returns the extent of the spatial domain as configured through the setExtent() function.

Implements Snapshot.

◆ extent() [2/2]

Box AdaptiveMeshSnapshot::extent ( int m ) const

This function returns the bounding box (which is by definition lined up with the coordinate axes) of the leaf cell with index m. If the index is out of range, the behavior is undefined.

◆ generatePosition() [1/2]

Position AdaptiveMeshSnapshot::generatePosition ( ) const

overridevirtual

This function returns a random position within the spatial domain of the snapshot, drawn from the mass density distribution represented by the snapshot. The function first selects a random leaf cell from the discrete probability distribution formed by the respective cell masses, and then generates a random position uniformly from the volume of that cell. If no density policy has been set or no mass information is being imported, the behavior is undefined.

Implements Snapshot.

◆ generatePosition() [2/2]

Position AdaptiveMeshSnapshot::generatePosition ( int m ) const

overridevirtual

This function returns a random position drawn uniformly from the (cuboidal) extent of the leaf cell with index m. If the index is out of range, the behavior is undefined.

Implements Snapshot.

◆ getEntities() [1/2]

void AdaptiveMeshSnapshot::getEntities	(	EntityCollection &	entities,
		Position	bfr
	)		const

overridevirtual

This function sets the specified entity collection to the cell containing the specified point \({\bf{r}}\), or to the empty collection if the point is outside the domain.

Implements Snapshot.

◆ getEntities() [2/2]

void AdaptiveMeshSnapshot::getEntities	(	EntityCollection &	entities,
		Position	bfr,
		Direction	bfk
	)		const

overridevirtual

This function replaces the contents of the specified entity collection by the set of cells crossed by the specified path with starting point \({\bf{r}}\) and direction \({\bf{k}}\). The weight of a cell is given by the length of the path segment inside the cell. If the path does not cross the spatial domain of the snapshot, the collection will be empty.

Implements Snapshot.

◆ mass()

double AdaptiveMeshSnapshot::mass ( ) const

overridevirtual

This function returns the total mass represented by the snapshot, in other words the sum of the masses of all leaf cells. If no density policy has been set or no mass information is being imported, the behavior is undefined.

Implements Snapshot.

◆ nearestEntity()

int AdaptiveMeshSnapshot::nearestEntity ( Position bfr ) const

overrideprotectedvirtual

This function returns the index \(0\le m \le N_\mathrm{ent}-1\) of the cell containing the specified point \({\bf{r}}\), or -1 if the point is outside the domain.

Implements Snapshot.

◆ numEntities()

int AdaptiveMeshSnapshot::numEntities ( ) const

overridevirtual

This function returns the number of leaf cells in the adaptive mesh snapshot.

Implements Snapshot.

◆ position()

Position AdaptiveMeshSnapshot::position ( int m ) const

overridevirtual

This function returns the position of the center of the leaf cell with index m. If the index is out of range, the behavior is undefined.

Implements Snapshot.

◆ properties()

const Array & AdaptiveMeshSnapshot::properties ( int m ) const

overrideprotectedvirtual

This function returns a reference to an array containing the imported properties (in column order) for the cell with index \(0\le m \le N_\mathrm{ent}-1\). If the index is out of range, the behavior is undefined.

Implements Snapshot.

◆ readAndClose()

void AdaptiveMeshSnapshot::readAndClose ( )

overridevirtual

This function reads the snapshot data from the input file, honoring the options set through the configuration functions, stores the data for later use, and closes the file by calling the base class Snapshot::readAndClose() function.

Cells with an associated temperature above the cutoff temperature (if one has been configured) are assigned a density value of zero, so that the cell has zero mass regardless of the imported mass/density properties.

The function logs some statistical information about the imported snapshot and the resulting data structures.

Reimplemented from Snapshot.

◆ setExtent()

void AdaptiveMeshSnapshot::setExtent ( const Box & extent )

This function sets the extent of the spatial domain for the adaptive mesh. It must be called during configuration, before the readAndClose() function is invoked. There is no default extent; failing to set the extent of the domain results in undefined behavior.

◆ volume()

double AdaptiveMeshSnapshot::volume ( int m ) const

overridevirtual

This function returns the volume of the leaf cell with index m. If the index is out of range, the behavior is undefined.

Implements Snapshot.

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

AdaptiveMeshSnapshot.hpp

Public Member Functions

Protected Member Functions

Private Attributes

Friends

Detailed Description

Tree structure, Morton ordering, and file format

Constructor & Destructor Documentation

◆ AdaptiveMeshSnapshot()

◆ ~AdaptiveMeshSnapshot()

Member Function Documentation

◆ addNeighbors()

◆ cellIndex()

◆ createPathSegmentGenerator()

◆ density() [1/2]

◆ density() [2/2]

◆ diagonal()

◆ extent() [1/2]

◆ extent() [2/2]

◆ generatePosition() [1/2]

◆ generatePosition() [2/2]

◆ getEntities() [1/2]

◆ getEntities() [2/2]

◆ mass()

◆ nearestEntity()

◆ numEntities()

◆ position()

◆ properties()

◆ readAndClose()

◆ setExtent()

◆ volume()