weipa/src/EscriptDataset.h


/*******************************************************
*
* Copyright (c) 2003-2010 by University of Queensland
* Earth Systems Science Computational Center (ESSCC)
* http://www.uq.edu.au/esscc
*
* Primary Business: Queensland, Australia
* Licensed under the Open Software License version 3.0
* http://www.opensource.org/licenses/osl-3.0.php
*
*******************************************************/

#ifndef __WEIPA_ESCRIPTDATASET_H__
#define __WEIPA_ESCRIPTDATASET_H__

#include <weipa/weipa.h>

#include <ostream>

class DBfile;

namespace escript {
    class AbstractDomain;
    class Data;
}


namespace weipa {

typedef std::vector<DataVar_ptr>     DataChunks;
typedef std::vector<DomainChunk_ptr> DomainChunks;

struct VarInfo {
    std::string varName;
    std::string units;
    DataChunks dataChunks;
    IntVec sampleDistribution;
    bool valid;
};

typedef std::vector<VarInfo> VarVector;


/// \brief Represents an escript dataset including a domain and data variables
///        for one timestep.
//
/// This class represents an escript dataset complete with domain and
/// variable data. It can read the dataset from files generated by the
/// dump() methods within escript or through an escript domain instance plus
/// a number of escript::Data instances. Subsequently, the dataset can be
/// saved in the Silo or VTK file format or accessed through a number of
/// accessor methods.
///
/// If the data is distributed via MPI then all ranks should create an instance
/// of this class and call the respective methods. Dump files that stem from
/// a parallel run can be read on one processor or on the same number of MPI
/// processes as they were created with.
class WEIPA_DLL_API EscriptDataset
{
public:
    /// \brief Default constructor.
    EscriptDataset();

#if HAVE_MPI
    /// \brief Constructor with communicator.
    EscriptDataset(MPI_Comm comm);
#endif

    /// \brief Destructor.
    ~EscriptDataset();

    /// \brief Sets the escript domain for this dataset. This method can only
    ///        be called once and should be the first call unless loading from
    ///        dump files.
    ///
    /// \note If MPI is enabled this method also initialises the communicator
    ///       that will be used subsequently.
    bool setDomain(const escript::AbstractDomain* domain);

    /// \brief Adds an escript data instance to this dataset. You must ensure
    ///        that the data is defined on the domain that was used in
    //         setDomain(), otherwise you will get undefined behaviour later!
    bool addData(escript::Data& data, const std::string name,
                 const std::string units = "");

    /// \brief Loads domain and variables from escript NetCDF files.
    ///
    /// \param domainFilePattern a printf-style pattern for the domain file
    ///                          names (e.g. "dom.%02d.nc")
    /// \param varFiles a vector of file name patterns for variables
    /// \param varNames a vector of variable names
    /// \param nChunks number of chunks to load
    ///
    /// \note If MPI is enabled nChunks must be equal to the size of the
    ///       communicator or this method fails.
    bool loadNetCDF(const std::string domainFilePattern,
                    const StringVec& varFiles, const StringVec& varNames,
                    int nChunks);

    /// \brief Loads only variables from escript NetCDF files using the domain
    ///        provided.
    bool loadNetCDF(const DomainChunks& domain, const StringVec& varFiles,
                    const StringVec& varNames);

    /// \brief Sets the cycle number and time value for this dataset.
    void setCycleAndTime(int c, double t) { cycle=c; time=t; }

    /// \brief Returns the cycle number.
    int getCycle() const { return cycle; }

    /// \brief Returns the time value.
    double getTime() const { return time; }

    /// \brief Sets labels for the mesh axes.
    /// \note This information is only used by the Silo writer.
    void setMeshLabels(const std::string x, const std::string y, const std::string z="");

    /// \brief Sets units for the mesh axes.
    /// \note This information is only used by the Silo writer.
    void setMeshUnits(const std::string x, const std::string y, const std::string z="");

    /// \brief Sets a metadata schema and content
    /// \note Only used by the VTK writer.
    void setMetadataSchemaString(const std::string schema,
                                 const std::string metadata)
        { mdSchema=schema; mdString=metadata; }

    /// \brief Saves the dataset in the Silo file format.
    bool saveSilo(const std::string fileName, bool useMultiMesh=true);

    /// \brief Saves the dataset in the VTK XML file format.
    bool saveVTK(const std::string fileName);

    /// \brief Returns the dataset's converted domain so it can be reused.
    DomainChunks getConvertedDomain() { return domainChunks; }

    /// \brief Returns a vector with the dataset's variables.
    const VarVector& getVariables() const { return variables; }

    /// \brief Returns a vector with the mesh variables.
    const VarVector& getMeshVariables() const { return meshVariables; }

#if HAVE_MPI
    MPI_Comm
#else
    void*
#endif
        getMPIComm() { return mpiComm; }

private:
    bool loadDomain(const std::string filePattern, int nChunks);
    bool setExternalDomain(const DomainChunks& domain);
    bool loadData(const std::string filePattern, const std::string name,
                  const std::string units);

    void convertMeshVariables();
    void updateSampleDistribution(VarInfo& vi);
    void putSiloMultiMesh(DBfile* dbfile, const std::string& meshName);
    void putSiloMultiTensor(DBfile* dbfile, const VarInfo& vi);
    void putSiloMultiVar(DBfile* dbfile, const VarInfo& vi,
                         bool useMeshFile = false);
    bool saveVTKsingle(const std::string& fileName,
                       const std::string& meshName, const VarVector& vars);
    void writeVarToVTK(const VarInfo& varInfo, std::ostream& os);

    int cycle;
    double time;
    std::string mdSchema, mdString;
    StringVec meshLabels, meshUnits;
    bool externalDomain;
    DomainChunks domainChunks;
    VarVector variables, meshVariables;
    int mpiRank, mpiSize;
#if HAVE_MPI
    MPI_Comm mpiComm;
#else
    void* mpiComm;
#endif
};

} // namespace weipa

#endif // __WEIPA_ESCRIPTDATASET_H__

1
2	/*******************************************************
3	*
4	* Copyright (c) 2003-2010 by University of Queensland
5	* Earth Systems Science Computational Center (ESSCC)
6	* http://www.uq.edu.au/esscc
7	*
8	* Primary Business: Queensland, Australia
9	* Licensed under the Open Software License version 3.0
10	* http://www.opensource.org/licenses/osl-3.0.php
11	*
12	*******************************************************/
13
14	#ifndef __WEIPA_ESCRIPTDATASET_H__
15	#define __WEIPA_ESCRIPTDATASET_H__
16
17	#include <weipa/weipa.h>
18
19	#include <ostream>
20
21	class DBfile;
22
23	namespace escript {
24	class AbstractDomain;
25	class Data;
26	}
27
28
29	namespace weipa {
30
31	typedef std::vector<DataVar_ptr> DataChunks;
32	typedef std::vector<DomainChunk_ptr> DomainChunks;
33
34	struct VarInfo {
35	std::string varName;
36	std::string units;
37	DataChunks dataChunks;
38	IntVec sampleDistribution;
39	bool valid;
40	};
41
42	typedef std::vector<VarInfo> VarVector;
43
44
45	/// \brief Represents an escript dataset including a domain and data variables
46	/// for one timestep.
47	//
48	/// This class represents an escript dataset complete with domain and
49	/// variable data. It can read the dataset from files generated by the
50	/// dump() methods within escript or through an escript domain instance plus
51	/// a number of escript::Data instances. Subsequently, the dataset can be
52	/// saved in the Silo or VTK file format or accessed through a number of
53	/// accessor methods.
54	///
55	/// If the data is distributed via MPI then all ranks should create an instance
56	/// of this class and call the respective methods. Dump files that stem from
57	/// a parallel run can be read on one processor or on the same number of MPI
58	/// processes as they were created with.
59	class WEIPA_DLL_API EscriptDataset
60	{
61	public:
62	/// \brief Default constructor.
63	EscriptDataset();
64
65	#if HAVE_MPI
66	/// \brief Constructor with communicator.
67	EscriptDataset(MPI_Comm comm);
68	#endif
69
70	/// \brief Destructor.
71	~EscriptDataset();
72
73	/// \brief Sets the escript domain for this dataset. This method can only
74	/// be called once and should be the first call unless loading from
75	/// dump files.
76	///
77	/// \note If MPI is enabled this method also initialises the communicator
78	/// that will be used subsequently.
79	bool setDomain(const escript::AbstractDomain* domain);
80
81	/// \brief Adds an escript data instance to this dataset. You must ensure
82	/// that the data is defined on the domain that was used in
83	// setDomain(), otherwise you will get undefined behaviour later!
84	bool addData(escript::Data& data, const std::string name,
85	const std::string units = "");
86
87	/// \brief Loads domain and variables from escript NetCDF files.
88	///
89	/// \param domainFilePattern a printf-style pattern for the domain file
90	/// names (e.g. "dom.%02d.nc")
91	/// \param varFiles a vector of file name patterns for variables
92	/// \param varNames a vector of variable names
93	/// \param nChunks number of chunks to load
94	///
95	/// \note If MPI is enabled nChunks must be equal to the size of the
96	/// communicator or this method fails.
97	bool loadNetCDF(const std::string domainFilePattern,
98	const StringVec& varFiles, const StringVec& varNames,
99	int nChunks);
100
101	/// \brief Loads only variables from escript NetCDF files using the domain
102	/// provided.
103	bool loadNetCDF(const DomainChunks& domain, const StringVec& varFiles,
104	const StringVec& varNames);
105
106	/// \brief Sets the cycle number and time value for this dataset.
107	void setCycleAndTime(int c, double t) { cycle=c; time=t; }
108
109	/// \brief Returns the cycle number.
110	int getCycle() const { return cycle; }
111
112	/// \brief Returns the time value.
113	double getTime() const { return time; }
114
115	/// \brief Sets labels for the mesh axes.
116	/// \note This information is only used by the Silo writer.
117	void setMeshLabels(const std::string x, const std::string y, const std::string z="");
118
119	/// \brief Sets units for the mesh axes.
120	/// \note This information is only used by the Silo writer.
121	void setMeshUnits(const std::string x, const std::string y, const std::string z="");
122
123	/// \brief Sets a metadata schema and content
124	/// \note Only used by the VTK writer.
125	void setMetadataSchemaString(const std::string schema,
126	const std::string metadata)
127	{ mdSchema=schema; mdString=metadata; }
128
129	/// \brief Saves the dataset in the Silo file format.
130	bool saveSilo(const std::string fileName, bool useMultiMesh=true);
131
132	/// \brief Saves the dataset in the VTK XML file format.
133	bool saveVTK(const std::string fileName);
134
135	/// \brief Returns the dataset's converted domain so it can be reused.
136	DomainChunks getConvertedDomain() { return domainChunks; }
137
138	/// \brief Returns a vector with the dataset's variables.
139	const VarVector& getVariables() const { return variables; }
140
141	/// \brief Returns a vector with the mesh variables.
142	const VarVector& getMeshVariables() const { return meshVariables; }
143
144	#if HAVE_MPI
145	MPI_Comm
146	#else
147	void*
148	#endif
149	getMPIComm() { return mpiComm; }
150
151	private:
152	bool loadDomain(const std::string filePattern, int nChunks);
153	bool setExternalDomain(const DomainChunks& domain);
154	bool loadData(const std::string filePattern, const std::string name,
155	const std::string units);
156
157	void convertMeshVariables();
158	void updateSampleDistribution(VarInfo& vi);
159	void putSiloMultiMesh(DBfile* dbfile, const std::string& meshName);
160	void putSiloMultiTensor(DBfile* dbfile, const VarInfo& vi);
161	void putSiloMultiVar(DBfile* dbfile, const VarInfo& vi,
162	bool useMeshFile = false);
163	bool saveVTKsingle(const std::string& fileName,
164	const std::string& meshName, const VarVector& vars);
165	void writeVarToVTK(const VarInfo& varInfo, std::ostream& os);
166
167	int cycle;
168	double time;
169	std::string mdSchema, mdString;
170	StringVec meshLabels, meshUnits;
171	bool externalDomain;
172	DomainChunks domainChunks;
173	VarVector variables, meshVariables;
174	int mpiRank, mpiSize;
175	#if HAVE_MPI
176	MPI_Comm mpiComm;
177	#else
178	void* mpiComm;
179	#endif
180	};
181
182	} // namespace weipa
183
184	#endif // __WEIPA_ESCRIPTDATASET_H__
185