ReservoirCouplingSlaveReportStep.hpp

/*
  Copyright 2025 Equinor ASA

  This file is part of the Open Porous Media project (OPM).

  OPM is free software: you can redistribute it and/or modify
  it under the terms of the GNU General Public License as published by
  the Free Software Foundation, either version 3 of the License, or
  (at your option) any later version.

  OPM 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 for more details.

  You should have received a copy of the GNU General Public License
  along with OPM.  If not, see <http://www.gnu.org/licenses/>.
*/

#ifndef OPM_RESERVOIR_COUPLING_SLAVE_REPORT_STEP_HPP
#define OPM_RESERVOIR_COUPLING_SLAVE_REPORT_STEP_HPP

#include <opm/simulators/flow/rescoup/ReservoirCoupling.hpp>
#include <opm/input/eclipse/EclipseState/Phase.hpp>
#include <opm/input/eclipse/Schedule/Group/Group.hpp>

#include <map>
#include <string>
#include <utility>

namespace Opm {

// Avoid including the complete definition of ReservoirCouplingSlave here to avoid circular dependency.
template <class Scalar> class ReservoirCouplingSlave;

template <class Scalar>
class ReservoirCouplingSlaveReportStep {
public:
    using InjectionGroupTarget = ReservoirCoupling::InjectionGroupTarget<Scalar>;
    using ProductionGroupConstraints = ReservoirCoupling::ProductionGroupConstraints<Scalar>;
    using MasterGroupNodePressure = ReservoirCoupling::MasterGroupNodePressure<Scalar>;
    using MessageTag = ReservoirCoupling::MessageTag;
    using MasterProductionLimits = ReservoirCoupling::MasterProductionLimits<Scalar>;
    using SlaveGroupInjectionData = ReservoirCoupling::SlaveGroupInjectionData<Scalar>;
    using SlaveGroupProductionData = ReservoirCoupling::SlaveGroupProductionData<Scalar>;

    ReservoirCouplingSlaveReportStep(
        ReservoirCouplingSlave<Scalar> &slave
    );

    const Parallel::Communication &comm() const { return this->slave_.getComm(); }

    MPI_Comm getSlaveMasterComm() const { return this->slave_.getMasterComm(); }

    bool hasMasterInjectionTarget(const std::string& gname, const Phase phase) const;

    bool hasMasterGroupNodePressure(const std::string& gname) const;

    bool hasMasterProductionLimits(const std::string& gname) const;

    bool hasMasterProductionTarget(const std::string& gname) const;

    bool isFirstSubstepOfSyncTimestep() const { return is_first_substep_of_sync_timestep_; }

    bool isLastSubstepOfSyncTimestep() const { return is_last_substep_of_sync_timestep_; }

    ReservoirCoupling::Logger& logger() const { return this->slave_.logger(); }

    Scalar masterGroupNodePressure(const std::string& gname) const;

    const std::map<std::string, Scalar>& masterGroupNodePressures() const
    { return master_group_node_pressures_; }

    std::pair<Scalar, Group::InjectionCMode> masterInjectionTarget(
        const std::string& gname, const Phase phase) const;

    const MasterProductionLimits& masterProductionLimits(const std::string& gname) const;

    std::pair<Scalar, Group::ProductionCMode> masterProductionTarget(const std::string& gname) const;

    void receiveMasterGroupNodePressuresFromMaster(std::size_t num_pressures);

    std::pair<std::size_t, bool> receiveNumMasterGroupNodePressuresFromMaster();

    void receiveCoupledNetworkActiveStatusFromMaster();

    bool lastReceivedMasterGroupNodePressuresIsFinal() const
    { return last_received_master_group_node_pressures_is_final_; }

    bool connectedToMasterCoupledNetwork() const
    { return connected_to_master_coupled_network_; }

    std::pair<std::size_t, std::size_t> receiveNumGroupConstraintsFromMaster() const;

    void receiveInjectionGroupTargetsFromMaster(std::size_t num_targets);

    void receiveProductionGroupConstraintsFromMaster(std::size_t num_targets);

    void sendProductionDataToMaster(const std::vector<SlaveGroupProductionData> &production_data) const;

    void sendInjectionDataToMaster(const std::vector<SlaveGroupInjectionData> &injection_data) const;

    void setFirstSubstepOfSyncTimestep(bool value) { is_first_substep_of_sync_timestep_ = value; }

    void setLastSubstepOfSyncTimestep(bool value) { is_last_substep_of_sync_timestep_ = value; }

    void markSlaveGroupsInSchedule(Schedule& schedule, int report_step_idx);

    const std::string& slaveName() const { return this->slave_.getSlaveName(); }

    void setMasterGroupNodePressure(const std::string& gname, const Scalar pressure);

    void setMasterInjectionTarget(
        const std::string& gname, const Phase phase, const Scalar target, const Group::InjectionCMode cmode);

    void setMasterProductionLimits(const std::string& gname, const MasterProductionLimits& limits);

    void setMasterProductionTarget(const std::string& gname, const Scalar target, const Group::ProductionCMode cmode);


private:
    template <class DataType>
    void sendDataToMaster_(
        const std::vector<DataType>& data,
        MessageTag tag,
        const std::string& data_type_name
    ) const;

    ReservoirCouplingSlave<Scalar> &slave_;
    // Flag to track if this is the first substep within a "sync" timestep.
    // Used to control reservoir coupling synchronization.
    bool is_first_substep_of_sync_timestep_{true};
    // Flag to track if this is the last substep within a "sync" timestep.
    // Used to control reservoir coupling synchronization of summary data sent from
    // the slave to the master process.
    bool is_last_substep_of_sync_timestep_{false};

    // Master-imposed targets and corresponding control modes, received from the master
    // process at the beginning of each sync timestep. Cleared and repopulated on every
    // receive cycle. Used by GroupStateHelper to override slave group targets.
    //
    // Key: slave group name. Value: (target rate, production control mode).
    std::map<std::string, std::pair<Scalar, Group::ProductionCMode>> master_production_targets_;
    // Key: (injection phase, slave group name). Value: (target rate, injection control mode).
    std::map<std::pair<Phase, std::string>, std::pair<Scalar, Group::InjectionCMode>> master_injection_targets_;
    // Per-rate-type production limits from master hierarchy. Key: slave group name.
    // A limit of -1 means no limit defined in the hierarchy for that rate type.
    std::map<std::string, MasterProductionLimits> master_production_limits_;
    // Master-computed network-leaf node pressures keyed by slave group name. Only
    // populated for master groups that are leaf nodes in the master's extended
    // network. Cleared and repopulated on every receive cycle.
    std::map<std::string, Scalar> master_group_node_pressures_;
    // Whether *this* slave is connected to the master's cross-rescoup network
    // this sync step. Set once per sync step by
    // receiveCoupledNetworkActiveStatusFromMaster() from the master's per-slave
    // flag (BlackoilWellModelRescoup::masterNetworkHasMasterGroupLeavesForSlave_()).
    // A slave that is not connected does not participate in the cross-rescoup
    // exchange at all and balances only its own (local) network.
    //
    // This is deliberately separate from
    // last_received_master_group_node_pressures_is_final_ below: connectivity is
    // a per-sync-step property, whereas is_final is the per-iteration
    // termination signal (only meaningful while connected).
    bool connected_to_master_coupled_network_{false};
    // The iteration-termination flag. Initialized for each sync step through:
    //   beginTimeStep() -> BlackoilWellModelRescoup::sendCoupledNetworkActiveStatus()
    // to is_final = !connected (so an unconnected slave sees is_final = true and
    // never enters the per-iteration receive). For a connected slave it then
    // tracks the per-iteration is_final from the node-pressure header:
    //
    // In that case it is set to "true" in the course of the network iteration
    // in BlackoilWellModel::assemble() -> BlackoilWellModel::updateWellControlsAndNetworkIteration()
    // based on the "more_network_update" return value of BlackoilWellModelNetwork::update().
    // If it returns "false" the flag is reset to "true" and stays true for the rest of the sync timestep.
    //
    // Connected slaves use this variable to determine when to exit the outer
    // network loop such that the MPI master-slave communication protocol is kept in sync.
    bool last_received_master_group_node_pressures_is_final_{true};
};
} // namespace Opm
#endif // OPM_RESERVOIR_COUPLING_SLAVE_REPORT_STEP_HPP