openPMD-api
Public Types | Public Member Functions | Static Public Attributes | Friends | List of all members
openPMD::RecordComponent Class Reference
Inheritance diagram for openPMD::RecordComponent:
Inheritance graph
[legend]
Collaboration diagram for openPMD::RecordComponent:
Collaboration graph
[legend]

Public Types

enum  Allocation { USER, API, AUTO }
 
- Public Types inherited from openPMD::Attributable
enum  ReadMode { IgnoreExisting, OverrideExisting, FullyReread }
 

Public Member Functions

RecordComponentsetUnitSI (double)
 
RecordComponentresetDataset (Dataset)
 Declare the dataset's type and extent. More...
 
uint8_t getDimensionality () const
 
Extent getExtent () const
 
template<typename T >
RecordComponentmakeConstant (T)
 Create a dataset with regular extent and constant value. More...
 
template<typename T >
RecordComponentmakeEmpty (uint8_t dimensions)
 Create a dataset with zero extent in each dimension. More...
 
RecordComponentmakeEmpty (Datatype dt, uint8_t dimensions)
 Non-template overload of RecordComponent::makeEmpty(). More...
 
bool empty () const
 Returns true if this is an empty record component. More...
 
template<typename T >
std::shared_ptr< TloadChunk (Offset={0u}, Extent={-1u})
 Load and allocate a chunk of data. More...
 
template<typename T >
void loadChunk (std::shared_ptr< T > data, Offset offset, Extent extent)
 Load a chunk of data into pre-allocated memory. More...
 
template<typename T >
void loadChunk (std::shared_ptr< T[]> data, Offset offset, Extent extent)
 Load a chunk of data into pre-allocated memory, array version. More...
 
template<typename T >
void loadChunkRaw (T *data, Offset offset, Extent extent)
 Load a chunk of data into pre-allocated memory, raw pointer version. More...
 
template<typename T >
void storeChunk (std::shared_ptr< T > data, Offset offset, Extent extent)
 Store a chunk of data from a chunk of memory. More...
 
template<typename T >
void storeChunk (std::shared_ptr< T[]> data, Offset offset, Extent extent)
 Store a chunk of data from a chunk of memory, array version. More...
 
template<typename T >
void storeChunk (UniquePtrWithLambda< T > data, Offset offset, Extent extent)
 Store a chunk of data from a chunk of memory, unique pointer version. More...
 
template<typename T , typename Del >
void storeChunk (std::unique_ptr< T, Del > data, Offset offset, Extent extent)
 Store a chunk of data from a chunk of memory, unique pointer version. More...
 
template<typename T >
void storeChunkRaw (T *data, Offset offset, Extent extent)
 Store a chunk of data from a chunk of memory, raw pointer version. More...
 
template<typename T_ContiguousContainer >
std::enable_if_t< auxiliary::IsContiguousContainer_v< T_ContiguousContainer > > storeChunk (T_ContiguousContainer &data, Offset offset={0u}, Extent extent={-1u})
 Store a chunk of data from a contiguous container. More...
 
template<typename T , typename F >
DynamicMemoryView< TstoreChunk (Offset offset, Extent extent, F &&createBuffer)
 Overload of storeChunk() that lets the openPMD API allocate a buffer. More...
 
template<typename T >
DynamicMemoryView< TstoreChunk (Offset, Extent)
 Overload of span-based storeChunk() that uses operator new() to create a buffer.
 
- Public Member Functions inherited from openPMD::BaseRecordComponent
double unitSI () const
 
BaseRecordComponentresetDatatype (Datatype)
 
Datatype getDatatype () const
 
bool constant () const
 Returns true if this is a constant record component. More...
 
ChunkTable availableChunks ()
 Get data chunks that are available to be loaded from the backend. More...
 
- Public Member Functions inherited from openPMD::Attributable
Attribute getAttribute (std::string const &key) const
 Retrieve value of Attribute stored with provided key. More...
 
bool deleteAttribute (std::string const &key)
 Remove Attribute of provided value both logically and physically. More...
 
std::vector< std::string > attributes () const
 List all currently stored Attributes' keys. More...
 
size_t numAttributes () const
 Count all currently stored Attributes. More...
 
bool containsAttribute (std::string const &key) const
 Check whether am Attribute with a given key exists. More...
 
std::string comment () const
 Retrieve a user-supplied comment associated with the object. More...
 
AttributablesetComment (std::string const &comment)
 Populate Attribute corresponding to a comment with the user-supplied comment. More...
 
void seriesFlush (std::string backendConfig="{}")
 Flush the corresponding Series object. More...
 
MyPath myPath () const
 The path to this object within its containing Series. More...
 
protected Series retrieveSeries () const
 
void seriesFlush (internal::FlushParams)
 
void flushAttributes (internal::FlushParams const &)
 
void readAttributes (ReadMode)
 
template<typename T >
T readFloatingpoint (std::string const &key) const
 Retrieve the value of a floating point Attribute of user-defined precision with ensured type-safety. More...
 
template<typename T >
std::vector< TreadVectorFloatingpoint (std::string const &key) const
 Retrieve a vector of values of a floating point Attributes of user-defined precision with ensured type-safety. More...
 
AbstractIOHandlerIOHandler ()
 
AbstractIOHandler const * IOHandler () const
 
Writable *& parent ()
 
Writable const * parent () const
 
Writablewritable ()
 
Writable const & writable () const
 
void setData (std::shared_ptr< internal::AttributableData > attri)
 
internal::AttributableDataget ()
 
internal::AttributableData const & get () const
 
bool dirty () const
 
bool & dirty ()
 
bool written () const
 
bool & written ()
 
template<typename T >
bool setAttribute (std::string const &key, T value)
 Populate Attribute of provided name with provided value. More...
 
bool setAttribute (std::string const &key, char const value[])
 
Iteration const & containingIteration () const
 Returns the corresponding Iteration. More...
 
IterationcontainingIteration ()
 

Static Public Attributes

static constexpr char const *const SCALAR = "\vScalar"
 

Friends

template<typename T , typename T_key , typename T_container >
class Container
 
class Iteration
 
class ParticleSpecies
 
template<typename T_elem >
class BaseRecord
 
template<typename T_elem >
class BaseRecordInterface
 
class Record
 
class Mesh
 
template<typename >
class DynamicMemoryView
 
class internal::RecordComponentData
 
class MeshRecordComponent
 

Additional Inherited Members

- Protected Member Functions inherited from openPMD::BaseRecordComponent
internal::BaseRecordComponentData const & get () const
 
internal::BaseRecordComponentDataget ()
 
void setData (std::shared_ptr< internal::BaseRecordComponentData > data)
 
 BaseRecordComponent (std::shared_ptr< internal::BaseRecordComponentData >)
 
- Protected Member Functions inherited from openPMD::Attributable
 Attributable (std::shared_ptr< internal::AttributableData >)
 
- Protected Attributes inherited from openPMD::BaseRecordComponent
std::shared_ptr< internal::BaseRecordComponentDatam_baseRecordComponentData {new internal::BaseRecordComponentData()}
 
- Protected Attributes inherited from openPMD::Attributable
std::shared_ptr< internal::AttributableDatam_attri
 

Member Function Documentation

◆ empty()

bool openPMD::RecordComponent::empty ( ) const

Returns true if this is an empty record component.

An empty record component has a defined dimensionality but zero extent and no value(s) stored in it.

Returns
true if an empty record component

◆ loadChunk() [1/3]

template<typename T >
std::shared_ptr<T> openPMD::RecordComponent::loadChunk ( Offset  = {0u},
Extent  = {-1u} 
)

Load and allocate a chunk of data.

Set offset to {0u} and extent to {-1u} for full selection.

If offset is non-zero and extent is {-1u} the leftover extent in the record component will be selected.

◆ loadChunk() [2/3]

template<typename T >
void openPMD::RecordComponent::loadChunk ( std::shared_ptr< T data,
Offset  offset,
Extent  extent 
)

Load a chunk of data into pre-allocated memory.

Parameters
dataPreallocated, contiguous buffer, large enough to load the the requested data into it. The shared pointer must either own and manage the buffer or have been created via shareRaw(). If using shareRaw(), it is in the user of this API call's responsibility to ensure that the lifetime of the buffer exceeds the next flush point. Optimizations might be implemented based on this assumption (e.g. skipping the operation if the backend is the unique owner). For raw pointers, use loadChunkRaw().
offsetOffset within the dataset. Set to {0u} for full selection.
extentExtent within the dataset, counted from the offset. Set to {-1u} for full selection. If offset is non-zero and extent is {-1u} the leftover extent in the record component will be selected.

◆ loadChunk() [3/3]

template<typename T >
void openPMD::RecordComponent::loadChunk ( std::shared_ptr< T[]>  data,
Offset  offset,
Extent  extent 
)

Load a chunk of data into pre-allocated memory, array version.

Parameters
dataPreallocated, contiguous buffer, large enough to load the the requested data into it. The shared pointer must own and manage the buffer. Optimizations might be implemented based on this assumption (e.g. skipping the operation if the backend is the unique owner). The array-based overload helps avoid having to manually specify the delete[] destructor (C++17 feature).
offsetOffset within the dataset. Set to {0u} for full selection.
extentExtent within the dataset, counted from the offset. Set to {-1u} for full selection. If offset is non-zero and extent is {-1u} the leftover extent in the record component will be selected.

◆ loadChunkRaw()

template<typename T >
void openPMD::RecordComponent::loadChunkRaw ( T data,
Offset  offset,
Extent  extent 
)

Load a chunk of data into pre-allocated memory, raw pointer version.

Parameters
dataPreallocated, contiguous buffer, large enough to load the the requested data into it. It is in the user of this API call's responsibility to ensure that the lifetime of the buffer exceeds the next flush point.
offsetOffset within the dataset. Set to {0u} for full selection.
extentExtent within the dataset, counted from the offset. Set to {-1u} for full selection. If offset is non-zero and extent is {-1u} the leftover extent in the record component will be selected.

◆ makeConstant()

template<typename T >
RecordComponent& openPMD::RecordComponent::makeConstant ( T  )

Create a dataset with regular extent and constant value.

In a constant record component, the value for each date in its extent is the same. Implemented by storing only a constant value as meta-data.

Template Parameters
Ttype of the stored value
Returns
A reference to this RecordComponent.

◆ makeEmpty() [1/2]

template<typename T >
RecordComponent& openPMD::RecordComponent::makeEmpty ( uint8_t  dimensions)

Create a dataset with zero extent in each dimension.

Implemented by creating a constant record component with a dummy value (default constructor of the respective datatype).

Parameters
dimensionsThe number of dimensions. Must be greater than zero.
Returns
A reference to this RecordComponent.

◆ makeEmpty() [2/2]

RecordComponent & openPMD::RecordComponent::makeEmpty ( Datatype  dt,
uint8_t  dimensions 
)

Non-template overload of RecordComponent::makeEmpty().

Uses the passed openPMD datatype to determine the template parameter.

Parameters
dtThe datatype of which to create an empty dataset.
dimensionsThe dimensionality of the dataset.
Returns
RecordComponent&

◆ resetDataset()

RecordComponent & openPMD::RecordComponent::resetDataset ( Dataset  d)

Declare the dataset's type and extent.

Calling this again after flushing will require resizing the dataset. Support for this depends on the backend. Unsupported are:

  • Changing the datatype.
  • Shrinking any dimension's extent.
  • Changing the number of dimensions.

Backend support for resizing datasets:

  • JSON: Supported
  • ADIOS1: Unsupported
  • ADIOS2: Supported as of ADIOS2 2.7.0
  • HDF5: (Currently) unsupported. Will be probably supported as soon as chunking is supported in HDF5.
Returns
RecordComponent&

◆ storeChunk() [1/6]

template<typename T >
void openPMD::RecordComponent::storeChunk ( std::shared_ptr< T data,
Offset  offset,
Extent  extent 
)

Store a chunk of data from a chunk of memory.

Parameters
dataPreallocated, contiguous buffer, large enough to read the the specified data from it. The shared pointer must either own and manage the buffer or have been created via shareRaw(). If using shareRaw(), it is in the user of this API call's responsibility to ensure that the lifetime of the buffer exceeds the next flush point. Optimizations might be implemented based on this assumption (e.g. further deferring the operation if the backend is the unique owner). For raw pointers, use storeChunkRaw().
offsetOffset within the dataset.
extentExtent within the dataset, counted from the offset.

◆ storeChunk() [2/6]

template<typename T >
void openPMD::RecordComponent::storeChunk ( std::shared_ptr< T[]>  data,
Offset  offset,
Extent  extent 
)

Store a chunk of data from a chunk of memory, array version.

Parameters
dataPreallocated, contiguous buffer, large enough to read the the specified data from it. The array-based overload helps avoid having to manually specify the delete[] destructor (C++17 feature).
offsetOffset within the dataset.
extentExtent within the dataset, counted from the offset.

◆ storeChunk() [3/6]

template<typename T >
void openPMD::RecordComponent::storeChunk ( UniquePtrWithLambda< T data,
Offset  offset,
Extent  extent 
)

Store a chunk of data from a chunk of memory, unique pointer version.

Parameters
dataPreallocated, contiguous buffer, large enough to read the the specified data from it. The unique pointer must own and manage the buffer. Optimizations might be implemented based on this assumption (e.g. further deferring the operation if the backend is the unique owner). For raw pointers, use storeChunkRaw().
offsetOffset within the dataset.
extentExtent within the dataset, counted from the offset.

◆ storeChunk() [4/6]

template<typename T , typename Del >
void openPMD::RecordComponent::storeChunk ( std::unique_ptr< T, Del >  data,
Offset  offset,
Extent  extent 
)

Store a chunk of data from a chunk of memory, unique pointer version.

Parameters
dataPreallocated, contiguous buffer, large enough to read the the specified data from it. The unique pointer must own and manage the buffer. Optimizations might be implemented based on this assumption (e.g. further deferring the operation if the backend is the unique owner). For raw pointers, use storeChunkRaw().
offsetOffset within the dataset.
extentExtent within the dataset, counted from the offset.

◆ storeChunk() [5/6]

template<typename T_ContiguousContainer >
std::enable_if_t< auxiliary::IsContiguousContainer_v<T_ContiguousContainer> > openPMD::RecordComponent::storeChunk ( T_ContiguousContainer &  data,
Offset  offset = {0u},
Extent  extent = {-1u} 
)

Store a chunk of data from a contiguous container.

Parameters
dataContiguous container, large enough to read the the specified data from it. A contiguous container in here is either a std::vector or a std::array. It is in the user of this API call's responsibility to ensure that the lifetime of the container exceeds the next flush point.
offsetOffset within the dataset.
extentExtent within the dataset, counted from the offset.

◆ storeChunk() [6/6]

template<typename T , typename F >
DynamicMemoryView<T> openPMD::RecordComponent::storeChunk ( Offset  offset,
Extent  extent,
F &&  createBuffer 
)

Overload of storeChunk() that lets the openPMD API allocate a buffer.

This may save memory if the openPMD backend in use is able to provide users a view into its own buffers, avoiding the need to allocate a new buffer.

Data can be written into the returned buffer until the next flush point at which time the data will be read from.

In order to provide a view into backend buffers, this call must possibly create files and datasets in the backend, making it MPI-collective. In order to avoid this, calling Series::flush() prior to this is recommended to flush definitions.

Parameters
offsetOffset within the dataset.
extentExtent within the dataset, counted from the offset.
createBufferIf the backend in use has no special support for this operation, the openPMD API will fall back to creating a buffer, queuing it for writing and returning a view into that buffer to the user. The functor createBuffer will be called for this purpose. It consumes a length parameter of type size_t and should return a shared_ptr of type T to a buffer at least that length. In that case, using this API call is equivalent to (1) creating a shared pointer via createBuffer and (2) then using the regular storeChunk() API on it. If the backend supports it, the buffer is not read before the next flush point and becomes invalid afterwards.
Returns
View into a buffer that can be filled with data.

◆ storeChunkRaw()

template<typename T >
void openPMD::RecordComponent::storeChunkRaw ( T data,
Offset  offset,
Extent  extent 
)

Store a chunk of data from a chunk of memory, raw pointer version.

Parameters
dataPreallocated, contiguous buffer, large enough to read the the specified data from it. It is in the user of this API call's responsibility to ensure that the lifetime of the buffer exceeds the next flush point.
offsetOffset within the dataset.
extentExtent within the dataset, counted from the offset.

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