Table of Contents

Class AgeMoea2CptSampler

Namespace
OptunaSharp.Samplers
Assembly
OptunaSharp.dll

AGE-MOEA-2-CPT ("AGE-MOEA-2 with Categorical Parameter Trees") — AGE-MOEA-2's geometry-based environmental selection (AgeMoea2ElitePopulationSelectionStrategy) joined to the conditional-parameter machinery NSGAIIICptSampler introduced, so the define-by-run, branch-defined hyperparameters Rock's gene trees produce are evolved instead of resampled at random. It is the AGE-MOEA-2 sibling of NSGAIIICptSampler and reuses the same CPT seams (NsgaiiiCptSearchSpace, NsgaiiiCptChildGenerationStrategy, ConditionalParams); only the survival rule and the default operators differ.

Why reach for this over NSGAIIICptSampler. Both handle conditional parameters identically. They differ only in survival: NSGA-III niches against a fixed reference-point simplex whose size grows as C(M+2, 3), so past ~5 objectives most of the population is mutually non-dominated and the front stops selecting; AGE-MOEA-2 estimates the front's geometry adaptively and keeps selection pressure in that regime. So this sampler is the one to use when the objective count is (or may grow) high; at 2–4 objectives the two are close and NSGA-III-CPT remains the conservative default. This is a genuine tradeoff, not a strict improvement — validate the swap on the actual objective set before adopting it.

Relationship to AgeMoea2Sampler. Constructed with conditionalParams: null this sampler is behaviorally identical to AgeMoea2Sampler (the CPT search space and child generation both fall through to the shared Optuna-parity fold, and the elite strategy, operators, and RNG draw order are the same), so it is a strict superset. The conditional behavior is the same deliberate, no-Optuna-analog divergence documented on ConditionalParams; AGE-MOEA-2 itself (Panichella, GECCO 2022) is a beyond-core, convergence-validated sampler with no Optuna counterpart, so no ExperimentalWarning is emitted. Unconstrained multi-objective only — AGE-MOEA-2's survival does not model constraints, so unlike NSGAIIICptSampler this class exposes no constraintsFunc.

public class AgeMoea2CptSampler : BaseGASampler
Inheritance
AgeMoea2CptSampler
Derived
Inherited Members

Constructors

AgeMoea2CptSampler(int, BaseMutation?, double?, BaseCrossover?, double, double, int?, Func<Study, List<FrozenTrial>, List<FrozenTrial>>?, Func<Study, OrderedDict<string, BaseDistribution>, List<FrozenTrial>, OrderedDict<string, object?>>?, Action<Study, FrozenTrial, TrialState, IReadOnlyList<double>?>?, ConditionalParams?)

Configures AGE-MOEA-2 survival, conditional-aware reproduction, and trial-completion hooks.

public AgeMoea2CptSampler(int populationSize = 50, BaseMutation? mutation = null, double? mutationProb = null, BaseCrossover? crossover = null, double crossoverProb = 0.9, double swappingProb = 0.5, int? seed = null, Func<Study, List<FrozenTrial>, List<FrozenTrial>>? elitePopulationSelectionStrategy = null, Func<Study, OrderedDict<string, BaseDistribution>, List<FrozenTrial>, OrderedDict<string, object?>>? childGenerationStrategy = null, Action<Study, FrozenTrial, TrialState, IReadOnlyList<double>?>? afterTrialStrategy = null, ConditionalParams? conditionalParams = null)

Parameters

populationSize int

Number of individuals (trials) per generation. Must be >= 2 and >= crossover.NParents.

mutation BaseMutation

Mutation applied when creating children. null selects AGE-MOEA-2's default PolynomialMutation with eta = 20 (NOT NSGA-III's uniform-resample default) — kept so this sampler matches AgeMoea2Sampler operator-for-operator.

mutationProb double?

Per-parameter mutation probability. null uses 1 / n_active_params — adaptive to each child's active-gene count, which is what makes it well-behaved for the fluctuating genome sizes conditional parameters produce.

crossover BaseCrossover

Crossover applied when creating children. null selects AGE-MOEA-2's default SBXCrossover with eta = 15. Categorical parameters always cross uniformly.

crossoverProb double

Probability that a crossover occurs (else a parent is copied).

swappingProb double

Probability of swapping each parameter of the parents during crossover.

seed int?

Seed for the random number generator; the same seed replays the search.

elitePopulationSelectionStrategy Func<Study, List<FrozenTrial>, List<FrozenTrial>>

Overrides environmental selection. null uses AgeMoea2ElitePopulationSelectionStrategy (the AGE-MOEA-2 survival that is the reason to choose this sampler); an override replaces exactly that and leaves conditional child generation intact.

childGenerationStrategy Func<Study, OrderedDict<string, BaseDistribution>, List<FrozenTrial>, OrderedDict<string, object>>

Overrides child generation. A custom strategy receives the (conditional-widened) search space and must itself cope with parents that lack conditional parameters; the built-in NsgaiiiCptChildGenerationStrategy is the one that honors conditionalParams, so an override drops conditional handling unless it reproduces it.

afterTrialStrategy Action<Study, FrozenTrial, TrialState, IReadOnlyList<double>>

Overrides the after-trial procedure (population bookkeeping).

conditionalParams ConditionalParams

The activation rules for parameters that only exist under some values of other parameters — the reason to reach for this sampler over AgeMoea2Sampler. Declared parameters are evolved (crossed over, mutated, inherited) whenever active instead of falling out of the intersection search space and being resampled at random on every trial. null makes this sampler behave exactly like AgeMoea2Sampler.

Exceptions

ValueError

Population size is below two or the crossover parent count, or a configured reproduction probability is invalid.

Methods

AfterTrial(Study, FrozenTrial, TrialState, IReadOnlyList<double>?)

Trial post-processing: called after the objective function returns and right before the trial is finished and its state is stored.

public override void AfterTrial(Study study, FrozenTrial trial, TrialState state, IReadOnlyList<double>? values)

Parameters

study Study

Study that owns the trial being finished.

trial FrozenTrial

Trial snapshot before its terminal state is written to storage.

state TrialState

Terminal state being recorded: complete, pruned, or failed.

values IReadOnlyList<double>

Resulting trial values in objective order; non-null for a successful trial.

Exceptions

Exception

A configured after-trial callback fails; its exception propagates.

BeforeTrial(Study, FrozenTrial)

Trial pre-processing: called during trial initialization, just before the InferRelativeSearchSpace(Study, FrozenTrial) call.

public override void BeforeTrial(Study study, FrozenTrial trial)

Parameters

study Study

Study that owns the newly initialized trial.

trial FrozenTrial

New trial snapshot available before search-space inference.

InferRelativeSearchSpace(Study, FrozenTrial)

Infer the search space that will be used by relative sampling in the target trial.

This method is called right before SampleRelative(Study, FrozenTrial, OrderedDict<string, BaseDistribution>), and the search space returned by this method is passed to it. The parameters not contained in the search space will be sampled by using SampleIndependent(Study, FrozenTrial, string, BaseDistribution).

public override OrderedDict<string, BaseDistribution> InferRelativeSearchSpace(Study study, FrozenTrial trial)

Parameters

study Study

Study supplying trial history, directions, and storage.

trial FrozenTrial

Current trial snapshot; copy it before modifying its contents.

Returns

OrderedDict<string, BaseDistribution>

Parameter distributions eligible for joint sampling, in sampler-defined order.

ReseedRng()

Reseed sampler's random number generator.

Parallel optimization calls this hook before a worker's sequential trial loop. Concrete samplers refresh their random streams so workers do not deliberately reuse a seeded sequence. OptunaSharp workers share the study's sampler instance; this hook does not clone it or make concurrent sampling reproducible.

public override void ReseedRng()

SampleIndependent(Study, FrozenTrial, string, BaseDistribution)

Sample a parameter for a given distribution.

This method is called only for the parameters not contained in the search space returned by SampleRelative(Study, FrozenTrial, OrderedDict<string, BaseDistribution>). This method is suitable for sampling algorithms that do not use relationship between parameters such as random sampling and TPE.

public override object? SampleIndependent(Study study, FrozenTrial trial, string paramName, BaseDistribution paramDistribution)

Parameters

study Study

Study supplying trial history, directions, and storage.

trial FrozenTrial

Current trial snapshot; copy it before modifying its contents.

paramName string

Name of the parameter being suggested.

paramDistribution BaseDistribution

Distribution defining the parameter's domain and scale.

Returns

object

A value in the distribution's external representation, including null categorical choices.

SampleRelative(Study, FrozenTrial, OrderedDict<string, BaseDistribution>)

Sample parameters in a given search space.

The trial invokes this method lazily when it first needs relative parameters and caches the result for its remaining suggestions. This method is suitable for sampling algorithms that use relationship between parameters such as Gaussian Process and CMA-ES.

public override OrderedDict<string, object?> SampleRelative(Study study, FrozenTrial trial, OrderedDict<string, BaseDistribution> searchSpace)

Parameters

study Study

Study supplying trial history, directions, and storage.

trial FrozenTrial

Current trial snapshot; copy it before modifying its contents.

searchSpace OrderedDict<string, BaseDistribution>

Distributions returned by InferRelativeSearchSpace(Study, FrozenTrial).

Returns

OrderedDict<string, object>

Jointly sampled external parameter values; omitted parameters use independent sampling.

SelectParent(Study, int)

Select parent trials from the population for the given generation. Called once per generation; the result is cached in the study system attributes.

public override List<FrozenTrial> SelectParent(Study study, int generation)

Parameters

study Study

Study supplying trial history, objective directions, and storage.

generation int

Zero-based generation whose individuals or optimizer state are requested.

Returns

List<FrozenTrial>

The selected parent trials for the requested generation.

See Also

AgeMoea2Sampler
NSGAIIICptSampler
ConditionalParams
Edit this page