Plot Peano's mesh data in Peano's patch file format with binary quantities. More...

#include <PeanoBinaryPatchFileWriter.h>

Inheritance diagram for tarch.plotter::griddata::blockstructured::PeanoBinaryPatchFileWriter:

Collaboration diagram for tarch.plotter::griddata::blockstructured::PeanoBinaryPatchFileWriter:

[legend]

Data Structures
class	CellDataWriter

class	VertexDataWriter

Public Types
enum class	IndexFileMode

Public Member Functions
	PeanoBinaryPatchFileWriter (int dimension, const std::string &fileName, const std::string &indexFileName, IndexFileMode appendToIndexFile, double timeStamp, int precision=6)
	Create a new Peano text file output.

virtual	~PeanoBinaryPatchFileWriter ()
	Destructor.

virtual CellDataWriter *	createCellDataWriter (const std::string &identifier, int unknownsPerAxis, int recordsPerCell, const std::string &description) override
	Caller has to destroy this instance manually.

virtual CellDataWriter *	createCellDataWriter (const std::string &identifier, int unknownsPerAxis, int recordsPerCell, const std::string &description, const std::string &metaData) override
	Create cell data writer.

virtual CellDataWriter *	createCellDataWriter (const std::string &identifier, int unknownsPerAxis, int recordsPerCell, const std::string &description, const std::string &metaData, double *mapping) override
	Create writer.

virtual VertexDataWriter *	createVertexDataWriter (const std::string &identifier, int unknownsPerAxis, int recordsPerVertex, const std::string &description) override
	Caller has to destroy this instance manually.

virtual VertexDataWriter *	createVertexDataWriter (const std::string &identifier, int unknownsPerAxis, int recordsPerVertex, const std::string &description, const std::string &metaData) override
	Create vertex data writer.

virtual VertexDataWriter *	createVertexDataWriter (const std::string &identifier, int unknownsPerAxis, int recordsPerVertex, const std::string &description, const std::string &metaData, double *mapping) override
	Create writer.

virtual int	plotPatch (const tarch::la::Vector< 2, double > &offset, const tarch::la::Vector< 2, double > &size) override

virtual int	plotPatch (const tarch::la::Vector< 3, double > &offset, const tarch::la::Vector< 3, double > &size) override

virtual bool	writeToFile () override

virtual bool	isOpen () override

virtual void	clear () override
	Clear local data.

Public Member Functions inherited from tarch.plotter::griddata::blockstructured::PatchWriter
virtual	~PatchWriter ()=default

Protected Member Functions
void	writeMetaData (const std::string &metaData)

void	writeMapping (int totalEntries, double *values)

void	createBackupOfMetaFile ()

void	createEmptyIndexFile ()

void	addNewDatasetToIndexFile (double timestamp)

void	addNewFileToCurrentDataSetInIndexFile (const std::string &filename)

double	getLatestTimeStepInIndexFile () const
	Find latest time step in index file.

Protected Attributes
std::string	_fileName

std::string	_indexFile

bool	_writtenToFile

int	_dimensions

int	_patchCounter

std::stringstream	_snapshotFileOut

bool	_haveWrittenAtLeastOnePatch

Static Protected Attributes
static tarch::logging::Log	_log

static const std::string	HEADER

Detailed Description

Plot Peano's mesh data in Peano's patch file format with binary quantities.

This writer is the sibling of tarch::plotter::griddata::blockstructured::PeanoTextPatchFileWriter. It writes exactly the same file, with two differences:

The header holds the line format Binary instead of format ASCII.
The quantities of a patch, i.e. the lines between begin cell-values and end cell-values (or the vertex counterparts), are not written as text. They are dumped as raw doubles, 8 bytes each in the byte order of the machine, followed by one line break. The surrounding lines (patch offset and size, metadata, mappings, markers) remain plain text. The reader knows from the metadata how many bytes to read.

Binary files are smaller and faster to write, and they hold the doubles bit-exact. The index file is a plain text file as before, as it holds no quantities. Use tarch::reader::PeanoBinaryPatchFileReader to read the data back.

As the doubles are written as they are, there is no notion of precision of the quantities. The precision passed to the constructor still determines the digits of the text entries (patch offsets and sizes, mappings).

Everything below on index file modes applies to this writer as well.

Consult the general plotting remarks on rationale and patterns behind the realisation of this class. This is a technical view. If you are interested in the file format that is written, you have to read the documentation of the Peano patch file format.

Meta file construction modes

There are different configuration modes. They are passed as an argument to the constructor:

IndexFileMode::CreateNew Create a new index file. The old one is thrown away.
IndexFileMode::NoIndexFile Ignore the whole index file stuff. Every instance of the plotter dumps its own data and they do not synchronise in any way.
IndexFileMode::AppendNewData Try to append a new data set to a given index file.

The last one is the most sophisticated variant and deserves further explanation. First of all, the code searches for the index (or meta) file. If there is none, the code basically falls back to IndexFileMode::CreateNew, i.e. creates a new index file.

If there is a file, we open it and look what the latest time stamp in there is. For this, we call getLatestTimeStepInIndexFile(). If that time stamp is bigger than the current time stamp, we know that this index file is from a previous run. We create a backup (some people do appreciate if we do so) and then again create a new index file.

If our own time stamp matches the last time stamp in the index file, we know that the current dump is one (of many) dumps by a spacetree which contributes towards the overall picture. That is, we add our own data set to the existing time stamp.

If our own time stamp is bigger than the last one, we know that we are the first plotter of all the plotters out there which started to dump the data of the next time stamp. We append a new section for a new dump and add our own file there.

Definition at line 94 of file PeanoBinaryPatchFileWriter.h.

Member Enumeration Documentation

◆ IndexFileMode

enum class tarch::plotter::griddata::blockstructured::PeanoBinaryPatchFileWriter::IndexFileMode

strong

Definition at line 245 of file PeanoBinaryPatchFileWriter.h.

Constructor & Destructor Documentation

◆ PeanoBinaryPatchFileWriter()

tarch.plotter::griddata::blockstructured::PeanoBinaryPatchFileWriter::PeanoBinaryPatchFileWriter	(	int	dimension,
		const std::string &	fileName,
		const std::string &	indexFileName,
		IndexFileMode	appendToIndexFile,
		double	timeStamp,
		int	precision = `6`
	)

Create a new Peano text file output.

An instance of this class has to be owned by each action set that wants to dump data.

AppendNewData and the order of operations

If appendToIndexFile is IndexFileMode::AppendNewData and no index file exists yet, the constructor has to both create that index file (which, via createEmptyIndexFile(), already writes one dataset section for timeStamp) and decide whether the current writer's own timeStamp is "newer" than whatever is already in the index file, to decide if a further, separate dataset section is required. That decision has to be made by calling getLatestTimeStepInIndexFile() after the index file has been (re)created if it had to be - not before. Comparing against the "no data yet" state that getLatestTimeStepInIndexFile() reports for a file that does not exist yet would make the writer for the very first data set of a run believe it also has to open a second, empty dataset section for its own (freshly written) time stamp, and every later writer for that same time stamp would then register its data in that spurious second section rather than the first, correct one. If you touch the ordering of operations in the AppendNewData branch of the implementation, preserve this "decide only after creating/recreating" order.

Parameters

dimension	I make this a free parameter, even though most codes will pass in the compile time parameter Dimensions. However, there are codes which plot submanifolds for example or want to write 3d data within a 2d code, as they implement a 2.5d model.
fileName	Name of the file to write. Has to be unique per dump.
indexFileName	Name of the index file. Can we empty if you select NoIndexFile.
precision	Number of significant digits of the text entries of the file, i.e. patch offsets and sizes and mappings. The quantities are written as raw doubles and are not affected. Keep at least six digits on deep adaptive meshes, as the patch offsets otherwise become imprecise.

◆ ~PeanoBinaryPatchFileWriter()

virtual tarch.plotter::griddata::blockstructured::PeanoBinaryPatchFileWriter::~PeanoBinaryPatchFileWriter ( )

virtual

Destructor.

The destructor is empty, i.e. if you destroy this object, your data are lost. You have to dump the data beforehand manually by calling writeToFile().

Member Function Documentation

◆ addNewDatasetToIndexFile()

void tarch.plotter::griddata::blockstructured::PeanoBinaryPatchFileWriter::addNewDatasetToIndexFile ( double timestamp )

protected

◆ addNewFileToCurrentDataSetInIndexFile()

void tarch.plotter::griddata::blockstructured::PeanoBinaryPatchFileWriter::addNewFileToCurrentDataSetInIndexFile ( const std::string & filename )

protected

◆ clear()

virtual void tarch.plotter::griddata::blockstructured::PeanoBinaryPatchFileWriter::clear ( )

overridevirtual

Clear local data.

Clear the writer, i.e. erase all the data. However, as the writer does not track how many vertex and cell writers you've created, it's up to you to ensure that none of these instances is left. So we clear the core data, but we do not clear the data within any data writer which you have created by calling routines such as createCellDataWriter().

Implements tarch.plotter::griddata::blockstructured::PatchWriter.

Referenced by peano4.api.output.Makefile.Makefile::__init__().

Here is the caller graph for this function:

◆ createBackupOfMetaFile()

void tarch.plotter::griddata::blockstructured::PeanoBinaryPatchFileWriter::createBackupOfMetaFile ( )

protected

◆ createCellDataWriter() [1/3]

virtual CellDataWriter * tarch.plotter::griddata::blockstructured::PeanoBinaryPatchFileWriter::createCellDataWriter	(	const std::string &	identifier,
		int	unknownsPerAxis,
		int	recordsPerCell,
		const std::string &	description
	)

overridevirtual

Caller has to destroy this instance manually.

Implements tarch.plotter::griddata::blockstructured::PatchWriter.

◆ createCellDataWriter() [2/3]

virtual CellDataWriter * tarch.plotter::griddata::blockstructured::PeanoBinaryPatchFileWriter::createCellDataWriter	(	const std::string &	identifier,
		int	unknownsPerAxis,
		int	recordsPerCell,
		const std::string &	description,
		const std::string &	metaData
	)

overridevirtual

Create cell data writer.

Wrapper around createCellDataWriter(std::string, int, int, std::string, std::string, double*) with default values. Please consult description of the more elaborate routine for details.

Implements tarch.plotter::griddata::blockstructured::PatchWriter.

◆ createCellDataWriter() [3/3]

virtual CellDataWriter * tarch.plotter::griddata::blockstructured::PeanoBinaryPatchFileWriter::createCellDataWriter	(	const std::string &	identifier,
		int	unknownsPerAxis,
		int	recordsPerCell,
		const std::string &	description,
		const std::string &	metaData,
		double *	mapping
	)

overridevirtual

Create writer.

Caller has to destroy this instance manually.

Parameters

identifier	Name of your data. I recommend to stick to C++ identifier rules for this one, i.e. no fancy chars and no spaces
unknownsPerAxis	We plot a (logically) Cartesian piece of data. This is the number of unknowns per axis
recordsPerVertex	Number of entries stores per unknown. Data is, by default, written as AoS
description	This is a description of the data. Should be a one-liner.
metaData	Further meta data without prescribed semantics. Can be a longer text block.
mapping	Array of positions within a unit cube/square. It is an AoS of vectors within the unit square which distorts all the plotting points within the logical Cartesian mesh imposed over the unit cube. By default, all data are Cartesian and spaced out equidistantly, i.e. if you have 4x4 data points per cell, then you get a chess board pattern of 16 smaller cubes over the cell in 2d. However, you might prefer something like Gauss Lobatto nodes, and then the data are not spaced out uniformly anymore.

Implements tarch.plotter::griddata::blockstructured::PatchWriter.

◆ createEmptyIndexFile()

void tarch.plotter::griddata::blockstructured::PeanoBinaryPatchFileWriter::createEmptyIndexFile ( )

protected

◆ createVertexDataWriter() [1/3]

virtual VertexDataWriter * tarch.plotter::griddata::blockstructured::PeanoBinaryPatchFileWriter::createVertexDataWriter	(	const std::string &	identifier,
		int	unknownsPerAxis,
		int	recordsPerVertex,
		const std::string &	description
	)

overridevirtual

Caller has to destroy this instance manually.

Implements tarch.plotter::griddata::blockstructured::PatchWriter.

◆ createVertexDataWriter() [2/3]

virtual VertexDataWriter * tarch.plotter::griddata::blockstructured::PeanoBinaryPatchFileWriter::createVertexDataWriter	(	const std::string &	identifier,
		int	unknownsPerAxis,
		int	recordsPerVertex,
		const std::string &	description,
		const std::string &	metaData
	)

overridevirtual

Create vertex data writer.

Wrapper around createVertexDataWriter(std::string, int, int, std::string, std::string, double*) with default values. Please consult description of the more elaborate routine for details.

Implements tarch.plotter::griddata::blockstructured::PatchWriter.

◆ createVertexDataWriter() [3/3]

virtual VertexDataWriter * tarch.plotter::griddata::blockstructured::PeanoBinaryPatchFileWriter::createVertexDataWriter	(	const std::string &	identifier,
		int	unknownsPerAxis,
		int	recordsPerVertex,
		const std::string &	description,
		const std::string &	metaData,
		double *	mapping
	)

overridevirtual

Create writer.

Caller has to destroy this instance manually.

Parameters

identifier	Name of your data. I recommend to stick to C++ identifier rules for this one, i.e. no fancy chars and no spaces
unknownsPerAxis	We plot a (logically) Cartesian piece of data. This is the number of unknowns per axis
recordsPerVertex	Number of entries stores per unknown. Data is, by default, written as AoS
description	This is a description of the data. Should be a one-liner.
metaData	Further meta data without prescribed semantics. Can be a longer text block.
mapping	Array of positions within a unit cube/square. It is an AoS of vectors within the unit square which distorts all the plotting points within the logical Cartesian mesh imposed over the unit cube. By default, all data are Cartesian and spaced out equidistantly, i.e. if you have 4x4 data points per cell, then you get a chess board pattern of 16 smaller cubes over the cell in 2d. However, you might prefer something like Gauss Lobatto nodes, and then the data are not spaced out uniformly anymore.

Implements tarch.plotter::griddata::blockstructured::PatchWriter.

◆ getLatestTimeStepInIndexFile()

double tarch.plotter::griddata::blockstructured::PeanoBinaryPatchFileWriter::getLatestTimeStepInIndexFile ( ) const

protected

Find latest time step in index file.

This routine runs through the index file and searches for the latest entry in there which looks similar to

timestamp 0.000000000000000000000000e+00

It will then return the value of this time stamp.

◆ isOpen()

virtual bool tarch.plotter::griddata::blockstructured::PeanoBinaryPatchFileWriter::isOpen ( )

overridevirtual

Returns: Whether writer is ready to accept data.

Implements tarch.plotter::griddata::blockstructured::PatchWriter.

◆ plotPatch() [1/2]

virtual int tarch.plotter::griddata::blockstructured::PeanoBinaryPatchFileWriter::plotPatch	(	const tarch::la::Vector< 2, double > &	offset,
		const tarch::la::Vector< 2, double > &	size
	)

overridevirtual

Returns: Patch index, i.e. unique number of this patch

Implements tarch.plotter::griddata::blockstructured::PatchWriter.

◆ plotPatch() [2/2]

virtual int tarch.plotter::griddata::blockstructured::PeanoBinaryPatchFileWriter::plotPatch	(	const tarch::la::Vector< 3, double > &	offset,
		const tarch::la::Vector< 3, double > &	size
	)

overridevirtual

Returns: Patch index, i.e. unique number of this patch

Implements tarch.plotter::griddata::blockstructured::PatchWriter.

◆ writeMapping()

void tarch.plotter::griddata::blockstructured::PeanoBinaryPatchFileWriter::writeMapping	(	int	totalEntries,
		double *	values
	)

protected

◆ writeMetaData()

void tarch.plotter::griddata::blockstructured::PeanoBinaryPatchFileWriter::writeMetaData ( const std::string & metaData )

protected

◆ writeToFile()

virtual bool tarch.plotter::griddata::blockstructured::PeanoBinaryPatchFileWriter::writeToFile ( )

overridevirtual

Returns: Write has been successful

Implements tarch.plotter::griddata::blockstructured::PatchWriter.

Field Documentation

◆ _dimensions

int tarch.plotter::griddata::blockstructured::PeanoBinaryPatchFileWriter::_dimensions

protected

Definition at line 104 of file PeanoBinaryPatchFileWriter.h.

Referenced by exaparty.api.Project.Project::__configure_makefile(), api.Project.Project::__configure_makefile(), exaparty.api.Project.Project::__export_constants(), api.Project.Project::__export_constants(), exahype2.api.Project.Project::__export_constants(), api.Project.Project::__init__(), solvers.api.ContinuousGalerkinDiscretisationGaussLobattoWithBlockJacobi.ContinuousGalerkinDiscretisationGaussLobattoWithBlockJacobi::_construct_narrow_to_interior_matrix(), scenarios.elastic_planar_waves.ElasticPlanarWaves::analytical_solution(), tarch.plotter.api.output.Visualiser.PatchFileData::apply_renderer_to_data(), exahype2.api.dslhype.SyntaxTree.Matrix::index(), scenarios.elastic_planar_waves.ElasticPlanarWaves::initial_conditions(), exahype2.api.dslhype.SyntaxTree.TSimpleMemref::print_mlir(), exahype2.api.dslhype.SyntaxTree.TDataBlock::print_mlir(), exaparty.api.Project.Project::set_global_simulation_parameters(), api.Project.Project::set_global_simulation_parameters(), api.Project.Project::set_global_simulation_parameters(), exahype2.api.Project.Project::set_global_simulation_parameters(), and scenarios.scenario.Scenario::set_global_simulation_parameters().

◆ _fileName

std::string tarch.plotter::griddata::blockstructured::PeanoBinaryPatchFileWriter::_fileName

protected

Definition at line 99 of file PeanoBinaryPatchFileWriter.h.

◆ _haveWrittenAtLeastOnePatch

bool tarch.plotter::griddata::blockstructured::PeanoBinaryPatchFileWriter::_haveWrittenAtLeastOnePatch

protected

Definition at line 109 of file PeanoBinaryPatchFileWriter.h.

◆ _indexFile

std::string tarch.plotter::griddata::blockstructured::PeanoBinaryPatchFileWriter::_indexFile

protected

Definition at line 100 of file PeanoBinaryPatchFileWriter.h.

◆ _log

tarch::logging::Log tarch.plotter::griddata::blockstructured::PeanoBinaryPatchFileWriter::_log

staticprotected

Definition at line 96 of file PeanoBinaryPatchFileWriter.h.

◆ _patchCounter

int tarch.plotter::griddata::blockstructured::PeanoBinaryPatchFileWriter::_patchCounter

protected

Definition at line 106 of file PeanoBinaryPatchFileWriter.h.

◆ _snapshotFileOut

std::stringstream tarch.plotter::griddata::blockstructured::PeanoBinaryPatchFileWriter::_snapshotFileOut

protected

Definition at line 108 of file PeanoBinaryPatchFileWriter.h.

◆ _writtenToFile

bool tarch.plotter::griddata::blockstructured::PeanoBinaryPatchFileWriter::_writtenToFile

protected

Definition at line 102 of file PeanoBinaryPatchFileWriter.h.

◆ HEADER

const std::string tarch.plotter::griddata::blockstructured::PeanoBinaryPatchFileWriter::HEADER

staticprotected

Definition at line 97 of file PeanoBinaryPatchFileWriter.h.

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

src/tarch/plotter/griddata/blockstructured/PeanoBinaryPatchFileWriter.h

Data Structures

Public Types

Public Member Functions

Protected Member Functions

Protected Attributes

Static Protected Attributes

Detailed Description

Meta file construction modes

Member Enumeration Documentation

◆ IndexFileMode

Constructor & Destructor Documentation

◆ PeanoBinaryPatchFileWriter()

AppendNewData and the order of operations

◆ ~PeanoBinaryPatchFileWriter()

Member Function Documentation

◆ addNewDatasetToIndexFile()

◆ addNewFileToCurrentDataSetInIndexFile()

◆ clear()

◆ createBackupOfMetaFile()

◆ createCellDataWriter() [1/3]

◆ createCellDataWriter() [2/3]

◆ createCellDataWriter() [3/3]

◆ createEmptyIndexFile()

◆ createVertexDataWriter() [1/3]

◆ createVertexDataWriter() [2/3]

◆ createVertexDataWriter() [3/3]

◆ getLatestTimeStepInIndexFile()

◆ isOpen()

◆ plotPatch() [1/2]

◆ plotPatch() [2/2]

◆ writeMapping()

◆ writeMetaData()

◆ writeToFile()

Field Documentation

◆ _dimensions

◆ _fileName

◆ _haveWrittenAtLeastOnePatch

◆ _indexFile

◆ _log

◆ _patchCounter

◆ _snapshotFileOut

◆ _writtenToFile

◆ HEADER