Model.h

// Copyright 2024, UChicago Argonne, LLC
// All Rights Reserved
// Software Name: NEML2 -- the New Engineering material Model Library, version 2
// By: Argonne National Laboratory
// OPEN SOURCE LICENSE (MIT)
//
// Permission is hereby granted, free of charge, to any person obtaining a copy
// of this software and associated documentation files (the "Software"), to deal
// in the Software without restriction, including without limitation the rights
// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
// copies of the Software, and to permit persons to whom the Software is
// furnished to do so, subject to the following conditions:
//
// The above copyright notice and this permission notice shall be included in
// all copies or substantial portions of the Software.
//
// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
// THE SOFTWARE.
 
#pragma once
 
#include "neml2/models/DependencyDefinition.h"
#include "neml2/base/DiagnosticsInterface.h"
 
#include "neml2/models/Data.h"
#include "neml2/models/ParameterStore.h"
#include "neml2/models/VariableStore.h"
#include "neml2/models/NonlinearParameter.h"
#include "neml2/tensors/jit.h"
 
// These headers are not directly used by Model, but are included here so that derived classes do
// not have to include them separately. This is a convenience for the user, and is a reasonable
// choice since these headers are light and bring in little dependency.
#include "neml2/base/LabeledAxis.h"
#include "neml2/models/Variable.h"
#include "neml2/tensors/Derivative.h"
 
namespace neml2
{
class Model;

bool & currently_assembling_nonlinear_system();
 
// Guard a region where implicit solve is being performed
struct AssemblyingNonlinearSystem
{
  AssemblyingNonlinearSystem(bool assembling = true);
 
  AssemblyingNonlinearSystem(const AssemblyingNonlinearSystem &) = delete;
  AssemblyingNonlinearSystem(AssemblyingNonlinearSystem &&) = delete;
  AssemblyingNonlinearSystem & operator=(const AssemblyingNonlinearSystem &) = delete;
  AssemblyingNonlinearSystem & operator=(AssemblyingNonlinearSystem &&) = delete;
  ~AssemblyingNonlinearSystem();
 
  const bool prev_bool;
};

class Model : public std::enable_shared_from_this<Model>,
              public Data,
              public ParameterStore,
              public VariableStore,
              public DependencyDefinition<VariableName>,
              public DiagnosticsInterface
{
public:
  struct EvaluationSchema
  {
    std::vector<Size> dynamic_dims;
    std::vector<TensorShape> intmd_shapes;
    at::DispatchKey dispatch_key;
    bool operator==(const EvaluationSchema & other) const;
    bool operator!=(const EvaluationSchema & other) const;
    bool operator<(const EvaluationSchema & other) const;
  };
 
  static OptionSet expected_options();

  Model(const OptionSet & options);
 
  void setup() override;
 
  void diagnose() const override;

  virtual bool defines_values() const { return _defines_value; }

  virtual bool defines_derivatives() const { return _defines_dvalue; }

  virtual bool defines_second_derivatives() const { return _defines_d2value; }

  virtual bool is_jit_enabled() const { return _jit; }

  virtual void to(const TensorOptions & options);

  const std::vector<std::shared_ptr<Model>> & registered_models() const
  {
    return _registered_models;
  }

  std::shared_ptr<Model> registered_model(const std::string & name) const;

  void register_nonlinear_parameter(const std::string & pname, const NonlinearParameter & param);

  bool has_nl_param(bool recursive = false) const;

  const VariableBase * nl_param(const std::string &) const;

  virtual std::map<std::string, NonlinearParameter>
  named_nonlinear_parameters(bool recursive = false) const;

  std::set<VariableName> consumed_items() const override;
  std::set<VariableName> provided_items() const override;

  void request_AD(VariableBase & y, const VariableBase & u);

  void request_AD(VariableBase & y, const VariableBase & u1, const VariableBase & u2);
 
  void clear_input() override;
  void clear_output() override;
  void zero_undefined_input() override;

  void forward_maybe_jit(bool out, bool dout, bool d2out);

  std::string variable_name_lookup(const ATensor & var) const;

  virtual ValueMap value(const ValueMap & in);

  virtual std::tuple<ValueMap, DerivMap> value_and_dvalue(const ValueMap & in);

  virtual DerivMap dvalue(const ValueMap & in);

  virtual std::tuple<ValueMap, DerivMap, SecDerivMap>
  value_and_dvalue_and_d2value(const ValueMap & in);

  virtual SecDerivMap d2value(const ValueMap & in);

  virtual std::tuple<DerivMap, SecDerivMap> dvalue_and_d2value(const ValueMap & in);

  friend class ParameterStore;

  friend class ComposedModel;

  friend class ModelNonlinearSystem;
 
protected:
  void diagnostic_assert_state(const VariableBase & v) const;
  void diagnostic_assert_old_state(const VariableBase & v) const;
  void diagnostic_assert_force(const VariableBase & v) const;
  void diagnostic_assert_old_force(const VariableBase & v) const;
  void diagnostic_assert_residual(const VariableBase & v) const;
  void diagnostic_check_input_variable(const VariableBase & v) const;
  void diagnostic_check_output_variable(const VariableBase & v) const;
 
  virtual void link_input_variables();
  virtual void link_input_variables(Model * submodel);
  virtual void link_output_variables();
  virtual void link_output_variables(Model * submodel);

  void check_precision() const;

  virtual std::string failed_graph_execution_hint() const;

  virtual void request_AD() {}

  void forward(bool out, bool dout, bool d2out);

  virtual void set_value(bool out, bool dout_din, bool d2out_din2) = 0;

  template <typename T = Model, typename = typename std::enable_if_t<std::is_base_of_v<Model, T>>>
  T & register_model(const std::string & name, bool merge_input = true)
  {
    auto model_name =
        input_options().contains(name) ? input_options().get<std::string>(name) : name;
    if (model_name == this->name())
      throw SetupException("Model named '" + this->name() +
                           "' is trying to register itself as a sub-model. This is not allowed.");
 
    OptionSet extra_opts;
    extra_opts.set<NEML2Object *>("_host") = host();
 
    if (!host()->factory())
      throw SetupException("Internal error: Host object '" + host()->name() +
                           "' does not have a factory set.");
    auto model = host()->factory()->get_object<T>("Models", model_name, extra_opts);
 
    register_model(model, merge_input);
    return *model;
  }

  template <typename T = Model, typename = typename std::enable_if_t<std::is_base_of_v<Model, T>>>
  void register_model(const std::shared_ptr<T> & model, bool merge_input = true)
  {
    if (std::find(_registered_models.begin(), _registered_models.end(), model) !=
        _registered_models.end())
      throw SetupException("Model named '" + model->name() + "' has already been registered.");
 
    if (merge_input)
      for (auto && [name, var] : model->input_variables())
        clone_input_variable(*var);
 
    _registered_models.push_back(model);
  }
 
  void assign_input_stack(jit::Stack & stack);
 
  jit::Stack collect_input_stack() const;

  std::vector<std::shared_ptr<Model>> _registered_models;
 
private:
  template <typename T>
  void forward_helper(T && in, bool out, bool dout, bool d2out)
  {
    check_precision();
    assign_input(std::forward<T>(in));
    zero_undefined_input();
    forward_maybe_jit(out, dout, d2out);
  }

  void enable_AD();

  void extract_AD_derivatives(bool dout, bool d2out);

  std::size_t forward_operator_index(bool out, bool dout, bool d2out) const;

  EvaluationSchema calculate_eval_schema() const;

  bool _defines_value;
  bool _defines_dvalue;
  bool _defines_d2value;

  std::map<std::string, NonlinearParameter> _nl_params;

  std::map<VariableBase *, std::set<const VariableBase *>> _ad_derivs;
  std::map<VariableBase *, std::map<const VariableBase *, std::set<const VariableBase *>>>
      _ad_secderivs;
  std::set<VariableBase *> _ad_args;

  const bool _jit;

  const bool _production;

  std::array<std::map<EvaluationSchema, std::unique_ptr<jit::GraphFunction>>, 8> _traced_functions;

  std::array<std::map<EvaluationSchema, std::unique_ptr<jit::GraphFunction>>, 8>
      _traced_functions_nl_sys;

  bool _currently_assembling_nonlinear_system = false;
};
 
std::ostream & operator<<(std::ostream & os, const Model & model);
} // namespace neml2