Iteration.hpp

/* Copyright 2017-2025 Fabian Koller, Axel Huebl, Franz Poeschel, Luca Fedeli
 *
 * 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, 
        Closed, 
    };
 
    namespace BeginStepTypes
    {
        struct DontBeginStep
        {};
        struct BeginStepSequentially
        {};
        struct BeginStepRandomAccess
        {
            size_t step;
        };
    } // namespace BeginStepTypes
 
    using BeginStep = std::variant<
        BeginStepTypes::DontBeginStep,
        BeginStepTypes::BeginStepSequentially,
        BeginStepTypes::BeginStepRandomAccess>;
 
    namespace BeginStepTypes
    {
        template <typename T, typename... Args>
        constexpr auto make(Args &&...args) -> BeginStep
        {
            return BeginStep{T{std::forward<Args>(args)...}};
        }
    } // namespace BeginStepTypes
 
    struct DeferredParseAccess
    {
        std::string path;
        uint64_t iteration = 0;
        bool fileBased = false;
        BeginStep beginStep = BeginStepTypes::DontBeginStep{};
    };
 
    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;
        /*
         * While parsing a file-based Series, each file is opened, read, then
         * closed again. Explicitly `Iteration::open()`ing a file should only be
         * necessary after having explicitly closed it (or in
         * defer_iteration_parsing mode). So, the parsing procedures will set
         * this flag as true when closing an Iteration.
         */
        bool allow_reopening_implicitly = false;

        StepStatus m_stepStatus = StepStatus::NoStep;

        std::optional<DeferredParseAccess> m_deferredParseAccess{};
    };
} // namespace internal
class Iteration : public Attributable
{
    template <typename T, typename T_key, typename T_container>
    friend class Container;
    friend class Series;
    friend class internal::AttributableData;
    template <typename T>
    friend T &internal::makeOwning(T &self, Series);
    friend class Writable;
    friend class StatefulIterator;
    friend class StatefulSnapshotsContainer;
 
public:
    Iteration(Iteration const &) = default;
    Iteration(Iteration &&) = default;
    Iteration &operator=(Iteration const &) = default;
    Iteration &operator=(Iteration &&) = 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;

    bool parsed() 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();
 
    using Data_t = internal::IterationData;
    std::shared_ptr<Data_t> m_iterationData;
 
    inline Data_t const &get() const
    {
        return *m_iterationData;
    }
 
    inline Data_t &get()
    {
        return *m_iterationData;
    }
 
    inline std::shared_ptr<Data_t> getShared()
    {
        return m_iterationData;
    }
 
    inline void setData(std::shared_ptr<Data_t> data)
    {
        m_iterationData = std::move(data);
        Attributable::setData(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(
        IterationIndex_t,
        std::string const &filePath,
        std::string const &groupPath,
        bool beginStep);
    void readGorVBased(
        std::string const &groupPath, internal::BeginStep const &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::vector<IterationIndex_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);

    void endStep();

    StepStatus getStepStatus();

    void setStepStatus(StepStatus);

    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");
}

class IndexedIteration : public Iteration
{
    friend class StatefulIterator;
    friend class LegacyIteratorAdaptor;
 
public:
    using index_t = Iteration::IterationIndex_t;
    index_t const iterationIndex;
 
    inline IndexedIteration(std::pair<index_t const, Iteration> pair)
        : Iteration(std::move(pair.second)), iterationIndex(pair.first)
    {}
 
private:
    template <typename Iteration_t>
    IndexedIteration(Iteration_t &&it, index_t index)
        : Iteration(std::forward<Iteration_t>(it)), iterationIndex(index)
    {}
};
} // namespace openPMD