SphericalCellSnapshot Class Reference

#include <SphericalCellSnapshot.hpp>

Inheritance diagram for SphericalCellSnapshot:

Public Member Functions
double	density (int m) const override
double	density (Position bfr) const override
Box	extent () const override
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	setNumAutoRevolveBins (int numInclinationBins, int numAzimuthBins)
double	volume (int m) const override
Public Member Functions inherited from Snapshot
	Snapshot ()
virtual	~Snapshot ()
double	age (int m) const
double	bias (int m) const
void	close ()
double	currentMass (int m) 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	hasBias () 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	importBias ()
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
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	setCoordinateSystem (CoordinateSystem coordinateSystem)
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	volume () const
virtual double	volume (int m) const =0

Protected Member Functions
const Array &	properties (int m) const override
Protected Member Functions inherited from Snapshot
int	ageIndex () const
int	biasIndex () const
int	boxIndex () const
void	calculateDensityAndMass (Array &rhov, Array &cumrhov, double &mass)
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
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< SphericalCell >	_cellv
Array	_cumrhov
double	_mass
int	_numAutoAzimuthBins
int	_numAutoInclinationBins
vector< Array >	_propv
Array	_rhov
BoxSearch	_search

Additional Inherited Members
Public Types inherited from Snapshot
enum class	CoordinateSystem { CARTESIAN , CYLINDRICAL , SPHERICAL }

Detailed Description

A SphericalCellSnapshot object represents the data in a 1D, 2D or 3D snapshot imported from a column text file and discretized using spherical coordinates.

3D data

By default, each line in the text file represents a 3D spherical cell lined up with the spherical coordinate axes. The columns specify the coordinates of the bordering surfaces, along with properties such as density. Specifically, each cell is bordered by:

• two spheres centered on the origin defined by radii $0\le r_{\text{min}}\le r_{\text{max}}$,
• two polar half-cones defined by inclination angles $0\le {\theta }_{\text{min}}\le {\theta }_{\text{max}}\le \pi$,
• two meridional half-planes defined by azimuth angles $-\pi \le {\phi }_{\text{min}}\le {\phi }_{\text{max}}\le \pi$ with ${\phi }_{\text{max}}-{\phi }_{\text{min}}\le \pi$.

Note

Because of the limitations on the range of $\phi$, a cell cannot straddle the negative x-axis of the Cartesian model coordinate system, and it cannot span more than half of the azimuth circle. Also, because of the limitations on the range of $\theta$, a cell cannot straddle the z-axis of the Cartesian model coordinate system.

The intention is for the cells to define a partition of the spatial domain, and usually they will, however this is not enforced. When two or more cells overlap at a given position, the properties for that position will be taken from the cell that is listed first in the imported file. When no cells overlap a given position, the density at that position is considered to be zero. To avoid thin slices of zero density between cells, the coordinates for common walls or corners in neighboring cells should be identical.

Velocities

If velocity or magnetic field vectors are being imported, the class converts these from spherical to Cartesian coordinates using

$$\begin{array}{rl}{v}_{\text{x}}& =v_r\sin \theta \cos \phi +v_{\theta }\cos \theta \cos \phi -v_{\phi }\sin \phi \\ v_{\text{y}}& =v_r\sin \theta \sin \phi +v_{\theta }\cos \theta \sin \phi +v_{\phi }\cos \phi \\ v_{\text{z}}& =v_r\cos \theta -v_{\theta }\sin \theta \end{array}$$

where $\theta =({\theta }_{\text{min}}+{\theta }_{\text{max}})/2$ and $\phi =({\phi }_{\text{min}}+{\phi }_{\text{max}})/2$ are the central inclination and azimuth angles of the corresponding cell.

2D or 1D data

If the inclination auto-revolve feature is enabled, each line in the text file represents a 2D cell in the equatorial plane, defined using just the $r$ and $\phi$ borders. After reading the text file, these cells will automatically be revolved around the origin using a user-specified number of $\theta$ bins. To enable this feature, the number of inclination auto-revolve bins must be set to at least 2, and all ${\theta }_{\text{min}}$ and ${\theta }_{\text{max}}$ values in the input file must be zero. A nonzero value in these columns will trigger a fatal error.

If the azimuth auto-revolve feature is enabled, each line in the text file represents a 2D cell in a meridional plane, defined using just the $r$ and $\theta$ borders. After reading the text file, these cells will automatically be revolved around the z-axis using a user-specified number of $\phi$ bins. To enable this feature, the number of azimuth auto-revolve bins must be set to at least 2, and all ${\phi }_{\text{min}}$ and ${\phi }_{\text{max}}$ values in the input file must be zero. A nonzero value in these columns will trigger a fatal error.

Finally, if both the inclination and azimuth auto-revolve features are enabled, each line in the text file represents a 1D cell along a radial axis, defined using just the $r$ borders. After reading the text file, these 1D cells will automatically be revolved using the user-specified number of $\theta$ and $\phi$ bins.

Note

It is not allowed to omit the unused columns; they must be present with zero values.

If the 1D or 2D input file specifies an integrated mass type (as opposed to a mass density), the mass of each 1D or 2D cell is evenly distributed over the revolved 3D bins.

For a model that includes velocities, the velocities will be converted from spherical to Cartesian coordinates as described above after revolving to a 3D representation. Because the result of this conversion depends on the inclination and azimuth angles, the user must set a sufficiently high number of auto-revolve bins to properly resolve the revolved velocity field.

Implementation

This class is based on the Snapshot class; it uses the facilities offered there to configure and read the snapshot data, and it implements all functions in the general Snapshot public interface. If the snapshot configuration requires the ability to determine the density at a given spatial position, an effort is made to accelerate the search for the cell containing that position even for a large number of cells.

Member Function Documentation

density() [1/2]

double SphericalCellSnapshot::density ( int  m ) const

overridevirtual

This function returns the mass density associated with the 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 SphericalCellSnapshot::density ( Position  bfr ) const

overridevirtual

This function returns the mass density of the cell containing the specified point $\mathbf{r}$. If the point is not inside any cell, the function returns zero. If no density policy has been set or no mass information is being imported, the behavior is undefined.

Implements Snapshot.

extent()

Box SphericalCellSnapshot::extent ( ) const

overridevirtual

This function returns the bounding box lined up with the coordinate axes surrounding all cells.

Implements Snapshot.

generatePosition() [1/2]

Position SphericalCellSnapshot::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 cell from the discrete probability distribution formed by the respective cell masses, and then generates a random position within 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 SphericalCellSnapshot::generatePosition ( int  m ) const

overridevirtual

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

Implements Snapshot.

getEntities() [1/2]

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

overridevirtual

This function sets the specified entity collection to the cell containing the specified point $\mathbf{r}$, or to the empty collection if the point is outside the domain or if there are no cells in the snapshot. If the search data structures were not created, invoking this function causes undefined behavior.

Implements Snapshot.

getEntities() [2/2]

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

overridevirtual

This function replaces the contents of the specified entity collection by the set of cells that overlap the specified path with starting point $\mathbf{r}$ and direction $\mathbf{k}$. The weight of a cell is given by the length of the path segment inside the cell. If the path does not overlap any cells, the collection will be empty. If the search data structures were not created, invoking this function causes undefined behavior.

Implements Snapshot.

mass()

double SphericalCellSnapshot::mass ( ) const

overridevirtual

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

Implements Snapshot.

numEntities()

int SphericalCellSnapshot::numEntities ( ) const

overridevirtual

This function returns the number of cells in the snapshot.

Implements Snapshot.

position()

Position SphericalCellSnapshot::position ( int  m ) const

overridevirtual

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

Implements Snapshot.

properties()

const Array & SphericalCellSnapshot::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{e}\mathrm{n}\mathrm{t}}-1$. If the index is out of range, the behavior is undefined.

Implements Snapshot.

readAndClose()

void SphericalCellSnapshot::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::close() function.

Cells with an associated temperature above the cutoff temperature (if one has been configured) are assigned a density value of zero, so that they have zero mass regardless of the imported mass/density properties. Note that we cannot simply ignore these cells because an empty cell may overlap and thus hide (a portion of) a nonempty cell later in the list.

If velocity and/or magnetic field vectors are being imported, the function converts these from spherical to Cartesian coordinates as described in the class header.

The function also logs some statistical information about the import. If the snapshot configuration requires the ability to determine the density at a given spatial position, this function builds a data structure that accelerates the search for the appropriate cell.

Reimplemented from Snapshot.

setNumAutoRevolveBins()

void SphericalCellSnapshot::setNumAutoRevolveBins	(	int	numInclinationBins,
		int	numAzimuthBins
	)

This function sets the number of auto-revolve inclination and azimuth bins; see the class header for more information.

volume()

double SphericalCellSnapshot::volume ( int  m ) const

overridevirtual

This function returns the volume of the 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:

• SphericalCellSnapshot.hpp