Iteration.hpp

/* Copyright 2017-2021 Fabian Koller
 *
 * This file is part of openPMD-api.
 *
 * openPMD-api is free software: you can redistribute it and/or modify
 * it under the terms of of either the GNU General Public License or
 * the GNU Lesser General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 *
 * openPMD-api is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License and the GNU Lesser General Public License
 * for more details.
 *
 * You should have received a copy of the GNU General Public License
 * and the GNU Lesser General Public License along with openPMD-api.
 * If not, see <http://www.gnu.org/licenses/>.
 */
#pragma once
 
#include "openPMD/IterationEncoding.hpp"
#include "openPMD/Mesh.hpp"
#include "openPMD/ParticleSpecies.hpp"
#include "openPMD/Streaming.hpp"
#include "openPMD/auxiliary/Variant.hpp"
#include "openPMD/backend/Attributable.hpp"
#include "openPMD/backend/Container.hpp"
 
#include <cstdint>
#include <deque>
#include <optional>
#include <set>
#include <tuple>
 
namespace openPMD
{
namespace internal
{
    enum class CloseStatus
    {
        ParseAccessDeferred, 
        Open, 
        ClosedInFrontend, 
        ClosedInBackend, 
        ClosedTemporarily 
    };
 
    struct DeferredParseAccess
    {
        std::string path;
        uint64_t iteration = 0;
        bool fileBased = false;
        std::string filename;
        bool beginStep = false;
    };
 
    class IterationData : public AttributableData
    {
    public:
        /*
         * An iteration may be logically closed in the frontend,
         * but not necessarily yet in the backend.
         * Will be propagated to the backend upon next flush.
         * Store the current status.
         * Once an iteration has been closed, no further flushes shall be
         * performed. If flushing a closed file, the old file may otherwise be
         * overwritten.
         */
        CloseStatus m_closed = CloseStatus::Open;
 
        StepStatus m_stepStatus = StepStatus::NoStep;
 
        std::optional<DeferredParseAccess> m_deferredParseAccess{};
 
        std::optional<std::string> m_overrideFilebasedFilename{};
    };
} // namespace internal
class Iteration : public Attributable
{
    template <typename T, typename T_key, typename T_container>
    friend class Container;
    friend class Series;
    friend class WriteIterations;
    friend class SeriesIterator;
 
public:
    Iteration(Iteration const &) = default;
    Iteration &operator=(Iteration const &) = default;
 
    using IterationIndex_t = uint64_t;
 
    template <typename T>
    T time() const;
    template <typename T>
    Iteration &setTime(T newTime);
 
    template <typename T>
    T dt() const;
    template <typename T>
    Iteration &setDt(T newDt);
 
    double timeUnitSI() const;
    Iteration &setTimeUnitSI(double newTimeUnitSI);
 
    /*
     * Note: If the API is changed in future to allow reopening closed
     * iterations, measures should be taken to prevent this in the streaming
     * API. Currently, disallowing to reopen closed iterations satisfies
     * the requirements of the streaming API.
     */
    Iteration &close(bool flush = true);
 
    Iteration &open();
 
    bool closed() const;
 
    [[deprecated("This attribute is no longer set by the openPMD-api.")]] bool
    closedByWriter() const;
 
    Container<Mesh> meshes{};
    Container<ParticleSpecies> particles{}; // particleSpecies?
 
    virtual ~Iteration() = default;
 
private:
    Iteration();
 
    std::shared_ptr<internal::IterationData> m_iterationData{
        new internal::IterationData};
 
    inline internal::IterationData const &get() const
    {
        return *m_iterationData;
    }
 
    inline internal::IterationData &get()
    {
        return *m_iterationData;
    }
 
    void flushFileBased(
        std::string const &, IterationIndex_t, internal::FlushParams const &);
    void flushGroupBased(IterationIndex_t, internal::FlushParams const &);
    void flushVariableBased(IterationIndex_t, internal::FlushParams const &);
    void flush(internal::FlushParams const &);
    void deferParseAccess(internal::DeferredParseAccess);
    /*
     * Control flow for runDeferredParseAccess(), readFileBased(),
     * readGroupBased() and read_impl():
     * runDeferredParseAccess() is called as the entry point.
     * File-based and group-based
     * iteration layouts need to be parsed slightly differently:
     * In file-based iteration layout, each iteration's file also contains
     * attributes for the /data group. In group-based layout, those have
     * already been parsed during opening of the Series.
     * Hence, runDeferredParseAccess() will call either readFileBased() or
     * readGroupBased() to
     * allow for those different control flows.
     * Finally, read_impl() is called which contains the common parsing
     * logic for an iteration.
     *
     * reread() reads again an Iteration that has been previously read.
     * Calling it on an Iteration not yet parsed is an error.
     *
     */
    void reread(std::string const &path);
    void readFileBased(
        std::string filePath, std::string const &groupPath, bool beginStep);
    void readGorVBased(std::string const &groupPath, bool beginStep);
    void read_impl(std::string const &groupPath);
    void readMeshes(std::string const &meshesPath);
    void readParticles(std::string const &particlesPath);
 
    struct BeginStepStatus
    {
        using AvailableIterations_t = std::optional<std::deque<uint64_t> >;
 
        AdvanceStatus stepStatus{};
        /*
         * If the iteration attribute `snapshot` is present, the value of that
         * attribute. Otherwise empty.
         */
        AvailableIterations_t iterationsInOpenedStep;
 
        /*
         * Most of the time, the AdvanceStatus part of this struct is what we
         * need, so let's make it easy to access.
         */
        inline operator AdvanceStatus() const
        {
            return stepStatus;
        }
 
        /*
         * Support for std::tie()
         */
        inline operator std::tuple<AdvanceStatus &, AvailableIterations_t &>()
        {
            return std::tuple<AdvanceStatus &, AvailableIterations_t &>{
                stepStatus, iterationsInOpenedStep};
        }
    };
 
    BeginStepStatus beginStep(bool reread);
 
    /*
     * Iteration-independent variant for beginStep().
     * Useful in group-based iteration encoding where the Iteration will only
     * be known after opening the step.
     */
    static BeginStepStatus beginStep(
        std::optional<Iteration> thisObject,
        Series &series,
        bool reread,
        std::set<IterationIndex_t> const &ignoreIterations = {});
 
    void endStep();
 
    StepStatus getStepStatus();
 
    void setStepStatus(StepStatus);
 
    /*
     * @brief Check recursively whether this Iteration is dirty.
     *        It is dirty if any attribute or dataset is read from or written to
     *        the backend.
     *
     * @return true If dirty.
     * @return false Otherwise.
     */
    bool dirtyRecursive() const;
 
    virtual void linkHierarchy(Writable &w);
 
    void runDeferredParseAccess();
}; // Iteration
 
extern template float Iteration::time<float>() const;
 
extern template double Iteration::time<double>() const;
 
extern template long double Iteration::time<long double>() const;
 
template <typename T>
inline T Iteration::time() const
{
    return this->readFloatingpoint<T>("time");
}
 
extern template float Iteration::dt<float>() const;
 
extern template double Iteration::dt<double>() const;
 
extern template long double Iteration::dt<long double>() const;
 
template <typename T>
inline T Iteration::dt() const
{
    return this->readFloatingpoint<T>("dt");
}
} // namespace openPMD