OptionSet.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 <map>
#include <string>
#include <memory>
 
#include "neml2/base/Option.h"
#include "neml2/misc/errors.h"
#include "neml2/misc/string_utils.h"
#include "neml2/misc/types.h"
 
namespace neml2
{
// Forward decl
class OptionSet;
template <typename T>
struct TensorName;
 
bool options_compatible(const OptionSet & opts, const OptionSet & additional_opts);
 
// Streaming operators
std::ostream & operator<<(std::ostream & os, const OptionSet & p);

class OptionSet
{
public:
  OptionSet() = default;
 
  OptionSet(const OptionSet &);
  OptionSet(OptionSet &&) noexcept;
  OptionSet & operator=(const OptionSet &);
  OptionSet & operator=(OptionSet &&) noexcept;
  virtual ~OptionSet() = default;


  void operator+=(const OptionSet & source);
  void operator+=(OptionSet && source);

  const std::string & name() const { return _metadata.name; }
  std::string & name() { return _metadata.name; }
  const std::string & type() const { return _metadata.type; }
  std::string & type() { return _metadata.type; }
  const std::string & path() const { return _metadata.path; }
  std::string & path() { return _metadata.path; }
  const std::string & doc() const { return _metadata.doc; }
  std::string & doc() { return _metadata.doc; }
  const std::string & section() const { return _metadata.section; }
  std::string & section() { return _metadata.section; }

  bool contains(const std::string &) const;

  bool user_specified(const std::string & name) const;

  bool defined(const std::string & name) const;

  void suppress(const std::string & name);

  std::size_t size() const { return _values.size(); }

  void clear();

  std::string to_str() const;

  template <typename T>
  T get(const std::string &) const;

  const OptionBase & get(const std::string &) const;

  template <typename K, typename V>
  std::map<K, V> get_map(const std::string &, const std::string &) const;

  template <typename T, FType f = FType::NONE>
  void add(const std::string & name, const T & default_value, std::string doc);

  template <typename T, FType f = FType::NONE>
  void add(const std::string & name, std::string doc);

  template <typename T, FType f = FType::NONE>
  void add_optional(const std::string & name, std::string doc);

  template <typename T>
  void add_private(const std::string & name, const T & default_value);

  template <typename T>
  void set(const std::string & name, const T & value);

  template <typename T>
  void set_private(const std::string & name, const T & value);

  void add_input(const std::string &, const VariableName &, std::string);
  void add_input(const std::string &, std::string);
  void add_optional_input(const std::string &, std::string);
  void add_output(const std::string &, const VariableName &, std::string);
  void add_output(const std::string &, std::string);
  void add_optional_output(const std::string &, std::string);
  template <typename T>
  void add_parameter(const std::string &, const TensorName<T> &, std::string);
  template <typename T>
  void add_parameter(const std::string &, std::string);
  template <typename T>
  void add_buffer(const std::string &, const TensorName<T> &, std::string);
  template <typename T>
  void add_buffer(const std::string &, std::string);

  using map_type = std::map<std::string, std::unique_ptr<OptionBase>, std::less<>>;
  using iterator = map_type::iterator;
  using const_iterator = map_type::const_iterator;

  iterator begin();
  const_iterator begin() const;
  iterator end();
  const_iterator end() const;
 
protected:
  struct Metadata
  {
    std::string name = "";
    std::string type = "";
    std::string path = "";
    std::string doc = "";
    std::string section = "";
  } _metadata;

  map_type _values;
};

// Implementation
 
template <typename T>
T
OptionSet::get(const std::string & name) const
{
  if (!this->contains(name))
    throw NEMLException("ERROR: no option named \"" + name + "\" found.\n\nKnown options:\n" +
                        to_str());
 
  auto * opt_base = _values.at(name).get();
  if (!opt_base->defined())
    throw NEMLException("ERROR: option named \"" + name +
                        "\" is being accessed before it is defined.");
 
  auto ptr = dynamic_cast<Option<T> *>(opt_base);
  if (!ptr)
    throw NEMLException("ERROR: option named \"" + name +
                        "\" is not of the requested type: " + opt_base->type());
  return ptr->get();
}
 
template <typename K, typename V>
std::map<K, V>
OptionSet::get_map(const std::string & key_option, const std::string & value_option) const
{
  const auto keys = this->get<std::vector<K>>(key_option);
  const auto values = this->get<std::vector<V>>(value_option);
  if (keys.size() != values.size())
    throw NEMLException("Trying to build a map from '" + key_option + "' and '" + value_option +
                        "' with " + std::to_string(keys.size()) + " keys and " +
                        std::to_string(values.size()) + " values.");
  std::map<K, V> result;
  for (size_t i = 0; i < keys.size(); i++)
  {
    if (result.find(keys[i]) != result.end())
      throw NEMLException("Trying to build a map from '" + key_option + "' and '" + value_option +
                          "' with duplicate key: " + utils::stringify(keys[i]));
    result[keys[i]] = values[i];
  }
  return result;
}
 
template <typename T, FType F>
void
OptionSet::add(const std::string & name, const T & default_value, std::string doc)
{
  if (this->contains(name))
    throw NEMLException("Trying to add option '" + name +
                        "', but an option with the same name already exists.");
  _values[name] = std::make_unique<Option<T>>(name);
  auto ptr = dynamic_cast<Option<T> *>(_values[name].get());
 
  // docstring and Ftype are always needed
  ptr->doc() = std::move(doc);
  ptr->ftype() = F;
 
  // default value
  ptr->set() = default_value;
 
  // metadata
  ptr->required() = false;
  ptr->suppressed() = false;
  ptr->user_specified() = false;
  ptr->defined() = true;
}
 
template <typename T, FType F>
void
OptionSet::add(const std::string & name, std::string doc)
{
  if (this->contains(name))
    throw NEMLException("Trying to add option '" + name +
                        "', but an option with the same name already exists.");
  _values[name] = std::make_unique<Option<T>>(name);
  auto ptr = dynamic_cast<Option<T> *>(_values[name].get());
 
  // docstring and Ftype are always needed
  ptr->doc() = std::move(doc);
  ptr->ftype() = F;
 
  // metadata
  ptr->required() = true;
  ptr->suppressed() = false;
  ptr->user_specified() = false;
  ptr->defined() = false;
}
 
template <typename T, FType F>
void
OptionSet::add_optional(const std::string & name, std::string doc)
{
  if (this->contains(name))
    throw NEMLException("Trying to add option '" + name +
                        "', but an option with the same name already exists.");
  _values[name] = std::make_unique<Option<T>>(name);
  auto ptr = dynamic_cast<Option<T> *>(_values[name].get());
 
  // docstring and Ftype are always needed
  ptr->doc() = std::move(doc);
  ptr->ftype() = F;
 
  // metadata
  ptr->required() = false;
  ptr->suppressed() = false;
  ptr->user_specified() = false;
  ptr->defined() = false;
}
 
template <typename T>
void
OptionSet::add_private(const std::string & name, const T & default_value)
{
  if (this->contains(name))
    throw NEMLException("Trying to add a private option '" + name +
                        "', but an option with the same name already exists.");
  _values[name] = std::make_unique<Option<T>>(name);
  auto ptr = dynamic_cast<Option<T> *>(_values[name].get());
 
  // default value
  ptr->set() = default_value;
 
  // metadata
  ptr->required() = false;
  ptr->suppressed() = true;
  ptr->user_specified() = false;
  ptr->defined() = true;
}
 
template <typename T>
void
OptionSet::set(const std::string & name, const T & value)
{
  if (!this->contains(name))
    throw NEMLException("Trying to set option '" + name + "', but it does not exist.");
 
  auto ptr = dynamic_cast<Option<T> *>(_values[name].get());
 
  if (ptr->suppressed())
    throw NEMLException("Trying to set private option '" + name +
                        "', which is not allowed. Use set_private() instead.");
 
  // value
  ptr->set() = value;
 
  // metadata
  ptr->user_specified() = false;
  ptr->defined() = true;
}
 
template <typename T>
void
OptionSet::set_private(const std::string & name, const T & value)
{
  if (!this->contains(name))
    throw NEMLException("Trying to set private option '" + name + "', but it does not exist.");
 
  auto ptr = dynamic_cast<Option<T> *>(_values[name].get());
 
  if (!ptr->suppressed())
    throw NEMLException("Trying to set private option '" + name +
                        "', but it is not marked as private.");
 
  // value
  ptr->set() = value;
 
  // metadata
  ptr->user_specified() = false;
  ptr->defined() = true;
}
 
template <typename T>
void
OptionSet::add_parameter(const std::string & name,
                         const TensorName<T> & tensor_name,
                         std::string doc)
{
  add<TensorName<T>, FType::PARAMETER>(name, tensor_name, std::move(doc));
}
 
template <typename T>
void
OptionSet::add_parameter(const std::string & name, std::string doc)
{
  add<TensorName<T>, FType::PARAMETER>(name, std::move(doc));
}
 
template <typename T>
void
OptionSet::add_buffer(const std::string & name, const TensorName<T> & tensor_name, std::string doc)
{
  add<TensorName<T>, FType::BUFFER>(name, tensor_name, std::move(doc));
}
 
template <typename T>
void
OptionSet::add_buffer(const std::string & name, std::string doc)
{
  add<TensorName<T>, FType::BUFFER>(name, std::move(doc));
}
 
} // namespace neml2