application_api/Federate.hpp

/*
Copyright (c) 2017-2026,
Battelle Memorial Institute; Lawrence Livermore National Security, LLC; Alliance for Energy
Innovation LLC.  See the top-level NOTICE for additional details. All rights reserved.
SPDX-License-Identifier: BSD-3-Clause
*/
#pragma once
#include "../core/LocalFederateId.hpp"
#include "../core/helicsTime.hpp"
#include "../helics_enums.h"
#include "FederateInfo.hpp"
#include "helics/helics-config.h"
#include "helicsTypes.hpp"
#include "helics_cxx_export.h"
 
#include <atomic>
#include <functional>
#include <memory>
#include <mutex>
#include <optional>
#include <stdexcept>
#include <string>
#include <utility>
 
namespace gmlc::libguarded {
template<class T, class M>
class shared_guarded;
}  // namespace gmlc::libguarded
 
namespace helics {
class Core;
class CoreApp;
class AsyncFedCallInfo;
class MessageOperator;
class ConnectorFederateManager;
class PotentialInterfacesManager;
class Filter;
class Translator;
class CloningFilter;
class Federate;
enum class FilterTypes;
 
class HELICS_CXX_EXPORT Federate {
  public:
    enum class Modes : char {
        STARTUP = 0,
        INITIALIZING = 1,
        EXECUTING = 2,
        FINALIZE = 3,
        ERROR_STATE = 4,
        // the following states are for asynchronous operations
        PENDING_INIT = 5,
        PENDING_EXEC = 6,
        PENDING_TIME = 7,
        PENDING_ITERATIVE_TIME = 8,
        PENDING_FINALIZE = 9,
        FINISHED = 10,
 
        PENDING_ITERATIVE_INIT = 12,
    };
 
  protected:
    std::atomic<Modes> currentMode{Modes::STARTUP};  
    char nameSegmentSeparator = '/';  
    bool strictConfigChecking{true};
    bool useJsonSerialization{false};
    bool observerMode{false};
    bool retriggerTimeRequest{false};
    /*** specify that the federate will only be used on a single thread*/
    bool singleThreadFederate{false};
    /*** specify that the federate has potential interfaces*/
    bool hasPotentialInterfaces{false};
 
  private:
    LocalFederateId fedID;  
  protected:
    std::shared_ptr<Core> coreObject;  
    Time mCurrentTime = Time::minVal();  
    Time mStopTime = Time::maxVal();  
    std::string configFile;  
  private:
    std::unique_ptr<gmlc::libguarded::shared_guarded<AsyncFedCallInfo, std::mutex>> asyncCallInfo;
    std::unique_ptr<ConnectorFederateManager> cManager;  
    std::unique_ptr<PotentialInterfacesManager> potManager;
    std::atomic<int> potInterfacesSequence{0};
    std::string mName;  
    std::function<void(Time, Time, bool)> timeRequestEntryCallback;
    std::function<void(Time, bool)> timeUpdateCallback;
    std::function<void(Modes, Modes)> modeUpdateCallback;
    std::function<void(Time, bool)> timeRequestReturnCallback;
    std::function<void(bool)> initializingEntryCallback;
    std::function<void()> executingEntryCallback;
    std::function<void()> cosimulationTerminationCallback;
    std::function<void(int, std::string_view)> errorHandlerCallback;
 
  public:
    Federate(std::string_view fedname, const FederateInfo& fedInfo);
    Federate(std::string_view fedname,
             const std::shared_ptr<Core>& core,
             const FederateInfo& fedInfo = FederateInfo{});
 
    Federate(std::string_view fedname, CoreApp& core, const FederateInfo& fedInfo = FederateInfo{});
    explicit Federate(const std::string& configString);
    Federate(std::string_view fedname, const std::string& configString);
    Federate() noexcept;
    Federate(Federate&& fed) noexcept;
    Federate(const Federate& fed) = delete;
    virtual ~Federate();
    Federate& operator=(Federate&& fed) noexcept;
    Federate& operator=(const Federate& fed) = delete;
    void enterInitializingMode();
 
    void enterInitializingModeAsync();
    bool isAsyncOperationCompleted() const;
    void enterInitializingModeComplete();
 
    void enterInitializingModeIterative();
 
    void enterInitializingModeIterativeAsync();
 
    void enterInitializingModeIterativeComplete();
 
    IterationResult enterExecutingMode(IterationRequest iterate = IterationRequest::NO_ITERATIONS);
    void enterExecutingModeAsync(IterationRequest iterate = IterationRequest::NO_ITERATIONS);
    IterationResult enterExecutingModeComplete();
    void finalize();
    void finalizeAsync();
    void finalizeComplete();
    void processCommunication(std::chrono::milliseconds period = std::chrono::milliseconds(0));
    virtual void disconnect();
 
    void localError(int errorcode, std::string_view message);
 
    void globalError(int errorcode, std::string_view message);
 
    void localError(int errorcode);
 
    void globalError(int errorcode);
 
    void setSeparator(char separator) { nameSegmentSeparator = separator; }
    Time requestTime(Time nextInternalTimeStep);
 
    Time requestNextStep() { return requestTime(timeZero); }
 
    Time requestTimeAdvance(Time timeDelta) { return requestTime(mCurrentTime + timeDelta); }
 
    iteration_time requestTimeIterative(Time nextInternalTimeStep, IterationRequest iterate);
 
    void requestTimeAsync(Time nextInternalTimeStep);
 
    void requestTimeIterativeAsync(Time nextInternalTimeStep, IterationRequest iterate);
 
    Time requestTimeComplete();
 
    iteration_time requestTimeIterativeComplete();
 
    void setTag(std::string_view tag, std::string_view value);
    const std::string& getTag(std::string_view tag) const;
 
    virtual void setProperty(int32_t option, double timeValue);
 
    virtual void setProperty(int32_t option, Time timeValue);
 
    virtual void setFlagOption(int flag, bool flagValue = true);
    virtual void setProperty(int32_t option, int32_t optionValue);
 
    virtual Time getTimeProperty(int32_t option) const;
 
    virtual bool getFlagOption(int flag) const;
    virtual int getIntegerProperty(int32_t option) const;
 
    void setLoggingCallback(
        const std::function<void(int, std::string_view, std::string_view)>& logFunction);
 
    void setInitializingEntryCallback(std::function<void(bool)> callback);
 
    void setExecutingEntryCallback(std::function<void()> callback);
 
    void setTimeRequestEntryCallback(std::function<void(Time, Time, bool)> callback);
 
    void setTimeUpdateCallback(std::function<void(Time, bool)> callback);
 
    void setModeUpdateCallback(std::function<void(Modes, Modes)> callback);
 
    void setTimeRequestReturnCallback(std::function<void(Time, bool)> callback);
 
    void setCosimulationTerminatedCallback(std::function<void()> callback);
 
    void setErrorHandlerCallback(std::function<void(int, std::string_view)> errorHandlerCallback);
 
    std::string query(std::string_view target,
                      std::string_view queryStr,
                      HelicsSequencingModes mode = HELICS_SEQUENCING_MODE_FAST);
 
    std::string query(std::string_view queryStr,
                      HelicsSequencingModes mode = HELICS_SEQUENCING_MODE_FAST);
 
    QueryId queryAsync(std::string_view target,
                       std::string_view queryStr,
                       HelicsSequencingModes mode = HELICS_SEQUENCING_MODE_FAST);
 
    QueryId queryAsync(std::string_view queryStr,
                       HelicsSequencingModes mode = HELICS_SEQUENCING_MODE_FAST);
 
    std::string queryComplete(QueryId queryIndex);
 
    bool isQueryCompleted(QueryId queryIndex) const;
 
    void setQueryCallback(const std::function<std::string(std::string_view)>& queryFunction);
 
    void setGlobal(std::string_view valueName, std::string_view value);
    void addAlias(std::string_view interfaceName, std::string_view alias);
    void sendCommand(
        std::string_view target,
        std::string_view commandStr,
        HelicsSequencingModes mode = HelicsSequencingModes::HELICS_SEQUENCING_MODE_FAST);
 
    std::pair<std::string, std::string> getCommand();
 
    std::pair<std::string, std::string> waitCommand();
 
    void addDependency(std::string_view fedName);
 
    Filter& registerGlobalFilter(std::string_view filterName,
                                 std::string_view inputType = std::string_view{},
                                 std::string_view outputType = std::string_view{});
 
    CloningFilter& registerGlobalCloningFilter(std::string_view filterName,
                                               std::string_view inputType = std::string_view{},
                                               std::string_view outputType = std::string_view{});
 
    Filter& registerFilter(std::string_view filterName,
                           std::string_view inputType = std::string_view{},
                           std::string_view outputType = std::string_view{});
 
    CloningFilter& registerCloningFilter(std::string_view filterName,
                                         std::string_view inputType = std::string_view{},
                                         std::string_view outputType = std::string_view{});
 
    Filter& registerFilter()
    {
        return registerGlobalFilter(std::string(), std::string_view{}, std::string_view{});
    }
 
    Translator& registerGlobalTranslator(std::int32_t translatorType,
                                         std::string_view translatorName,
                                         std::string_view endpointType = std::string_view{},
                                         std::string_view units = std::string_view{});
 
    Translator& registerTranslator(std::int32_t translatorType,
                                   std::string_view translatorName,
                                   std::string_view endpointType = std::string_view{},
                                   std::string_view units = std::string_view{});
 
    Translator& registerGlobalTranslator(std::string_view translatorName,
                                         std::string_view endpointType = std::string_view{},
                                         std::string_view units = std::string_view{})
    {
        return registerGlobalTranslator(0, translatorName, endpointType, units);
    }
 
    Translator& registerTranslator(std::string_view translatorName,
                                   std::string_view endpointType = std::string_view{},
                                   std::string_view units = std::string_view{})
    {
        return registerTranslator(0, translatorName, endpointType, units);
    }
 
    Translator& registerTranslator() { return registerGlobalTranslator(""); }
    CloningFilter& registerCloningFilter()
    {
        return registerGlobalCloningFilter(std::string(), std::string(), std::string());
    }
 
    const Filter& getFilter(std::string_view filterName) const;
 
    const Filter& getFilter(int index) const;
 
    Filter& getFilter(std::string_view filterName);
 
    Filter& getFilter(int index);
 
    [[deprecated]] static void setFilterOperator(Filter& filt,
                                                 std::shared_ptr<FilterOperator> filtOp);
 
    int getFilterCount() const;
 
    // translator retrieval
    const Translator& getTranslator(std::string_view translatorName) const;
 
    const Translator& getTranslator(int index) const;
 
    Translator& getTranslator(std::string_view translatorName);
 
    Translator& getTranslator(int index);
 
    [[deprecated]] static void setTranslatorOperator(Translator& trans,
                                                     std::shared_ptr<TranslatorOperator> transOp);
 
    int getTranslatorCount() const;
    const std::string& getConfigFile() const { return configFile; }
 
  protected:
    void enteringInitializingMode(IterationResult iterating);
 
    void enteringExecutingMode(iteration_time res);
    void finalizeOperations();
    void preTimeRequestOperations(Time nextStep, bool iterating);
    void postTimeRequestOperations(Time newTime, bool iterating);
    virtual void updateTime(Time newTime, Time oldTime);
    virtual void startupToInitializeStateTransition();
    virtual void initializeToExecuteStateTransition(iteration_time iterate);
    virtual void disconnectTransition();
    virtual std::string localQuery(std::string_view queryStr) const;
    std::string localNameGenerator(std::string_view addition) const;
    void handleError(int errorCode, std::string_view errorString, bool noThrow);
    void setAsyncCheck(std::function<bool()> asyncCheck);
 
  public:
    virtual void registerInterfaces(const std::string& configString);
    void registerConnectorInterfaces(const std::string& configString);
    void registerFilterInterfaces(const std::string& configString)
    {
        registerConnectorInterfaces(configString);
    }
    auto getID() const noexcept { return fedID; }
    Modes getCurrentMode() const noexcept { return currentMode.load(); }
    Time getCurrentTime() const noexcept { return mCurrentTime; }
    const std::string& getName() const { return mName; }
    const std::shared_ptr<Core>& getCorePointer() { return coreObject; }
 
    void logMessage(int level, std::string_view message) const;
 
    void logErrorMessage(std::string_view message) const
    {
        logMessage(HELICS_LOG_LEVEL_ERROR, message);
    }
    void logWarningMessage(std::string_view message) const
    {
        logMessage(HELICS_LOG_LEVEL_WARNING, message);
    }
    void logInfoMessage(std::string_view message) const
    {
        logMessage(HELICS_LOG_LEVEL_SUMMARY, message);
    }
    void logDebugMessage(std::string_view message) const
    {
        logMessage(HELICS_LOG_LEVEL_DEBUG, message);
    }
    void completeOperation();
 
  private:
    void getCore(const FederateInfo& fedInfo);
    void verifyCore();
    void registerFederate(const FederateInfo& fedInfo);
 
    void updateFederateMode(Modes newMode);
    void potentialInterfacesStartupSequence();
    void updateSimulationTime(Time newTime, Time oldTime, bool iterating);
    void registerConnectorInterfacesJson(const std::string& jsonString);
    void registerConnectorInterfacesToml(const std::string& tomlString);
    void registerConnectorInterfacesJsonDetail(const fileops::JsonBuffer& json);
    bool
        checkValidFilterType(bool useTypes, FilterTypes opType, const std::string& operation) const;
};
 
class HELICS_CXX_EXPORT Interface {
  protected:
    Core* mCore{nullptr};  
    InterfaceHandle handle{};  
    std::string mName;  
  public:
    Interface() = default;
    Interface(Federate* federate, InterfaceHandle hid, std::string_view actName);
    Interface(Core* core, InterfaceHandle hid, std::string_view actName):
        mCore(core), handle(hid), mName(actName)
    {
    }
    virtual ~Interface() = default;
    InterfaceHandle getHandle() const { return handle; }
    operator InterfaceHandle() const { return handle; }
    bool isValid() const { return handle.isValid(); }
    bool operator<(const Interface& inp) const { return (handle < inp.handle); }
    bool operator>(const Interface& inp) const { return (handle > inp.handle); }
    bool operator==(const Interface& inp) const { return (handle == inp.handle); }
    bool operator!=(const Interface& inp) const { return (handle != inp.handle); }
    const std::string& getLocalName() const { return mName; }
    const std::string& getName() const;
    [[deprecated]] const std::string& getTarget() const;
    void addSourceTarget(std::string_view newTarget, InterfaceType hint = InterfaceType::UNKNOWN);
    void addDestinationTarget(std::string_view newTarget,
                              InterfaceType hint = InterfaceType::UNKNOWN);
    void removeTarget(std::string_view targetToRemove);
    void addAlias(std::string_view alias);
    const std::string& getInfo() const;
    void setInfo(std::string_view info);
    void setTag(std::string_view tag, std::string_view value);
    const std::string& getTag(std::string_view tag) const;
    virtual void setOption(int32_t option, int32_t value = 1);
 
    virtual int32_t getOption(int32_t option) const;
 
    const std::string& getInjectionType() const;
 
    const std::string& getExtractionType() const;
 
    const std::string& getInjectionUnits() const;
 
    const std::string& getExtractionUnits() const;
    virtual const std::string& getDisplayName() const = 0;
    const std::string& getSourceTargets() const;
    const std::string& getDestinationTargets() const;
    std::size_t getSourceTargetCount() const;
    std::size_t getDestinationTargetCount() const;
    void close();
    void disconnectFromCore();
};
 
HELICS_CXX_EXPORT void cleanupHelicsLibrary();
}  // namespace helics