This class is intended to do all the heavy lifting when it comes to reading and writing "big data" files. It supports multiple backends, i.e. different I/O libraries. The default is "Parallel netCDF". More...

#include <parallelio.h>

Inheritance diagram for ParallelIoBase< Backend >:

[legend]

Collaboration diagram for ParallelIoBase< Backend >:

[legend]

Public Types
using	size_type = MLong
	Type used for all size- and offset-related values. More...

using	maiabd_type = maia::parallel_io::maiabd_type
	Type used for all constants that are defined in maia::parallel_io. More...

Public Member Functions
MBool	hasDataset (const MString &name, MInt dimension)
	Check if the file contains an dataset with the given name and dimension. More...

MBool	hasDataset (const MString &name, const MString &path)

MBool	hasDataset (const MString &name)
	Check if the file contains an dataset with the given name. More...

MBool	hasObject (const MString &path)

MInt	getDatasetType (const MString &name)
	Returns the data type of an array. More...

std::vector< MString >	getDatasetNames (const size_type dimensions=-1)
	Returns a vector with the names of all existing datasets with given dimensionality in the file. More...

std::vector< MString >	getDatasetNames (const MString &path)

std::vector< MString >	getGroupNames (const MString &path)

size_type	getDatasetNoDims (const MString &name)
	Get the number of dimensions of a dataset with given name. More...

size_type	getDatasetNoDims (const MString &name, const MString &path)

std::vector< size_type >	getArrayDims (const MString &name)
	Get the lengths of all dimensions of a dataset with given name. More...

size_type	getArraySize (const MString &name, const size_type dimensionId=0)
	Get the length of an array in the file. More...

void	getArraySize (const MString &name, const MString &path, size_type *datasetSize)

MBool	hasAttribute (const MString &name, const MString &path="")
	Check if a given attribute exists in the file. More...

maiabd_type	getAttributeType (const MString &name, const MString &datasetName="")
	Returns the data type of an attribute in the file. More...

void	defineArray (maiabd_type type, const MString &name, size_type totalCount)
	Create a new array in the file. More...

void	defineArray (maiabd_type type, const MString &name, size_type noDims, size_type *totalCount)
	Create a new array in the file. More...

void	defineArray (maiabd_type type, const std::vector< MString > &name, size_type totalCount)
	Create multiple new arrays in the file. More...

void	defineArray (maiabd_type type, const MString &datasetName, const MString &name, size_type noDims, size_type *totalCount)
	Creates new array in the file. More...

void	defineScalar (maiabd_type type, const MString &name)
	Create a new scalar in the file. More...

template<class T >
void	writeArray (const T *array, const MString &name, size_type memoryStride=-1, size_type diskStride=-1)
	Write array data to file. [MPI] More...

template<class T >
void	writeArray (const T *array, const std::vector< MString > &names, size_type memoryStride=-1, size_type diskStride=-1)
	Write array data to file (multi-array version). [MPI] More...

template<class T >
void	writeArray (const T array, const MString &path, const MString &name, const size_type noDims, size_type offset, size_type *localCount)
	Write multidimensional array data to file. [MPI] More...

template<class T >
void	writeArray (const T array, const MString &path, const MString &name, const size_type noDims, size_type offset, size_type localCount, size_type ghost)
	Write multidimensional array data to file [ghost cell version]. [MPI] More...

template<class T >
void	writeScalar (T scalar, const MString &name)
	Write scalar data to file. [MPI] More...

template<class T >
void	setAttribute (const T &value, const MString &name, const MString &datasetName="")
	Set a file or dataset attribute. [MPI] More...

void	setAttribute (const MChar *value, const MString &name, const MString &datasetName="")

template<class T >
void	setAttributes (const T *value, const MString &name, size_type totalCount, const MString &datasetName="")

template<class T >
void	readArray (T *array, const MString &name, size_type memoryStride=-1, size_type diskStride=-1)
	Read array data from file. [MPI] More...

template<class T >
void	readArray (std::vector< T > &array, const MString &name, size_type memoryStride=-1, size_type diskStride=-1)

template<class T >
void	readArray (T *array, const std::vector< MString > &names, size_type memoryStride=-1, size_type diskStride=-1)
	Read array data from file (multi-array version). [MPI] More...

template<class T >
void	readArray (T array, const MString &datasetName, const MString &name, const size_type noDims, const size_type offset, const size_type *localCount)
	Read array data from file. [MPI] More...

template<class T >
void	readArray (T array, const MString &datasetName, const MString &name, const size_type noDims, const size_type localCount)
	Read array data from file [no offset version]. [MPI] More...

template<class T >
void	readScalar (T *scalar, const MString &name)
	Read scalar data from file. [MPI] More...

template<class T >
void	getAttribute (T *value, const MString &name, const MString &datasetName="")
	Retrieve a file or dataset attribute. More...

template<class T >
void	getAttribute (T *value, const MString &name, const size_type totalCount, const MString &datasetName="")

void	getAttributeCount (const MString &name, size_type *totalCount, const MString &datasetName="")

void	setOffset (const size_type localCount, const size_type offset, const size_type noDims, const size_type noChunks)
	Set the local and global counts, as well the local offset for array operations. More...

void	setOffset (const size_type localCount, const size_type offset, const size_type noDims)
	Set the local and global counts, as well the local offset for array operations (overload). More...

void	setOffset (size_type localCount, size_type offset)
	Set the local and global counts, as well the local offset for array operations (overload). More...

Static Public Member Functions
static MBool	fileExists (const MString &name, const MPI_Comm &mpiComm)
	Check whether a file exists. [MPI] More...

static void	deleteFile (const MString &name)
	Deletes the specified file. [MPI] More...

static MBool	isParallelIoFile (const MString &name, const MPI_Comm &mpiComm)
	Check if specified file is a valid ParallelIoHdf5 file. [MPI] More...

static MString	fileExt ()
	Returns backend-specific ending of filename (either ".Netcdf" or ".Hdf5") More...

static void	calcOffset (size_type localCount, size_type offset, size_type totalCount, const MPI_Comm &mpiComm, size_type *noChunks=nullptr)
	Calculates the totalCount and offset information needed in setOffset(). [MPI] More...

Protected Member Functions
	ParallelIoBase (MString fileName, MInt fileMode, const MPI_Comm &mpiComm)
	Creates a new object to read and write big data files. [MPI] More...

virtual	~ParallelIoBase ()
	empty destructor. [MPI] More...

void	validateType (const maiabd_type type) const
	Auxiliary method that aborts MAIA if type is not a valid type constant for ParallelIo. More...

Protected Attributes
const MString	m_fileName {}

const MInt	m_fileMode = -1

MBool	m_isHeaderSaved = false

MInt	m_domainId = -1

MInt	m_noDomains = -1

MPI_Comm	m_mpiComm {}

MPI_Info	m_mpiInfo = MPI_INFO_NULL

MBool	m_offsetsAreSet = false

std::vector< size_type >	m_localCount = {-1}

std::vector< size_type >	m_offset = {-1}

size_type	m_noChunks = -1

MFloat	m_creationTime = MFloatNaN

std::set< MString >	m_unwrittenArrays

std::set< MString >	m_unwrittenScalars

std::set< MString >	m_writtenArrays

std::set< MString >	m_writtenScalars

std::set< MString >	m_readArrays

std::set< MString >	m_readScalars

Static Protected Attributes
static const size_type	s_maxChunkSize = 2147483645

static const MPI_Datatype	s_mpiSizeType = maia::type_traits<ParallelIoBase<Backend>::size_type>::mpiType()

Private Member Functions
Backend &	derived ()

const Backend &	derived () const

Detailed Description

template<class Backend>
class ParallelIoBase< Backend >

Author: Michael Schlottke (mic) mic@a.nosp@m.ia.r.nosp@m.wth-a.nosp@m.ache.nosp@m.n.de, Konstantin Froehlich

Date: 2013-03-27

As of fall 2015 there are two backends available: Parallel netCDF and HDF5.

The main intention of the class is : complete separation of I/O calls from the user, so that nobody has to deal with the different ways of how to use (Parallel) NetCDF, HDF5, MPI I/O etc. The class also offers an easy way to make sure that data files (i.e. restart files, solution files) and grid files always have the correct format.

Note: All methods that may be slow or incur a significant overhead since they use MPI communication (either for I/O or other purposes) are marked with [MPI]. While they might not always have this overhead, it is better to assume they have and to use them only when necessary.

Note: Almost all methods in this class are collective, i.e. they have to be called on all ranks within the given MPI communicator to work properly (even if they themselves are not marked with [MPI]). Some methods may fail if you try to call them from a subset of the ranks, but do not rely on a meaningful error.

Note: Since I/O is often an error-prone area, it is usually advisable to check all I/O operations for possible occurring errors. In order to relieve the user from the burden of doing correct and repeated checking of possible error values/message, ParallelIo adheres to the following rule:

ALL ERRORS ARE FATAL!

Exceptions to this rule are marked as such. This has the advantage that there is no need to do extra checking in the production code of MAIA itself on the one hand, and on the other hand it is assured that it is not possible that I/O operations leave MAIA in an undefined state if an error occurred.

Definition at line 101 of file parallelio.h.

Member Typedef Documentation

◆ maiabd_type

template<class Backend >

using ParallelIoBase< Backend >::maiabd_type = maia::parallel_io::maiabd_type

Definition at line 128 of file parallelio.h.

◆ size_type

template<class Backend >

using ParallelIoBase< Backend >::size_type = MLong

This type will be used internally and externally for all values that can be used as size values or offsets. Examples are 'count', 'size', 'stride' etc. The usage of this type is to ensure that this type may be changed with little to no necessary changes within the code. A change might be necessary e.g. if the previous type's range becomes to small to hold all relevant size information.

Note: If you change this type, you also MUST check if the static member s_mpiSizeType needs to be changed as well, since it is used as the MPI type to communicate values of the 'size_type' kind.

Definition at line 123 of file parallelio.h.

Constructor & Destructor Documentation

◆ ParallelIoBase()

template<class Backend >

ParallelIoBase< Backend >::ParallelIoBase	(	MString	fileName,
		MInt	fileMode,
		const MPI_Comm &	mpiComm
	)

protected

Author: Michael Schlottke (mic) mic@a.nosp@m.ia.r.nosp@m.wth-a.nosp@m.ache.nosp@m.n.de

Date: 2013-03-26

Author: (Modified by: )Ramandeep Jain (HiWi) raman.nosp@m.deep.nosp@m.jain@.nosp@m.gmai.nosp@m.l.com, Konstantin Froehlich

Date: 2015-03-01

Parameters

[in]	fileMode	The file mode can be either maia::parallel_io::PIO_CREATE, maia::parallel_io::PIO_APPEND, or maia::parallel_io::PIO_READ.
[in]	mpiComm	The MPI communicator that should be used to open/create the file.

Definition at line 405 of file parallelio.h.

  : m_fileName(std::move(fileName)), m_fileMode(fileMode), m_mpiComm(mpiComm) {
  TRACE();
 
  using namespace maia::parallel_io;
  // Make sure that the file mode is supported
  if(fileMode != PIO_CREATE && fileMode != PIO_APPEND && fileMode != PIO_REPLACE && fileMode != PIO_READ) {
    TERMM(1, "File mode must be one of PIO_CREATE/PIO_APPEND/PIO_REPLACE/PIO_READ!");
  }
 
  // Set domain id and number of domains
  MPI_Comm_rank(m_mpiComm, &m_domainId);
  MPI_Comm_size(m_mpiComm, &m_noDomains);
 
  // Store creation time stamp
  m_creationTime = wallTime();
}

◆ ~ParallelIoBase()

template<class Backend >

ParallelIoBase< Backend >::~ParallelIoBase

protectedvirtual

Author: Konstantin Froehlich

Date: 2013-03-26

Definition at line 431 of file parallelio.h.

                                         {
  TRACE();
 
  // Log the total file lifetime
  const MFloat lifetime = wallTime() - m_creationTime;
 
  const MInt maxLineLength = 256;
  MChar b[maxLineLength];
  snprintf(b, maxLineLength, "=== PARALLELIO FILE LIFETIME: %-35s | %.4e s |\n", m_fileName.c_str(), lifetime);
  if(m_domainId == 0) {
    std::cerr << b;
  }
  m_log << b;
}

Member Function Documentation

◆ calcOffset()

template<class Backend >

void ParallelIoBase< Backend >::calcOffset	(	size_type	localCount,
		size_type *	offset,
		size_type *	totalCount,
		const MPI_Comm &	mpiComm,
		size_type *	noChunks = `nullptr`
	)

static

Author: Michael Schlottke (mic) mic@a.nosp@m.ia.r.nosp@m.wth-a.nosp@m.ache.nosp@m.n.de, Konstantin Froehlich

Date: 2013-04-09

Parameters

[in]	localCount	Number of elements in an array on the current domain.
[out]	offset	Starting offset in the file, from which this domain should start writing/reading (is zero if localCount=0).
[out]	totalCount	Total number of elements in an array across all domains.
[in]	mpiComm	MPI communicator for which the totalCount and the offset should be calculated.
[in]	noChunks	Number of Chunks for chunked IO.

This must be a collective call from all ranks in mpiComm.

Definition at line 1927 of file parallelio.h.

                                                                                       {
  TRACE();
 
  // Ensure reasonable parameter values
  if(localCount < 0) {
    TERMM(1, "The local size may not be less than zero (was:" + std::to_string(localCount) + ")!");
  }
 
  // Get rank and size
  MInt domainId, noDomains;
  MPI_Comm_rank(mpiComm, &domainId);
  MPI_Comm_size(mpiComm, &noDomains);
 
  // Calculate offset and total size values
  MPI_Exscan(&localCount, offset, 1, s_mpiSizeType, MPI_SUM, mpiComm, AT_, "localCount", "offset");
  if(domainId == 0) {
    offset[0] = 0;
  }
 
  totalCount[0] = offset[0] + localCount;
  MPI_Bcast(totalCount, 1, s_mpiSizeType, (noDomains - 1), mpiComm, AT_, "totalCount");
 
  // If a domain has zero size set the offset to zero such that reading/writing
  // can not result in an error caused by exceeding the array size
  if(localCount == 0) {
    offset[0] = 0;
  }
 
  // If noChunks is not a null pointer, calculate & set number of chunks
  if(noChunks != nullptr) {
    // Divide total count by maximum chunk size
    noChunks[0] = totalCount[0] / s_maxChunkSize;
 
    // If there is a remainder for the division, increment number by one
    if(totalCount[0] % s_maxChunkSize > 0) {
      noChunks[0] += 1;
    }
  }
}

◆ defineArray() [1/4]

template<class Backend >

void ParallelIoBase< Backend >::defineArray	(	maiabd_type	type,
		const MString &	datasetName,
		const MString &	name,
		size_type	noDims,
		size_type *	totalCount
	)

Author: Marian Albers <m.alb.nosp@m.ers@.nosp@m.aia.r.nosp@m.wth-.nosp@m.aache.nosp@m.n.de

Date: 2022-09-25

Parameters

[in]	type	Data type of the arrays (either maia::parallel_io::PIO_FLOAT or maia::parallel_io::PIO_INT).
[in]	Name	of the array
[in]	Number	of dimensions of array
[in]	Size	of array in each space direction

Definition at line 891 of file parallelio.h.

                                                                                   {
  TRACE();
 
  using namespace maia::parallel_io;
 
  // Prevent adding data in read-only mode
  if(m_fileMode == PIO_READ) {
    mTerm(1, AT_, "Cannot add data in read-only mode!");
  }
 
#ifdef MAIA_EXTRA_DEBUG
  m_unwrittenArrays.insert(name);
#endif
 
  // Ensure reasonable parameter values
  validateType(type);
  if(name.empty()) {
    TERMM(1, "Invalid name! Name must not be empty.");
  }
  if(noDims <= 0) {
    TERMM(1, "Invalid number of dimensions! Must at least be 1.");
  }
 
  derived().b_defineArray(type, datasetName, name, noDims, totalCount);
}

◆ defineArray() [2/4]

template<class Backend >

void ParallelIoBase< Backend >::defineArray	(	maiabd_type	type,
		const MString &	name,
		size_type	noDims,
		size_type *	totalCount
	)

Author: Michael Schlottke (mic) mic@a.nosp@m.ia.r.nosp@m.wth-a.nosp@m.ache.nosp@m.n.de, Konstantin Froehlich

Date: 2013-04-08

Parameters

[in]	type	Data type of the array (either maia::parallel_io::PIO_FLOAT, maia::parallel_io::PIO_INT, maia::parallel_io::PIO_LONG or maia::parallel_io::PIO_STRING or maia::parallel_io::PIO_UCHAR).
[in]	name	Name of the array (may not be empty).
[in]	noDims	Number of array dimensions
[in]	totalCount	Total size of the array for all dimensions (i.e. combined size of all involved domains).

This method may not be called after the first call to writeArray() or writeScalar().

Definition at line 812 of file parallelio.h.

                                                                 {
  TRACE();
 
#ifdef DISABLE_OUTPUT
  return;
#endif
 
  using namespace maia::parallel_io;
 
  // Prevent adding data in read-only mode
  if(m_fileMode == PIO_READ) {
    mTerm(1, AT_, "Cannot add data in read-only mode!");
  }
 
  // Abort if header was already written
  if(m_isHeaderSaved) {
    mTerm(1, AT_, "Cannot add new data after header was written!");
  }
 
#ifdef MAIA_EXTRA_DEBUG
  m_unwrittenArrays.insert(name);
#endif
 
  // Ensure reasonable parameter values
  validateType(type);
  if(name.empty()) {
    TERMM(1, "Invalid name! Name must not be empty.");
  }
  if(noDims <= 0) {
    TERMM(1, "Invalid number of dimensions! Must at least be 1.");
  }
 
  derived().b_defineArray(type, name, noDims, totalCount);
}

◆ defineArray() [3/4]

template<class Backend >

void ParallelIoBase< Backend >::defineArray	(	maiabd_type	type,
		const MString &	name,
		size_type	totalCount
	)

Author: Michael Schlottke (mic) mic@a.nosp@m.ia.r.nosp@m.wth-a.nosp@m.ache.nosp@m.n.de, Konstantin Froehlich

Date: 2013-04-08

Parameters

[in]	type	Data type of the array (either maia::parallel_io::PIO_FLOAT, maia::parallel_io::PIO_INT, maia::parallel_io::PIO_LONG or maia::parallel_io::PIO_STRING or maia::parallel_io::PIO_UCHAR).
[in]	name	Name of the array (may not be empty).
[in]	totalCount	Total size of the array (i.e. combined size of all involved domains).

This method may not be called after the first call to writeArray() or writeScalar().

Definition at line 783 of file parallelio.h.

                                                                                                     {
  TRACE();
 
#ifdef DISABLE_OUTPUT
  return;
#endif
 
  defineArray(type, name, 1, &totalCount);
}

◆ defineArray() [4/4]

template<class Backend >

void ParallelIoBase< Backend >::defineArray	(	maiabd_type	type,
		const std::vector< MString > &	names,
		size_type	totalCount
	)

Author: Michael Schlottke (mic) mic@a.nosp@m.ia.r.nosp@m.wth-a.nosp@m.ache.nosp@m.n.de, Konstantin Froehlich

Date: 2013-04-08

Parameters

[in]	type	Data type of the arrays (either maia::parallel_io::PIO_FLOAT or maia::parallel_io::PIO_INT).
[in]	names	Names of the arrays (may not be empty).
[in]	totalCount	Total size of each array (i.e. combined size of all involved domains).

This method may not be called after the first call to writeArray() or writeScalar().

Definition at line 865 of file parallelio.h.

                                                                                                                 {
  TRACE();
 
#ifdef DISABLE_OUTPUT
  return;
#endif
 
  for(const auto& name : names) {
    defineArray(type, name, totalCount);
  }
}

◆ defineScalar()

template<class Backend >

void ParallelIoBase< Backend >::defineScalar	(	maiabd_type	type,
		const MString &	name
	)

Author: Michael Schlottke (mic) mic@a.nosp@m.ia.r.nosp@m.wth-a.nosp@m.ache.nosp@m.n.de, Konstantin Froehlich

Date: 2013-04-08

Parameters

[in]	type	Data type of the scalar (either maia::parallel_io::PIO_FLOAT or maia::parallel_io::PIO_INT).
[in]	name	Name of the scalar (may not be empty).

This method may not be called after the first call to writeArray() or writeScalar().

Definition at line 933 of file parallelio.h.

                                                                                {
  TRACE();
 
#ifdef DISABLE_OUTPUT
  return;
#endif
 
  using namespace maia::parallel_io;
 
  // Prevent adding data in read-only mode
  if(m_fileMode == PIO_READ) {
    TERMM(1, "Cannot add data in read-only mode!");
  }
 
  // Abort if header was already written
  if(m_isHeaderSaved) {
    TERMM(1, "Cannot add new data after header was written!");
  }
 
#ifdef MAIA_EXTRA_DEBUG
  m_unwrittenScalars.insert(name);
#endif
 
  // Ensure reasonable parameter values
  validateType(type);
  if(name.empty()) {
    TERMM(1, "Invalid name! Name must not be empty.");
  }
 
  derived().b_defineScalar(type, name);
}

◆ deleteFile()

template<typename Backend >

void ParallelIoBase< Backend >::deleteFile ( const MString & name )

static

Author: Michael Schlottke (mic) mic@a.nosp@m.ia.r.nosp@m.wth-a.nosp@m.ache.nosp@m.n.de

Date: 2013-04-01

This method does not check if the file exists before attempting to delete it.

Definition at line 346 of file parallelio.h.

                                                            {
  TRACE();
 
  MPI_File_delete(const_cast<MChar*>(name.c_str()), MPI_INFO_NULL);
}

◆ derived() [1/2]

template<class Backend >

Backend & ParallelIoBase< Backend >::derived ( )

inlineprivate

Definition at line 104 of file parallelio.h.

104{ return static_cast<Backend&>(*this); }

◆ derived() [2/2]

template<class Backend >

const Backend & ParallelIoBase< Backend >::derived ( ) const

inlineprivate

Definition at line 105 of file parallelio.h.

105{ return static_cast<const Backend&>(*this); }

◆ fileExists()

template<typename Backend >

MBool ParallelIoBase< Backend >::fileExists	(	const MString &	name,
		const MPI_Comm &	mpiComm
	)

static

Author: Michael Schlottke (mic) mic@a.nosp@m.ia.r.nosp@m.wth-a.nosp@m.ache.nosp@m.n.de, Konstantin Froehlich

Date: 2013-04-01

Parameters

[in] mpiComm The MPI communicator to be used to check the file existence.

Returns: True, if the specified file exists.

This must be a collective call from all ranks in mpiComm.

Definition at line 318 of file parallelio.h.

                                                                                      {
  TRACE();
 
  // Try to stat file on rank 0 - will return something other than zero of file
  // does not exist - and broadcast to others
  int rank, status;
  MPI_Comm_rank(mpiComm, &rank);
  if(rank == 0) {
    struct stat buffer {};
    status = static_cast<int>(stat(name.c_str(), &buffer) == 0);
  }
  MPI_Bcast(&status, 1, MPI_INT, 0, mpiComm, AT_, "status");
 
  return status != 0;
}

◆ fileExt()

template<class Backend >

MString ParallelIoBase< Backend >::fileExt

static

Author: Konstantin Froehlich

Date: 2015-10-21

Definition at line 379 of file parallelio.h.

                                         {
  TRACE();
 
  return Backend::b_fileExt();
}

◆ getArrayDims()

template<class Backend >

std::vector< typename ParallelIoBase< Backend >::size_type > ParallelIoBase< Backend >::getArrayDims ( const MString & name )

Author: Ansgar Niemoeller, Konstantin Froehlich

Date: 2015-08-19

Parameters

[in]	name	Name of dataset to check
[out]	dims	Contains the lengths of all dimensions of the dataset

Definition at line 633 of file parallelio.h.

                                                                                                              {
  TRACE();
 
  // Abort if array does not exist
  if(!hasDataset(name) || hasDataset(name, 0)) {
    TERMM(1, "The specified array '" + name + "' does not exist.");
  }
 
  // Get number of dimensions
  size_type noDims = getDatasetNoDims(name);
 
  std::vector<size_type> dims;
 
  // Get lengths of all dimensions
  for(size_type dimId = 0; dimId < noDims; dimId++) {
    dims.push_back(getArraySize(name, dimId));
  }
 
  return dims;
}

◆ getArraySize() [1/2]

template<class Backend >

void ParallelIoBase< Backend >::getArraySize	(	const MString &	name,
		const MString &	path,
		size_type *	datasetSize
	)

Definition at line 688 of file parallelio.h.

                                                                                                           {
  TRACE();
 
  // Abort if dataset does not exist or if its a scalar
  if(!hasDataset(name, path)) {
    TERMM(1, "The specified array '" + name + "' does not exist.");
  }
 
  size_type noDims = derived().b_getDatasetNoDims(name, path);
  derived().b_getDatasetSize(name, path, noDims, datasetSize);
}

◆ getArraySize() [2/2]

template<class Backend >

ParallelIoBase< Backend >::size_type ParallelIoBase< Backend >::getArraySize	(	const MString &	name,
		const size_type	dimensionId = `0`
	)

Author: Michael Schlottke (mic) mic@a.nosp@m.ia.r.nosp@m.wth-a.nosp@m.ache.nosp@m.n.de, Konstantin Froehlich

Date: 2013-04-01

Parameters

[in]	name	Name of the array to check.
[in]	dimensionId	Dimension of the array to check (default 0).

Returns: Total number of elements of the array in the given dimension.

Definition at line 667 of file parallelio.h.

                                                                                                               {
  TRACE();
 
  // Abort if dataset does not exist or if its a scalar
  if(!hasDataset(name) || hasDataset(name, 0)) {
    TERMM(1, "The specified array '" + name + "' does not exist.");
  }
 
  // Abort if dimensionId exceeds number of dimensions
  size_type noDims = getDatasetNoDims(name);
  if(dimensionId >= noDims) {
    TERMM(1, "The specified dimension for array '" + name + "'does not exist.");
  }
 
  size_type returnValue = derived().b_getDatasetSize(name, dimensionId);
 
  return returnValue;
}

◆ getAttribute() [1/2]

template<class Backend >

template<class T >

void ParallelIoBase< Backend >::getAttribute	(	T *	value,
		const MString &	name,
		const MString &	datasetName = `""`
	)

Author: Michael Schlottke (mic) mic@a.nosp@m.ia.r.nosp@m.wth-a.nosp@m.ache.nosp@m.n.de, Konstantin Froehlich

Date: 2013-04-09

Template Parameters

T	Data type of the attribute (can be either MFloat, MInt, or MString).

Parameters

[in]	value	Value of the attribute.
[in]	name	Name of the attribute.
[in]	datasetName	Reads the attribute from this dataset (i.e. array or scalar). If empty, retrieve as file attribute.

Definition at line 1788 of file parallelio.h.

                                                                                                    {
  TRACE();
  getAttribute(value, name, 1, datasetName);
}

◆ getAttribute() [2/2]

template<class Backend >

template<class T >

void ParallelIoBase< Backend >::getAttribute	(	T *	value,
		const MString &	name,
		const size_type	totalCount,
		const MString &	datasetName = `""`
	)

Definition at line 1795 of file parallelio.h.

                                                                       {
  TRACE();
  derived().b_getAttribute(value, name, datasetName, totalCount);
}

◆ getAttributeCount()

template<class Backend >

void ParallelIoBase< Backend >::getAttributeCount	(	const MString &	name,
		size_type *	totalCount,
		const MString &	datasetName = `""`
	)

Definition at line 1802 of file parallelio.h.

                                                                            {
  TRACE();
  derived().b_getAttributeCount(name, totalCount, datasetName);
}

◆ getAttributeType()

template<class Backend >

MInt ParallelIoBase< Backend >::getAttributeType	(	const MString &	name,
		const MString &	datasetName = `""`
	)

Author: Michael Schlottke (mic) mic@a.nosp@m.ia.r.nosp@m.wth-a.nosp@m.ache.nosp@m.n.de, Konstantin Froehlich

Date: 2013-04-01

Parameters

[in]	name	Name of the attribute to be checked.
[in]	datasetName	Name of the dataset for which the attribute is checked. If empty, a file attribute is checked.

Returns: The data type as defined in the namespace maia::parallel_io.

Calls hasAttribute() first to check if the attribute exists and aborts fatally if not.

Definition at line 749 of file parallelio.h.

                                                                                              {
  TRACE();
 
  // Abort if attribute does not exist
  if(!hasAttribute(name, datasetName)) {
    mTerm(1, AT_, "The specified attribute does not exist.");
  }
 
  return derived().b_getAttributeType(name, datasetName);
}

◆ getDatasetNames() [1/2]

template<class Backend >

std::vector< MString > ParallelIoBase< Backend >::getDatasetNames ( const MString & path )

Definition at line 565 of file parallelio.h.

                                                                               {
  TRACE();
 
  std::vector<MString> names;
  derived().b_getDatasetNames(names, path);
 
  return names;
}

◆ getDatasetNames() [2/2]

template<class Backend >

std::vector< MString > ParallelIoBase< Backend >::getDatasetNames ( const size_type dimension = -1 )

Author: Ansgar Niemoeller, , Konstantin Froehlich

Date: 2015-08-19

Parameters

[in]	dimension	Return datasets with given dimensionality (default -1)
[out]	names	Contains all found dataset names with the given dimensionality (if any).

Definition at line 554 of file parallelio.h.

                                                                                     {
  TRACE();
 
  std::vector<MString> names;
  derived().b_getDatasetNames(names, dimension);
 
  return names;
}

◆ getDatasetNoDims() [1/2]

template<class Backend >

ParallelIoBase< Backend >::size_type ParallelIoBase< Backend >::getDatasetNoDims ( const MString & name )

Author: Ansgar Niemoeller, Konstantin Froehlich

Date: 2015-08-19

Parameters

[in]	name	Name of dataset to check
[out]	noDims	Number of dimensions of the dataset

Definition at line 594 of file parallelio.h.

                                                                                                       {
  TRACE();
 
  // Abort if dataset does not exist
  if(!hasDataset(name)) {
    TERMM(1, "The specified dataset '" + name + "' does not exist.");
  }
 
  size_type noDims = derived().b_getDatasetNoDims(name);
 
  return noDims;
}

◆ getDatasetNoDims() [2/2]

template<class Backend >

ParallelIoBase< Backend >::size_type ParallelIoBase< Backend >::getDatasetNoDims	(	const MString &	name,
		const MString &	path
	)

Definition at line 608 of file parallelio.h.

                                                                                                           {
  TRACE();
 
  // Abort if dataset does not exist
  if(!hasDataset(name, path)) {
    TERMM(1, "The specified dataset '" + name + "' does not exist.");
  }
 
  size_type noDims = derived().b_getDatasetNoDims(name, path);
 
  return noDims;
}

◆ getDatasetType()

template<class Backend >

MInt ParallelIoBase< Backend >::getDatasetType ( const MString & name )

Author: Michael Schlottke (mic) mic@a.nosp@m.ia.r.nosp@m.wth-a.nosp@m.ache.nosp@m.n.de

Date: 2013-04-01

Author: Modified by: Ramandeep Jain (HiWi) raman.nosp@m.deep.nosp@m.jain@.nosp@m.gmai.nosp@m.l.com, Konstantin Froehlich

Date: 2015-Mar

Parameters

[in] name Name of the array to check.

Returns: The data type as defined in the namespace maia::parallel_io.

Calls hasDataset() first to check if the array exists and aborts fatally if not.

Definition at line 530 of file parallelio.h.

                                                                {
  TRACE();
 
  // Abort if dataset does not exist
  if(!hasDataset(name)) {
    TERMM(1, "The specified dataset '" + name + "' does not exist.");
  }
 
  return derived().b_getDatasetType(name);
}

◆ getGroupNames()

template<class Backend >

std::vector< MString > ParallelIoBase< Backend >::getGroupNames ( const MString & path )

Definition at line 575 of file parallelio.h.

                                                                             {
  TRACE();
 
  std::vector<MString> names;
  derived().b_getGroupNames(names, path);
 
  return names;
}

◆ hasAttribute()

template<class Backend >

MBool ParallelIoBase< Backend >::hasAttribute	(	const MString &	name,
		const MString &	path = `""`
	)

Author: Michael Schlottke (mic) mic@a.nosp@m.ia.r.nosp@m.wth-a.nosp@m.ache.nosp@m.n.de, Konstantin Froehlich

Date: 2013-04-01

Parameters

[in]	name	Name of the attribute to be checked.
[in]	datasetName	Name of the dataset for which the attribute is checked. If empty, a file attribute is checked.

Returns: True, if the attribute exists.

Definition at line 714 of file parallelio.h.

                                                                                    {
  TRACE();
 
  // If the dataset name is empty, this means a file attribute should be
  // checked.
  // Otherwise a dataset attribute (scalar or array) is to be checked - abort if
  // no dataset can be found.
  if(!path.empty()) {
    if(!hasObject(path)) {
      return false;
    }
  }
 
  MBool returnValue = derived().b_hasAttribute(name, path);
 
  return returnValue;
}

◆ hasDataset() [1/3]

template<class Backend >

MBool ParallelIoBase< Backend >::hasDataset ( const MString & name )

Author: Michael Schlottke (mic) mic@a.nosp@m.ia.r.nosp@m.wth-a.nosp@m.ache.nosp@m.n.de, Konstantin Froehlich

Date: 2013-04-01

Parameters

[in] name The name of the dataset that should be checked.

Returns: True if an dataset of the given name exists.

Definition at line 487 of file parallelio.h.

                                                             {
  TRACE();
 
  MBool returnValue = derived().b_hasDataset(name, -1);
 
  return returnValue;
}

◆ hasDataset() [2/3]

template<class Backend >

MBool ParallelIoBase< Backend >::hasDataset	(	const MString &	name,
		const MString &	path
	)

Definition at line 496 of file parallelio.h.

                                                                                  {
  TRACE();
 
  MBool returnValue = derived().b_hasDataset(name, path);
 
  return returnValue;
}

◆ hasDataset() [3/3]

template<class Backend >

MBool ParallelIoBase< Backend >::hasDataset	(	const MString &	name,
		MInt	dimension
	)

Author: Michael Schlottke (mic) mic@a.nosp@m.ia.r.nosp@m.wth-a.nosp@m.ache.nosp@m.n.de, Konstantin Froehlich

Date: 2013-04-01

Parameters

[in]	name	The name of the dataset that should be checked.
[in]	dimension	Dimension of dataset to match, -1 will match any dataset, 0 will only match scalars, 1 arrays with one dimensions, ...

Returns: True if an dataset of the given name with given dimension exists.

Definition at line 467 of file parallelio.h.

                                                                                   {
  TRACE();
 
  MBool returnValue = derived().b_hasDataset(name, dimension);
 
  return returnValue;
}

◆ hasObject()

template<class Backend >

MBool ParallelIoBase< Backend >::hasObject ( const MString & path )

Definition at line 505 of file parallelio.h.

                                                            {
  TRACE();
 
  MBool returnValue = derived().b_hasObject(name);
 
  return returnValue;
}

◆ isParallelIoFile()

template<class Backend >

MBool ParallelIoBase< Backend >::isParallelIoFile	(	const MString &	name,
		const MPI_Comm &	mpiComm
	)

static

Author: Ramandeep Jain (HiWi) raman.nosp@m.deep.nosp@m.jain@.nosp@m.gmai.nosp@m.l.com, Konstantin Froehlich

Date: 2015-03-01

Parameters

[in] mpiComm MPI communicator to be used.

This must be a collective call from all ranks in mpiComm.

Definition at line 364 of file parallelio.h.

                                                                                            {
  TRACE();
 
  return Backend::b_isValidFile(name, mpiComm);
}

◆ readArray() [1/5]

template<class Backend >

template<class T >

void ParallelIoBase< Backend >::readArray	(	std::vector< T > &	array,
		const MString &	name,
		size_type	memoryStride = `-1`,
		size_type	diskStride = `-1`
	)

inline

Definition at line 195 of file parallelio.h.

                                                                                                                   {
    readArray(array.data(), name, memoryStride, diskStride);
  }

◆ readArray() [2/5]

template<class Backend >

template<class T >

void ParallelIoBase< Backend >::readArray	(	T *	array,
		const MString &	datasetName,
		const MString &	name,
		const size_type	noDims,
		const size_type *	localCount
	)

Author: Marian Albers m.alb.nosp@m.ers@.nosp@m.aia.r.nosp@m.wth-.nosp@m.aache.nosp@m.n.de

Date: 2022-09-029

Template Parameters

T	Data type of the array (can be either MFloat or MInt and must match the previous definition of the array).

Parameters

[in]	array	Pointer to the data in memory.
[in]	name	Name of the array in the file.
[in]	path	Group name in which the array shall be located (works only with HDF5).
[in]	noDims	Number of dimensions of the array
[in]	localCount	Size of the array in each dimension, must of of size noDims

Definition at line 1645 of file parallelio.h.

                                                                                             {
  TRACE();
 
#ifdef MAIA_EXTRA_DEBUG
  // In debug mode, check if array was already read and give a warning
  if(m_readArrays.count(name) != 0) {
    std::cerr << "Warning: in " << AT_ << " (" << __FILE__ << ":" << __LINE__ << ") "
              << "the array '" << name << "' is read more than once. Make sure that this is the"
              << "intended behavior." << std::endl;
  }
  m_readArrays.insert(name);
#endif
 
  if(array == 0 && localCount[0] > 0) {
    mTerm(1, AT_, "Data pointer must point to a valid location (is: null pointer)!");
  }
 
  ScratchSpace<size_type> offset(noDims, FUN_, "offset");
  offset.fill(0);
 
  // Read array
  derived().b_readArray(array, datasetName, name, noDims, &offset[0], localCount);
}

◆ readArray() [3/5]

template<class Backend >

template<class T >

void ParallelIoBase< Backend >::readArray	(	T *	array,
		const MString &	datasetName,
		const MString &	name,
		const size_type	noDims,
		const size_type *	offset,
		const size_type *	localCount
	)

Author: Marian Albers m.alb.nosp@m.ers@.nosp@m.aia.r.nosp@m.wth-.nosp@m.aache.nosp@m.n.de

Date: 2022-09-029

Template Parameters

T	Data type of the array (can be either MFloat or MInt and must match the previous definition of the array).

Parameters

[in]	array	Pointer to the data in memory.
[in]	name	Name of the array in the file.
[in]	path	Group name in which the array shall be located (works only with HDF5).
[in]	noDims	Number of dimensions of the array
[in]	offset	Offset of the of the array in the dataset in each dimension, must be of size noDims
[in]	localCount	Size of the array in each dimension, must of of size noDims

Definition at line 1602 of file parallelio.h.

                                                                     {
  TRACE();
 
#ifdef MAIA_EXTRA_DEBUG
  // In debug mode, check if array was already read and give a warning
  if(m_readArrays.count(name) != 0) {
    std::cerr << "Warning: in " << AT_ << " (" << __FILE__ << ":" << __LINE__ << ") "
              << "the array '" << name << "' is read more than once. Make sure that this is the"
              << "intended behavior." << std::endl;
  }
  m_readArrays.insert(name);
#endif
 
  if(array == 0 && localCount[0] > 0) {
    mTerm(1, AT_, "Data pointer must point to a valid location (is: null pointer)!");
  }
 
  // Read array
  derived().b_readArray(array, datasetName, name, noDims, offset, localCount);
}

◆ readArray() [4/5]

template<class Backend >

template<class T >

void ParallelIoBase< Backend >::readArray	(	T *	array,
		const MString &	name,
		size_type	memoryStride = `-1`,
		size_type	diskStride = `-1`
	)

Author: Michael Schlottke (mic) mic@a.nosp@m.ia.r.nosp@m.wth-a.nosp@m.ache.nosp@m.n.de, Konstantin Froehlich

Date: 2013-04-09

Template Parameters

T	Data type of the array (can be either MFloat or MInt and must match the previous definition of the array).

Parameters

[in]	array	Pointer to the data in memory.
[in]	name	Name of the array in the file.
[in]	memoryStride	Offset between two data values in memory (or -1 to set automatically).
[in]	diskStride	Offset between two data values on disk (or -1 to set automatically).

The size and file offset have to be set using setOffset() before this method is called. If no stride is given (or -1), the stride will be set to 1.

Note: This method is the exact counterpart to writeArray().

Example:

Suppose you would like to read in the z-coordinates you previously saved to a file in the example of writeArray(maiabd_type, const MString&, size_type). In this case, you just set the offset as before

setOffset(550, 0);   // <-- This line on domain0. We have 550 cells and
                     //     start at the beginning.
setOffset(450, 550); // <-- This line on domain1. We have 450 cells and
                     //     leave a gap of 550.

and then call readArray() with the exact same arguments as you used for writeArray():

readArray(&a_coordinates[2], "coordinates_2", 3);

Definition at line 1523 of file parallelio.h.

                                                                                                                   {
  TRACE();
 
  // Abort if offsets were not set
  if(!m_offsetsAreSet) {
    mTerm(1, AT_, "Offsets have to be set before calling readArray!");
  }
 
#ifdef MAIA_EXTRA_DEBUG
  // In debug mode, check if array was already read and give a warning
  if(m_readArrays.count(name) != 0) {
    std::cerr << "Warning: in " << AT_ << " (" << __FILE__ << ":" << __LINE__ << ") "
              << "the array '" << name << "' is read more than once. Make sure that this is the"
              << "intended behavior." << std::endl;
  }
  m_readArrays.insert(name);
#endif
 
  // Ensure reasonable parameter values
  if(memoryStride != -1 && memoryStride <= 0) {
    mTerm(1, AT_, "memoryStride must be greater than zero (or -1 to set automatically)!");
  }
  if(diskStride != -1 && diskStride <= 0) {
    mTerm(1, AT_, "diskStride must be greater than zero (or -1 to set automatically)!");
  }
  if(array == 0 && m_localCount[0] > 0) {
    mTerm(1, AT_, "Data pointer must point to a valid location (is: null pointer)!");
  }
 
  // Set actual stride if no explicit stride value was given
  size_type actualMemoryStride;
  if(memoryStride == -1) {
    actualMemoryStride = 1;
  } else {
    actualMemoryStride = memoryStride;
  }
  size_type actualDiskStride = (diskStride == -1) ? 1 : diskStride;
 
  // Set number of chunks
  const size_type noChunks = (m_noChunks == -1) ? 1 : m_noChunks;
 
  size_type noDims = getDatasetNoDims(name);
 
  ScratchSpace<MPI_Offset> localCount(noDims, FUN_, "localCount");
  ScratchSpace<MPI_Offset> offset(noDims, FUN_, "offset");
 
  localCount[0] = m_localCount[0];
  // Set counts for all dimensions except first to total dimension length
  // m_localCount[0] is set via setOffset(...)
  for(MInt dimId = 1; dimId < noDims; dimId++) {
    localCount[dimId] = getArraySize(name, dimId);
  }
  for(MInt dimId = 0; dimId < noDims; dimId++) {
    offset[dimId] = m_offset[dimId];
  }
 
  // Read array
  derived().b_readArray(array, name, noDims, &offset[0], &localCount[0], actualMemoryStride, noChunks,
                        actualDiskStride);
}

◆ readArray() [5/5]

template<class Backend >

template<class T >

void ParallelIoBase< Backend >::readArray	(	T *	array,
		const std::vector< MString > &	names,
		size_type	memoryStride = `-1`,
		size_type	diskStride = `-1`
	)

Author: Michael Schlottke (mic) mic@a.nosp@m.ia.r.nosp@m.wth-a.nosp@m.ache.nosp@m.n.de, Konstantin Froehlich

Date: 2013-04-09

Template Parameters

T	Data type of the arrays (can be either MFloat or MInt and must match the previous definition of the array).

Parameters

[in]	array	Pointer to the data of the first array in memory.
[in]	names	Names of the arrays in the file.
[in]	memoryStride	Offset between two data values in memory (or -1 to set automatically).
[in]	diskStride	Offset between two data values on disk (or -1 to set automatically).

The size and file offset have to be set using setOffset() before this method is called. If no stride is given (or -1), the stride will be set to the number of provided names. A call to this method with n elements in 'names' is equivalent to calling readArray() n times, each time with the data pointer 'array' being advanced by 1.

Example:

Suppose you would like to read in the all coordinates you previously saved to a file in the example of writeArray(maiabd_type, const vector<MString>&, size_type). In this case, you just set the offset as before

setOffset(550, 0);   // <-- This line on domain0. We have 550 cells and
                     //     start at the beginning.
setOffset(450, 550); // <-- This line on domain1. We have 450 cells and
                     //     leave a gap of 550.

and then call readArray(maiabd_type, const vector<MString>&, size_type) with the exact same arguments as you used for writeArray(maiabd_type, const vector<MString>&, size_type):

readArray(&cells[0].m_coordinates[0], names);

Definition at line 1711 of file parallelio.h.

                                                              {
  TRACE();
 
  // Ensure reasonable parameter values
  if(memoryStride != -1 && memoryStride < static_cast<size_type>(names.size())) {
    mTerm(1, AT_,
          "memoryStride must be greater than or equal to number of "
          "variables (or -1 to set automatically)!");
  }
  if(diskStride != -1 && diskStride < static_cast<size_type>(names.size())) {
    mTerm(1, AT_,
          "diskStride must be greater than or equal to number of "
          "variables (or -1 to set automatically)!");
  }
 
  // Set actual stride if no explicit stride value was given
  size_type actualMemoryStride;
  if(memoryStride == -1) {
    actualMemoryStride = static_cast<size_type>(names.size());
  } else {
    actualMemoryStride = memoryStride;
  }
  size_type actualDiskStride = (diskStride == -1) ? 1 : diskStride;
 
  // Read arrays from vector using normal readArray call
  for(std::vector<MString>::size_type i = 0; i < names.size(); i++) {
    readArray(array + i, names[i], actualMemoryStride, actualDiskStride);
  }
}

◆ readScalar()

template<class Backend >

template<class T >

void ParallelIoBase< Backend >::readScalar	(	T *	scalar,
		const MString &	name
	)

Author: Michael Schlottke (mic) mic@a.nosp@m.ia.r.nosp@m.wth-a.nosp@m.ache.nosp@m.n.de, Konstantin Froehlich

Date: 2013-04-09

Template Parameters

T	Data type of the scalar (can be either MFloat or MInt and must match the previous definition of the scalar).

Parameters

[in]	scalar	Value that should be read from file.
[in]	name	Name of the scalar in the file.

Note: This method is the exact counterpart to writeScalar().

Definition at line 1758 of file parallelio.h.

                                                                       {
#ifdef MAIA_EXTRA_DEBUG
  // In debug mode, check if scalar was already read and give a warning
  if(m_readScalars.count(name) != 0) {
    std::cerr << "Warning: in " << AT_ << " (" << __FILE__ << ":" << __LINE__ << ") "
              << "the scalar '" << name << "' is read more than once. Make sure that this is the"
              << "intended behavior." << std::endl;
  }
  m_readScalars.insert(name);
#endif
 
  derived().b_readScalar(scalar, name);
}

◆ setAttribute() [1/2]

template<class Backend >

void ParallelIoBase< Backend >::setAttribute	(	const MChar *	value,
		const MString &	name,
		const MString &	datasetName = `""`
	)

Definition at line 1445 of file parallelio.h.

                                                                                                              {
  const MString tmpValue = MString(value);
  setAttributes(&tmpValue, name, 1, datasetName);
}

◆ setAttribute() [2/2]

template<class Backend >

template<class T >

void ParallelIoBase< Backend >::setAttribute	(	const T &	value,
		const MString &	name,
		const MString &	datasetName = `""`
	)

Author: Michael Schlottke (mic) mic@a.nosp@m.ia.r.nosp@m.wth-a.nosp@m.ache.nosp@m.n.de, Konstantin Froehlich

Date: 2013-04-09

Template Parameters

T	Data type of the attribute (can be either MFloat, MInt, or MString).

Parameters

[in]	value	Value of the attribute.
[in]	name	Name of the attribute (must not be empty).
[in]	datasetName	Attaches the attribute to this dataset (i.e. array or scalar). If empty, use as file attribute.

You can add attributes to datasets as soon as they were defined with defineArray()/ defineScalar(). You can also use this to overwrite an attribute of the same name. When you call this method before the first read or write operation, there is no MPI overhead.

Definition at line 1438 of file parallelio.h.

                                                                                                          {
  TRACE();
  setAttributes(&value, name, 1, datasetName);
}

◆ setAttributes()

template<class Backend >

template<class T >

void ParallelIoBase< Backend >::setAttributes	(	const T *	value,
		const MString &	name,
		size_type	totalCount,
		const MString &	datasetName = `""`
	)

Definition at line 1452 of file parallelio.h.

                                                                        {
  TRACE();
 
#ifdef DISABLE_OUTPUT
  return;
#endif
 
  using namespace maia::parallel_io;
 
  // Prevent rewriting data in read-only mode
  if(m_fileMode == PIO_READ) {
    mTerm(1, AT_, "Cannot write data in read-only mode!");
  }
 
  // Ensure reasonable parameter values
  if(name.empty()) {
    mTerm(1, AT_, "Invalid name! Name must not be empty.");
  }
  ASSERT(totalCount > 0, "");
 
  derived().b_setAttribute(value, name, datasetName, totalCount);
}

◆ setOffset() [1/3]

template<class Backend >

void ParallelIoBase< Backend >::setOffset	(	const size_type	localCount,
		const size_type	offset,
		const size_type	noDims
	)

Definition at line 1889 of file parallelio.h.

                                                                                                                  {
  TRACE();
 
  setOffset(localCount, offset, noDims, -1);
}

◆ setOffset() [2/3]

template<class Backend >

void ParallelIoBase< Backend >::setOffset	(	const size_type	localCount,
		const size_type	offset,
		const size_type	noDims,
		const size_type	noChunks
	)

Author: Michael Schlottke (mic) mic@a.nosp@m.ia.r.nosp@m.wth-a.nosp@m.ache.nosp@m.n.de, Konstantin Froehlich

Date: 2013-04-09

Parameters

[in]	localCount	Number of elements in an array on the current domain.
[in]	offset	Starting offset in the file, from which this domain should start writing/reading.
[in]	noDims	number of dimensions of the array for more than one dimension localCount and offset refer to the first dimension, for all other dimensions the count will be set to the total dimension length, multidimensional counts and offsets are not yet supported
[in]	noChunks	Number of Chunks for chunked IO.

You have to call this method at least once before your first call to readArray()/writeArray(). The reason for storing the offset and count information with the object is that there are usually only a very limited number of different array sizes in each file, and thus it is more convenient to set the offsets once and write/read multiple times afterwards.

The offset may be calculated by hand (or known beforehand), or may be conveniently calculated using calcOffset().

Definition at line 1840 of file parallelio.h.

                                                                  {
  TRACE();
 
  // Ensure reasonable parameter values
  if(localCount < 0) {
    TERMM(1, "The local size may not be less than zero (was:" + std::to_string(localCount) + ")!");
  }
  if(offset < 0) {
    TERMM(1, "The offset may not be less than zero (was:" + std::to_string(offset) + ")!");
  }
  if(noDims <= 0) {
    TERMM(1, "The number of dimensions must at least be one!");
  }
  if(noChunks == 0) {
    TERMM(1, "The number of chunks may not be zero!");
  }
 
  // TODO labels:IO add support for setting a multi-dimensional count/offset for reading/writing data
 
  // Set member variables
  m_localCount.reserve(noDims);
  m_localCount.assign(noDims, -1); // -1 as a precaution
  m_localCount[0] = localCount;
 
  // Note:
  // if noDims>1: {m_localCount[i], i>0} will be set to the total count for that
  // dimension before reading/writing the multi-d array
  // setting the local count for multiple dimensions is not yet supported
  m_offset.reserve(noDims);
  m_offset.assign(noDims, 0);
  m_offset[0] = offset;
 
  if(noChunks > 0) {
    m_noChunks = noChunks;
  }
 
  // Set state variable
  m_offsetsAreSet = true;
}

◆ setOffset() [3/3]

template<class Backend >

void ParallelIoBase< Backend >::setOffset	(	size_type	localCount,
		size_type	offset
	)

Definition at line 1901 of file parallelio.h.

                                                                                          {
  TRACE();
 
  setOffset(localCount, offset, 1, -1);
}

◆ validateType()

template<class Backend >

void ParallelIoBase< Backend >::validateType ( const maiabd_type type ) const

protected

Author: Michael Schlottke-Lakemper (mic) mic@a.nosp@m.ia.r.nosp@m.wth-a.nosp@m.ache.nosp@m.n.de

Date: 2017-06-23

Parameters

[in] type The type constant (integer) to check for validity.

Definition at line 1976 of file parallelio.h.

                                                                       {
  TRACE();
 
  using namespace maia::parallel_io;
 
  if(type != PIO_FLOAT && type != PIO_INT && type != PIO_LONG && type != PIO_STRING && type != PIO_UCHAR
     && type != PIO_ULONGLONG) {
    TERMM(1, "Invalid data type! Must be PIO_FLOAT or PIO_INT or PIO_LONG or PIO_STRING or PIO_UCHAR.");
  }
}

◆ writeArray() [1/4]

template<class Backend >

template<class T >

void ParallelIoBase< Backend >::writeArray	(	const T *	array,
		const MString &	name,
		size_type	memoryStride = `-1`,
		size_type	diskStride = `-1`
	)

Author: Michael Schlottke (mic) mic@a.nosp@m.ia.r.nosp@m.wth-a.nosp@m.ache.nosp@m.n.de, Konstantin Froehlich

Date: 2013-04-09

Template Parameters

T	Data type of the array (can be either MFloat or MInt and must match the previous definition of the array).

Parameters

[in]	array	Pointer to the data in memory.
[in]	name	Name of the array in the file.
[in]	memoryStride	Offset between two data values in memory (or -1 to set automatically).
[in]	diskStride	Offset between two data values on disk (or -1 to set automatically).

The size and file offset have to be set using setOffset() before this method is called. If no stride is given (or -1), the stride will be set to 1.

Example:

Suppose you would like to store all z-coordinates of your cells in a file, and assign them the name 'coordinates_2'. You have a total of 1000 cells which are split across two domains, domain0 with 550 cells and domain1 with the remaing 450.

Then you first have to define the array with a call

defineArray(PIO_FLOAT, "coordinates_2", 1000);

Note that '1000' denoting the total count, i.e. the number of values you would like to write from all domains (or, alternatively worded, this is the size the dataset will have in the file). If you do not know the total count yet, you can use calcOffset() to conveniently calculate it.

Next you have to set the offset, so each processor knows where it should start writing. In this case its rather simple: domain0 should write its first value at the beginning of the file, and domain1 should leave a gap of 550 values for domain0. Thus you have to call setOffset() once on each domain, i.e.

setOffset(550, 0);   // <-- This line on domain0. We have 550 cells and
                     //     start at the beginning.
setOffset(450, 550); // <-- This line on domain1. We have 450 cells and
                     //     leave a gap of 550.

Now you can start writing. For this you need to know how your data is distributed in memory. In MAIA, most cell data is stored contiguously in memory, grouped by cell. This means that for 3D, the coordinates are layed out in memory as (noted as cellId:direction)

| 0:x | 0:y | 0:z | 1:x | 1:y | 1:z | 2:x | 2:y | 2:z | 3:x | 3:y | ...

For the writeArray() methods you always need to get a pointer to the first value in memory that should be written. The memory address of the z-coordinate of the first cell can be obtained using '&cells[0].m_coordinates[2]'. Therefore, in order to write your data you make the same call to writeArray() on both domains:

writeArray(&a_coordinates[2], "coordinates_2", 3);

What is the '3' doing there? Well, since the data values in memory are not contiguous (we only want to write the z-coordinates, i.e. we only need every third value), you need to provide a stride. The stride always refers to the layout in memory - in the file the values will always be contiguous.

Finally, when we check the file, we will see the following data in 'coordinates_2':

| 0:z | 1:z | 2:z | 3:z | 4:z | ... | 998:z | 999:z |

Now, that wasn't so hard, was it?

Definition at line 1046 of file parallelio.h.

                                                               {
  TRACE();
 
#ifdef DISABLE_OUTPUT
  return;
#endif
 
  using namespace maia::parallel_io;
 
  // Prevent rewriting data in read-only mode
  if(m_fileMode == PIO_READ) {
    TERMM(1, "Cannot write data in read-only mode!");
  }
 
  // Abort if offsets were not set
  if(!m_offsetsAreSet) {
    TERMM(1, "Offsets have to be set before calling writeArray!");
  }
 
#ifdef MAIA_EXTRA_DEBUG
  // In debug mode, check if array was already written and give a warning
  if(m_writtenArrays.count(name) != 0) {
    std::cerr << "Warning: in " << AT_ << " (" << __FILE__ << ":" << __LINE__ << ") "
              << "the array '" << name << "' is written more than once. Make sure that this is the"
              << "intended behavior." << std::endl;
  }
  m_writtenArrays.insert(name);
  if(m_unwrittenArrays.count(name)) {
    m_unwrittenArrays.erase(name);
  }
#endif
 
  // Ensure reasonable parameter values
  if(memoryStride != -1 && memoryStride <= 0) {
    TERMM(1, "memoryStride must be greater than zero (or -1 to set automatically)!");
  }
  if(diskStride != -1 && diskStride <= 0) {
    TERMM(1, "diskStride must be greater than zero (or -1 to set automatically)!");
  }
  if(array == 0 && m_localCount[0] > 0) {
    TERMM(1, "Data pointer must point to a valid location (is: null pointer)!");
  }
 
  // Set actual stride if no explicit stride value was given
  size_type actualMemoryStride;
  if(memoryStride == -1) {
    actualMemoryStride = 1;
  } else {
    actualMemoryStride = memoryStride;
  }
  size_type actualDiskStride = (diskStride == -1) ? 1 : diskStride;
 
  // Save header (if not yet
  if(!m_isHeaderSaved) {
    derived().b_saveHeader();
    m_isHeaderSaved = true;
  }
 
  // Set number of chunks
  const size_type noChunks = (m_noChunks == -1) ? 1 : m_noChunks;
 
  size_type noDims = getDatasetNoDims(name);
 
  ScratchSpace<MPI_Offset> localCount(noDims, FUN_, "localCount");
  ScratchSpace<MPI_Offset> offset(noDims, FUN_, "offset");
 
  // Set counts for all dimensions except first to total dimension length
  // localCount[0] is set via setOffset(...)
  localCount[0] = m_localCount[0];
  for(MInt dimId = 1; dimId < noDims; dimId++) {
    localCount[dimId] = getArraySize(name, dimId);
  }
  for(MInt dimId = 0; dimId < noDims; dimId++) {
    offset[dimId] = m_offset[dimId];
  }
 
  // Write array
  derived().b_writeArray(array, name, noDims, &offset[0], &localCount[0], actualMemoryStride, noChunks,
                         actualDiskStride);
}

◆ writeArray() [2/4]

template<class Backend >

template<class T >

void ParallelIoBase< Backend >::writeArray	(	const T *	array,
		const MString &	path,
		const MString &	name,
		const size_type	noDims,
		size_type *	offset,
		size_type *	localCount
	)

Author: Marian Albers m.alb.nosp@m.ers@.nosp@m.aia.r.nosp@m.wth-.nosp@m.aache.nosp@m.n.de

Date: 2022-09-029

Template Parameters

T	Data type of the array (can be either MFloat or MInt and must match the previous definition of the array).

Parameters

[in]	array	Pointer to the data in memory.
[in]	path	Group name in which the array shall be located (works only with HDF5).
[in]	name	Name of the array in the file.
[in]	noDims	Number of dimensions of the array
[in]	offset	Offset of the of the array in the dataset in each dimension, must be of size noDims
[in]	localCount	Size of the array in each dimension, must of of size noDims

Definition at line 1255 of file parallelio.h.

                                                                                                           {
  TRACE();
 
  ScratchSpace<size_type> ghost(noDims, FUN_, "ghost");
  ghost.fill(0);
 
  derived().b_writeArray(array, path, name, noDims, offset, localCount, &ghost[0]);
}

◆ writeArray() [3/4]

template<class Backend >

template<class T >

void ParallelIoBase< Backend >::writeArray	(	const T *	array,
		const MString &	path,
		const MString &	name,
		const size_type	noDims,
		size_type *	offset,
		size_type *	localCount,
		size_type *	ghost
	)

Author: Marian Albers m.alb.nosp@m.ers@.nosp@m.aia.r.nosp@m.wth-.nosp@m.aache.nosp@m.n.de

Date: 2022-09-029

Template Parameters

T	Data type of the array (can be either MFloat or MInt and must match the previous definition of the array).

Parameters

[in]	array	Pointer to the data in memory.
[in]	path	Group name in which the array shall be located (works only with HDF5).
[in]	name	Name of the array in the file.
[in]	noDims	Number of dimensions of the array
[in]	offset	Offset of the of the array in the dataset in each dimension, must be of size noDims
[in]	localCount	Size of the array in each dimension, must of of size noDims
[in]	ghost	Number of ghost cells in memory preceding the actual values

This method is specifically for storing two- or three-dimensional arrays from the structured solver. Typically the in-memory array has a number of ghost cells at the beginning in every dimension (and at the end) which should be added to the offset when reading from memory, but should be ignored for the dataset in the file that you're writing to. That is, the ghost values are used for the access of the data in memory but ignored when they are being written to the actual dataset in the file.

Definition at line 1292 of file parallelio.h.

                                                           {
  TRACE();
 
#ifdef DISABLE_OUTPUT
  return;
#endif
 
  using namespace maia::parallel_io;
 
  // Prevent rewriting data in read-only mode
  if(m_fileMode == PIO_READ) {
    TERMM(1, "Cannot write data in read-only mode!");
  }
 
#ifdef MAIA_EXTRA_DEBUG
  // In debug mode, check if array was already written and give a warning
  if(m_writtenArrays.count(name) != 0) {
    std::cerr << "Warning: in " << AT_ << " (" << __FILE__ << ":" << __LINE__ << ") "
              << "the array '" << name << "' is written more than once. Make sure that this is the"
              << "intended behavior." << std::endl;
  }
  m_writtenArrays.insert(name);
  if(m_unwrittenArrays.count(name)) {
    m_unwrittenArrays.erase(name);
  }
#endif
 
  // Save header (if not yet
  if(!m_isHeaderSaved) {
    derived().b_saveHeader();
    m_isHeaderSaved = true;
  }
 
  // Ensure reasonable parameter values
  if(array == 0 && localCount[0] > 0) {
    TERMM(1, "Data pointer must point to a valid location (is: null pointer)!");
  }
 
  // Write array
  derived().b_writeArray(array, path, name, noDims, offset, localCount, ghost);
}

◆ writeArray() [4/4]

template<class Backend >

template<class T >

void ParallelIoBase< Backend >::writeArray	(	const T *	array,
		const std::vector< MString > &	names,
		size_type	memoryStride = `-1`,
		size_type	diskStride = `-1`
	)

Author: Michael Schlottke (mic) mic@a.nosp@m.ia.r.nosp@m.wth-a.nosp@m.ache.nosp@m.n.de, Konstantin Froehlich

Date: 2013-04-09

Template Parameters

T	Data type of the arrays (can be either MFloat or MInt and must match the previous definition of the array).

Parameters

[in]	array	Pointer to the data of the first array in memory.
[in]	names	Names of the arrays in the file.
[in]	memoryStride	Offset between two data values in memory (or -1 to set automatically).
[in]	diskStride	Offset between two data values on disk (or -1 to set automatically).

The size and file offset have to be set using setOffset() before this method is called. If no stride is given (or -1), the stride will be set to the number of provided names. A call to this method with n elements in 'names' is equivalent to calling writeArray() n times, each time with the data pointer 'array' being advanced by 1.

Example:

Suppose you would like to write all coordinates of all cells to a file, and store them as separate variables 'coordinates_0' ... 'coordinates_2' (in 3D). Similarly to the example in writeArray(), you have two domains with 550 cells on domain0, and 450 cells on domain1.

First you have to call defineArray() and setOffset(). You call both with the same arguments as described in writeArray(). The only difference is that instead of defining each array individually, you can call defineArray(maiabd_type, const vector<MString>&, size_type) with a vector that holds your names (in our case the aforementioned 'coordinates_0', 'coordinates_1', and 'coordinates_2'), which we call 'names' in this example:

defineArray(PIO_FLOAT, names, 1000);

This is fully equivalent to writing

defineArray(PIO_FLOAT, 'coordinates_0', 1000);
defineArray(PIO_FLOAT, 'coordinates_1', 1000);
defineArray(PIO_FLOAT, 'coordinates_2', 1000);

Next, to set the offset, you call setOffset():

setOffset(550, 0);   // <-- This line on domain0. We have 550 cells and
                     //     start at the beginning.
setOffset(450, 550); // <-- This line on domain1. We have 450 cells and
                     //     leave a gap of 550.

Finally, we can write the data. Using the vector-of-strings version of writeArray(maiabd_type, const vector<MString>&, size_type), we only need one call:

writeArray(&a_coordinates[0], names, 3);

This is fully equivalent to writing

writeArray(&a_coordinates[0], 'coordinates_0', 3);
writeArray(&a_coordinates[1], 'coordinates_1', 3);
writeArray(&a_coordinates[2], 'coordinates_2', 3);

but more convenient :-). It gets even better: If you have want to write all components of a multi-component array from memory to the file (as in this example), writeArray(maiabd_type, const vector<MString>&, size_type) can do the stride calculation automatically for you. So we could just leave it out and write

writeArray(&cells[0].m_coordinates[0], names);

instead.

Definition at line 1204 of file parallelio.h.

                                                               {
  TRACE();
 
#ifdef DISABLE_OUTPUT
  return;
#endif
 
  // Ensure reasonable parameter values
  if(memoryStride != -1 && memoryStride < static_cast<size_type>(names.size())) {
    TERMM(1, "memoryStride must be greater than or equal to number of "
             "variables (or -1 to set automatically)!");
  }
  if(diskStride != -1 && diskStride < static_cast<size_type>(names.size())) {
    TERMM(1, "diskStride must be greater than or equal to number of "
             "variables (or -1 to set automatically)!");
  }
 
  // Set actual stride if no explicit stride value was given
  size_type actualMemoryStride;
  if(memoryStride == -1) {
    actualMemoryStride = static_cast<size_type>(names.size());
  } else {
    actualMemoryStride = memoryStride;
  }
  size_type actualDiskStride = (diskStride == -1) ? 1 : diskStride;
 
  // Write arrays from vector using normal writeArray call
  for(std::vector<MString>::size_type i = 0; i < names.size(); i++) {
    writeArray(array + i, names[i], actualMemoryStride, actualDiskStride);
  }
}

◆ writeScalar()

template<class Backend >

template<class T >

void ParallelIoBase< Backend >::writeScalar	(	T	scalar,
		const MString &	name
	)

Author: Michael Schlottke (mic) mic@a.nosp@m.ia.r.nosp@m.wth-a.nosp@m.ache.nosp@m.n.de, Konstantin Froehlich

Date: 2013-04-09

Template Parameters

T	Data type of the scalar (can be either MFloat or MInt and must match the previous definition of the scalar).

Parameters

[in]	scalar	Value that should be written to file.
[in]	name	Name of the scalar in the file.

Definition at line 1354 of file parallelio.h.

                                                                       {
  TRACE();
 
#ifdef DISABLE_OUTPUT
  return;
#endif
 
  using namespace maia::parallel_io;
 
  // Prevent rewriting data in read-only mode
  if(m_fileMode == PIO_READ) {
    mTerm(1, AT_, "Cannot write data in read-only mode!");
  }
 
#ifndef NDEBUG
  // In debug mode check if scalar value is the same on all ranks
  const T localValue = scalar;
  ScratchSpace<T> globalValues(m_noDomains, AT_, "globalValues");
  // Gather scalar values on rank 0
  MPI_Gather(&localValue, 1, maia::type_traits<T>::mpiType(), &globalValues[0], 1, maia::type_traits<T>::mpiType(), 0,
             m_mpiComm, AT_, "localValue", "globalValues[0]");
 
  // Compare values
  if(m_domainId == 0) {
    for(MInt i = 0; i < m_noDomains; i++) {
      MBool equal = true;
      // Note: cannot use == for floating point values
      if(globalValues[i] < localValue) {
        equal = false;
      }
      if(globalValues[i] > localValue) {
        equal = false;
      }
      if(!equal) {
        TERMM(1, "Error: scalar variable has not the same value on all domains, rank 0: " + std::to_string(localValue)
                     + " != " + std::to_string(globalValues[i]) + " (domain " + std::to_string(i) + ")");
      }
    }
  }
#endif
 
#ifdef MAIA_EXTRA_DEBUG
  // In extra debug mode, check if scalar was already written and give a warning
  if(m_writtenScalars.count(name) != 0) {
    std::cerr << "Warning: in " << AT_ << " (" << __FILE__ << ":" << __LINE__ << ") "
              << "the scalar '" << name << "' is written more than once. Make sure that this is the"
              << "intended behavior." << std::endl;
  }
  m_writtenScalars.insert(name);
  if(m_unwrittenScalars.count(name)) {
    m_unwrittenScalars.erase(name);
  }
#endif
 
  // Save header (if not yet done)
  if(!m_isHeaderSaved) {
    derived().b_saveHeader();
    m_isHeaderSaved = true;
  }
 
  derived().b_writeScalar(scalar, name);
}

Definition at line 270 of file parallelio.h.

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

/home/gitlab-runner/scratch/builds/oxpnswJ6/1/aia/m-AIA/m-AIA/src/IO/parallelio.h

Public Types

Public Member Functions

Static Public Member Functions

Protected Member Functions

Protected Attributes

Static Protected Attributes

Private Member Functions

Detailed Description

Member Typedef Documentation

◆ maiabd_type

◆ size_type

Constructor & Destructor Documentation

◆ ParallelIoBase()

◆ ~ParallelIoBase()

Member Function Documentation

◆ calcOffset()

◆ defineArray() [1/4]

◆ defineArray() [2/4]

◆ defineArray() [3/4]

◆ defineArray() [4/4]

◆ defineScalar()

◆ deleteFile()

◆ derived() [1/2]

◆ derived() [2/2]

◆ fileExists()

◆ fileExt()

◆ getArrayDims()

◆ getArraySize() [1/2]

◆ getArraySize() [2/2]

◆ getAttribute() [1/2]

◆ getAttribute() [2/2]

◆ getAttributeCount()

◆ getAttributeType()

◆ getDatasetNames() [1/2]

◆ getDatasetNames() [2/2]

◆ getDatasetNoDims() [1/2]

◆ getDatasetNoDims() [2/2]

◆ getDatasetType()

◆ getGroupNames()

◆ hasAttribute()

◆ hasDataset() [1/3]

◆ hasDataset() [2/3]

◆ hasDataset() [3/3]

◆ hasObject()

◆ isParallelIoFile()

◆ readArray() [1/5]

◆ readArray() [2/5]

◆ readArray() [3/5]

◆ readArray() [4/5]

◆ readArray() [5/5]

◆ readScalar()

◆ setAttribute() [1/2]

◆ setAttribute() [2/2]

◆ setAttributes()

◆ setOffset() [1/3]

◆ setOffset() [2/3]

◆ setOffset() [3/3]

◆ validateType()

◆ writeArray() [1/4]

◆ writeArray() [2/4]

◆ writeArray() [3/4]

◆ writeArray() [4/4]

◆ writeScalar()

Member Data Documentation

◆ m_creationTime

◆ m_domainId

◆ m_fileMode

◆ m_fileName

◆ m_isHeaderSaved

◆ m_localCount

◆ m_mpiComm

◆ m_mpiInfo

◆ m_noChunks

◆ m_noDomains

◆ m_offset

◆ m_offsetsAreSet

◆ m_readArrays

◆ m_readScalars

◆ m_unwrittenArrays

◆ m_unwrittenScalars