dae_builder_internal.hpp

/*
 *    This file is part of CasADi.
 *
 *    CasADi -- A symbolic framework for dynamic optimization.
 *    Copyright (C) 2010-2023 Joel Andersson, Joris Gillis, Moritz Diehl,
 *                            KU Leuven. All rights reserved.
 *    Copyright (C) 2011-2014 Greg Horn
 *
 *    CasADi is free software; you can redistribute it and/or
 *    modify it under the terms of 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.
 *
 *    CasADi 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
 *    Lesser General Public License for more details.
 *
 *    You should have received a copy of the GNU Lesser General Public
 *    License along with CasADi; if not, write to the Free Software
 *    Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
 *
 */
 
 
#ifndef CASADI_DAE_BUILDER_INTERNAL_HPP
#define CASADI_DAE_BUILDER_INTERNAL_HPP
 
#include <unordered_map>
 
#include "dae_builder.hpp"
#include "shared_object.hpp"
#include "casadi_enum.hpp"
#include "resource.hpp"
 
namespace casadi {
 
// Forward declarations
struct XmlNode;
 
enum class TypeFmi2 {REAL, INTEGER, BOOLEAN, STRING, ENUM, NUMEL};
 
enum class Type {FLOAT32, FLOAT64, INT8, UINT8, INT16, UINT16, INT32, UINT32, INT64, UINT64,
  BOOLEAN, STRING, BINARY, ENUMERATION, CLOCK, NUMEL};
 
enum class Causality {PARAMETER, CALCULATED_PARAMETER, INPUT, OUTPUT, LOCAL, INDEPENDENT, NUMEL};
 
enum class Variability {CONSTANT, FIXED, TUNABLE, DISCRETE, CONTINUOUS, NUMEL};
 
// CasADi classification of model variables, cf. Table 18 in FMI specification, 3.0.2
//              PARAMETER  CALCULATED_PARAMETER  INPUT   OUTPUT     LOCAL      INDEPENDENT
// CONSTANT     -          -                     -       C          C          -
// FIXED        C          D                     -       -          D          -
// TUNABLE      P          D                     -       -          D          -
// DISCRETE     -          -                     U       X/Q/0      X/Q/0      -
// CONTINUOUS   -          -                     U       X/Q/W/Z/0  X/Q/W/Z/0  X/Q/T/0
 
// Variable categories
enum class Category {T, C, P, D, W, U, X, Z, Q, CALCULATED,
  ODE, ALG, QUAD, ZERO, DDEF, WDEF, Y, NUMEL};
 
enum class Initial {EXACT, APPROX, CALCULATED, NA, NUMEL};
 
// Attributes
enum class Attribute {MIN, MAX, NOMINAL, START, VALUE, STRINGVALUE, NUMEL};
 
// Permitted dependenciesKind values
enum class DependenciesKind {DEPENDENT, CONSTANT, FIXED, TUNABLE, DISCRETE, NUMEL};
 
struct CASADI_EXPORT Variable {
  friend class DaeBuilderInternal;
 
 private:
  Variable(casadi_int index, const std::string& name,
    const std::vector<casadi_int>& dimension, const MX& expr);
 
 public:
  casadi_int index;
 
  std::string name;
 
  std::vector<casadi_int> dimension;
 
  casadi_int numel;
 
  unsigned int value_reference;
  std::string description;
  Type type;
  Causality causality;
  Variability variability;
 
  Category category;
 
  // std::string declared_type;
  std::string unit;
  std::string display_unit;
  Initial initial;
  // std::string quantity;
  // bool relative_quantity;
  // bool unbounded;
  double min;
  double max;
  double nominal;
  std::vector<double> start;
  casadi_int der_of;  // 'derivative' in FMI specification
  casadi_int parent;
 
  // corresponding derivative variable, if any
  casadi_int der;
 
  // corresponding binding expression, if any
  casadi_int bind;
 
  // Does it appear in any right-hand-side?
  bool in_rhs;
 
  std::vector<double> value;
 
  std::string stringvalue;
 
  bool dependency;
 
  mutable std::vector<casadi_int> dependencies;
 
  mutable std::vector<DependenciesKind> dependenciesKind;
 
  MX v;
 
  MX ieq;
 
  casadi_int size(Attribute a) const;
 
  void get_attribute(Attribute a, double* val) const;
  void get_attribute(Attribute a, std::vector<double>* val) const;
  void get_attribute(Attribute a, std::string* val) const;
 
  void set_attribute(Attribute a, double val);
  void set_attribute(Attribute a, const std::vector<double>& val);
  void set_attribute(Attribute a, const std::string& val);
 
  // Export as XML
  XmlNode export_xml(const DaeBuilderInternal& self) const;
 
  // Is the variable real?
  bool is_real() const {return type == Type::FLOAT32 || type == Type::FLOAT64;}
 
  // Does the variable need a start attribute?
  bool has_start() const;
 
  // Unused derivative variable?
  bool has_der() const {
    return der != size_t(-1) || causality == Causality::INDEPENDENT;
  }
 
  // Permitted categories for the variable
  std::vector<Category> categories() const;
 
  // Is a category permitted for the variable?
  bool permitted(Category cat) const;
 
  // Has the variable been set
  bool is_set() const {
    return !(type==Type::STRING ? stringvalue.empty() : std::isnan(value.front()));
  }
 
  // Does the variable have a binding equation
  bool has_beq() const {return bind >= 0;}
 
  // Does the variable need a derivative variable?
  bool needs_der() const;
 
  // Derivative of the expression, create at first encounter
  MX get_der(DaeBuilderInternal& self, bool may_allocate = true);
 
  // Derivative of the expression, never create
  MX get_der(const DaeBuilderInternal& self) const;
};
 
class CASADI_EXPORT DaeBuilderInternal : public SharedObjectInternal {
  friend class DaeBuilder;
  friend class FmuInternal;
  friend class FmuFunction;
  friend class Variable;
 
 public:
 
  explicit DaeBuilderInternal(const std::string& name, const std::string& path, const Dict& opts);
 
  ~DaeBuilderInternal() override;
 
  std::string class_name() const override {return "DaeBuilderInternal";}
 
  void sanity_check() const;
 
 
  void eliminate(Category cat);
 
  void sort(Category cat);
 
  void lift(bool lift_shared, bool lift_calls);
 
  void sort_z(const std::vector<std::string>& z_order);
 
  std::vector<size_t>& indices(Category cat);
 
  const std::vector<size_t>& indices(Category cat) const;
 
  size_t size(Category cat) const {return indices(cat).size();}
 
  void reorder(Category cat, const std::vector<size_t>& v);
 
  void reorder(const std::string& n, std::vector<size_t>& ind,
    const std::vector<size_t>& v) const;
 
  void prune(bool prune_p, bool prune_u);
 
  void tearing_variables(std::vector<std::string>* res, std::vector<std::string>* iv,
    std::vector<std::string>* iv_on_hold) const;
 
  void tear();
 
  void load_fmi_description(const std::string& filename);
 
  static std::string iso_8601_time();
 
  // Generate a random 32 digit hexadecimal number
  static std::string generate_guid();
 
  Dict export_fmu(const Dict& opts) const;
 
  Dict compile_fmu(const Dict& files, const Dict& opts) const;
 
  std::string pack_fmu(const Dict& files, const Dict& opts) const;
 
  std::string generate_wrapper(const std::string& guid, const CodeGenerator& gen) const;
 
  std::string generate_build_description(const std::vector<std::string>& cfiles) const;
 
  std::string generate_model_description(const std::string& guid) const;
 
  XmlNode generate_model_variables() const;
 
  XmlNode generate_model_structure(bool dae = false) const;
 
  void update_dependencies() const;
 
  static std::string generate(const std::vector<size_t>& v);
  static std::string generate(const std::vector<double>& v);
 
  // Get input expressions, given enum
  std::vector<MX> inputs(Category ind) const;
 
  // Get output expressions, given enum
  std::vector<MX> outputs(Category ind) const;
 
  // Get input expressions, given enum
  std::vector<MX> inputs(const std::vector<Category>& ind) const;
 
  // Get output expressions, given enum
  std::vector<MX> outputs(const std::vector<Category>& ind) const;
 
  void add_lc(const std::string& name, const std::vector<std::string>& f_out);
 
  Function create(const std::string& fname,
      const std::vector<std::string>& name_in,
      const std::vector<std::string>& name_out,
      const Dict& opts, bool sx, bool lifted_calls) const;
 
  Function fmu_fun(const std::string& fname,
      const std::vector<std::string>& name_in,
      const std::vector<std::string>& name_out,
      const Dict& opts) const;
 
  Function dependent_fun(const std::string& fname,
      const std::vector<std::string>& s_in,
      const std::vector<std::string>& s_out) const;
 
  Function transition(const std::string& fname, casadi_int index,
    bool dummy_index_input = false) const;
 
  Function transition(const std::string& fname) const;
 
  Function gather_eq() const;
 
  const MX& var(const std::string& name) const;
 
  MX get_der(size_t ind) const {return variable(ind).get_der(*this);}
 
  MX get_der(size_t ind, bool may_allocate = true) {
    return variable(ind).get_der(*this, may_allocate);
  }
 
  MX der(const MX& var) const;
 
  MX der(const MX& var, bool may_allocate = true);
 
  std::string unique_name(const std::string& prefix, bool allow_no_prefix = false) const;
 
  std::string type_name() const {return "DaeBuilderInternal";}
 
  void disp(std::ostream& stream, bool more) const override;
 
  std::string get_str(bool more=false) const {
    std::stringstream ss;
    disp(ss, more);
    return ss.str();
  }
 
  Variable& new_variable(const std::string& name,
    const std::vector<casadi_int>& dimension = {1},
    const MX& expr = MX());
 
  bool has(const std::string& name) const;
 
  std::vector<std::string> all() const;
 
  std::vector<std::string> all(Category cat) const;
 
  size_t n_variables() const {return variables_.size();}
 
  size_t n_mem() const;
 
  std::vector<double> start_all() const;
 
  Variable& variable(size_t ind) {return *variables_.at(ind);}
  const Variable& variable(size_t ind) const {return *variables_.at(ind);}
 
  Variable& variable(Category cat, size_t ind) {return variable(indices(cat).at(ind));}
  const Variable& variable(Category cat, size_t ind) const {
    return variable(indices(cat).at(ind));
  }
 
  Variable& variable(const std::string& name) {return variable(find(name));}
  const Variable& variable(const std::string& name) const {return variable(find(name));}
 
  Variable& variable(const MX& v) {return variable(find(v));}
  const Variable& variable(const MX& v) const {return variable(find(v));}
 
  const MX& var(size_t ind) const;
 
  const MX& var(Category cat, size_t ind) const {return var(indices(cat).at(ind));}
 
  std::vector<MX> var(const std::vector<size_t>& ind) const;
 
  std::vector<MX> var(Category cat) const {return var(indices(cat));}
 
  size_t find(const std::string& name) const;
 
  size_t find(const MX& v) const;
 
  std::vector<size_t> find(const std::vector<std::string>& name) const;
 
  std::vector<size_t> find(const std::vector<MX>& v) const;
 
  const std::string& name(size_t ind) const;
 
  std::vector<std::string> name(const std::vector<size_t>& ind) const;
 
  const Function& oracle(bool sx = false, bool elim_w = false, bool lifted_calls = false) const;
 
  Sparsity jac_sparsity(const std::vector<size_t>& oind, const std::vector<size_t>& iind) const;
 
  Sparsity hess_sparsity(const std::vector<size_t>& oind, const std::vector<size_t>& iind) const;
 
  // Internal methods
protected:
 
  static std::string qualified_name(const XmlNode& nn, Attribute* att = nullptr);
 
  // User-set options
  bool debug_;
  double fmutol_;
  bool ignore_time_;
  bool enable_ls_dae_, enable_ls_serialization_;
 
  // FMI attributes
  std::string fmi_version_;
  std::string model_name_;
  std::string instantiation_token_;  // In FMI 2: guid
  std::string description_;
  std::string author_;
  std::string copyright_;
  std::string license_;
  std::string generation_tool_;
  std::string generation_date_and_time_;
  std::string variable_naming_convention_;
  casadi_int nzero_;
 
  // Default experiment
  double start_time_, stop_time_, tolerance_, step_size_;
 
  // Model Exchange
  std::string model_identifier_;
  bool provides_directional_derivatives_;
  bool provides_adjoint_derivatives_;
  bool can_be_instantiated_only_once_per_process_;
  std::vector<std::string> source_files_;
 
  std::string name_;
 
  // Path to FMU, if any
  Resource resource_;
 
  // Symbolic representation of the model equations?
  bool symbolic_;
 
  // Original index of the independent variable, if any
  casadi_int orig_time_index_;
 
  // Detect quadrature states
  bool detect_quad_;
 
  // FMI major version
  casadi_int fmi_major_;
 
  std::vector<Variable*> variables_;
 
  // Model structure
  std::vector<size_t> der_, initial_unknowns_;
 
  std::unordered_map<std::string, size_t> varind_;
 
  std::unordered_map<unsigned int, size_t> vrmap_;
 
  std::vector<std::vector<size_t>> indices_;
 
  // Initial equations
  std::vector<size_t> init_;
 
  // Event conditions and transition equations
  std::vector<std::pair<size_t, std::vector<size_t>>> when_;
 
  // Convert XML model variable index to DaeBuilder index
  casadi_int convert_index(casadi_int index) const;
 
  bool has_t() const;
 
  // Time variable
  const MX& time() const;
 
  std::vector<MX> cdef() const;
 
  std::vector<MX> init_lhs() const;
 
  std::vector<MX> init_rhs() const;
 
  static Variability default_variability(Causality causality, Type type);
 
  // Default initial attribute, per the FMI specification
  static Initial default_initial(Causality causality, Variability variability);
 
  Variable& add(const std::string& name, Causality causality, Variability variability,
    const Dict& opts);
 
  Variable& add(const std::string& name, Causality causality, Variability variability,
    const MX& expr, const Dict& opts);
 
  Variable& add(const std::string& name, Causality causality, const Dict& opts);
 
  Variable& add(const std::string& name, const Dict& opts) {
    // Per FMI 3.0.2 specification, section 2.4.7.4: Default causality is LOCAL
    return add(name, Causality::LOCAL, opts);
  }
 
  void categorize(size_t ind, Category cat);
 
  void insert(std::vector<size_t>& v, size_t ind) const;
 
  void remove(std::vector<size_t>& v, size_t ind) const;
 
  Causality causality(size_t ind) const;
 
  void set_causality(size_t ind, Causality causality);
 
  Variability variability(size_t ind) const;
 
  void set_variability(size_t ind, Variability variability);
 
  Category category(size_t ind) const;
 
  void set_category(size_t ind, Category cat);
 
  void eq(const MX& lhs, const MX& rhs, const Dict& opts);
 
  void when(const MX& cond, const std::vector<std::string>& eqs, const Dict& opts);
 
  Variable& assign(const std::string& name, const MX& val);
 
  Variable& reinit(const std::string& name, const MX& val);
 
  void set_init(const std::string& name, const MX& init_rhs);
 
  Function::AuxOut lc_;
 
  std::vector<Function> fun_;
 
  mutable Function oracle_[2][2][2];
 
  mutable bool clear_cache_;
 
  MX read_expr(const XmlNode& node);
 
  MX read_identifier(const XmlNode& node);
 
  Variable& read_variable(const XmlNode& node, Attribute* att = nullptr);
 
  // Read DefaultExperiment
  void import_default_experiment(const XmlNode& n);
 
  // Read dependencies node
  std::vector<casadi_int> read_dependencies(const XmlNode& n);
 
  // Read dependenciesKind node
  std::vector<DependenciesKind> read_dependencies_kind(const XmlNode& n, size_t ndep);
 
  // Read ModelExchange
  void import_model_exchange(const XmlNode& n);
 
  void import_model_variables(const XmlNode& modvars);
 
  // Read ModelStructure
  void import_model_structure(const XmlNode& n);
 
  // Read LS-DAE manifest, if any
  XmlNode import_ls_dae(const std::string& lsdae);
 
  // Read symbolic binding equations
  void import_binding_equations(const XmlNode& eqs);
 
  // Read symbolic dynamic equations
  void import_dynamic_equations(const XmlNode& eqs);
 
  // Read symbolic initial equations
  void import_initial_equations(const XmlNode& eqs);
 
  void clear_cache() const;
 
  Function add_fun(const std::string& name,
                   const std::vector<std::string>& arg,
                   const std::vector<std::string>& res, const Dict& opts=Dict());
 
  Function add_fun(const Function& f);
 
  bool has_fun(const std::string& name) const;
 
  Function fun(const std::string& name) const;
 
  // Reset value attributes
  void reset();
 
  double attribute(Attribute a, const std::string& name) const;
  std::vector<double> attribute(Attribute a, const std::vector<std::string>& name) const;
 
  void set_attribute(Attribute a, const std::string& name, double val);
  void set_attribute(Attribute a, const std::vector<std::string>& name,
    const std::vector<double>& val);
 
  std::string string_attribute(Attribute a, const std::string& name) const;
  std::vector<std::string> string_attribute(Attribute a,
    const std::vector<std::string>& name) const;
 
  void set_string_attribute(Attribute a, const std::string& name, const std::string& val);
  void set_string_attribute(Attribute a, const std::vector<std::string>& name,
    const std::vector<std::string>& val);
 
  casadi_int size(Attribute a, const std::vector<std::string>& name) const;
 
  struct CallIO {
    // Function instances
    Function f, adj1_f, J, H;
    // Index in v and vdef
    std::vector<size_t> v, vdef;
    // Nondifferentiated inputs
    std::vector<MX> arg;
    // Nondifferentiated inputs
    std::vector<MX> res;
    // Jacobian outputs
    std::vector<MX> jac_res;
    // Adjoint seeds
    std::vector<MX> adj1_arg;
    // Adjoint sensitivities
    std::vector<MX> adj1_res;
    // Hessian outputs
    std::vector<MX> hess_res;
    // Calculate Jacobian blocks
    void calc_jac();
    // Calculate gradient of Lagrangian
    void calc_grad();
    // Calculate Hessian of Lagrangian
    void calc_hess();
    // Access a specific Jacobian block
    const MX& jac(casadi_int oind, casadi_int iind) const;
    // Access a specific Hessian block
    const MX& hess(casadi_int iind1, casadi_int iind2) const;
  };
 
  MX jac_vdef_v_from_calls(std::map<MXNode*, CallIO>& call_nodes,
    const std::vector<casadi_int>& h_offsets) const;
 
  MX hess_v_v_from_calls(std::map<MXNode*, CallIO>& call_nodes,
    const std::vector<casadi_int>& h_offsets) const;
 
  // Sort dependent variables/parameters
  static void sort_dependent(std::vector<MX>& v, std::vector<MX>& vdef);
};
 
CASADI_EXPORT Type from_fmi2(TypeFmi2 v);
CASADI_EXPORT TypeFmi2 to_fmi2(Type v);
 
CASADI_EXPORT std::string to_string(TypeFmi2 v);
CASADI_EXPORT std::string to_string(Type v);
CASADI_EXPORT std::string to_string(Causality v);
CASADI_EXPORT std::string to_string(Variability v);
CASADI_EXPORT std::string to_string(Initial v);
CASADI_EXPORT std::string to_string(Attribute v);
CASADI_EXPORT std::string to_string(DependenciesKind v);
CASADI_EXPORT std::string to_string(Category v);
 
CASADI_EXPORT std::string description(Category v);
 
// Check if input category
CASADI_EXPORT bool is_input_category(Category cat);
 
// Check if output category
CASADI_EXPORT bool is_output_category(Category cat);
 
// Check if acyclic dependency category
CASADI_EXPORT bool is_acyclic(Category cat);
 
// Definition for acyclyc dependency categories
CASADI_EXPORT Category dependent_definition(Category cat);
 
// Get all input categories
CASADI_EXPORT std::vector<Category> input_categories();
 
// Get all output categories
CASADI_EXPORT std::vector<Category> output_categories();
 
// Get the input category for a particular output category
CASADI_EXPORT Category input_category(Category cat);
 
 
} // namespace casadi
 
#endif // CASADI_DAE_BUILDER_INTERNAL_HPP