Implementation for the root level of the openPMD hierarchy. More...

#include <Series.hpp>

Inheritance diagram for openPMD::Series:

Collaboration diagram for openPMD::Series:

Classes
struct	ParsedInput

Public Types
enum class	IterationOpened : bool { HasBeenOpened , RemainsClosed }

using	IterationIndex_t = Iteration::IterationIndex_t
	An unsigned integer type, used to identify Iterations in a Series.

using	IterationsContainer_t = internal::SeriesData::IterationsContainer_t
	Type for a container of Iterations indexed by IterationIndex_t.

using	iterations_t = decltype(internal::SeriesData::iterations)

using	iterations_iterator = iterations_t::iterator

using	Data_t = internal::SeriesData

Public Types inherited from openPMD::Attributable
enum	ReadMode { IgnoreExisting , OverrideExisting , FullyReread }

enum class	EnqueueAsynchronously : bool { Yes , No }

Public Member Functions
	Series (std::string const &filepath, Access at, MPI_Comm comm, std::string const &options="{}")
	Construct a new Series. More...

	Series (std::string const &filepath, Access at, std::string const &options="{}")
	Construct a new Series. More...

	Series (Series const &)=default

	Series (Series &&)=default

Series &	operator= (Series const &)=default

Series &	operator= (Series &&)=default

	operator bool () const
	Is this a usable Series object? More...

std::string	openPMD () const

Series &	setOpenPMD (std::string const &openPMD)
	Set the version of the enforced openPMD standard. More...

uint32_t	openPMDextension () const

Series &	setOpenPMDextension (uint32_t openPMDextension)
	Set a 32-bit mask of applied extensions to the openPMD standard. More...

std::string	basePath () const

Series &	setBasePath (std::string const &basePath)
	Set the common prefix for all data sets and sub-groups of a specific iteration. More...

std::string	meshesPath () const

Series &	setMeshesPath (std::string const &meshesPath)
	Set the path to mesh records, relative(!) to `basePath`. More...

bool	hasRankTableRead ()

chunk_assignment::RankMeta	rankTable (bool collective)

Series &	setRankTable (std::string const &myRankInfo)
	Set the Mpi Ranks Meta Info attribute, i.e. More...

std::string	particlesPath () const

Series &	setParticlesPath (std::string const &particlesPath)
	Set the path to groups for each particle species, relative(!) to `basePath`. More...

std::string	author () const

Series &	setAuthor (std::string const &author)
	Indicate the author and contact for the information in the file. More...

std::string	software () const

Series &	setSoftware (std::string const &newName, std::string const &newVersion=std::string("unspecified"))
	Indicate the software/code/simulation that created the file. More...

std::string	softwareVersion () const

Series &	setSoftwareVersion (std::string const &softwareVersion)
	Indicate the version of the software/code/simulation that created the file. More...

std::string	date () const

Series &	setDate (std::string const &date)
	Indicate the date of creation. More...

std::string	softwareDependencies () const

Series &	setSoftwareDependencies (std::string const &newSoftwareDependencies)
	Indicate dependencies of software that were used to create the file. More...

std::string	machine () const

Series &	setMachine (std::string const &newMachine)
	Indicate the machine or relevant hardware that created the file. More...

IterationEncoding	iterationEncoding () const

Series &	setIterationEncoding (IterationEncoding iterationEncoding)
	Set the encoding style for multiple iterations in this series. More...

std::string	iterationFormat () const

Series &	setIterationFormat (std::string const &iterationFormat)
	Set a pattern describing how to access single iterations in the raw file. More...

std::string	name () const

Series &	setName (std::string const &name)
	Set the pattern for file names. More...

std::string	backend () const
	The currently used backend. More...

std::string	backend ()

void	flush (std::string backendConfig="{}")
	Execute all required remaining IO operations to write or read data. More...

ReadIterations	readIterations ()
	Entry point to the reading end of the streaming API. More...

Snapshots	snapshots ()
	Preferred way to access Iterations/Snapshots. More...

void	parseBase ()
	Parse the Series. More...

WriteIterations	writeIterations ()
	Entry point to the writing end of the streaming API. More...

void	close ()
	Close the Series and release the data storage/transport backends. More...

template<typename X = void, typename... Args>
auto	iterationFlush (Args &&...)
	This overrides Attributable::iterationFlush() which will fail on Series.

Data_t &	get ()

Data_t const &	get () const

void	setData (std::shared_ptr< internal::SeriesData > series)

std::unique_ptr< ParsedInput >	parseInput (std::string)

template<typename TracingJSON >
void	parseJsonOptions (TracingJSON &options, ParsedInput &)
	Parse non-backend-specific configuration in JSON config. More...

bool	hasExpansionPattern (std::string filenameWithExtension)

bool	reparseExpansionPattern (std::string filenameWithExtension)

template<typename... MPI_Communicator>
void	init (std::string const &filepath, Access at, std::string const &options, MPI_Communicator &&...)

template<typename TracingJSON , typename... MPI_Communicator>
std::tuple< std::unique_ptr< ParsedInput >, TracingJSON >	initIOHandler (std::string const &filepath, std::string const &options, Access at, bool resolve_generic_extension, MPI_Communicator &&...)

void	initSeries (std::unique_ptr< AbstractIOHandler >, std::unique_ptr< ParsedInput >)

void	initDefaults (IterationEncoding, bool initAll=false)

std::future< void >	flush_impl (iterations_iterator begin, iterations_iterator end, internal::FlushParams const &flushParams, bool flushIOHandler=true)
	Internal call for flushing a Series. More...

void	flushFileBased (iterations_iterator begin, iterations_iterator end, internal::FlushParams const &flushParams, bool flushIOHandler=true)

void	flushGorVBased (iterations_iterator begin, iterations_iterator end, internal::FlushParams const &flushParams, bool flushIOHandler=true)

void	flushMeshesPath ()

void	flushParticlesPath ()

void	flushRankTable ()

void	readFileBased (std::optional< IterationIndex_t > read_only_this_single_iteration)

void	readOneIterationFileBased (std::string const &filePath)

std::vector< IterationIndex_t >	readGorVBased (bool do_always_throw_errors, bool init, std::optional< IterationIndex_t > read_only_this_single_iteration)
	Note on re-parsing of a Series: If init == false, the parsing process will seek for new Iterations/Records/Record Components etc. More...

void	readBase ()

std::string	iterationFilename (IterationIndex_t i)

IterationOpened	openIterationIfDirty (IterationIndex_t index, Iteration &iteration)

void	openIteration (IterationIndex_t index, Iteration &iteration)

iterations_iterator	indexOf (Iteration const &)
	Find the given iteration in Series::iterations and return an iterator into Series::iterations at that place.

AdvanceStatus	advance (AdvanceMode mode, internal::AttributableData &file, iterations_iterator it)
	In step-based IO mode, begin or end an IO step for the given iteration. More...

AdvanceStatus	advance (AdvanceMode mode)

void	flushStep (bool doFlush)
	Called at the end of an IO step to store the iterations defined in the IO step to the snapshot attribute and to store that at least one step was written. More...

Series &	setIterationEncoding_internal (IterationEncoding iterationEncoding, internal::default_or_explicit)

std::optional< std::vector< IterationIndex_t > >	currentSnapshot ()

AbstractIOHandler *	runDeferredInitialization ()

AbstractIOHandler *	IOHandler ()

AbstractIOHandler const *	IOHandler () const

std::optional< std::vector< std::vector< IterationIndex_t > > >	preparseSnapshots ()

Snapshots	makeRandomAccessSnapshots ()

Snapshots	makeSynchronousSnapshots ()

bool	randomAccessSteps () const

std::vector< std::string >	availableDatasets ()

template<typename... MPI_Communicator>
void	init (std::string const &filepath, Access at, std::string const &options, MPI_Communicator &&...comm)

template<typename TracingJSON , typename... MPI_Communicator>
auto	initIOHandler (std::string const &filepath, std::string const &options, Access at, bool resolve_generic_extension, MPI_Communicator &&...comm) -> std::tuple< std::unique_ptr< ParsedInput >, TracingJSON >

Public Member Functions inherited from openPMD::Attributable
	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.

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

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

Public Attributes
IterationsContainer_t	iterations

std::shared_ptr< Data_t >	m_series = nullptr

Static Public Attributes
static constexpr private char const *const	BASEPATH = "/data/%T/"

Friends
class	Attributable

class	Iteration

class	Writable

class	ReadIterations

class	StatefulIterator

class	internal::SeriesData

class	internal::AttributableData

class	StatefulSnapshotsContainer

Additional Inherited Members
Protected Types inherited from openPMD::Attributable
using	Data_t = internal::AttributableData

Protected Attributes inherited from openPMD::Attributable
std::shared_ptr< Data_t >	m_attri

Detailed Description

Implementation for the root level of the openPMD hierarchy.

Entry point and common link between all iterations of particle and mesh data.

See also: https://github.com/openPMD/openPMD-standard/blob/latest/STANDARD.md#hierarchy-of-the-data-file; https://github.com/openPMD/openPMD-standard/blob/latest/STANDARD.md#iterations-and-time-series

Constructor & Destructor Documentation

◆ Series() [1/2]

openPMD::Series::Series	(	std::string const &	filepath,
		Access	at,
		MPI_Comm	comm,
		std::string const &	options = `"{}"`
	)

Construct a new Series.

For further details, refer to the documentation of the non-MPI overload.

Parameters

filepath	The file path.
at	Access mode.
comm	The MPI communicator.
options	Advanced backend configuration via JSON. May be specified as a JSON-formatted string directly, or as a path to a JSON textfile, prepended by an at sign '@'.

◆ Series() [2/2]

openPMD::Series::Series	(	std::string const &	filepath,
		Access	at,
		std::string const &	options = `"{}"`
	)

Construct a new Series.

For details on access modes, JSON/TOML configuration and iteration encoding, refer to:

In case of file-based iteration encoding, the file names for each iteration are determined by an expansion pattern that must be specified. It takes one out of two possible forms:

Simple form: T is replaced with the iteration index, e.g. simData_T.bp becomes simData_50.bp.
Padded form: e.g. %06T is replaced with the iteration index padded to at least six digits. simData_%06T.bp becomes simData_000050.bp.

The backend is determined:

Explicitly via the JSON/TOML parameter backend, e.g. {"backend": "adios2"}.
Otherwise implicitly from the filename extension, e.g. simData_T.h5.

The filename extension can be replaced with a globbing pattern E. It will be replaced with an automatically determined file name extension:

In CREATE mode: The extension is set to a backend-specific default extension. This requires that the backend is specified via JSON/TOML.
In READ_ONLY, READ_WRITE and READ_LINEAR modes: These modes require that files already exist on disk. The disk will be scanned for files that match the pattern and the resulting file extension will be used. If the result is ambiguous or no such file is found, an error is raised.
In APPEND mode: Like (2.), except if no matching file is found. In that case, the procedure of (1.) is used, owing to the fact that APPEND mode can be used to create new datasets.

Parameters

filepath	The file path.
at	Access mode.
options	Advanced backend configuration via JSON. May be specified as a JSON/TOML-formatted string directly, or as a path to a JSON/TOML textfile, prepended by an at sign '@'.

Member Function Documentation

◆ advance()

AdvanceStatus openPMD::Series::advance	(	AdvanceMode	mode,
		internal::AttributableData &	file,
		iterations_iterator	it
	)

In step-based IO mode, begin or end an IO step for the given iteration.

Called internally by Iteration::beginStep and Iteration::endStep.

Parameters

mode	Whether to begin or end a step.
file	The Attributable representing the iteration. In file-based iteration layout, this is an Iteration object, in group- based layout, it's the Series object.
it	The iterator within Series::iterations pointing to that iteration.

Returns: AdvanceStatus

◆ author()

std::string openPMD::Series::author ( ) const

Exceptions

no_such_attribute_error If optional attribute is not present.

Returns: String indicating author and contact for the information in the file.

◆ backend()

std::string openPMD::Series::backend ( ) const

The currently used backend.

See also: AbstractIOHandler::backendName()

Returns: String of a pattern for data backend.

◆ basePath()

std::string openPMD::Series::basePath ( ) const

Returns: String representing the common prefix for all data sets and sub-groups of a specific iteration.

◆ close()

void openPMD::Series::close ( )

Close the Series and release the data storage/transport backends.

This is an explicit API call for what the Series::~Series() destructor would do otherwise. All backends are closed after calling this method. The Series should be treated as destroyed after calling this method. The Series will be evaluated as false in boolean contexts after calling this method.

◆ date()

std::string openPMD::Series::date ( ) const

Exceptions

no_such_attribute_error If optional attribute is not present.

Returns: String indicating date of creation.

◆ flush()

void openPMD::Series::flush ( std::string backendConfig = "{}" )

Execute all required remaining IO operations to write or read data.

Parameters

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

◆ flush_impl()

std::future< void > openPMD::Series::flush_impl	(	iterations_iterator	begin,
		iterations_iterator	end,
		internal::FlushParams const &	flushParams,
		bool	flushIOHandler = `true`
	)

Internal call for flushing a Series.

Any flushing of the Series will pass through this call.

Parameters

begin	Start of the range of iterations to flush.
end	End of the range of iterations to flush.
flushParams	Flush params, as documented in AbstractIOHandler.hpp.
flushIOHandler	Tasks will always be enqueued to the backend. If this flag is true, tasks will be flushed to the backend.

◆ flushStep()

void openPMD::Series::flushStep ( bool doFlush )

Called at the end of an IO step to store the iterations defined in the IO step to the snapshot attribute and to store that at least one step was written.

Parameters

doFlush If true, flush the IO handler.

◆ hasRankTableRead()

bool openPMD::Series::hasRankTableRead ( )

Returns: True if there is a rankTable dataset defined for this Series. False in write-only access modes. Will indiscriminately return false in file encoding: rankTable is not explicitly supported in file encoding, finding out if one is defined would require opening all available files. You may still call Series::rankTable() to retrieve the rank table if you know that there is one, but note that it will return the rank table from the file that was last opened.

◆ iterationEncoding()

IterationEncoding openPMD::Series::iterationEncoding ( ) const

Returns: Current encoding style for multiple iterations in this series.

◆ iterationFormat()

std::string openPMD::Series::iterationFormat ( ) const

Returns: String describing a pattern describing how to access single iterations in the raw file.

◆ machine()

std::string openPMD::Series::machine ( ) const

Exceptions

no_such_attribute_error If optional attribute is not present.

Returns: String indicating the machine or relevant hardware that created the file.

◆ meshesPath()

std::string openPMD::Series::meshesPath ( ) const

Exceptions

no_such_attribute_error If optional attribute is not present.

Returns: String representing the path to mesh records, relative(!) to basePath.

◆ name()

std::string openPMD::Series::name ( ) const

Returns: String of a pattern for file names.

◆ openPMD()

std::string openPMD::Series::openPMD ( ) const

Returns: String representing the current enforced version of the openPMD standard.

◆ openPMDextension()

uint32_t openPMD::Series::openPMDextension ( ) const

Returns: 32-bit mask of applied extensions to the openPMD standard.

◆ operator bool()

openPMD::Series::operator bool ( ) const

Is this a usable Series object?

Returns: true If a Series has been opened for reading and/or writing.; false If the object has been default-constructed.

◆ parseBase()

void openPMD::Series::parseBase ( )

Parse the Series.

Only necessary in linear read mode. In linear read mode, the Series constructor does not do any IO accesses. This call effectively triggers the side effects of Series::readIterations(), for use cases where data needs to be accessed before iterating through the iterations.

The reason for introducing this restricted alias to Series::readIterations() is that the name "readIterations" is misleading for that use case: When using IO steps, this call only ensures that the first step is parsed.

◆ parseJsonOptions()

template<typename TracingJSON >

void openPMD::Series::parseJsonOptions	(	TracingJSON &	options,
		ParsedInput &	input
	)

Parse non-backend-specific configuration in JSON config.

Currently this parses the keys defer_iteration_parsing, backend and iteration_encoding.

Template Parameters

TracingJSON template parameter so we don't have to include the JSON lib here

◆ particlesPath()

std::string openPMD::Series::particlesPath ( ) const

Exceptions

no_such_attribute_error If optional attribute is not present.

Returns: String representing the path to particle species, relative(!) to basePath.

◆ rankTable()

chunk_assignment::RankMeta openPMD::Series::rankTable ( bool collective )

Exceptions

no_such_attribute_error If optional attribute is not present.

Parameters

collective Run this read operation collectively. There might be an enormous IO overhead if running this operation non-collectively. To make this explicit to users, there is no default parameter. Parameter is ignored if compiling without MPI support, (it is present for the sake of a consistent API).

Returns: Vector with a String per (writing) MPI rank, indicating user- defined meta information per rank. Example: host name.

◆ readGorVBased()

auto openPMD::Series::readGorVBased	(	bool	do_always_throw_errors,
		bool	init,
		std::optional< IterationIndex_t >	read_only_this_single_iteration
	)

Note on re-parsing of a Series: If init == false, the parsing process will seek for new Iterations/Records/Record Components etc.

If series.iterations contains the attribute snapshot, returns its value. If do_always_throw_errors is false, this method will try to handle errors and turn them into a warning (useful when parsing a Series, since parsing should succeed without issue). If true, the error will always be re-thrown (useful when using ReadIterations since those methods should be aware when the current step is broken). Parameter read_only_this_single_iteration used for reopening an Iteration after closing it.

◆ readIterations()

ReadIterations openPMD::Series::readIterations ( )

Entry point to the reading end of the streaming API.

Creates and returns an instance of the ReadIterations class which can be used for iterating over the openPMD iterations in a C++11-style for loop. Series::readIterations() is an intentionally restricted API that ensures a workflow which also works in streaming setups, e.g. an iteration cannot be opened again once it has been closed. For a less restrictive API in non-streaming situations, Series::iterations can be accessed directly. Look for the ReadIterations class for further documentation.

Returns: ReadIterations

◆ setAuthor()

Series & openPMD::Series::setAuthor ( std::string const & author )

Indicate the author and contact for the information in the file.

Parameters

author String indicating author and contact for the information in the file.

Returns: Reference to modified series.

◆ setBasePath()

Series & openPMD::Series::setBasePath ( std::string const & basePath )

Set the common prefix for all data sets and sub-groups of a specific iteration.

Parameters

basePath String of the common prefix for all data sets and sub-groups of a specific iteration.

Returns: Reference to modified series.

◆ setDate()

Series & openPMD::Series::setDate ( std::string const & date )

Indicate the date of creation.

Parameters

date	String indicating the date of creation.

Returns: Reference to modified series.

◆ setIterationEncoding()

Series & openPMD::Series::setIterationEncoding ( IterationEncoding iterationEncoding )

Set the encoding style for multiple iterations in this series.

A preview on the openPMD 2.0 variable-based iteration encoding can be activated with this call. Making full use of the variable-based iteration encoding requires (1) explicit support by the backend (available only in ADIOS2) and (2) use of the openPMD streaming API. In other backends and without the streaming API, only one iteration/snapshot may be written in the variable-based encoding, making this encoding a good choice for single-snapshot data dumps.

Parameters

iterationEncoding Desired encoding style for multiple iterations in this series.

Returns: Reference to modified series.

◆ setIterationFormat()

Series & openPMD::Series::setIterationFormat ( std::string const & iterationFormat )

Set a pattern describing how to access single iterations in the raw file.

Parameters

iterationFormat String with the iteration regex %T defining either the series of files (fileBased) or the series of groups within a single file (groupBased) that allows to extract the iteration from it. For fileBased formats the iteration must be included in the file name. The format depends on the selected iterationEncoding method.

Returns: Reference to modified series.

◆ setMachine()

Series & openPMD::Series::setMachine ( std::string const & newMachine )

Indicate the machine or relevant hardware that created the file.

Parameters

newMachine String indicating the machine or relevant hardware that created the file (semicolon-separated list if needed)..

Returns: Reference to modified series.

◆ setMeshesPath()

Series & openPMD::Series::setMeshesPath ( std::string const & meshesPath )

Set the path to mesh records, relative(!) to basePath.

Parameters

meshesPath String of the path to mesh records, relative(!) to basePath.

Returns: Reference to modified series.

◆ setName()

Series & openPMD::Series::setName ( std::string const & name )

Set the pattern for file names.

Parameters

name	String of the pattern for file names. Must include iteration regex `%T` for fileBased data.

Returns: Reference to modified series.

◆ setOpenPMD()

Series & openPMD::Series::setOpenPMD ( std::string const & openPMD )

Set the version of the enforced openPMD standard.

Parameters

openPMD String MAJOR.MINOR.REVISION of the desired version of the openPMD standard.

Returns: Reference to modified series.

◆ setOpenPMDextension()

Series & openPMD::Series::setOpenPMDextension ( uint32_t openPMDextension )

Set a 32-bit mask of applied extensions to the openPMD standard.

Parameters

openPMDextension Unsigned 32-bit integer used as a bit-mask of applied extensions.

Returns: Reference to modified series.

◆ setParticlesPath()

Series & openPMD::Series::setParticlesPath ( std::string const & particlesPath )

Set the path to groups for each particle species, relative(!) to basePath.

Parameters

particlesPath String of the path to groups for each particle species, relative(!) to basePath.

Returns: Reference to modified series.

◆ setRankTable()

Series & openPMD::Series::setRankTable ( std::string const & myRankInfo )

Set the Mpi Ranks Meta Info attribute, i.e.

a Vector with a String per (writing) MPI rank, indicating user- defined meta information per rank. Example: host name.

Returns: Reference to modified series.

◆ setSoftware()

Series & openPMD::Series::setSoftware	(	std::string const &	newName,
		std::string const &	newVersion = `std::string("unspecified")`
	)

Indicate the software/code/simulation that created the file.

Parameters

newName	String indicating the software/code/simulation that created the file.
newVersion	String indicating the version of the software/code/simulation that created the file.

Returns: Reference to modified series.

◆ setSoftwareDependencies()

Series & openPMD::Series::setSoftwareDependencies ( std::string const & newSoftwareDependencies )

Indicate dependencies of software that were used to create the file.

Parameters

newSoftwareDependencies String indicating dependencies of software that were used to create the file (semicolon-separated list if needed).

Returns: Reference to modified series.

◆ setSoftwareVersion()

Series & openPMD::Series::setSoftwareVersion ( std::string const & softwareVersion )

Indicate the version of the software/code/simulation that created the file.

Deprecated:: Set the version with the second argument of setSoftware()

Parameters

softwareVersion String indicating the version of the software/code/simulation that created the file.

Returns: Reference to modified series.

◆ snapshots()

Snapshots openPMD::Series::snapshots ( )

Preferred way to access Iterations/Snapshots.

Single API for all workflows and access modi.

Two fundamental workflows for Iteration/Snapshot processing exist:

Random-access workflow: Iterations/Snapshots are accessed independently from one another. Users must take care to open() and close() them as needed. More than one Iteration can be open at the same time.
Linear/Synchronous workflow: The (parallel) Series has one shared state. The effect is twofold: (a) Advancing one iterator, e.g. via operator++() will advance all other iterators as well. (b) Advancing an iterator is collective, all MPI ranks must participate. The workflow is generally managed more automatically, Iteration::open() is not needed, Iteration::close() is recommended, but not needed. In READ_LINEAR mode, parsed Iteration data is deleted upon closing (and will be reparsed upon reopening) for a better support of datasets with many Snapshots/Iterations. This happens only if user code explicitly calls Iteration::close(). This mode generally brings better performance than random access mode due to the more restricted workflow. For accessing some kinds of Series, Synchronous access is even necessary, e.g. for Streaming workflows or variable-based encoding. (In future, random-access of Series with variable-based encoding will be possible under the condition that each Iteration/Snapshot has the same internal structure).

As a rule of thumb, the synchronous workflow should be preferred as long as possible. The random-access workflow should be chosen when more flexible interaction with Snapshots is needed (especially for random-access read patterns).

Random-vs.-Synchronous access is determined by the chosen Access modes: Access modes suffixed with _LINEAR will select the linear workflow, those suffixed with _RANDOM_ACCESS will select the random-access workflows. READ_WRITE selects the RANDOM_ACCESS workflow. Legacy access names (CREATE, APPEND, READ_ONLY) map to their RANDOM_ACCESS counterparts.

◆ software()

std::string openPMD::Series::software ( ) const

Exceptions

no_such_attribute_error If optional attribute is not present.

Returns: String indicating the software/code/simulation that created the file;

◆ softwareDependencies()

std::string openPMD::Series::softwareDependencies ( ) const

Exceptions

no_such_attribute_error If optional attribute is not present.

Returns: String indicating dependencies of software that were used to create the file.

◆ softwareVersion()

std::string openPMD::Series::softwareVersion ( ) const

Exceptions

no_such_attribute_error If optional attribute is not present.

Returns: String indicating the version of the software/code/simulation that created the file.

◆ writeIterations()

WriteIterations openPMD::Series::writeIterations ( )

Entry point to the writing end of the streaming API.

Shorthand for Series::snapshots() for access types CREATE and APPEND called with parameter SnapshotWorkflow::Synchronous, i.e. for streaming-aware data producers.

Returns: WriteIterations

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

/home/docs/checkouts/readthedocs.org/user_builds/openpmd-api/checkouts/1821/include/openPMD/Series.hpp
/home/docs/checkouts/readthedocs.org/user_builds/openpmd-api/checkouts/1821/src/Series.cpp

Classes

Public Types

Public Member Functions

Public Attributes

Static Public Attributes

Friends

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ Series() [1/2]

◆ Series() [2/2]

Member Function Documentation

◆ advance()

◆ author()

◆ backend()

◆ basePath()

◆ close()

◆ date()

◆ flush()

◆ flush_impl()

◆ flushStep()

◆ hasRankTableRead()

◆ iterationEncoding()

◆ iterationFormat()

◆ machine()

◆ meshesPath()

◆ name()

◆ openPMD()

◆ openPMDextension()

◆ operator bool()

◆ parseBase()

◆ parseJsonOptions()

◆ particlesPath()

◆ rankTable()

◆ readGorVBased()

◆ readIterations()

◆ setAuthor()

◆ setBasePath()

◆ setDate()

◆ setIterationEncoding()

◆ setIterationFormat()

◆ setMachine()

◆ setMeshesPath()

◆ setName()

◆ setOpenPMD()

◆ setOpenPMDextension()

◆ setParticlesPath()

◆ setRankTable()

◆ setSoftware()

◆ setSoftwareDependencies()

◆ setSoftwareVersion()

◆ snapshots()

◆ software()

◆ softwareDependencies()

◆ softwareVersion()

◆ writeIterations()