Inputs.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 "Federate.hpp"
#include "HelicsPrimaryTypes.hpp"
#include "helicsTypes.hpp"
 
#include <memory>
#include <string>
#include <utility>
#include <vector>
 
namespace units {
class precise_unit;
}  // namespace units
 
namespace helics {
 
class ValueFederate;
enum MultiInputHandlingMethod : uint16_t {
    NO_OP = HELICS_MULTI_INPUT_NO_OP,
    VECTORIZE_OPERATION = HELICS_MULTI_INPUT_VECTORIZE_OPERATION,
    AND_OPERATION = HELICS_MULTI_INPUT_AND_OPERATION,
    OR_OPERATION = HELICS_MULTI_INPUT_OR_OPERATION,
    SUM_OPERATION = HELICS_MULTI_INPUT_SUM_OPERATION,
    DIFF_OPERATION = HELICS_MULTI_INPUT_DIFF_OPERATION,
    MAX_OPERATION = HELICS_MULTI_INPUT_MAX_OPERATION,
    MIN_OPERATION = HELICS_MULTI_INPUT_MIN_OPERATION,
    AVERAGE_OPERATION = HELICS_MULTI_INPUT_AVERAGE_OPERATION
};
 
class HELICS_CXX_EXPORT Input: public Interface {
  protected:
    ValueFederate* fed = nullptr;  
  private:
    int referenceIndex{-1};  
    void* dataReference{nullptr};  
 
    DataType targetType{DataType::HELICS_UNKNOWN};  
    DataType injectionType{
        DataType::HELICS_UNKNOWN};  
    bool changeDetectionEnabled{false};  
    bool hasUpdate{false};  
    bool disableAssign{false};  
    bool useThreshold{false};  
    bool multiUnits{false};  
    MultiInputHandlingMethod inputVectorOp{
        MultiInputHandlingMethod::NO_OP};  
    int32_t prevInputCount{0};  
    size_t customTypeHash{0U};  
    defV lastValue{invalidDouble};  
    std::shared_ptr<units::precise_unit> outputUnits;  
    std::shared_ptr<units::precise_unit> inputUnits;  
    std::vector<std::pair<DataType, std::shared_ptr<units::precise_unit>>>
        sourceTypes;  
    std::string givenTarget;  
    double delta{-1.0};  
    double threshold{0.0};  
    // this needs to match the defV type
    std::variant<std::function<void(const double&, Time)>,
                 std::function<void(const int64_t&, Time)>,
                 std::function<void(const std::string&, Time)>,
                 std::function<void(const std::complex<double>&, Time)>,
                 std::function<void(const std::vector<double>&, Time)>,
                 std::function<void(const std::vector<std::complex<double>>&, Time)>,
                 std::function<void(const NamedPoint&, Time)>,
                 std::function<void(const bool&, Time)>,
                 std::function<void(const Time&, Time)>>
        value_callback;  
  public:
    Input() = default;
    Input(ValueFederate* valueFed,
          InterfaceHandle id,
          std::string_view actName,
          std::string_view unitsOut = {});
 
    Input(ValueFederate* valueFed,
          std::string_view key,
          std::string_view defaultType = "def",
          std::string_view units = {});
 
    template<class FedPtr>
    Input(FedPtr& valueFed,
          std::string_view key,
          std::string_view defaultType = "def",
          std::string_view units = {}): Input(std::addressof(*valueFed), key, defaultType, units)
    {
        static_assert(
            std::is_base_of<ValueFederate, std::remove_reference_t<decltype(*valueFed)>>::value,
            "first argument must be a pointer to a ValueFederate");
    }
 
    Input(InterfaceVisibility locality,
          ValueFederate* valueFed,
          std::string_view key,
          std::string_view defaultType = "def",
          std::string_view units = {});
 
    template<class FedPtr>
    Input(InterfaceVisibility locality,
          FedPtr& valueFed,
          std::string_view key,
          std::string_view defaultType = "def",
          std::string_view units = {}):
        Input(locality, std::addressof(*valueFed), key, defaultType, units)
    {
        static_assert(
            std::is_base_of<ValueFederate, std::remove_reference_t<decltype(*valueFed)>>::value,
            "first argument must be a pointer to a ValueFederate");
    }
 
    Input(ValueFederate* valueFed,
          std::string_view key,
          DataType defType,
          std::string_view units = {}): Input(valueFed, key, typeNameStringRef(defType), units)
    {
    }
 
    template<class FedPtr>
    Input(FedPtr& valueFed, std::string_view key, DataType defType, std::string_view units = {}):
        Input(valueFed, key, typeNameStringRef(defType), units)
    {
    }
 
    Input(InterfaceVisibility locality,
          ValueFederate* valueFed,
          std::string_view key,
          std::string_view units = {}): Input(locality, valueFed, key, "def", units)
    {
    }
 
    template<class FedPtr>
    Input(InterfaceVisibility locality,
          FedPtr& valueFed,
          std::string_view key,
          std::string_view units = {}): Input(locality, valueFed, key, "def", units)
    {
    }
 
    Input(InterfaceVisibility locality,
          ValueFederate* valueFed,
          std::string_view key,
          DataType defType,
          std::string_view units = {}):
        Input(locality, valueFed, key, typeNameStringRef(defType), units)
    {
    }
 
    template<class FedPtr>
    Input(InterfaceVisibility locality,
          FedPtr& valueFed,
          std::string_view key,
          DataType defType,
          std::string_view units = {}):
        Input(locality, valueFed, key, typeNameStringRef(defType), units)
    {
    }
 
    Time getLastUpdate() const;
 
    void registerNotificationCallback(std::function<void(Time)> callback);
 
    const std::string& getPublicationType() const
    {
        return ((injectionType == DataType::HELICS_UNKNOWN) ||
                (injectionType == DataType::HELICS_CUSTOM)) ?
            getInjectionType() :
            typeNameStringRef(injectionType);
    }
    const std::string& getType() const { return getExtractionType(); }
    const std::string& getUnits() const { return getExtractionUnits(); }
    void addPublication(std::string_view target);
    void addTarget(std::string_view target) { addPublication(target); }
    bool checkUpdate(bool assumeUpdate = false);
 
    void clearUpdate();
    bool isUpdated();
    bool isUpdated() const;
 
    virtual void setOption(int32_t option, int32_t value = 1) override;
    virtual int32_t getOption(int32_t option) const override;
    template<class X>
    void setInputNotificationCallback(std::function<void(const X&, Time)> callback)
    {
        static_assert(
            helicsType<X>() != DataType::HELICS_CUSTOM,
            "callback type must be a primary helics type one of \"double, int64_t, named_point, bool, Time "
            "std::vector<double>, std::vector<std::complex<double>>, std::complex<double>\"");
        value_callback = std::move(callback);
        registerCallback();
    }
 
  private:
    template<class X>
    void setDefault_impl(std::integral_constant<int, 0> /*V*/, X&& val)
    {
        lastValue = make_valid(std::forward<X>(val));
    }
 
    template<class X>
    void setDefault_impl(std::integral_constant<int, 1> /*V*/, X&& val)
    {
        lastValue = make_valid(std::forward<X>(val));
    }
 
    template<class X>
    void setDefault_impl(std::integral_constant<int, 2> /*V*/, X&& val)
    {
        auto res = ValueConverter<remove_cv_ref<X>>::convert(std::forward<X>(val));
        lastValue = std::string(res.to_string());
        setDefaultBytes(res);
    }
 
    void registerCallback();
 
  public:
    template<class X>
    void setDefault(X&& val)
    {
        setDefault_impl<X>(typeCategory<X>(), std::forward<X>(val));
    }
 
    void setDefaultBytes(data_view val);
    void setMinimumChange(double deltaV) noexcept
    {
        // this first check enables change detection if it was disabled via negative delta
        if (delta < 0.0) {
            changeDetectionEnabled = true;
        }
        delta = deltaV;
        // the second checks if we should disable from negative delta
        if (delta < 0.0) {
            changeDetectionEnabled = false;
        }
    }
    void enableChangeDetection(bool enabled = true) noexcept { changeDetectionEnabled = enabled; }
 
  private:
    void handleCallback(Time time);
    template<class X>
    void getValue_impl(std::integral_constant<int, primaryType> /*V*/, X& out);
 
    void getValue_impl(std::integral_constant<int, primaryType> /*V*/, char& out)
    {
        out = getValueChar();
    }
 
    void getValue_impl(std::integral_constant<int, convertibleType> /*V*/, char& out)
    {
        out = getValueChar();
    }
 
    template<class X>
    void getValue_impl(std::integral_constant<int, convertibleType> /*V*/, X& out)
    {
        std::conditional_t<std::is_integral<X>::value,
                           std::conditional_t<std::is_same<X, char>::value, char, int64_t>,
                           double>
            gval;
        getValue_impl(std::integral_constant<int, primaryType>(), gval);
        out = static_cast<X>(gval);
    }
 
    template<class X>
    void getValue_impl(std::integral_constant<int, nonConvertibleType> /*V*/, X& out)
    {
        ValueConverter<X>::interpret(getBytes(), out);
    }
 
    template<class X>
    X getValue_impl(std::integral_constant<int, primaryType> /*V*/)
    {
        X val;  // NOLINT
        getValue_impl(std::integral_constant<int, primaryType>(), val);
        return val;
    }
 
    template<class X>
    X getValue_impl(std::integral_constant<int, convertibleType> /*V*/)
    {
        std::conditional_t<std::is_integral<X>::value,
                           std::conditional_t<std::is_same<X, char>::value, char, int64_t>,
                           double>
            gval;
        getValue_impl(std::integral_constant<int, primaryType>(), gval);
        return static_cast<X>(gval);
    }
 
    template<class X>
    X getValue_impl(std::integral_constant<int, nonConvertibleType> /*V*/)
    {
        return ValueConverter<X>::interpret(getBytes());
    }
 
  public:
    int getValue(double* data, int maxsize);
    int getComplexValue(double* data, int maxsize);
    int getValue(char* str, int maxsize);
    template<class X>
    void getValue(X& out)
    {
        getValue_impl<X>(typeCategory<X>(), out);
    }
    template<class X>
    auto getValue()
    {
        return getValue_impl<remove_cv_ref<X>>(typeCategory<X>());
    }
 
    template<class X>
    const X& getValueRef();
    double getDouble() { return getValue_impl<double>(std::integral_constant<int, primaryType>()); }
    const std::string& getString() { return getValueRef<std::string>(); }
 
    data_view getBytes();
    size_t getByteCount();
    size_t getStringSize();
    size_t getVectorSize();
 
    DataType getHelicsType() const { return targetType; }
 
    DataType getHelicsInjectionType() const { return injectionType; }
 
    MultiInputHandlingMethod getMultiInputMode() const { return inputVectorOp; }
 
    bool vectorDataProcess(const std::vector<std::shared_ptr<const SmallBuffer>>& dataV);
 
    const std::string& getTarget() const
    {
        return (!givenTarget.empty()) ? givenTarget : getSourceTargets();
    }
 
    virtual const std::string& getDisplayName() const override
    {
        return (mName.empty()) ? getTarget() : getName();
    }
 
  private:
    void loadSourceInformation();
    char getValueChar();
    bool allowDirectFederateUpdate() const
    {
        return hasUpdate && !changeDetectionEnabled &&
            inputVectorOp == MultiInputHandlingMethod::NO_OP;
    }
    data_view checkAndGetFedUpdate();
    void forceCoreDataUpdate();
    friend class ValueFederateManager;
};
 
HELICS_CXX_EXPORT double
    doubleExtractAndConvert(const data_view& dv,
                            const std::shared_ptr<units::precise_unit>& inputUnits,
                            const std::shared_ptr<units::precise_unit>& outputUnits);
 
HELICS_CXX_EXPORT void
    integerExtractAndConvert(defV& store,
                             const data_view& dv,
                             const std::shared_ptr<units::precise_unit>& inputUnits,
                             const std::shared_ptr<units::precise_unit>& outputUnits);
 
template<class X>
void Input::getValue_impl(std::integral_constant<int, primaryType> /*V*/, X& out)
{
    auto dv = checkAndGetFedUpdate();
    if (!dv.empty()) {
        if (injectionType == DataType::HELICS_UNKNOWN) {
            loadSourceInformation();
        }
 
        if (injectionType == helics::DataType::HELICS_DOUBLE) {
            defV val = doubleExtractAndConvert(dv, inputUnits, outputUnits);
            valueExtract(val, out);
        } else if (injectionType == helics::DataType::HELICS_INT) {
            defV val;
            integerExtractAndConvert(val, dv, inputUnits, outputUnits);
            valueExtract(val, out);
        } else {
            valueExtract(dv, injectionType, out);
        }
        if (changeDetectionEnabled) {
            if (changeDetected(lastValue, out, delta)) {
                lastValue = make_valid(out);
            } else {
                valueExtract(lastValue, out);
            }
        } else {
            lastValue = make_valid(out);
        }
    } else {
        valueExtract(lastValue, out);
    }
    hasUpdate = false;
}
 
template<class X>
inline const X& getValueRefImpl(defV& val)
{
    valueConvert(val, helicsType<X>());
    return std::get<X>(val);
}
 
template<>
inline const std::string& getValueRefImpl(defV& val)
{
    // don't convert a named point to a string
    if ((val.index() == named_point_loc)) {
        return std::get<NamedPoint>(val).name;
    }
    valueConvert(val, DataType::HELICS_STRING);
    return std::get<std::string>(val);
}
 
HELICS_CXX_EXPORT bool checkForNeededCoreRetrieval(std::size_t currentIndex,
                                                   DataType injectionType,
                                                   DataType conversion);
 
template<class X>
const X& Input::getValueRef()
{
    static_assert(std::is_same<typeCategory<X>, std::integral_constant<int, primaryType>>::value,
                  "calling getValue By ref must be with a primary type");
    auto dv = checkAndGetFedUpdate();
    if (!dv.empty()) {
        if (injectionType == DataType::HELICS_UNKNOWN) {
            loadSourceInformation();
        }
 
        if (changeDetectionEnabled) {
            X out;
            if (injectionType == helics::DataType::HELICS_DOUBLE) {
                defV val = doubleExtractAndConvert(dv, inputUnits, outputUnits);
                valueExtract(val, out);
            } else if (injectionType == helics::DataType::HELICS_INT) {
                defV val;
                integerExtractAndConvert(val, dv, inputUnits, outputUnits);
                valueExtract(val, out);
            } else {
                valueExtract(dv, injectionType, out);
            }
            if (changeDetected(lastValue, out, delta)) {
                lastValue = make_valid(std::move(out));
            }
        } else {
            valueExtract(dv, injectionType, lastValue);
        }
    } else {
        if (checkForNeededCoreRetrieval(lastValue.index(),
                                        injectionType,
                                        helicsType<remove_cv_ref<X>>())) {
            forceCoreDataUpdate();
        }
    }
 
    hasUpdate = false;
    return getValueRefImpl<remove_cv_ref<X>>(lastValue);
}
}  // namespace helics