SpatialOps
SpatialOps::SpatialField< FieldLocation, T > Class Template Reference

Abstracts a field. More...

#include <SpatialField.h>

Inheritance diagram for SpatialOps::SpatialField< FieldLocation, T >:

Public Types

typedef SpatialField< FieldLocation, T > field_type
 this field's type
 
typedef FieldLocation Location
 this field's location
 
typedef T value_type
 the underlying value type for this field (nominally double)
 
typedef MemoryWindow memory_window
 the window type for this field
 
typedef FieldIterator< field_typeiterator
 the iterator type
 
typedef ConstFieldIterator< field_typeconst_iterator
 const iterator type
 

Public Member Functions

 SpatialField (const MemoryWindow window, const BoundaryCellInfo bc, const GhostData ghosts, T *const fieldValues=NULL, const StorageMode mode=InternalStorage, const short int devIdx=CPU_INDEX)
 SpatialField constructor. More...
 
 SpatialField (const SpatialField &other)
 SpatialField shallow copy constructor. More...
 
 SpatialField (const MemoryWindow window, const SpatialField &other)
 SpatialField shallow copy constructor with new window. More...
 
void swap (SpatialField &other)
 Performs a swap of the two fields. Note that this does not do a deep copy - it is essentially a pointer swap on the memory. More...
 
const BoundaryCellInfoboundary_info () const
 return the boundary cell information
 
const GhostDataget_ghost_data () const
 return the number of total ghost cells
 
const GhostDataget_valid_ghost_data () const
 return the number of current valid ghost cells
 
void reset_valid_ghosts (const GhostData &input)
 set the number of valid ghost cells to given ghosts More...
 
unsigned int allocated_bytes () const
 returns the number of allocated bytes (for copying memory)
 
void wait_for_synchronization ()
 wait until the current stream is done with all work
 
short int active_device_index () const
 return the index of the current active device
 
void add_device (short int deviceIndex)
 add device memory to this field for given device and populate it with values from current active device SYNCHRONOUS VERSION More...
 
void add_device_async (short int deviceIndex)
 add device memory to this field for given device and populate it with values from current active device ASYNCHRONOUS VERSION More...
 
void validate_device (short int deviceIndex)
 populate memory on the given device (deviceIndex) with values from the active device SYNCHRONOUS VERSION More...
 
void validate_device_async (short int deviceIndex)
 populate memory on the given device (deviceIndex) with values from the active device ASYNCHRONOUS VERSION More...
 
void set_device_as_active (const short int deviceIndex)
 set given device (deviceIndex) as active SYNCHRONOUS VERSION More...
 
void set_device_as_active_async (const short int deviceIndex)
 set given device (deviceIndex) as active ASYNCHRONOUS VERSION More...
 
bool is_valid (const short int deviceIndex) const
 check if the device (deviceIndex) is available and valid More...
 
bool is_available (const short int deviceIndex) const
 check if the device (deviceIndex) is available More...
 
T * field_values (const short int deviceIndex=CPU_INDEX)
 return a non-constant pointer to memory on the given device More...
 
const T * field_values (const short int deviceIndex=CPU_INDEX) const
 return a constant pointer to memory on the given device More...
 
const_iterator begin () const
 return a constant iterator for CPU with valid ghost cells
 
iterator begin ()
 return a non-constant iterator for CPU with valid ghost cells
 
const_iterator end () const
 return a constant iterator to end for CPU with valid ghost cells
 
iterator end ()
 return a non-constant iterator to end for CPU with valid ghost cells
 
const_iterator interior_begin () const
 return a constant iterator for CPU without ghost cells
 
iterator interior_begin ()
 return a non-constant iterator for CPU without ghost cells
 
const_iterator interior_end () const
 return a constant iterator to end for CPU without ghost cells
 
iterator interior_end ()
 return a non-constant iterator to end for CPU without ghost cells
 
const T & operator[] (const size_t i) const
 return constant reference to cell at given flat index on CPU More...
 
T & operator[] (const size_t i)
 return non-constant reference to cell at given flat index on CPU More...
 
T & operator() (const IntVec &ijk)
 return non-constant reference to cell at given index (ijk) on CPU More...
 
const T & operator() (const IntVec &ijk) const
 return constant reference to cell at given index (ijk) on CPU More...
 
T & operator() (const size_t i, const size_t j, const size_t k)
 return non-constant reference to cell at given index (i,j,k) on CPU More...
 
const T & operator() (const size_t i, const size_t j, const size_t k) const
 return constant reference to cell at given index (i,j,k) on CPU More...
 
field_typeoperator= (const field_type &)
 copies the contents of one field into another More...
 

Detailed Description

template<typename FieldLocation, typename T = double>
class SpatialOps::SpatialField< FieldLocation, T >

Abstracts a field.

Template Parameters
FieldLocationtype traits to describe the location of this field. On staggered meshes, this will describe the mesh this field is associated with. It also defines whether this field is on a volume or surface.
Tthe underlying datatype (defaults to double)
Related classes:
Public Typedefs
  • field_type - this field's type
  • Location - the location type traits
  • value_type - the type of underlying data being stored in this SpatialField
  • iterator, const_iterator - iterators to the elements in this field
  • iterator, const_iterator - iterators to the interior elements in this field (excludes ghost cells).

Definition at line 132 of file SpatialField.h.

Constructor & Destructor Documentation

◆ SpatialField() [1/3]

template<typename FieldLocation, typename T = double>
SpatialOps::SpatialField< FieldLocation, T >::SpatialField ( const MemoryWindow  window,
const BoundaryCellInfo  bc,
const GhostData  ghosts,
T *const  fieldValues = NULL,
const StorageMode  mode = InternalStorage,
const short int  devIdx = CPU_INDEX 
)
inline

SpatialField constructor.

Parameters
windowMemoryWindow for the entire field (including ghost cells)
bcBoundaryConditionInfo for field
ghostsGhostData for entire field (all possible ghosts)
fieldValuespointer to memory for ExternalStorage mode (default: NULL)
modeeither InternalStorage or ExternalStorage (default: InternalStorage)
devIdxdevice index of originally active device (default: CPU_INDEX)

Definition at line 158 of file SpatialField.h.

◆ SpatialField() [2/3]

template<typename FieldLocation, typename T = double>
SpatialOps::SpatialField< FieldLocation, T >::SpatialField ( const SpatialField< FieldLocation, T > &  other)
inline

SpatialField shallow copy constructor.

Parameters
otherSpatialField to copy

This results in two fields that share the same underlying memory and window information.

Definition at line 189 of file SpatialField.h.

◆ SpatialField() [3/3]

template<typename FieldLocation, typename T = double>
SpatialOps::SpatialField< FieldLocation, T >::SpatialField ( const MemoryWindow  window,
const SpatialField< FieldLocation, T > &  other 
)
inline

SpatialField shallow copy constructor with new window.

Parameters
windowmemory window to use
otherSpatialField to copy

This results in two fields that share the same underlying memory but have window information.

If window maintains the underlying field's interior memory window (window without ghost), and is within the field's global window (window with all possible ghosts), then this copy can change the number of global valid ghost cells. (These sort of changes would change the number of valid ghost cells in other copies of this same field that meet the same requirements.)

Definition at line 213 of file SpatialField.h.

Member Function Documentation

◆ add_device()

template<typename FieldLocation, typename T = double>
void SpatialOps::SpatialField< FieldLocation, T >::add_device ( short int  deviceIndex)
inline

add device memory to this field for given device and populate it with values from current active device SYNCHRONOUS VERSION

Parameters
deviceIndexthe index of the device to add

If device (deviceIndex) is already available for this field and valid, this function becomes a no op.

If device (deviceIndex) is already available for this field but not valid, this function becomes identical to validate_device().

Thus, regardless of the status of device (deviceIndex) for this field, this function does the bare minimum to make device available and valid for this field.

Note: This operation is guaranteed to be synchronous: The host thread waits until the task is completed (on the GPU).

Note: This operation is thread safe.

Definition at line 354 of file SpatialField.h.

◆ add_device_async()

template<typename FieldLocation, typename T = double>
void SpatialOps::SpatialField< FieldLocation, T >::add_device_async ( short int  deviceIndex)
inline

add device memory to this field for given device and populate it with values from current active device ASYNCHRONOUS VERSION

Parameters
deviceIndexthe index of the device to add

If device (deviceIndex) is already available for this field and valid, this function becomes a no op.

If device (deviceIndex) is already available for this field but not valid, this function becomes identical to validate_device().

Thus, regardless of the status of device (deviceIndex) for this field, this function does the bare minimum to make device available and valid for this field.

Note: This operation is asynchronous: The host thread returns immediately after it launches on the GPU.

Note: This operation is thread safe.

Definition at line 377 of file SpatialField.h.

◆ field_values() [1/2]

template<typename FieldLocation, typename T = double>
T* SpatialOps::SpatialField< FieldLocation, T >::field_values ( const short int  deviceIndex = CPU_INDEX)
inline

return a non-constant pointer to memory on the given device

Note: This method will invalidate all the other devices apart from the deviceIndex.

Parameters
deviceIndexindex of device for device memory to return (defaults to CPU_INDEX)

Definition at line 462 of file SpatialField.h.

Referenced by SpatialOps::SpatialField< SpatialOps::SingleValue, T >::operator=().

Here is the caller graph for this function:

◆ field_values() [2/2]

template<typename FieldLocation, typename T = double>
const T* SpatialOps::SpatialField< FieldLocation, T >::field_values ( const short int  deviceIndex = CPU_INDEX) const
inline

return a constant pointer to memory on the given device

Parameters
deviceIndexdevice index for device memory to return (defaults to CPU_INDEX)

Definition at line 471 of file SpatialField.h.

◆ is_available()

template<typename FieldLocation, typename T = double>
bool SpatialOps::SpatialField< FieldLocation, T >::is_available ( const short int  deviceIndex) const
inline

check if the device (deviceIndex) is available

Parameters
deviceIndexindex of device to check

Definition at line 451 of file SpatialField.h.

◆ is_valid()

template<typename FieldLocation, typename T = double>
bool SpatialOps::SpatialField< FieldLocation, T >::is_valid ( const short int  deviceIndex) const
inline

check if the device (deviceIndex) is available and valid

Parameters
deviceIndexindex of device to check

Definition at line 442 of file SpatialField.h.

◆ operator()() [1/4]

template<typename FieldLocation, typename T = double>
T& SpatialOps::SpatialField< FieldLocation, T >::operator() ( const IntVec ijk)
inline

return non-constant reference to cell at given index (ijk) on CPU

Parameters
ijkIntVec coordinate (X,Y,Z) index

Accessing cells with this function can be slow (depending on access pattern), so this function should be used for testing, not production code.

Note that CPU_INDEX must be active for this function to work.

Definition at line 576 of file SpatialField.h.

◆ operator()() [2/4]

template<typename FieldLocation, typename T = double>
const T& SpatialOps::SpatialField< FieldLocation, T >::operator() ( const IntVec ijk) const
inline

return constant reference to cell at given index (ijk) on CPU

Parameters
ijkIntVec coordinate (X,Y,Z) index

Accessing cells with this function can be slow (depending on access pattern), so this function should be used for testing, not production code.

Note that CPU_INDEX must be valid for this function to work.

Definition at line 591 of file SpatialField.h.

◆ operator()() [3/4]

template<typename FieldLocation, typename T = double>
T& SpatialOps::SpatialField< FieldLocation, T >::operator() ( const size_t  i,
const size_t  j,
const size_t  k 
)
inline

return non-constant reference to cell at given index (i,j,k) on CPU

Parameters
iX-dimension index
jY-dimension index
kZ-dimension index

Accessing cells with this function can be slow (depending on access pattern), so this function should be used for testing, not production code.

Note that CPU_INDEX must be active for this function to work.

Definition at line 608 of file SpatialField.h.

◆ operator()() [4/4]

template<typename FieldLocation, typename T = double>
const T& SpatialOps::SpatialField< FieldLocation, T >::operator() ( const size_t  i,
const size_t  j,
const size_t  k 
) const
inline

return constant reference to cell at given index (i,j,k) on CPU

Parameters
iX-dimension index
jY-dimension index
kZ-dimension index

Accessing cells with this function can be slow (depending on access pattern), so this function should be used for testing, not production code.

Note that CPU_INDEX must be valid for this function to work.

Definition at line 625 of file SpatialField.h.

◆ operator=()

template<typename Location , typename T >
SpatialField< Location, T > & SpatialOps::SpatialField< Location, T >::operator= ( const field_type other)
inline

copies the contents of one field into another

Parameters
otherSpatialField to copy data from

The copy happens regardless of what active devices on each field are.

This function WILL modify data outside of memory windows. This limitation is in place for two reasons:

  1. Currently, assignment only happens on windows that take up all memory (or nearly all).
  2. This limitation simplifies the implementation (which is easier to maintain) to use standard libraries (which should be more efficient).

Definition at line 654 of file SpatialField.h.

◆ operator[]() [1/2]

template<typename FieldLocation, typename T = double>
const T& SpatialOps::SpatialField< FieldLocation, T >::operator[] ( const size_t  i) const
inline

return constant reference to cell at given flat index on CPU

Parameters
iflat index of cell to return a constant reference to

Accessing cells with this function can be slow (depending on access pattern), so this function should be used for testing, not production code.

Note that CPU_INDEX must be valid for this function to work.

Definition at line 546 of file SpatialField.h.

◆ operator[]() [2/2]

template<typename FieldLocation, typename T = double>
T& SpatialOps::SpatialField< FieldLocation, T >::operator[] ( const size_t  i)
inline

return non-constant reference to cell at given flat index on CPU

Parameters
iflat index of cell to return a reference to

Accessing cells with this function can be slow (depending on access pattern), so this function should be used for testing, not production code.

Note that CPU_INDEX must be active for this function to work.

Definition at line 561 of file SpatialField.h.

◆ reset_valid_ghosts()

template<typename FieldLocation, typename T = double>
void SpatialOps::SpatialField< FieldLocation, T >::reset_valid_ghosts ( const GhostData input)
inline

set the number of valid ghost cells to given ghosts

Parameters
inputghost cells to be made valid

Definition at line 278 of file SpatialField.h.

◆ set_device_as_active()

template<typename FieldLocation, typename T = double>
void SpatialOps::SpatialField< FieldLocation, T >::set_device_as_active ( const short int  deviceIndex)
inline

set given device (deviceIndex) as active SYNCHRONOUS VERSION

Given device must exist and be valid, otherwise an exception is thrown.

Parameters
deviceIndexindex to device to be made active

Note: This operation is guaranteed to be synchronous: The host thread waits until the task is completed (on the GPU).

Definition at line 419 of file SpatialField.h.

◆ set_device_as_active_async()

template<typename FieldLocation, typename T = double>
void SpatialOps::SpatialField< FieldLocation, T >::set_device_as_active_async ( const short int  deviceIndex)
inline

set given device (deviceIndex) as active ASYNCHRONOUS VERSION

Given device must exist and be valid, otherwise an exception is thrown.

Parameters
deviceIndexindex to device to be made active

Note: This operation is asynchronous: The host thread returns immediately after it launches on the GPU.

Definition at line 433 of file SpatialField.h.

◆ swap()

template<typename FieldLocation, typename T = double>
void SpatialOps::SpatialField< FieldLocation, T >::swap ( SpatialField< FieldLocation, T > &  other)
inline

Performs a swap of the two fields. Note that this does not do a deep copy - it is essentially a pointer swap on the memory.

Parameters
otherthe field to exchange with this one.

Definition at line 230 of file SpatialField.h.

◆ validate_device()

template<typename FieldLocation, typename T = double>
void SpatialOps::SpatialField< FieldLocation, T >::validate_device ( short int  deviceIndex)
inline

populate memory on the given device (deviceIndex) with values from the active device SYNCHRONOUS VERSION

This function performs data-transfers when needed and only when needed.

Parameters
deviceIndexindex for device to synchronize

Note: This operation is guaranteed to be synchronous: The host thread waits until the task is completed (on the GPU).

Definition at line 390 of file SpatialField.h.

◆ validate_device_async()

template<typename FieldLocation, typename T = double>
void SpatialOps::SpatialField< FieldLocation, T >::validate_device_async ( short int  deviceIndex)
inline

populate memory on the given device (deviceIndex) with values from the active device ASYNCHRONOUS VERSION

This function performs data-transfers when needed and only when needed.

Parameters
deviceIndexindex for device to synchronize

Note: This operation is asynchronous: The host thread returns immediately after it launches on the GPU.

Definition at line 405 of file SpatialField.h.


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