sampler.hpp

Go to the documentation of this file.

#pragma once
 
#include <cstdint>
#include <cstddef>
#include <memory>
#include <optional>
#include <random>
#include <vector>
 
#include "pineforge/hpo/search_space.hpp"
 
namespace pineforge::hpo {
 
class Sampler {
public:
    virtual ~Sampler() = default;
 
    virtual std::optional<Candidate> next() = 0;
    virtual void reset() = 0;
    virtual std::uint64_t generated() const noexcept = 0;
};
 
class GridSampler final : public Sampler {
public:
    explicit GridSampler(SearchSpace space);
 
    std::optional<Candidate> next() override;
    void reset() override;
    std::uint64_t generated() const noexcept override { return generated_; }
    std::uint64_t total_candidates() const noexcept { return total_candidates_; }
 
private:
    SearchSpace space_;
    std::uint64_t total_candidates_ = 0;
    std::uint64_t generated_ = 0;
};
 
class RandomSampler final : public Sampler {
public:
    RandomSampler(SearchSpace space, std::uint64_t seed, std::uint64_t max_candidates = 0);
 
    std::optional<Candidate> next() override;
    void reset() override;
    std::uint64_t generated() const noexcept override { return generated_; }
    std::uint64_t seed() const noexcept { return seed_; }
 
private:
    SearchSpace space_;
    std::uint64_t seed_;
    std::uint64_t max_candidates_;
    std::uint64_t generated_ = 0;
    std::mt19937_64 engine_;
};
 
enum class ObjectiveDirection {
    Maximize,  
    Minimize,  
};
 
enum class CandidatePolicy {
    SamplerDefault,      
    WithoutReplacement,  
    Exhaustive,           
};
 
const char* candidate_policy_name(CandidatePolicy policy) noexcept;
 
std::uint64_t continuation_seed(std::uint64_t seed, std::uint64_t warm_trials) noexcept;
 
struct WarmStartObservation {
    Candidate candidate;
    std::optional<double> objective;
};
 
class WarmStartSource {
public:
    virtual ~WarmStartSource() = default;
    virtual std::uint64_t size() const noexcept = 0;
    virtual std::uint64_t id(std::uint64_t row) const = 0;
    virtual ParameterValue parameter(std::uint64_t row, std::size_t dimension) const = 0;
    virtual std::optional<double> objective(std::uint64_t row) const = 0;
    WarmStartObservation observation(const SearchSpace& space, std::uint64_t row) const;
};
 
struct TpeSamplerConfig {
    std::uint64_t startup_trials = 10;
 
    std::uint64_t ei_candidates = 24;
 
    double gamma_fraction = 0.10;
    std::uint64_t gamma_cap = 25;
 
    double prior_weight = 1.0;
 
    bool constant_liar = true;
 
    std::optional<std::uint64_t> history_switch = std::nullopt;
 
    std::uint64_t scale_ei_candidates = 8;
 
    std::uint64_t bad_reservoir_size = 448;
 
    std::uint32_t max_threads = 0;
};
 
class TpeSampler final : public Sampler {
public:
    TpeSampler(SearchSpace space,
               std::uint64_t seed,
               ObjectiveDirection direction = ObjectiveDirection::Maximize,
               std::uint64_t max_candidates = 0,
               TpeSamplerConfig config = {},
               CandidatePolicy candidate_policy = CandidatePolicy::SamplerDefault);
    ~TpeSampler() override;
 
    TpeSampler(const TpeSampler&) = delete;
    TpeSampler& operator=(const TpeSampler&) = delete;
    TpeSampler(TpeSampler&&) noexcept;
    TpeSampler& operator=(TpeSampler&&) noexcept;
 
    std::optional<Candidate> next() override;
 
    std::optional<Candidate> ask();
 
    void tell(std::uint64_t candidate_id, double objective_value);
 
    void abandon(std::uint64_t candidate_id);
 
    bool warm_start(const std::vector<WarmStartObservation>& observations,
                   std::uint64_t replay_batch_size = 0,
                   const std::string& sampler_state = {});
 
    bool warm_start(std::shared_ptr<const WarmStartSource> source,
                    std::uint64_t replay_batch_size = 0,
                    const std::string& sampler_state = {});
 
    std::string sampler_state() const;
 
    void reset() override;
    std::uint64_t generated() const noexcept override;
    std::uint64_t completed() const noexcept;
    std::uint64_t outstanding() const noexcept;
    std::size_t retained_observations() const;
    std::uint64_t duplicate_proposals_skipped() const noexcept;
    std::uint64_t seed() const noexcept { return seed_; }
    ObjectiveDirection direction() const noexcept { return direction_; }
    const TpeSamplerConfig& config() const noexcept { return config_; }
    CandidatePolicy candidate_policy() const noexcept { return candidate_policy_; }
 
private:
    class Impl;
 
    SearchSpace space_;
    std::uint64_t seed_;
    ObjectiveDirection direction_;
    std::uint64_t max_candidates_;
    TpeSamplerConfig config_;
    CandidatePolicy candidate_policy_;
    std::unique_ptr<Impl> impl_;
};
 
class DlibGlobalSampler final : public Sampler {
public:
    DlibGlobalSampler(SearchSpace space,
                      std::uint64_t seed,
                      ObjectiveDirection direction = ObjectiveDirection::Maximize,
                      std::uint64_t max_candidates = 0);
    ~DlibGlobalSampler() override;
 
    DlibGlobalSampler(const DlibGlobalSampler&) = delete;
    DlibGlobalSampler& operator=(const DlibGlobalSampler&) = delete;
    DlibGlobalSampler(DlibGlobalSampler&&) noexcept;
    DlibGlobalSampler& operator=(DlibGlobalSampler&&) noexcept;
 
    std::optional<Candidate> next() override;
 
    std::optional<Candidate> ask();
 
    void tell(std::uint64_t candidate_id, double objective_value);
 
    void abandon(std::uint64_t candidate_id);
 
    void reset() override;
    std::uint64_t generated() const noexcept override;
    std::uint64_t completed() const noexcept;
    std::uint64_t outstanding() const noexcept;
    std::uint64_t seed() const noexcept { return seed_; }
    ObjectiveDirection direction() const noexcept { return direction_; }
 
private:
    class Impl;
 
    SearchSpace space_;
    std::uint64_t seed_;
    ObjectiveDirection direction_;
    std::uint64_t max_candidates_;
    std::unique_ptr<Impl> impl_;
};
 
}  // namespace pineforge::hpo