Series.hpp

/* Copyright 2017-2021 Fabian Koller, Axel Huebl
 *
 * 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/config.hpp"
#include "openPMD/backend/Attributable.hpp"
#include "openPMD/backend/Container.hpp"
#include "openPMD/IO/AbstractIOHandler.hpp"
#include "openPMD/IO/Access.hpp"
#include "openPMD/IO/Format.hpp"
#include "openPMD/Iteration.hpp"
#include "openPMD/IterationEncoding.hpp"
#include "openPMD/Streaming.hpp"
#include "openPMD/WriteIterations.hpp"
#include "openPMD/auxiliary/Option.hpp"
#include "openPMD/auxiliary/Variant.hpp"
#include "openPMD/backend/Attributable.hpp"
#include "openPMD/backend/Container.hpp"
#include "openPMD/config.hpp"
#include "openPMD/version.hpp"

#if openPMD_HAVE_MPI
#   include <mpi.h>
#endif

#include <map>
#include <string>

// expose private and protected members for invasive testing
#ifndef OPENPMD_private
#   define OPENPMD_private private
#endif


namespace openPMD
{
class ReadIterations;
class Series;
class SeriesInterface;

namespace internal
{
class SeriesData : public AttributableData
{
public:
    explicit SeriesData() = default;

    SeriesData( SeriesData const & ) = delete;
    SeriesData( SeriesData && ) = delete;

    SeriesData & operator=( SeriesData const & ) = delete;
    SeriesData & operator=( SeriesData && ) = delete;

    virtual ~SeriesData() = default;

    Container< Iteration, uint64_t > iterations{};

    auxiliary::Option< WriteIterations > m_writeIterations;
    auxiliary::Option< std::string > m_overrideFilebasedFilename;
    std::string m_name;
    std::string m_filenamePrefix;
    std::string m_filenamePostfix;
    int m_filenamePadding;
    IterationEncoding m_iterationEncoding{};
    Format m_format;
    StepStatus m_stepStatus = StepStatus::NoStep;
    bool m_parseLazily = false;
    bool m_lastFlushSuccessful = true;
}; // SeriesData

class SeriesInternal;
} // namespace internal

class SeriesInterface : public AttributableInterface
{
    friend class AttributableInterface;
    friend class Iteration;
    friend class Writable;
    friend class SeriesIterator;
    friend class internal::SeriesInternal;
    friend class Series;
    friend class WriteIterations;

protected:
    // Should not be called publicly, only by implementing classes
    SeriesInterface( internal::SeriesData *, internal::AttributableData * );

public:
    std::string openPMD() const;
    SeriesInterface& setOpenPMD(std::string const& openPMD);

    uint32_t openPMDextension() const;
    SeriesInterface& setOpenPMDextension(uint32_t openPMDextension);

    std::string basePath() const;
    SeriesInterface& setBasePath(std::string const& basePath);

    std::string meshesPath() const;
    SeriesInterface& setMeshesPath(std::string const& meshesPath);

    std::string particlesPath() const;
    SeriesInterface& setParticlesPath(std::string const& particlesPath);

    std::string author() const;
    SeriesInterface& setAuthor(std::string const& author);

    std::string software() const;
    SeriesInterface& setSoftware(std::string const& newName, std::string const& newVersion = std::string("unspecified"));

    std::string softwareVersion() const;
    [[deprecated("Set the version with the second argument of setSoftware()")]]
    SeriesInterface& setSoftwareVersion(std::string const& softwareVersion);

    std::string date() const;
    SeriesInterface& setDate(std::string const& date);

    std::string softwareDependencies() const;
    SeriesInterface& setSoftwareDependencies(std::string const& newSoftwareDependencies);

    std::string machine() const;
    SeriesInterface& setMachine(std::string const& newMachine);

    IterationEncoding iterationEncoding() const;
    SeriesInterface& setIterationEncoding(IterationEncoding iterationEncoding);

    std::string iterationFormat() const;
    SeriesInterface& setIterationFormat(std::string const& iterationFormat);

    std::string name() const;

    SeriesInterface& setName(std::string const& name);

    std::string backend() const;

    void flush();

OPENPMD_private:
    static constexpr char const * const BASEPATH = "/data/%T/";

    struct ParsedInput;
    using iterations_t = decltype(internal::SeriesData::iterations);
    using iterations_iterator = iterations_t::iterator;

    internal::SeriesData * m_series = nullptr;

    inline internal::SeriesData & get()
    {
        if( m_series )
        {
            return *m_series;
        }
        else
        {
            throw std::runtime_error(
                "[Series] Cannot use default-constructed Series." );
        }
    }

    inline internal::SeriesData const & get() const
    {
        if( m_series )
        {
            return *m_series;
        }
        else
        {
            throw std::runtime_error(
                "[Series] Cannot use default-constructed Series." );
        }    }

    std::unique_ptr< ParsedInput > parseInput(std::string);
    void init(std::shared_ptr< AbstractIOHandler >, std::unique_ptr< ParsedInput >);
    void initDefaults( IterationEncoding );
    std::future< void > flush_impl(
        iterations_iterator begin,
        iterations_iterator end,
        FlushLevel level,
        bool flushIOHandler = true );
    void flushFileBased( iterations_iterator begin, iterations_iterator end );
    /*
     * Group-based and variable-based iteration layouts share a lot of logic
     * (realistically, the variable-based iteration layout only throws out
     *  one layer in the hierarchy).
     * As a convention, methods that deal with both layouts are called
     * .*GorVBased, short for .*GroupOrVariableBased
     */
    void flushGorVBased( iterations_iterator begin, iterations_iterator end );
    void flushMeshesPath();
    void flushParticlesPath();
    void readFileBased( );
    void readOneIterationFileBased( std::string const & filePath );
    void readGorVBased( bool init = true );
    void readBase();
    std::string iterationFilename( uint64_t i );

    enum class IterationOpened : bool
    {
        HasBeenOpened,
        RemainsClosed
    };
    /*
     * For use by flushFileBased, flushGorVBased
     * Open an iteration, but only if necessary.
     * Only open if the iteration is dirty and if it is not in deferred
     * parse state.
     */
    IterationOpened openIterationIfDirty( uint64_t index, Iteration iteration );
    /*
     * Open an iteration. Ensures that the iteration's m_closed status
     * is set properly and that any files pertaining to the iteration
     * is opened.
     * Does not create files when called in CREATE mode.
     */
    void openIteration( uint64_t index, Iteration iteration );

    iterations_iterator
    indexOf( Iteration const & );

    AdvanceStatus
    advance(
        AdvanceMode mode,
        internal::AttributableData & file,
        iterations_iterator it,
        Iteration & iteration );
}; // SeriesInterface

namespace internal
{
class SeriesInternal : public SeriesData, public SeriesInterface
{
    friend struct SeriesShared;
    friend class openPMD::Iteration;
    friend class openPMD::Series;
    friend class openPMD::Writable;

public:
#if openPMD_HAVE_MPI
    SeriesInternal(
        std::string const & filepath,
        Access at,
        MPI_Comm comm,
        std::string const & options = "{}" );
#endif

    SeriesInternal(
        std::string const & filepath,
        Access at,
        std::string const & options = "{}" );
    // @todo make AttributableInterface<>::linkHierarchy non-virtual
    virtual ~SeriesInternal();
};
} // namespace internal

class Series : public SeriesInterface
{
private:
    std::shared_ptr< internal::SeriesInternal > m_series;

public:
    explicit Series();

#if openPMD_HAVE_MPI
    Series(
        std::string const & filepath,
        Access at,
        MPI_Comm comm,
        std::string const & options = "{}" );
#endif

    Series(
        std::string const & filepath,
        Access at,
        std::string const & options = "{}" );

    virtual ~Series() = default;

    Container< Iteration, uint64_t > iterations;

    operator bool() const;

    ReadIterations readIterations();

    WriteIterations writeIterations();
};
} // namespace openPMD

// Make sure that this one is always included if Series.hpp is included,
// otherwise SeriesInterface::readIterations() cannot be used
#include "openPMD/ReadIterations.hpp"