Struct Nsga3 

pub struct Nsga3 { /* private fields */ }

The reference-point-based many-objective genetic algorithm (NSGA-III) as a Sampler.

The builder mirrors Nsga2’s — population size and the variation knobs — plus the reference-point settings. Hand it to a study through StudyBuilder::sampler. See the module documentation for the algorithm.

use atune_core::sampler::Nsga3;

let nsga3 = Nsga3::try_new_with_population_size(92)?.with_dividing_parameter(12)?;
assert_eq!(nsga3.population_size(), 92);
// Three objectives at twelve divisions: the classic 91 reference points.
assert_eq!(nsga3.reference_points(3).len(), 91);
assert_eq!(nsga3.generation(), 0);

Implementations

impl Nsga3

pub fn new() -> Self

A sampler with DEFAULT_POPULATION_SIZE, η_c = η_m = 20 and DEFAULT_DIVIDING_PARAMETER divisions.

pub fn try_new_with_population_size(population_size: usize) -> Result<Self>

A sampler with an explicit population size.

Errors

Error::InvalidSpace outside MIN_POPULATION_SIZE ..= MAX_POPULATION_SIZE, the bounds Nsga2 uses for the same reasons.

pub fn with_dividing_parameter(self, divisions: usize) -> Result<Self>

Sets the Das–Dennis divisions per objective axis (default DEFAULT_DIVIDING_PARAMETER). Ignored when explicit reference points are set.

Errors

Error::InvalidSpace for 0, which would put a single reference point at the origin, where no reference line exists.

pub fn with_reference_points(self, points: Vec<Vec<f64>>) -> Result<Self>

Replaces the Das–Dennis lattice with caller-chosen reference points (Optuna’s reference_points), one per row, in the normalized objective space (minimization form: a maximized objective’s axis is its negation).

Only each point’s direction matters — association measures the distance to the ray through it. The row length must equal the study’s objective count, which sample_relative checks.

use atune_core::sampler::Nsga3;

let nsga3 = Nsga3::new().with_reference_points(vec![vec![1.0, 0.0], vec![1.0, 1.0]])?;
assert_eq!(nsga3.reference_points(2).len(), 2);
Nsga3::new()
    .with_reference_points(vec![vec![0.0, 0.0]])
    .expect_err("a zero vector cannot be a reference direction");

Errors

Error::InvalidSpace when the set is empty or above MAX_REFERENCE_POINTS, the rows are empty or of unequal length, or a row has a non-finite entry or is the zero vector.

pub fn with_crossover_eta(self, eta: f64) -> Self

Sets the SBX distribution index η_c (default DEFAULT_CROSSOVER_ETA); a non-finite or negative value restores the default.

pub fn with_mutation_eta(self, eta: f64) -> Self

Sets the polynomial-mutation distribution index η_m (default DEFAULT_MUTATION_ETA); a non-finite or negative value restores the default.

pub fn with_swapping_prob(self, probability: f64) -> Self

Sets the categorical uniform-crossover swap probability (default DEFAULT_SWAPPING_PROB), clamped into [0, 1].

pub fn with_mutation_rate(self, rate: f64) -> Self

Sets the per-gene mutation probability, overriding the customary 1/d.

Clamped into [0, 1]; a non-finite value restores the 1/d default.

pub const fn population_size(&self) -> usize

How many children make one generation.

pub const fn crossover_eta(&self) -> f64

The SBX distribution index η_c.

pub const fn mutation_eta(&self) -> f64

The polynomial-mutation distribution index η_m.

pub const fn swapping_prob(&self) -> f64

The categorical uniform-crossover swap probability.

pub const fn dividing_parameter(&self) -> usize

The Das–Dennis divisions per objective axis.

pub fn reference_points(&self, n_objectives: usize) -> Vec<Vec<f64>>

The reference points survival uses for a study with n_objectives objectives: the caller’s set if one was supplied, otherwise the Das–Dennis lattice (reduced to at most MAX_REFERENCE_POINTS, or to the n_objectives axis directions if even that is more).

pub fn generation(&self) -> u64

How many generations have closed. 0 while the initial population is still being evaluated, or if the state lock is poisoned (an inspection accessor, not a decision path).

pub fn elite_values(&self) -> Vec<Vec<f64>>

The current elite population’s objective vectors: front by front, and within a front by ascending pool index (surviving parents before surviving children). Empty while the initial population is still being evaluated.

Trait Implementations

impl Debug for Nsga3

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Nsga3

fn default() -> Self

A sampler with DEFAULT_POPULATION_SIZE, the customary operator constants and the default Das–Dennis lattice.

impl Sampler for Nsga3

fn infer_relative_space(&self, study: &StudyView) -> Result<SpaceSchema>

The study’s declared space, verbatim; a define-by-run study yields an empty relative space (every parameter takes the uniform fallback), as for Nsga2.

Errors

Never.

fn sample_relative( &self, study: &StudyView, trial: &TrialMeta, space: &SpaceSchema, ) -> Result<Assignment>

Breeds this trial’s configuration: a uniform point while the initial population is evaluated, a tournament-selected crossover-and-mutation afterwards. Every value is produced by Distribution::from_unit and so lies in its support.

Errors

Error::Sampler if explicit reference points do not have one coordinate per study direction, or the state lock is poisoned; Error::InvalidSpace if a declared distribution is malformed; Error::Backpressure when 4096 jobs are already in flight.

fn sample_independent( &self, _study: &StudyView, trial: &TrialMeta, name: &str, dist: &Distribution, ) -> Result<ParamValue>

The uniform draw keyed on (sampler seed, name), as every population sampler’s fallback.

Errors

Error::InvalidSpace if dist is malformed.

fn after_trial(&self, study: &StudyView, trial: &FrozenTrial) -> Result<()>

Admits the finished trial to the offspring buffer and, once a full generation has been evaluated, runs reference-point survival.

The admission rules are Nsga2’s: the pending job is released first; the child is admitted only with one finite value per direction, finite constraints, and an evaluated point equal to the bred one.

Errors

Never — a poisoned lock skips the update rather than failing the trial.

fn state(&self) -> Result<Option<SamplerState>>

The whole population as a versioned blob.

Errors

Error::Sampler if the lock is poisoned or serialization fails.

fn restore_state(&self, blob: &SamplerState) -> Result<()>

Rebuilds the population from a persisted blob, validated against the live sampler exactly as Nsga2 validates its own.

Errors

Error::Incompatible if the blob is not an NSGA-III blob of the expected version. Error::Storage if the payload cannot be decoded. Error::Sampler if the blob was saved for a different population size, fails validation, or the lock is poisoned.

fn reseed(&self, _seed: u64)

A no-op: breeding is keyed on the per-trial seed and survival on the persisted survival seed, so there is no auxiliary stream to move.

fn snapshots_space(&self) -> bool

Whether this sampler enumerates a snapshot of the space it was constructed with, rather than the space each ask presents.

fn reads_constraints(&self) -> bool

Whether this sampler reads FrozenTrial::constraints on the views it is asked with.