externalFunction.hpp

/*
 * CoDiPack, a Code Differentiation Package
 *
 * Copyright (C) 2015-2026 Chair for Scientific Computing (SciComp), University of Kaiserslautern-Landau
 * Homepage: http://scicomp.rptu.de
 * Contact:  Prof. Nicolas R. Gauger (codi@scicomp.uni-kl.de)
 *
 * Lead developers: Max Sagebaum, Johannes Blühdorn (SciComp, University of Kaiserslautern-Landau)
 *
 * This file is part of CoDiPack (http://scicomp.rptu.de/software/codi).
 *
 * CoDiPack 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.
 *
 * CoDiPack 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 CoDiPack.
 * If not, see <http://www.gnu.org/licenses/>.
 *
 * For other licensing options please contact us.
 *
 * Authors:
 *  - SciComp, University of Kaiserslautern-Landau:
 *    - Max Sagebaum
 *    - Johannes Blühdorn
 *    - Former members:
 *      - Tim Albring
 */
#pragma once
 
#include "../../config.h"
#include "../../expressions/lhsExpressionInterface.hpp"
#include "../../misc/exceptions.hpp"
#include "../../misc/macros.hpp"
#include "../data/position.hpp"
#include "../interfaces/externalFunctionTapeInterface.hpp"
#include "../misc/vectorAccessInterface.hpp"
#include "lowLevelFunctionEntry.hpp"

namespace codi {

  struct ExternalFunctionInternalData {
    protected:
      using CallFunctionUntyped = void (*)(void* tape, void* data,
                                           void* adjointInterface);    
      using DeleteFunctionUntyped = void (*)(void* tape, void* data);  
 
      using IterCallbackUntyped = void (*)(void* id, void* userData);  
      using IterateIdsFunctionUntyped = void (*)(void* tape, void* data, IterCallbackUntyped callback,
                                                 void* userData);  
 
      CallFunctionUntyped funcReverse;        
      CallFunctionUntyped funcForward;        
      CallFunctionUntyped funcPrimal;         
      DeleteFunctionUntyped funcDelete;       
      IterateIdsFunctionUntyped funcIterIn;   
      IterateIdsFunctionUntyped funcIterOut;  
 
      void* data;  
 
    public:

      ExternalFunctionInternalData()
          : funcReverse(nullptr),
            funcForward(nullptr),
            funcPrimal(nullptr),
            funcDelete(nullptr),
            funcIterIn(nullptr),
            funcIterOut(nullptr),
            data(nullptr) {}
 
    protected:

      ExternalFunctionInternalData(CallFunctionUntyped funcReverse, CallFunctionUntyped funcForward,
                                   CallFunctionUntyped funcPrimal, DeleteFunctionUntyped funcDelete,
                                   IterateIdsFunctionUntyped funcIterIn, IterateIdsFunctionUntyped funcIterOut,
                                   void* data)
          : funcReverse(funcReverse),
            funcForward(funcForward),
            funcPrimal(funcPrimal),
            funcDelete(funcDelete),
            funcIterIn(funcIterIn),
            funcIterOut(funcIterOut),
            data(data) {}
  };

  template<typename T_Tape>
  struct ExternalFunction : public ExternalFunctionInternalData {
    public:
 
      using Tape = CODI_DD(T_Tape,
                           CODI_T(ExternalFunctionTapeInterface<double, double, int>));  
      using Real = typename Tape::Real;                                                  
      using Identifier = typename Tape::Identifier;                                      
 
      using VectorAccess = VectorAccessInterface<Real, Identifier>;  
      using IterCallback =
          typename LowLevelFunctionEntry<Tape, Real, Identifier>::IterCallback;  
 
      using CallFunction = void (*)(Tape* tape, void* data,
                                    VectorAccess* adjointInterface);  
      using DeleteFunction = void (*)(Tape* tape, void* data);        
      using IterateIdsFunction = void (*)(Tape* tape, void* data, IterCallback callback,
                                          void* userData);  

      ExternalFunction(CallFunction funcReverse, CallFunction funcForward, CallFunction funcPrimal, void* data,
                       DeleteFunction funcDelete, IterateIdsFunction funcIterIn, IterateIdsFunction funcIterOut)
          : ExternalFunctionInternalData((ExternalFunctionInternalData::CallFunctionUntyped)funcReverse,
                                         (ExternalFunctionInternalData::CallFunctionUntyped)funcForward,
                                         (ExternalFunctionInternalData::CallFunctionUntyped)funcPrimal,
                                         (ExternalFunctionInternalData::DeleteFunctionUntyped)funcDelete,
                                         (ExternalFunctionInternalData::IterateIdsFunctionUntyped)funcIterIn,
                                         (ExternalFunctionInternalData::IterateIdsFunctionUntyped)funcIterOut, data) {}

      static ExternalFunction create(CallFunction funcReverse, void* data, DeleteFunction funcDelete,
                                     CallFunction funcForward = nullptr, CallFunction funcPrimal = nullptr,
                                     IterateIdsFunction funcIterIn = nullptr,
                                     IterateIdsFunction funcIterOut = nullptr) {
        return ExternalFunction(funcReverse, funcForward, funcPrimal, data, funcDelete, funcIterIn, funcIterOut);
      }

      void deleteData(Tape* tape) {
        if (funcDelete != nullptr) {
          funcDelete(tape, data);
          data = nullptr;
        }
      }

      void evaluateReverse(Tape* tape, VectorAccess* adjointInterface) const {
        if (nullptr != funcReverse) {
          funcReverse(tape, data, adjointInterface);
        } else {
          CODI_EXCEPTION(
              "Calling an external function in reverse mode without providing a reverse evaluation function.");
        }
      }

      void evaluateForward(Tape* tape, VectorAccess* adjointInterface) const {
        if (nullptr != funcForward) {
          funcForward(tape, data, adjointInterface);
        } else {
          CODI_EXCEPTION(
              "Calling an external function in forward mode without providing a forward evaluation function.");
        }
      }

      void evaluatePrimal(Tape* tape, VectorAccess* adjointInterface) const {
        if (nullptr != funcPrimal) {
          funcPrimal(tape, data, adjointInterface);
        } else {
          CODI_EXCEPTION("Calling an external function in primal mode without providing a primal evaluation function.");
        }
      }

      void iterateInputs(Tape* tape, IterCallback func, void* userData) const {
        if (nullptr != funcIterIn) {
          funcIterIn(tape, data, (ExternalFunctionInternalData::IterCallbackUntyped)func, userData);
        } else {
          CODI_EXCEPTION(
              "Calling an external function for iteration of inputs without providing an iteration function.");
        }
      }

      void iterateOutputs(Tape* tape, IterCallback func, void* userData) const {
        if (nullptr != funcIterOut) {
          funcIterOut(tape, data, (ExternalFunctionInternalData::IterCallbackUntyped)func, userData);
        } else {
          CODI_EXCEPTION(
              "Calling an external function for iteration of outputs without providing an iteration function.");
        }
      }
  };

  template<typename T_Tape, typename T_Real, typename T_Identifier>
  struct ExternalFunctionLowLevelEntryMapper {
      using Tape = CODI_DD(T_Tape, CODI_DEFAULT_TAPE);  
      using Real = CODI_DD(T_Real, double);             
      using Identifier = CODI_DD(T_Identifier, int);    

      using IterCallback = typename LowLevelFunctionEntry<T_Tape, T_Real, T_Identifier>::IterCallback;
 
      using ExtFunc = ExternalFunction<Tape>;  
      using VectorAccess = VectorAccessInterface<Real, Identifier>;

      CODI_INLINE static void forward(Tape* tape, ByteDataView& data, VectorAccess* access) {
        ExtFunc* extFunc = data.read<ExtFunc>(1);
        extFunc->evaluateForward(tape, access);
      }

      CODI_INLINE static void primal(Tape* tape, ByteDataView& data, VectorAccess* access) {
        ExtFunc* extFunc = data.read<ExtFunc>(1);
        extFunc->evaluatePrimal(tape, access);
      }

      CODI_INLINE static void reverse(Tape* tape, ByteDataView& data, VectorAccess* access) {
        ExtFunc* extFunc = data.read<ExtFunc>(1);
        extFunc->evaluateReverse(tape, access);
      }

      CODI_INLINE static void del(Tape* tape, ByteDataView& data) {
        ExtFunc* extFunc = data.read<ExtFunc>(1);
        extFunc->deleteData(tape);
      }

      CODI_INLINE static void iterateInputs(Tape* tape, ByteDataView& data, IterCallback func, void* userData) {
        CODI_UNUSED(tape);
 
        ExtFunc* extFunc = data.read<ExtFunc>(1);
        extFunc->iterateInputs(tape, func, userData);
      }

      CODI_INLINE static void iterateOutputs(Tape* tape, ByteDataView& data, IterCallback func, void* userData) {
        CODI_UNUSED(tape);
 
        ExtFunc* extFunc = data.read<ExtFunc>(1);
        extFunc->iterateOutputs(tape, func, userData);
      }

      CODI_INLINE static void store(Tape& tape, Config::LowLevelFunctionToken token, ExtFunc const& extFunc) {
        ByteDataView data = {};
        tape.pushLowLevelFunction(token, sizeof(ExtFunc), data);
 
        data.write(extFunc);
      }

      CODI_INLINE static LowLevelFunctionEntry<Tape, Real, Identifier> create() {
        return LowLevelFunctionEntry<Tape, Real, Identifier>(reverse, forward, primal, del, iterateInputs,
                                                             iterateOutputs);
      }
  };
}