openPMD-api
Iteration.hpp
1 /* Copyright 2017-2021 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/Option.hpp"
24 #include "openPMD/auxiliary/Variant.hpp"
25 #include "openPMD/backend/Attributable.hpp"
26 #include "openPMD/backend/Container.hpp"
27 #include "openPMD/IterationEncoding.hpp"
28 #include "openPMD/Mesh.hpp"
29 #include "openPMD/ParticleSpecies.hpp"
30 #include "openPMD/Streaming.hpp"
31 
32 
33 namespace openPMD
34 {
40 {
41  template<
42  typename T,
43  typename T_key,
44  typename T_container
45  >
46  friend class Container;
47  friend class SeriesInterface;
48  friend class WriteIterations;
49  friend class SeriesIterator;
50 
51 public:
52  Iteration( Iteration const & ) = default;
53  Iteration & operator=( Iteration const & ) = default;
54 
59  template< typename T >
60  T time() const;
67  template< typename T >
68  Iteration& setTime(T newTime);
69 
74  template< typename T >
75  T dt() const;
82  template< typename T >
83  Iteration& setDt(T newDt);
84 
88  double timeUnitSI() const;
94  Iteration& setTimeUnitSI(double newTimeUnitSI);
95 
105  /*
106  * Note: If the API is changed in future to allow reopening closed
107  * iterations, measures should be taken to prevent this in the streaming
108  * API. Currently, disallowing to reopen closed iterations satisfies
109  * the requirements of the streaming API.
110  */
111  Iteration &
112  close( bool flush = true );
113 
127  Iteration &
128  open();
129 
136  bool
137  closed() const;
138 
150  bool
151  closedByWriter() const;
152 
153  Container< Mesh > meshes;
154  Container< ParticleSpecies > particles; //particleSpecies?
155 
156  virtual ~Iteration() = default;
157 private:
158  Iteration();
159 
160  struct DeferredParseAccess
161  {
167  std::string path;
171  uint64_t iteration = 0;
176  bool fileBased = false;
181  std::string filename;
182  };
183 
184  void flushFileBased(std::string const&, uint64_t);
185  void flushGroupBased(uint64_t);
186  void flushVariableBased(uint64_t);
187  void flush();
188  void deferParseAccess( DeferredParseAccess );
189  /*
190  * Control flow for read(), readFileBased(), readGroupBased() and
191  * read_impl():
192  * read() is called as the entry point. File-based and group-based
193  * iteration layouts need to be parsed slightly differently:
194  * In file-based iteration layout, each iteration's file also contains
195  * attributes for the /data group. In group-based layout, those have
196  * already been parsed during opening of the Series.
197  * Hence, read() will call either readFileBased() or readGroupBased() to
198  * allow for those different control flows.
199  * Finally, read_impl() is called which contains the common parsing
200  * logic for an iteration.
201  *
202  * reread() reads again an Iteration that has been previously read.
203  * Calling it on an Iteration not yet parsed is an error.
204  *
205  */
206  void read();
207  void reread( std::string const & path );
208  void readFileBased( std::string filePath, std::string const & groupPath );
209  void readGorVBased( std::string const & groupPath );
210  void read_impl( std::string const & groupPath );
211 
216  enum class CloseStatus
217  {
218  ParseAccessDeferred,
219  Open,
220  ClosedInFrontend,
222  ClosedInBackend,
224  ClosedTemporarily
226  };
227 
228  /*
229  * An iteration may be logically closed in the frontend,
230  * but not necessarily yet in the backend.
231  * Will be propagated to the backend upon next flush.
232  * Store the current status.
233  * Once an iteration has been closed, no further flushes shall be performed.
234  * If flushing a closed file, the old file may otherwise be overwritten.
235  */
236  std::shared_ptr< CloseStatus > m_closed =
237  std::make_shared< CloseStatus >( CloseStatus::Open );
238 
246  std::shared_ptr< StepStatus > m_stepStatus =
247  std::make_shared< StepStatus >( StepStatus::NoStep );
248 
249  std::shared_ptr< auxiliary::Option< DeferredParseAccess > >
250  m_deferredParseAccess =
251  std::make_shared< auxiliary::Option< DeferredParseAccess > >(
253 
262  beginStep();
263 
271  void
272  endStep();
273 
282  StepStatus
283  getStepStatus();
284 
293  void setStepStatus( StepStatus );
294 
295  /*
296  * @brief Check recursively whether this Iteration is dirty.
297  * It is dirty if any attribute or dataset is read from or written to
298  * the backend.
299  *
300  * @return true If dirty.
301  * @return false Otherwise.
302  */
303  bool
304  dirtyRecursive() const;
305 
311  virtual void linkHierarchy(Writable& w);
312 
318  void runDeferredParseAccess();
319 }; // Iteration
320 
321 extern template
322 float
323 Iteration::time< float >() const;
324 
325 extern template
326 double
327 Iteration::time< double >() const;
328 
329 extern template
330 long double
331 Iteration::time< long double >() const;
332 
333 template< typename T >
334 inline T
336 { return this->readFloatingpoint< T >("time"); }
337 
338 
339 extern template
340 float
341 Iteration::dt< float >() const;
342 
343 extern template
344 double
345 Iteration::dt< double >() const;
346 
347 extern template
348 long double
349 Iteration::dt< long double >() const;
350 
351 template< typename T >
352 inline T
354 { return this->readFloatingpoint< T >("dt"); }
355 } // openPMD
openPMD::Writable
Layer to mirror structure of logical data and persistent data in file.
Definition: Writable.hpp:64
openPMD::Iteration::setTime
Iteration & setTime(T newTime)
Set the global reference time for this iteration.
Definition: Iteration.cpp:49
openPMD::Iteration::close
Iteration & close(bool flush=true)
Close an iteration.
Definition: Iteration.cpp:83
openPMD::LegacyAttributable
Definition: Attributable.hpp:401
openPMD::UnitDimension::T
@ T
time
openPMD::WriteIterations
Writing side of the streaming API.
Definition: WriteIterations.hpp:47
openPMD::AdvanceStatus
AdvanceStatus
In step-based mode (i.e.
Definition: Streaming.hpp:20
openPMD::Iteration::timeUnitSI
double timeUnitSI() const
Definition: Iteration.cpp:68
openPMD::auxiliary::Option< DeferredParseAccess >
openPMD::SeriesInterface
Implementation for the root level of the openPMD hierarchy.
Definition: Series.hpp:112
openPMD::Iteration
Logical compilation of data from one snapshot (e.g.
Definition: Iteration.hpp:39
openPMD::Iteration::closedByWriter
bool closedByWriter() const
Has the iteration been closed by the writer? Background: Upon calling Iteration::close(),...
Definition: Iteration.cpp:186
openPMD
Public definitions of openPMD-api.
Definition: Date.cpp:29
openPMD::StepStatus
StepStatus
Used in step-based mode (i.e.
Definition: Streaming.hpp:44
openPMD::Iteration::time
T time() const
Definition: Iteration.hpp:335
openPMD::Iteration::open
Iteration & open()
Open an iteration.
Definition: Iteration.cpp:149
openPMD::Container
Map-like container that enforces openPMD requirements and handles IO.
Definition: Container.hpp:106
openPMD::SeriesIterator
Definition: ReadIterations.hpp:50
openPMD::Iteration::setTimeUnitSI
Iteration & setTimeUnitSI(double newTimeUnitSI)
Set the conversion factor to convert time and dt to seconds.
Definition: Iteration.cpp:74
openPMD::Iteration::setDt
Iteration & setDt(T newDt)
Set the time step used to reach this iteration.
Definition: Iteration.cpp:59
openPMD::Iteration::dt
T dt() const
Definition: Iteration.hpp:353
openPMD::Iteration::closed
bool closed() const
Has the iteration been closed? A closed iteration may not (yet) be reopened.
Definition: Iteration.cpp:165