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/backend/Attributable.hpp"
24 #include "openPMD/backend/Container.hpp"
25 #include "openPMD/Mesh.hpp"
26 #include "openPMD/ParticleSpecies.hpp"
27 
28 
29 namespace openPMD
30 {
35 class Iteration : public Attributable
36 {
37  template<
38  typename T,
39  typename T_key,
40  typename T_container
41  >
42  friend class Container;
43  friend class Series;
44 
45 public:
46  Iteration(Iteration const&);
47  Iteration& operator=(Iteration const&);
48 
53  template< typename T >
54  T time() const;
61  template< typename T >
62  Iteration& setTime(T newTime);
63 
68  template< typename T >
69  T dt() const;
76  template< typename T >
77  Iteration& setDt(T newDt);
78 
82  double timeUnitSI() const;
88  Iteration& setTimeUnitSI(double newTimeUnitSI);
89 
96  /*
97  * Note: If the API is changed in future to allow reopening closed
98  * iterations, measures should be taken to prevent this in the streaming
99  * API. Currently, disallowing to reopen closed iterations satisfies
100  * the requirements of the streaming API.
101  */
102  Iteration &
103  close( bool flush = true );
104 
111  bool
112  closed() const;
113 
125  bool
126  closedByWriter() const;
127 
128  Container< Mesh > meshes;
129  Container< ParticleSpecies > particles; //particleSpecies?
130 
131  virtual ~Iteration() = default;
132 private:
133  Iteration();
134 
135  void flushFileBased(std::string const&, uint64_t);
136  void flushGroupBased(uint64_t);
137  void flush();
138  void read();
139 
144  enum class CloseStatus
145  {
146  Open,
147  ClosedInFrontend,
149  ClosedInBackend
151  };
152 
153  /*
154  * An iteration may be logically closed in the frontend,
155  * but not necessarily yet in the backend.
156  * Will be propagated to the backend upon next flush.
157  * Store the current status.
158  */
159  std::shared_ptr< CloseStatus > m_closed =
160  std::make_shared< CloseStatus >( CloseStatus::Open );
161 
162  /*
163  * @brief Check recursively whether this Iteration is dirty.
164  * It is dirty if any attribute or dataset is read from or written to
165  * the backend.
166  *
167  * @return true If dirty.
168  * @return false Otherwise.
169  */
170  bool
171  dirtyRecursive() const;
172 
173  virtual void linkHierarchy(std::shared_ptr< Writable > const& w);
174 }; // Iteration
175 
176 extern template
177 float
178 Iteration::time< float >() const;
179 
180 extern template
181 double
182 Iteration::time< double >() const;
183 
184 extern template
185 long double
186 Iteration::time< long double >() const;
187 
188 template< typename T >
189 inline T
191 { return Attributable::readFloatingpoint< T >("time"); }
192 
193 
194 extern template
195 float
196 Iteration::dt< float >() const;
197 
198 extern template
199 double
200 Iteration::dt< double >() const;
201 
202 extern template
203 long double
204 Iteration::dt< long double >() const;
205 
206 template< typename T >
207 inline T
209 { return Attributable::readFloatingpoint< T >("dt"); }
210 } // openPMD
T time() const
Definition: Iteration.hpp:190
Iteration & setDt(T newDt)
Set the time step used to reach this iteration.
Definition: Iteration.cpp:85
double timeUnitSI() const
Definition: Iteration.cpp:94
Logical compilation of data from one snapshot (e.g.
Definition: Iteration.hpp:35
T dt() const
Definition: Iteration.hpp:208
Iteration & close(bool flush=true)
Close an iteration.
Definition: Iteration.cpp:107
bool closed() const
Has the iteration been closed? A closed iteration may not (yet) be reopened.
Definition: Iteration.cpp:153
Root level of the openPMD hierarchy.
Definition: Series.hpp:55
Public definitions of openPMD-api.
Definition: Date.cpp:28
Iteration & setTime(T newTime)
Set the global reference time for this iteration.
Definition: Iteration.cpp:75
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:159
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:100
Layer to manage storage of attributes associated with file objects.
Definition: Attributable.hpp:65