nsga_optimizer

Multi-objective NSGA-II/III optimization for walkers.

Multi-objective NSGA-II/III optimizer for walking mechanisms.

Wraps pymoo’s NSGA-II/III to optimize walking linkages against multiple physics-based objectives simultaneously (e.g., distance + efficiency + stability). Returns a ParetoFront of non-dominated solutions with optional gait analysis and stability data.

Example:

from leggedsnake import (
    DistanceFitness, StabilityFitness, Walker,
    nsga_walking_optimization, NsgaWalkingConfig,
)

def make_walker():
    return Walker(topology, dimensions)

result = nsga_walking_optimization(
    walker_factory=make_walker,
    objectives=[DistanceFitness(duration=10), StabilityFitness(duration=10)],
    bounds=(lower, upper),
    objective_names=["distance", "stability"],
    nsga_config=NsgaWalkingConfig(n_generations=50, pop_size=40),
)

best = result.pareto_front.best_compromise()
print(best.scores)

class leggedsnake.nsga_optimizer.NsgaWalkingConfig(n_generations: int = 100, pop_size: int = 100, algorithm: Literal['nsga2', 'nsga3'] = 'nsga2', seed: int | None = None, verbose: bool = True, crossover_prob: float = 0.9, mutation_eta: float = 20.0, n_workers: int = 1)

Bases: object

Configuration for NSGA-II/III walking optimization.

Variables:

n_generations (int) – Number of evolutionary generations.
pop_size (int) – Population size per generation.
algorithm ({"nsga2", "nsga3"}) – Multi-objective algorithm. NSGA-II is best for 2–3 objectives; NSGA-III handles more.
seed (int | None) – Random seed for reproducibility.
verbose (bool) – Show progress during optimization.
crossover_prob (float) – Simulated binary crossover probability.
mutation_eta (float) – Polynomial mutation distribution index.

__init__(n_generations: int = 100, pop_size: int = 100, algorithm: Literal['nsga2', 'nsga3'] = 'nsga2', seed: int | None = None, verbose: bool = True, crossover_prob: float = 0.9, mutation_eta: float = 20.0, n_workers: int = 1) → None

algorithm: Literal['nsga2', 'nsga3'] = 'nsga2'

crossover_prob: float = 0.9

mutation_eta: float = 20.0

n_generations: int = 100

n_workers: int = 1: Number of parallel workers for fitness evaluation. 1 = sequential (default). >1 uses a process pool.

pop_size: int = 100

seed: int | None = None

verbose: bool = True

class leggedsnake.nsga_optimizer.NsgaWalkingResult(pareto_front: ~pylinkage.optimization.collections.pareto.ParetoFront, gait_analyses: dict[int, ~leggedsnake.gait_analysis.GaitAnalysisResult] | None = None, stability_series: dict[int, ~leggedsnake.stability.StabilityTimeSeries] | None = None, config: ~leggedsnake.nsga_optimizer.NsgaWalkingConfig = <factory>)

Bases: object

Result of multi-objective walking optimization.

Variables:

pareto_front (ParetoFront) – Non-dominated solutions with scores and dimensions.
gait_analyses (dict[int, GaitAnalysisResult] | None) – Gait analysis for each Pareto solution (index → analysis). Only populated when include_gait=True.
stability_series (dict[int, StabilityTimeSeries] | None) – Stability time series for each Pareto solution. Only populated when include_stability=True.
config (NsgaWalkingConfig) – The configuration used.

__init__(pareto_front: ~pylinkage.optimization.collections.pareto.ParetoFront, gait_analyses: dict[int, ~leggedsnake.gait_analysis.GaitAnalysisResult] | None = None, stability_series: dict[int, ~leggedsnake.stability.StabilityTimeSeries] | None = None, config: ~leggedsnake.nsga_optimizer.NsgaWalkingConfig = <factory>) → None

best_compromise(weights: Sequence[float] | None = None) → ParetoSolution: Return the best compromise solution (delegates to ParetoFront).

best_for_objective(objective_index: int) → ParetoSolution

Return the Pareto solution that is best for a single objective.

Walking fitnesses maximize (distance, efficiency, stability all larger-is-better), and scores are stored un-negated after _ensemble_to_pareto_front, so max is correct here.

Parameters:: objective_index (int) – Index into the scores tuple (0-based).

config: NsgaWalkingConfig

gait_analyses: dict[int, GaitAnalysisResult] | None = None

pareto_front: ParetoFront

stability_series: dict[int, StabilityTimeSeries] | None = None

class leggedsnake.nsga_optimizer.WalkingNsgaProblem(walker_factory: Callable[[], Any], objectives: Sequence[DynamicFitness], bounds: tuple[Sequence[float], Sequence[float]], config: Any | None = None, n_workers: int = 1)

Bases: object

Pymoo Problem for multi-objective walking optimization.

Each candidate is a vector of linkage constraint dimensions. Evaluation builds a Walker, runs physics for each objective, and returns the negated scores (pymoo minimizes; our fitness functions maximize).

Parameters:

walker_factory (callable) – Zero-argument callable returning a fresh Walker.
objectives (sequence of DynamicFitness) – Fitness evaluators. Each produces a FitnessResult.score.
bounds (tuple of (lower, upper)) – Parameter bounds as sequences of floats.
config (WorldConfig | None) – Simulation config override.

__init__(walker_factory: Callable[[], Any], objectives: Sequence[DynamicFitness], bounds: tuple[Sequence[float], Sequence[float]], config: Any | None = None, n_workers: int = 1) → None

close() → None

Shut down the shared process pool, if one was created.

Safe to call repeatedly. The driver in nsga_walking_optimization() invokes this in a finally block so workers don’t outlive the optimization.

property problem: Any: The pymoo Problem instance.

leggedsnake.nsga_optimizer.nsga_walking_optimization(walker_factory: Callable[[], Any], objectives: Sequence[DynamicFitness], bounds: tuple[Sequence[float], Sequence[float]], objective_names: Sequence[str] | None = None, nsga_config: NsgaWalkingConfig | None = None, world_config: Any | None = None, include_gait: bool = False, include_stability: bool = False) → NsgaWalkingResult

Multi-objective walking optimization via NSGA-II/III.

Optimizes a walking mechanism against multiple DynamicFitness objectives simultaneously using pymoo. Returns a Pareto front of non-dominated solutions with optional gait and stability analysis.

Parameters:

walker_factory (callable) – Zero-argument callable returning a fresh Walker instance.
objectives (sequence of DynamicFitness) – Fitness evaluators (e.g., DistanceFitness, StabilityFitness).
bounds (tuple of (lower, upper)) – Parameter bounds as sequences of floats, one per constraint dimension.
objective_names (sequence of str, optional) – Human-readable names for each objective.
nsga_config (NsgaWalkingConfig, optional) – Algorithm configuration. Uses defaults if None.
world_config (WorldConfig, optional) – Simulation config passed to fitness evaluators.
include_gait (bool) – If True, run gait analysis on Pareto-front solutions after optimization completes.
include_stability (bool) – If True, collect stability time series for Pareto-front solutions.

Returns:

Pareto front with optional gait/stability analysis.

Return type:

NsgaWalkingResult