oracle.h

Go to the documentation of this file.

 
#if !defined(ULTRA_ORACLE_H)
#define      ULTRA_ORACLE_H
 
#include "kernel/exceptions.h"
#include "kernel/gp/src/predictor.h"
#include "kernel/gp/src/interpreter.h"
#include "kernel/gp/team.h"
 
#include <numbers>
 
namespace ultra::src
{
 
#include "kernel/gp/src/oracle_internal.tcc"
 
// Forward declarations.
class basic_oracle;
 
namespace serialize
{
 
namespace oracle
{
 
template<Individual P = gp::individual>
[[nodiscard]] std::unique_ptr<basic_oracle>
load(std::istream &, const symbol_set &);
 
}  // namespace oracle
 
bool save(std::ostream &, const basic_oracle *);
bool save(std::ostream &, const basic_oracle &);
bool save(std::ostream &, const std::unique_ptr<basic_oracle> &);
 
}  // namespace serialize


/// `basic_oracle` always calculates a meaningful value for the end-user (the
/// class of an example, an approximation...) while `src::interpreter` often
/// outputs an intermediate value that is just a building block for
/// `basic_oracle` (e.g. classification tasks with discriminant functions).
/// The typical use chain is:
/// src::evaluator --[uses]--> basic_oracle --[uses]--> interpreter.
///
/// \note
/// Another interesting function of `basic_oracle` is that it extends the
/// functionalities of interpreter to teams.
///
class basic_oracle
{
public:
  virtual ~basic_oracle() = default;
 
  [[nodiscard]] virtual value_t operator()(
    const std::vector<value_t> &) const = 0;
 
  [[nodiscard]] virtual bool is_valid() const = 0;
 
  [[nodiscard]] virtual std::string name(const value_t &) const = 0;
  [[nodiscard]] virtual classification_result tag(
    const std::vector<value_t> &) const = 0;
 
private:
  // ---- Serialization ----
  [[nodiscard]] virtual std::string serialize_id() const = 0;
  virtual bool save(std::ostream &) const = 0;
 
  template<Individual P> friend std::unique_ptr<basic_oracle>
  serialize::oracle::load(std::istream &, const symbol_set &);
  friend bool serialize::save(std::ostream &, const basic_oracle &);
};
 
// ***********************************************************************
// * Symbolic regression                                                 *
// ***********************************************************************

///           everything it needs inside (it will survive the death of the
///           individual it's constructed on). Sometimes we prefer space
///           efficiency (typically inside an evaluator)
///
template<Individual P, bool S>
class basic_reg_oracle : public basic_oracle,
                         protected internal::reg_oracle_storage<P, S>
{
public:
  explicit basic_reg_oracle(const P &);
  basic_reg_oracle(std::istream &, const symbol_set &);
 
  [[nodiscard]] value_t operator()(const std::vector<value_t> &) const final;
 
  [[nodiscard]] std::string name(const value_t &) const final;
 
  [[nodiscard]] bool is_valid() const final;
 
  // ---- Serialization ----
  static const std::string SERIALIZE_ID;
  bool save(std::ostream &) const final;
 
private:
  // Not useful for regression tasks and moved to private section.
  [[noreturn]] classification_result tag(
    const std::vector<value_t> &) const final;
 
  [[nodiscard]] std::string serialize_id() const noexcept final
  { return SERIALIZE_ID; }
};

/// \tparam O predictor type
///
/// This adaptor allows any user-defined regression predictor to be used as a
/// `basic_oracle`. The wrapped predictor must satisfy `RegressionPredictor`,
/// i.e. be callable with an input example and return a `value_t`.
///
/// \note
/// Calling `tag()` on this adaptor is invalid and results in an exception.
///
/// \note
/// The adaptor is intentionally non-serializable.
///
template<RegressionPredictor O>
class reg_oracle_adaptor final : public basic_oracle
{
public:
  explicit reg_oracle_adaptor(O);
 
  [[nodiscard]] value_t operator()(const std::vector<value_t> &) const override;

  [[nodiscard]] bool is_valid() const override { return true; }
 
  [[nodiscard]] std::string name(const value_t &v) const override;
 
private:
  [[noreturn]] classification_result tag(
    const std::vector<value_t> &) const override;
  [[nodiscard]] std::string serialize_id() const override;
  bool save(std::ostream &) const override;
 
  O oracle_;
};
 
// ***********************************************************************
// * Classification                                                      *
// ***********************************************************************

enum class team_composition
{
  mv,  // majority voting
  wta, // winner takes all
 
  standard = wta
};

class basic_class_oracle : public basic_oracle
{
public:
  [[nodiscard]] value_t operator()(const std::vector<value_t> &) const final;
 
  [[nodiscard]] std::string name(const value_t &) const final;
 
protected:
  explicit basic_class_oracle(std::vector<std::string> = {});
 
  [[nodiscard]] static std::vector<std::string> class_names(const dataframe &);
 
  bool load_names(std::istream &);
  bool save_names(std::ostream &) const;
 
private:
  std::vector<std::string> names_ {};
};

template<class I, bool S>
class basic_gaussian_oracle : public basic_class_oracle
{
public:
  basic_gaussian_oracle(const I &, const dataframe &,
                        std::vector<std::string> = {});
  basic_gaussian_oracle(std::istream &, const symbol_set &);
 
  [[nodiscard]] classification_result tag(
    const std::vector<value_t> &) const final;
 
  [[nodiscard]] bool is_valid() const final;
 
  // ---- Serialization ----
  static const std::string SERIALIZE_ID;
  bool save(std::ostream &) const final;
 
private:
  // ---- Private support methods ----
  void fill_vector(const dataframe &);
 
  [[nodiscard]] std::string serialize_id() const noexcept final
  { return SERIALIZE_ID; }
 
  // ---- Private data members ----
  basic_reg_oracle<I, S> oracle_;
 
  // `gauss_dist[i]` contains the gaussian distribution of the i-th class of
  // the classification problem.
  std::vector<distribution<double>> gauss_dist_ {};
};

template<class I, bool S>
class basic_binary_oracle : public basic_class_oracle
{
public:
  basic_binary_oracle(const I &, const dataframe &,
                      std::vector<std::string> = {});
  basic_binary_oracle(std::istream &, const symbol_set &);
 
  [[nodiscard]] classification_result tag(
    const std::vector<value_t> &) const final;
 
  [[nodiscard]] bool is_valid() const final;
 
  // ---- Serialization ----
  static const std::string SERIALIZE_ID;
  bool save(std::ostream &) const final;
 
private:
  [[nodiscard]] std::string serialize_id() const noexcept final
  { return SERIALIZE_ID; }
 
  basic_reg_oracle<I, S> oracle_;
};

template<ClassificationPredictor O>
class class_oracle_adaptor final : public basic_class_oracle
{
public:
  explicit class_oracle_adaptor(O, std::vector<std::string> = {});

  [[nodiscard]] bool is_valid() const override { return true; }
 
  [[nodiscard]] classification_result tag(
    const std::vector<value_t> &) const override;
 
private:
  [[nodiscard]] std::string serialize_id() const override;
  bool save(std::ostream &) const override;
 
  O oracle_;
};
 
// ***********************************************************************
// * Extensions to support teams                                          *
// ***********************************************************************

template<ClassificationPredictor O,
         team_composition C = team_composition::standard>
class team_class_oracle : public basic_class_oracle
{
public:
  template<Individual I>
  team_class_oracle(const gp::team<I> &, const dataframe &,
                   std::vector<std::string> = {});
  team_class_oracle(std::istream &, const symbol_set &);
 
  [[nodiscard]] classification_result tag(
    const std::vector<value_t> &) const final;
 
  [[nodiscard]] bool is_valid() const final;
 
  static const std::string SERIALIZE_ID;
 
private:
  bool save(std::ostream &) const final;
  [[nodiscard]] std::string serialize_id() const noexcept final;
 
  // The components of the team never store the names of the classes. If we
  // need the names, the master class will memorize them.
  std::vector<O> team_;
 
  src::class_t classes_ {};
};

template<class I, bool S>
class basic_gaussian_oracle<gp::team<I>, S>
  : public team_class_oracle<basic_gaussian_oracle<I, S>>
{
public:
  using basic_gaussian_oracle::team_class_oracle::team_class_oracle;
};

template<class I, bool S>
class basic_binary_oracle<gp::team<I>, S>
  : public team_class_oracle<basic_binary_oracle<I, S>>
{
public:
  using basic_binary_oracle::team_class_oracle::team_class_oracle;
};
 
// ***********************************************************************
// *  Template aliases to simplify the syntax and help the user          *
// ***********************************************************************
template<Individual P>
class reg_oracle : public basic_reg_oracle<P, true>
{
public:
  using reg_oracle::basic_reg_oracle::basic_reg_oracle;
};
template<Individual P> reg_oracle(const P &) -> reg_oracle<P>;
 
template<Individual P>
class gaussian_oracle : public basic_gaussian_oracle<P, true>
{
public:
  gaussian_oracle(const P &ind, const dataframe &d)
    : basic_gaussian_oracle<P, true>(ind, d, basic_class_oracle::class_names(d))
  {}
 
  gaussian_oracle(std::istream &in, const symbol_set &ss)
    : basic_gaussian_oracle<P, true>(in, ss)
  {}
};
template<Individual P> gaussian_oracle(const P &, const dataframe &)
  -> gaussian_oracle<P>;
 
template<Individual P>
class binary_oracle : public basic_binary_oracle<P, true>
{
public:
  binary_oracle(const P &ind, const dataframe &d)
    : basic_binary_oracle<P, true>(ind, d, basic_class_oracle::class_names(d))
  {}
 
  binary_oracle(std::istream &in, const symbol_set &ss)
    : basic_binary_oracle<P, true>(in, ss)
  {}
};
template<class P> binary_oracle(const P &, const dataframe &)
  -> binary_oracle<P>;
 
#include "kernel/gp/src/oracle.tcc"
 
}  // namespace ultra::src
 
#endif  // include guard