openPMD::RecordComponent Class Reference

Inheritance diagram for openPMD::RecordComponent:

Collaboration diagram for openPMD::RecordComponent:

Public Types
enum class	Allocation { USER , API , AUTO }
using	shared_ptr_dataset_types = auxiliary::detail::map_variant< auxiliary::detail::as_shared_pointer, dataset_types >::type
Public Types inherited from openPMD::Attributable
enum	ReadMode { IgnoreExisting , OverrideExisting , FullyReread }

Public Member Functions
	RecordComponent (BaseRecord< RecordComponent > const &)
	Avoid object slicing when using a Record as a scalar Record Component. More...
RecordComponent &	setUnitSI (double)
virtual RecordComponent &	resetDataset (Dataset)
	Declare the dataset's type and extent. More...
uint8_t	getDimensionality () const
Extent	getExtent () const
template<typename T >
RecordComponent &	makeConstant (T)
	Create a dataset with regular extent and constant value. More...
template<typename T >
RecordComponent &	makeEmpty (uint8_t dimensions)
	Create a dataset with zero extent in each dimension. More...
RecordComponent &	makeEmpty (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< T >	loadChunk (Offset={0u}, Extent={-1u})
	Load and allocate a chunk of data. More...
shared_ptr_dataset_types	loadChunkVariant (Offset={0u}, Extent={-1u})
	std::variant-based version of allocating loadChunk<T>(Offset, Extent) 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< T >	storeChunk (Offset offset, Extent extent, F &&createBuffer)
	Overload of storeChunk() that lets the openPMD API allocate a buffer. More...
template<typename T >
DynamicMemoryView< T >	storeChunk (Offset, Extent)
	Overload of span-based storeChunk() that uses operator new() to create a buffer.
template<typename Visitor , typename... Args>
auto	visit (Args &&...args) -> decltype(Visitor::template call< char >(std::declval< RecordComponent & >(), std::forward< Args >(args)...))
	Run a template functor on the type of the record component, similar to std::visit(). More...
Public Member Functions inherited from openPMD::BaseRecordComponent
	BaseRecordComponent (BaseRecordComponent const &other)
	BaseRecordComponent (BaseRecordComponent &&other)
BaseRecordComponent &	operator= (BaseRecordComponent const &other)
BaseRecordComponent &	operator= (BaseRecordComponent &&other)
double	unitSI () const
BaseRecordComponent &	resetDatatype (Datatype)
Datatype	getDatatype () const
bool	constant () const
	Returns true if this is a constant record component. More...
std::optional< size_t >	joinedDimension () const
ChunkTable	availableChunks ()
	Get data chunks that are available to be loaded from the backend. More...
Public Member Functions inherited from openPMD::Attributable
	Attributable (NoInit)
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...
Attributable &	setComment (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 const &)
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< T >	readVectorFloatingpoint (std::string const &key) const
	Retrieve a vector of values of a floating point Attributes of user-defined precision with ensured type-safety. More...
AbstractIOHandler *	IOHandler ()
AbstractIOHandler const *	IOHandler () const
Writable *&	parent ()
Writable const *	parent () const
Writable &	writable ()
Writable const &	writable () const
void	setData (std::shared_ptr< internal::AttributableData > attri)
internal::AttributableData &	get ()
internal::AttributableData const &	get () const
bool	dirty () const
bool	dirtyRecursive () const
	O(1).
void	setDirty (bool dirty_in)
void	setDirtyRecursive (bool dirty_in)
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...
Iteration &	containingIteration ()

Static Public Attributes
static constexpr char const *const	SCALAR = "\vScalar"

Protected Member Functions
void	flush (std::string const &, internal::FlushParams const &)
void	read (bool require_unit_si)
Protected Member Functions inherited from openPMD::BaseRecordComponent
Data_t const &	get () const
Data_t &	get ()
void	setData (std::shared_ptr< Data_t > data)
virtual void	setDatasetDefined (Data_t &)
bool	datasetDefined () const
	BaseRecordComponent (NoInit)

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

Additional Inherited Members
Protected Types inherited from openPMD::BaseRecordComponent
using	Data_t = internal::BaseRecordComponentData
Protected Types inherited from openPMD::Attributable
using	Data_t = internal::AttributableData
Protected Attributes inherited from openPMD::BaseRecordComponent
std::shared_ptr< Data_t >	m_baseRecordComponentData
Protected Attributes inherited from openPMD::Attributable
std::shared_ptr< Data_t >	m_attri

Constructor & Destructor Documentation

RecordComponent()

openPMD::RecordComponent::RecordComponent

(

BaseRecord< RecordComponent > const &

baseRecord

)

Avoid object slicing when using a Record as a scalar Record Component.

It's still preferred to directly use the Record, or alternatively a Record-Component-type reference to a Record.

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

data	Preallocated, 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().
offset	Offset within the dataset. Set to {0u} for full selection.
extent	Extent 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

data	Preallocated, 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).
offset	Offset within the dataset. Set to {0u} for full selection.
extent	Extent 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

data	Preallocated, 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.
offset	Offset within the dataset. Set to {0u} for full selection.
extent	Extent 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.

loadChunkVariant()

auto openPMD::RecordComponent::loadChunkVariant	(	Offset	o = {0u},
		Extent	e = {-1u}
	)

std::variant-based version of allocating loadChunk<T>(Offset, Extent)

Returns

The same result that loadChunk() would return, but as a std::variant of all possible return types, instantiated with the actual type of this RecordComponent.

Note: shared_ptr_dataset_types resolves to: std::variant<std::shared_ptr<char>, std::shared_ptr<unsigned char>, ..., std::shared_ptr<std::complex<long double>>>

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

T	type of the stored value

Returns

A reference to this RecordComponent.

makeEmpty() [1/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

dt	The datatype of which to create an empty dataset.
dimensions	The dimensionality of the dataset.

Returns

RecordComponent&

makeEmpty() [2/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

dimensions

The number of dimensions. Must be greater than zero.

Returns

A reference to this RecordComponent.

resetDataset()

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

virtual

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
• 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&

Reimplemented in openPMD::PatchRecordComponent.

storeChunk() [1/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

offset	Offset within the dataset.
extent	Extent within the dataset, counted from the offset.
createBuffer	If 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.

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.

Parameters

data	Preallocated, 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().
offset	Offset within the dataset.
extent	Extent within the dataset, counted from the offset.

storeChunk() [3/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

data	Preallocated, 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).
offset	Offset within the dataset.
extent	Extent 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

data	Preallocated, 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().
offset	Offset within the dataset.
extent	Extent 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

data	Contiguous 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.
offset	Offset within the dataset.
extent	Extent within the dataset, counted from the offset.

storeChunk() [6/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

data	Preallocated, 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().
offset	Offset within the dataset.
extent	Extent within the dataset, counted from the offset.

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

data	Preallocated, 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.
offset	Offset within the dataset.
extent	Extent within the dataset, counted from the offset.

visit()

template<typename Visitor , typename... Args>

auto openPMD::RecordComponent::visit

(

Args &&...

args

)

-> decltype(Visitor::template call< char >(std::declval< RecordComponent & >(), std::forward< Args >(args)...))

Run a template functor on the type of the record component, similar to std::visit().

Note that unlike std::visit(), this template cannot "switch" over a single existing value, meaning that the interface needs to work a bit different. The functor is given as a struct/class with a call() operation.

(Ideally, this can be harmonized by using template lambdas once we support C++20)

Template Parameters

Visitor	A struct type that has a static template method: Visitor::template call<T>(RecordComponent &, ...) In here, T will be instantiated with this RecordComponent's type and a reference to this RecordComponent will be passed as first argument.
Args	Types of optional further arguments.

Parameters

args	Optional further arguments that will be forwarded to Visitor::template call()

Returns

Whatever Visitor::template call() returned. Take special note that the return types must match (i.e. cannot be different across instantiations of T for Visitor::template call<T>()). Formally, the return type is that of Visitor::template call<char>(RecordComponent &, Args&&...) and returned values from other template instantiations might then be implicitly converted.

---

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

• /home/docs/checkouts/readthedocs.org/user_builds/openpmd-api/checkouts/latest/include/openPMD/RecordComponent.hpp
• /home/docs/checkouts/readthedocs.org/user_builds/openpmd-api/checkouts/latest/src/RecordComponent.cpp