Layer to manage storage of attributes associated with file objects. More...

#include <Attributable.hpp>

Inheritance diagram for openPMD::Attributable:

Collaboration diagram for openPMD::Attributable:

Classes
struct	MyPath
	String serialization to describe an Attributable. More...

struct	NoInit

Public Types
enum	ReadMode { IgnoreExisting , OverrideExisting , FullyReread }

enum class	EnqueueAsynchronously : uint8_t { OnlyAsync , Both , No }

Public Member Functions
	Attributable (NoInit) noexcept

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...

void	iterationFlush (std::string backendConfig="{}")
	Flush the containing Iteration. More...

MyPath	myPath () const
	The path to this object within its containing Series. More...

void	touch ()
	Sets the object dirty to make internal procedures think it has been modified.

virtual void	visitHierarchy (HierarchyVisitor &visitor, bool recursive)
	Visitor pattern for the openPMD object hierarchy in postfix traversal. More...

template<typename Lambda >
void	visitHierarchyFromLambda (Lambda &&lambda, bool recursive)
	Visitor pattern for the openPMD object hierarchy in postfix traversal, lambda version. More...

void	populateMissingMetadata (bool recursive)
	Create standard defined attributes with default values now, insofar they are still missing. More...

OpenpmdStandard	openPMDStandard () const

protected Series	retrieveSeries () const

template<bool flush_entire_series>
void	seriesFlush_impl (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::SharedAttributableData &	get ()

internal::SharedAttributableData const &	get () const

bool	dirty () const

bool	dirtyRecursive () const
	O(1).

void	setDirty (bool dirty_in)

void	setDirtyRecursive (bool dirty_in)

bool	written () const

void	setWritten (bool val, EnqueueAsynchronously)


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[])

bool	setAttribute (std::string const &key, Attribute value)


auto	containingIteration () const -> std::pair< std::optional< internal::IterationData const * >, internal::SeriesData const * >
	Returns the corresponding Iteration. More...

auto	containingIteration () -> std::pair< std::optional< internal::IterationData * >, internal::SeriesData * >

Protected Types
using	Data_t = internal::AttributableData

Protected Attributes
std::shared_ptr< Data_t >	m_attri

Friends
template<typename T_elem >
class	BaseRecord

template<typename T_elem >
class	BaseRecordInterface

template<typename , typename >
class	internal::BaseRecordData

template<typename T , typename T_key , typename T_container >
class	Container

template<typename T >
struct	traits::GenerationPolicy

class	Iteration

class	Series

class	Writable

class	internal::RecordComponentData

class	StatefulSnapshotsContainer

class	internal::AttributableData

class	Snapshots

struct	internal::HomogenizeExtents

struct	internal::ConfigAttribute

class	internal::ScientificDefaults

Writable *	getWritable (Attributable *)

void	debug::printDirty (Series const &)

template<typename T >
T &	internal::makeOwning (T &self, Series)

Detailed Description

Layer to manage storage of attributes associated with file objects.

Mandatory and user-defined Attributes and their data for every object in the openPMD hierarchy are stored and managed through this class.

Member Enumeration Documentation

◆ ReadMode

enum openPMD::Attributable::ReadMode

Enumerator
IgnoreExisting	Don't read an attribute from the backend if it has been previously read.
OverrideExisting	Read all the attributes that the backend has to offer and override if it has been read previously.
FullyReread	Remove all attributes that have been read previously and read everything that the backend currently has to offer.

Member Function Documentation

◆ attributes()

std::vector< std::string > openPMD::Attributable::attributes ( ) const

List all currently stored Attributes' keys.

Returns: Vector of keys (i.e. names) of all currently stored Attributes.

◆ comment()

std::string openPMD::Attributable::comment ( ) const

Retrieve a user-supplied comment associated with the object.

Exceptions

no_such_attribute_error If no comment is currently stored.

Returns: String containing the user-supplied comment.

◆ containingIteration()

auto openPMD::Attributable::containingIteration ( ) const -> std::pair< std::optional<internal::IterationData const *>, internal::SeriesData const *>

Returns the corresponding Iteration.

Return the openPMD::iteration that this Attributable is contained in. This walks up the linked parents until it finds the Iteration object. Throws an error otherwise, e.g., for Series objects.

◆ containsAttribute()

bool openPMD::Attributable::containsAttribute ( std::string const & key ) const

Check whether am Attribute with a given key exists.

Parameters

key	Key (i.e. name) of the Attribute to find.

Returns: true if provided key was present, false otherwise.

◆ deleteAttribute()

bool openPMD::Attributable::deleteAttribute ( std::string const & key )

Remove Attribute of provided value both logically and physically.

Parameters

key	Key (i.e. name) of the Attribute to remove.

Returns: true if provided key was present and removal succeeded, false otherwise.

◆ getAttribute()

Attribute openPMD::Attributable::getAttribute ( std::string const & key ) const

Retrieve value of Attribute stored with provided key.

Exceptions

no_such_attribute_error If no Attribute is currently stored with the provided key.

Parameters

key	Key (i.e. name) of the Attribute to retrieve value for.

Returns: Stored Attribute in Variant form.

◆ iterationFlush()

void openPMD::Attributable::iterationFlush ( std::string backendConfig = "{}" )

Flush the containing Iteration.

Writable connects all objects of an openPMD series through a linked list of parents. This method will walk up the parent list to find the containing Iteration. The Iteration will be flushed regardless if it is dirty.

Parameters

backendConfig Further backend-specific instructions on how to implement this flush call. Must be provided in-line, configuration is not read from files.

◆ myPath()

auto openPMD::Attributable::myPath ( ) const

The path to this object within its containing Series.

Returns: A struct informing about the context of this Attributable.

◆ numAttributes()

size_t openPMD::Attributable::numAttributes ( ) const

Count all currently stored Attributes.

Returns: Number of currently stored Attributes.

◆ populateMissingMetadata()

void openPMD::Attributable::populateMissingMetadata ( bool recursive )

Create standard defined attributes with default values now, insofar they are still missing.

Does not flush.

Refer to https://github.com/openPMD/openPMD-standard/blob/latest/STANDARD.md for the attributes implied by this operation.

By default, standard defined attributes are written upon closing the containing Iteration / Series. Calling this soon can make data available for early readers (e.g. read while the writer is still modifying). In workflows that keep single Iterations open over an extended period of time (e.g. back-transformed diagnostics), this can help creating readable files earlier than without.

Attributes may still be modified after this as usual. Attributes defined before this call will not be modified by it.

Parameters

recursive Extend the operation recursively to children.

◆ readFloatingpoint()

template<typename T >

T openPMD::Attributable::readFloatingpoint ( std::string const & key ) const

inline

Retrieve the value of a floating point Attribute of user-defined precision with ensured type-safety.

Note: Since the precision of certain Attributes is intentionally left unspecified in the openPMD standard, this provides a mechanism to retrieve those values without giving up type-safety.

See also: https://github.com/openPMD/openPMD-standard/blob/latest/STANDARD.md#conventions-throughout-these-documents

Note: If the supplied and stored floating point precision are not the same, the value is cast to the desired precision unconditionally.

Exceptions

no_such_attribute_error If no Attribute is currently stored with the provided key.

Template Parameters

T	Floating point type of user-defined precision to retrieve the value as.

Parameters

key	Key (i.e. name) of the floating-point Attribute to retrieve value for.

Returns: Value of stored Attribute as supplied floating point type.

◆ readVectorFloatingpoint()

template<typename T >

std::vector< T > openPMD::Attributable::readVectorFloatingpoint ( std::string const & key ) const

inline

Retrieve a vector of values of a floating point Attributes of user-defined precision with ensured type-safety.

Note: Since the precision of certain Attributes is intentionally left unspecified in the openPMD standard, this provides a mechanism to retrieve those values without giving up type-safety.

See also: https://github.com/openPMD/openPMD-standard/blob/latest/STANDARD.md#conventions-throughout-these-documents

Note: If the supplied and stored floating point precision are not the same, the values are cast to the desired precision unconditionally.

Exceptions

no_such_attribute_error If no Attribute is currently stored with the provided key.

Template Parameters

T	Floating point type of user-defined precision to retrieve the values as.

Parameters

key	Key (i.e. name) of the floating-point Attribute to retrieve values for.

Returns: Vector of values of stored Attribute as supplied floating point type.

◆ seriesFlush()

void openPMD::Attributable::seriesFlush ( std::string backendConfig = "{}" )

Flush the corresponding Series object.

Writable connects all objects of an openPMD series through a linked list of parents. This method will walk up the parent list until it reaches an object that has no parent, which is the Series object, and flush()-es it. If the Attributable is an Iteration or any object contained in an Iteration, that Iteration will be flushed regardless of its dirty status.

Parameters

backendConfig Further backend-specific instructions on how to implement this flush call. Must be provided in-line, configuration is not read from files.

◆ setAttribute()

template<typename T >

bool openPMD::Attributable::setAttribute	(	std::string const &	key,
		T	value
	)

inline

Populate Attribute of provided name with provided value.

Note: If the provided Attribute already exists, the value is replaced. If it does not exist, a new Attribute is created.

Template Parameters

T	Type of the object to be stored. Only types contained in Datatype can be handled.

Parameters

key	Key (i.e. name) to identify and store an Attributes value by.
value	Value of Attribute stored with the provided key.

Returns: true if key was already present, false otherwise

◆ setComment()

Attributable & openPMD::Attributable::setComment ( std::string const & comment )

Populate Attribute corresponding to a comment with the user-supplied comment.

Parameters

comment String value to be stored as a comment.

Returns: Reference to modified Attributable.

◆ visitHierarchy()

void openPMD::Attributable::visitHierarchy	(	HierarchyVisitor &	visitor,
		bool	recursive
	)

virtual

Visitor pattern for the openPMD object hierarchy in postfix traversal.

Note: As the HierarchyVisitor interface can be tedious to implement, consider using visitHierarchyFromLambda for a more convenient interface.; to developers: if at any point a prefix traversal should become necessary, consider emplacing configuration options for this inside HierarchyVisitor to keep the interface clean.

Parameters

visitor	Operations to run for each object.
recursive	Extend the operation recursively to children.

Reimplemented in openPMD::Series, openPMD::RecordComponent, openPMD::Record, openPMD::ParticleSpecies, openPMD::ParticlePatches, openPMD::Mesh, openPMD::Iterations, openPMD::Iteration, openPMD::Particles, openPMD::Meshes, openPMD::PatchRecordComponent, openPMD::PatchRecord, and openPMD::MeshRecordComponent.

◆ visitHierarchyFromLambda()

template<typename Lambda >

void openPMD::Attributable::visitHierarchyFromLambda	(	Lambda &&	lambda,
		bool	recursive
	)

Visitor pattern for the openPMD object hierarchy in postfix traversal, lambda version.

The lambda parameter will be called with a reference to each object in the current object's enclosed hierarchy.

Note: Definition inside include/openPMD/backend/HierarchyVisitorImpl.hpp.

Parameters

lambda	Operations to run for each object.
recursive	Extend the operation recursively to children.

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

/home/docs/checkouts/readthedocs.org/user_builds/openpmd-api/checkouts/latest/include/openPMD/backend/Attributable.hpp
/home/docs/checkouts/readthedocs.org/user_builds/openpmd-api/checkouts/latest/src/backend/Attributable.cpp
/home/docs/checkouts/readthedocs.org/user_builds/openpmd-api/checkouts/latest/include/openPMD/backend/HierarchyVisitorImpl.hpp

Classes

Public Types

Public Member Functions

Protected Types

Protected Attributes

Friends

Detailed Description

Member Enumeration Documentation

◆ ReadMode

Member Function Documentation

◆ attributes()

◆ comment()

◆ containingIteration()

◆ containsAttribute()

◆ deleteAttribute()

◆ getAttribute()

◆ iterationFlush()

◆ myPath()

◆ numAttributes()

◆ populateMissingMetadata()

◆ readFloatingpoint()

◆ readVectorFloatingpoint()

◆ seriesFlush()

◆ setAttribute()

◆ setComment()

◆ visitHierarchy()

◆ visitHierarchyFromLambda()