SpatialOps
Field Tools

Information about fields and how to manipulate and create them. More...

Files

file  FieldComparisons.h
 Comparison operators.
 

Classes

class  SpatialOps::BitField
 Implements a mask as a bitfield. More...
 
class  SpatialOps::FieldInfo< T >
 Abstracts the internals of a field. More...
 
class  SpatialOps::GhostData
 Holds information about the number of ghost cells on each side of the domain. More...
 
class  SpatialOps::MemoryWindow
 Provides tools to index into a sub-block of memory. More...
 
class  SpatialOps::FieldIterator< FieldType >
 provides iterator support for SpatialField. Only works for CPU. More...
 
class  SpatialOps::ConstFieldIterator< FieldType >
 provides iterator support for SpatialField. Only works for CPU. More...
 
class  SpatialOps::SpatialField< FieldLocation, T >
 Abstracts a field. More...
 

Enumerations

enum  SpatialOps::StorageMode { SpatialOps::InternalStorage, SpatialOps::ExternalStorage }
 Specifies how memory should be treated in a SpatialField.
 

Functions

template<typename Field >
void SpatialOps::initialize_field (Field &f, const double start=0.0, const bool print=false, const double range=1.0)
 initialize a field (and ghost cells) with pseudorandom numbers More...
 
template<typename Field >
void SpatialOps::interior_initialize_field (Field &f, const double start=0.0, const bool print=false, const double range=1.0)
 initialize a field (without ghost cells) with pseudorandom numbers More...
 
template<typename Field >
void SpatialOps::print_field (const Field &f, std::ostream &os, const bool addFormat=false)
 print the values of a field (and ghost cells) to standard output More...
 
template<typename Field >
void SpatialOps::interior_print_field (const Field &f, std::ostream &os, const bool addFormat=false)
 print the values of a field (without ghost cells) to standard output More...
 
template<typename Field >
bool SpatialOps::display_fields_compare (const Field &field1, const Field &field2, const bool display=false, const bool print=false)
 compare two fields and possibly print values (with ghost cells) More...
 
template<typename Field >
bool SpatialOps::interior_display_fields_compare (const Field &field1, const Field &field2, const bool display=false, const bool print=false)
 compare two fields and possibly print values (without ghost cells) More...
 
template<typename FieldT >
bool SpatialOps::field_not_equal (const FieldT &f1, const FieldT &f2, double error=0.0)
 Returns if f1 is element-wise not equal to f2 within a certain relative tolerance.This function simply calls field_equal and negates it. return !field_equal(f1, f2, error, error_abs); error_abs is defined as default to be the L2 norm of f1 multiplied by error and FIELDCOMPARISONS_ABS_ERROR_CONST. More...
 
template<typename FieldT >
bool SpatialOps::field_equal (const double d, const FieldT &f1, double error, const double errorAbs)
 Returns if f1 is element-wise equal to the scalar value d within a certain relative tolerance. More...
 
int SpatialOps::get_dim_with_ghost (const int nNoGhost, const int minusGhost, const int plusGhost, const int bc)
 obtain the number of points in the x direction More...
 
MemoryWindow SpatialOps::get_window_with_ghost (const IntVec &localDim, const GhostData &ghost, const BoundaryCellInfo &bc)
 Obtain the memory window for a field on a patch that is a single, contiguous memory block. More...
 

Detailed Description

Information about fields and how to manipulate and create them.

Function Documentation

◆ display_fields_compare()

template<typename Field >
bool SpatialOps::display_fields_compare ( const Field &  field1,
const Field &  field2,
const bool  display = false,
const bool  print = false 
)
inline

compare two fields and possibly print values (with ghost cells)

Parameters
field1first field to use to read values
field2second field to use to read values
displayboolean value, if true prints comparison of each index
printboolean value, if true prints values of each index of each iterator
Returns
boolean value, if true fields are equal within given window

This function prints values starting with the lowest index first (0,0,0). The first line contains the X-axis row of values (with Y and Z indices fixed at 0). The second line contains the X-axis row of values (with Y index of 1, and Z index of 0). A blank line represents the end of one XY plane and the start of the next.

Graphically, with X-axis extent of I, Y-axis extent of J, and Z-axis extent of K:

 (0,0,0) (1,0,0) ... (I,0,0)
 (0,1,0) (1,1,0) ... (I,1,0)
    .       .    .      .
    .       .     .     .
    .       .      .    .
 (0,J,0) (1,J,0) ... (I,J,0)

 (0,0,1) (1,0,1) ... (I,0,1)
 (0,1,1) (1,1,1) ... (I,1,1)
    .       .    .      .
    .       .     .     .
    .       .      .    .
 (0,J,1) (1,J,1) ... (I,J,1)

 (0,0,K) (1,0,K) ... (I,0,K)
 (0,1,K) (1,1,K) ... (I,1,K)
    .       .    .      .
    .       .     .     .
    .       .      .    .
 (0,J,K) (1,J,K) ... (I,J,K)

For the use in this function, (0,0,0) is the lowest ghost cell, and (I,J,K) is the highest ghost cell.

If display is true, prints 0 or 1 for each index. 0 is printed if values in fields are different at that index. 1 is printed if values in fields are the same.

If print is true, prints two tabs, then values for the first field in one X-axis row, two more tabs, and then values for the second field in one X-axis row. Thus, the values of the two fields can be compared visually side-by-side. Note that the values printed with the print flag are rounded and do NOT show machine-precision values.

If both display and print are true, the output of both appear, side-by-side, per X-axis row.

If both display and print are false, nothing is printed to standard output.

Printing values may be difficult to read if the fields' extents are too large, or the screen used to view them is too small.

Currently this function only works on CPU-allocated memory and fields. (CPU is at least valid, if not active.)

Definition at line 512 of file FieldHelper.h.

◆ field_equal()

template<typename FieldT >
template< typename FieldT > bool SpatialOps::field_equal ( const double  d,
const FieldT &  f1,
double  error,
const double  errorAbs 
)

Returns if f1 is element-wise equal to the scalar value d within a certain relative tolerance.

This function returns the result of |d - f1|/(error_abs + |d|) > error element wise.

WARNING: Slow in general and comparison with external fields will incur copy penalties.

Template Parameters
FieldT– Any type of SpatialField
Parameters
d– Scalar value
f1– Field 1
error– Allowable percentage of error. i.e. 1% = .01
errorAbs– Allowable absolute error. This term becomes significant in the calculation as d approaches zero.

Definition at line 392 of file FieldComparisons.h.

Referenced by SpatialOps::field_not_equal().

Here is the caller graph for this function:

◆ field_not_equal()

template<typename FieldT >
template< typename FieldT > bool SpatialOps::field_not_equal ( const FieldT &  f1,
const FieldT &  f2,
double  error = 0.0 
)

Returns if f1 is element-wise not equal to f2 within a certain relative tolerance.This function simply calls field_equal and negates it. return !field_equal(f1, f2, error, error_abs); error_abs is defined as default to be the L2 norm of f1 multiplied by error and FIELDCOMPARISONS_ABS_ERROR_CONST.

WARNING: Undefined behavior if f1 is a field of all 0's.

WARNING: Slow in general and comparison with external fields will incur copy penalties.

Template Parameters
FieldT– Any type of SpatialField
Parameters
f1– Field 1
f2– Field 2
error– Allowable percentage of error. i.e. 1% = .01

Definition at line 67 of file FieldComparisons.h.

References SpatialOps::field_not_equal().

Referenced by SpatialOps::field_not_equal().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ get_dim_with_ghost()

int SpatialOps::get_dim_with_ghost ( const int  nNoGhost,
const int  minusGhost,
const int  plusGhost,
const int  bc 
)
inline

obtain the number of points in the x direction

Parameters
nNoGhostnumber of points in the current direction excluding ghost cells
minusGhostthe number of ghost cells on the negative face
plusGhostthe number of ghost cells on the positive face
bcthe number of boundary cells on the positive face
Returns
the number of points in the current direction, including ghost cells and boundary cells

Definition at line 290 of file MemoryWindow.h.

◆ get_window_with_ghost()

MemoryWindow SpatialOps::get_window_with_ghost ( const IntVec localDim,
const GhostData ghost,
const BoundaryCellInfo bc 
)
inline

Obtain the memory window for a field on a patch that is a single, contiguous memory block.

Parameters
localDimnumber of points in each direction excluding ghost cells
ghostthe GhostData information
bcBoundaryCellInfo describing the behavior of a field when a (+) side boundary is present. Note that a MemoryWindow obtained here is paired for use specifically with fields that share common BoundaryCellInfo.
Returns
the total number of points in the field, including ghost cells.

Definition at line 314 of file MemoryWindow.h.

References SpatialOps::MemoryWindow::MemoryWindow().

Here is the call graph for this function:

◆ initialize_field()

template<typename Field >
void SpatialOps::initialize_field ( Field &  f,
const double  start = 0.0,
const bool  print = false,
const double  range = 1.0 
)
inline

initialize a field (and ghost cells) with pseudorandom numbers

Parameters
ffield to initialize
startdouble that represents minimum value to assign (defaults to 0.0)
printboolean value, if true prints the values it assigns to standard output (defaults to false)
rangemaximum value to assign (negation will be minimum value) (defaults to 1.0)

This function assigns non-integer values to the field f, including ghost cells. The value assigned to a cell with index (x,y,z) is given by:

range * sin(start + x + y * xExtent + z * xExtent * yExtent)

Since sine of anything returns values between [-1, 1], the range of values assigned by this function are [-range, range].

This function can be used to initialize multiple fields with different pseudorandom numbers by setting start to different values. This function turns each index triplet into a flat index. For new values, set start to be past the last used flat index. So in general, for the first field, set start to 0. Assuming all fields are the same size, set start to xExtent * yExtent * zExtent for the second field. For the third field, set start to be twice that value, and so on.

Currently this function only works on CPU-allocated memory and fields. (CPU set to active.)

Definition at line 124 of file FieldHelper.h.

◆ interior_display_fields_compare()

template<typename Field >
bool SpatialOps::interior_display_fields_compare ( const Field &  field1,
const Field &  field2,
const bool  display = false,
const bool  print = false 
)
inline

compare two fields and possibly print values (without ghost cells)

Parameters
field1first field to use to read values
field2second field to use to read values
displayboolean value, if true prints comparison of each index
printboolean value, if true prints values of each index of each iterator
Returns
boolean value, if true fields are equal within given window

This function prints values starting with the lowest index first (0,0,0). The first line contains the X-axis row of values (with Y and Z indicies fixed at 0). The second line contains the X-axis row of values (with Y index of 1, and Z index of 0). A blank line represents the end of one XY plane and the start of the next.

Graphically, with X-axis extent of I, Y-axis extent of J, and Z-axis extent of K:

 (0,0,0) (1,0,0) ... (I,0,0)
 (0,1,0) (1,1,0) ... (I,1,0)
    .       .    .      .
    .       .     .     .
    .       .      .    .
 (0,J,0) (1,J,0) ... (I,J,0)

 (0,0,1) (1,0,1) ... (I,0,1)
 (0,1,1) (1,1,1) ... (I,1,1)
    .       .    .      .
    .       .     .     .
    .       .      .    .
 (0,J,1) (1,J,1) ... (I,J,1)

 (0,0,K) (1,0,K) ... (I,0,K)
 (0,1,K) (1,1,K) ... (I,1,K)
    .       .    .      .
    .       .     .     .
    .       .      .    .
 (0,J,K) (1,J,K) ... (I,J,K)

For the use in this function, (0,0,0) is the lowest interior cell, and (I,J,K) is the highest interior cell. No ghost cells are printed with this function.

If display is true, prints 0 or 1 for each index. 0 is printed if values in fields are different at that index. 1 is printed if values in fields are the same.

If print is true, prints two tabs, then values for the first field in one X-axis row, two more tabs, and then values for the second field in one X-axis row. Thus, the values of the two fields can be compared visually side-by-side. Note that the values printed with the print flag are rounded and do NOT show machine-precision values.

If both display and print are true, the output of both appear, side-by-side, per X-axis row.

If both display and print are false, nothing is printed to standard output.

Printing values may be difficult to read if the fields' extents are too large, or the screen used to view them is too small.

Currently this function only works on CPU-allocated memory and fields. (CPU is at least valid, if not active.)

Definition at line 590 of file FieldHelper.h.

◆ interior_initialize_field()

template<typename Field >
void SpatialOps::interior_initialize_field ( Field &  f,
const double  start = 0.0,
const bool  print = false,
const double  range = 1.0 
)
inline

initialize a field (without ghost cells) with pseudorandom numbers

Parameters
ffield to initialize
startdouble that represents minimum value to assign (defaults to 0.0)
printboolean value, if true prints the values it assigns to standard output (defaults to false)
rangemaximum value to assign (negation will be minimum value) (defaults to 1.0)

This function assigns non-integer values to the field f, NOT including ghost cells. The value assigned to a cell with index (x,y,z) is given by:

range * sin(start + x + y * xExtent + z * xExtent * yExtent)

Since sine of anything returns values between [-1, 1], the range of values assigned by this function are [-range, range].

This function can be used to initialize multiple fields with different pseudorandom numbers by setting start to different values. This function turns each index triplet into a flat index. For new values, set start to be past the last used flat index. So in general, for the first field, set start to 0. Assuming all fields are the same size, set start to xExtent * yExtent * zExtent for the second field. For the third field, set start to be twice that value, and so on.

Currently this function only works on CPU-allocated memory and fields. (CPU set to active.)

Definition at line 162 of file FieldHelper.h.

◆ interior_print_field()

template<typename Field >
void SpatialOps::interior_print_field ( const Field &  f,
std::ostream &  os,
const bool  addFormat = false 
)
inline

print the values of a field (without ghost cells) to standard output

Parameters
ffield to print
osoutput stream to write to
addFormatboolean flag to either print with tight format or standard precision

This function prints values starting with the lowest index first (0,0,0). The first line contains the X-axis row of values (with Y and Z indicies fixed at 0). The second line contains the X-axis row of values (with Y index of 1, and Z index of 0). A blank line represents the end of one XY plane and the start of the next.

Graphically, with X-axis extent of I, Y-axis extent of J, and Z-axis extent of K:

 (0,0,0) (1,0,0) ... (I,0,0)
 (0,1,0) (1,1,0) ... (I,1,0)
    .       .    .      .
    .       .     .     .
    .       .      .    .
 (0,J,0) (1,J,0) ... (I,J,0)

 (0,0,1) (1,0,1) ... (I,0,1)
 (0,1,1) (1,1,1) ... (I,1,1)
    .       .    .      .
    .       .     .     .
    .       .      .    .
 (0,J,1) (1,J,1) ... (I,J,1)

 (0,0,K) (1,0,K) ... (I,0,K)
 (0,1,K) (1,1,K) ... (I,1,K)
    .       .    .      .
    .       .     .     .
    .       .      .    .
 (0,J,K) (1,J,K) ... (I,J,K)

For the use in this function, (0,0,0) is the lowest interior cell, and (I,J,K) is the highest interior cell. No ghost cells are printed with this function.

Currently this function only works on CPU-allocated memory and fields. (CPU is at least valid, if not active.)

Definition at line 333 of file FieldHelper.h.

◆ print_field()

template<typename Field >
void SpatialOps::print_field ( const Field &  f,
std::ostream &  os,
const bool  addFormat = false 
)
inline

print the values of a field (and ghost cells) to standard output

Parameters
ffield to print
osoutput stream to write to
addFormatboolean flag to either print with tight format or standard precision

This function prints values starting with the lowest index first (0,0,0). The first line contains the X-axis row of values (with Y and Z indicies fixed at 0). The second line contains the X-axis row of values (with Y index of 1, and Z index of 0). A blank line represents the end of one XY plane and the start of the next.

Graphically, with X-axis extent of I, Y-axis extent of J, and Z-axis extent of K:

 (0,0,0) (1,0,0) ... (I,0,0)
 (0,1,0) (1,1,0) ... (I,1,0)
    .       .    .      .
    .       .     .     .
    .       .      .    .
 (0,J,0) (1,J,0) ... (I,J,0)

 (0,0,1) (1,0,1) ... (I,0,1)
 (0,1,1) (1,1,1) ... (I,1,1)
    .       .    .      .
    .       .     .     .
    .       .      .    .
 (0,J,1) (1,J,1) ... (I,J,1)

 (0,0,K) (1,0,K) ... (I,0,K)
 (0,1,K) (1,1,K) ... (I,1,K)
    .       .    .      .
    .       .     .     .
    .       .      .    .
 (0,J,K) (1,J,K) ... (I,J,K)

For the use in this function, (0,0,0) is the lowest ghost cell, and (I,J,K) is the highest ghost cell.

Currently this function only works on CPU-allocated memory and fields. (CPU is at least valid, if not active.)

Definition at line 281 of file FieldHelper.h.