openPMD-api
Iteration.hpp
1 /* Copyright 2017-2020 Fabian Koller
2  *
3  * This file is part of openPMD-api.
4  *
5  * openPMD-api is free software: you can redistribute it and/or modify
6  * it under the terms of of either the GNU General Public License or
7  * the GNU Lesser General Public License as published by
8  * the Free Software Foundation, either version 3 of the License, or
9  * (at your option) any later version.
10  *
11  * openPMD-api is distributed in the hope that it will be useful,
12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14  * GNU General Public License and the GNU Lesser General Public License
15  * for more details.
16  *
17  * You should have received a copy of the GNU General Public License
18  * and the GNU Lesser General Public License along with openPMD-api.
19  * If not, see <http://www.gnu.org/licenses/>.
20  */
21 #pragma once
22 
23 #include "openPMD/auxiliary/Variant.hpp"
24 #include "openPMD/backend/Attributable.hpp"
25 #include "openPMD/backend/Container.hpp"
26 #include "openPMD/IterationEncoding.hpp"
27 #include "openPMD/Mesh.hpp"
28 #include "openPMD/ParticleSpecies.hpp"
29 #include "openPMD/Streaming.hpp"
30 
31 
32 namespace openPMD
33 {
38 class Iteration : public Attributable
39 {
40  template<
41  typename T,
42  typename T_key,
43  typename T_container
44  >
45  friend class Container;
46  friend class Series;
47  friend class WriteIterations;
48  friend class SeriesIterator;
49 
50 public:
51  Iteration(Iteration const&);
52  Iteration& operator=(Iteration const&);
53 
58  template< typename T >
59  T time() const;
66  template< typename T >
67  Iteration& setTime(T newTime);
68 
73  template< typename T >
74  T dt() const;
81  template< typename T >
82  Iteration& setDt(T newDt);
83 
87  double timeUnitSI() const;
93  Iteration& setTimeUnitSI(double newTimeUnitSI);
94 
104  /*
105  * Note: If the API is changed in future to allow reopening closed
106  * iterations, measures should be taken to prevent this in the streaming
107  * API. Currently, disallowing to reopen closed iterations satisfies
108  * the requirements of the streaming API.
109  */
110  Iteration &
111  close( bool flush = true );
112 
123  Iteration &
124  open();
125 
132  bool
133  closed() const;
134 
146  bool
147  closedByWriter() const;
148 
149  Container< Mesh > meshes;
150  Container< ParticleSpecies > particles; //particleSpecies?
151 
152  virtual ~Iteration() = default;
153 private:
154  Iteration();
155 
156  void flushFileBased(std::string const&, uint64_t);
157  void flushGroupBased(uint64_t);
158  void flush();
159  void read();
160 
165  enum class CloseStatus
166  {
167  Open,
168  ClosedInFrontend,
170  ClosedInBackend,
172  ClosedTemporarily
174  };
175 
176  /*
177  * An iteration may be logically closed in the frontend,
178  * but not necessarily yet in the backend.
179  * Will be propagated to the backend upon next flush.
180  * Store the current status.
181  * Once an iteration has been closed, no further flushes shall be performed.
182  * If flushing a closed file, the old file may otherwise be overwritten.
183  */
184  std::shared_ptr< CloseStatus > m_closed =
185  std::make_shared< CloseStatus >( CloseStatus::Open );
186 
194  std::shared_ptr< StepStatus > m_stepStatus =
195  std::make_shared< StepStatus >( StepStatus::NoStep );
196 
205  beginStep();
206 
214  void
215  endStep();
216 
225  StepStatus
226  getStepStatus();
227 
236  void setStepStatus( StepStatus );
237 
238  /*
239  * @brief Check recursively whether this Iteration is dirty.
240  * It is dirty if any attribute or dataset is read from or written to
241  * the backend.
242  *
243  * @return true If dirty.
244  * @return false Otherwise.
245  */
246  bool
247  dirtyRecursive() const;
248 
249  virtual void linkHierarchy(std::shared_ptr< Writable > const& w);
250 }; // Iteration
251 
252 extern template
253 float
254 Iteration::time< float >() const;
255 
256 extern template
257 double
258 Iteration::time< double >() const;
259 
260 extern template
261 long double
262 Iteration::time< long double >() const;
263 
264 template< typename T >
265 inline T
267 { return Attributable::readFloatingpoint< T >("time"); }
268 
269 
270 extern template
271 float
272 Iteration::dt< float >() const;
273 
274 extern template
275 double
276 Iteration::dt< double >() const;
277 
278 extern template
279 long double
280 Iteration::dt< long double >() const;
281 
282 template< typename T >
283 inline T
285 { return Attributable::readFloatingpoint< T >("dt"); }
286 } // openPMD
T time() const
Definition: Iteration.hpp:266
Iteration & setDt(T newDt)
Set the time step used to reach this iteration.
Definition: Iteration.cpp:89
double timeUnitSI() const
Definition: Iteration.cpp:98
Logical compilation of data from one snapshot (e.g.
Definition: Iteration.hpp:38
Iteration & open()
Open an iteration.
Definition: Iteration.cpp:179
StepStatus
Used in step-based mode (i.e.
Definition: Streaming.hpp:44
T dt() const
Definition: Iteration.hpp:284
Iteration & close(bool flush=true)
Close an iteration.
Definition: Iteration.cpp:113
AdvanceStatus
In step-based mode (i.e.
Definition: Streaming.hpp:20
Writing side of the streaming API.
Definition: Series.hpp:484
bool closed() const
Has the iteration been closed? A closed iteration may not (yet) be reopened.
Definition: Iteration.cpp:196
Root level of the openPMD hierarchy.
Definition: Series.hpp:64
Public definitions of openPMD-api.
Definition: Date.cpp:29
Definition: Series.hpp:402
Iteration & setTime(T newTime)
Set the global reference time for this iteration.
Definition: Iteration.cpp:79
bool closedByWriter() const
Has the iteration been closed by the writer? Background: Upon calling Iteration::close(), the openPMD API will add metadata to the iteration in form of an attribute, indicating that the iteration has indeed been closed.
Definition: Iteration.cpp:202
Map-like container that enforces openPMD requirements and handles IO.
Definition: Container.hpp:70
Iteration & setTimeUnitSI(double newTimeUnitSI)
Set the conversion factor to convert time and dt to seconds.
Definition: Iteration.cpp:104
Layer to manage storage of attributes associated with file objects.
Definition: Attributable.hpp:65