gait_optimization

Phase-offset optimization for multi-leg walkers.

Phase-offset optimization for multi-leg walking mechanisms.

Evolves the per-leg phase offsets of an N-leg walker — the discrete parameters that distinguish a rotating-stack gait (evenly spaced) from trot (opposite pairs in phase), pace, canter, bound, and other asymmetric gaits that emerge in nature but that the classical Walker.add_legs(n) constructor cannot express.

The optimizer wraps scipy.optimize.differential_evolution on an (n_legs - 1)-dimensional continuous search space (one offset per added leg, in radians). Each candidate rebuilds the walker via Walker.add_legs(offsets=...) and evaluates a user-supplied DynamicFitness.

Example

from leggedsnake import DistanceFitness, optimize_gait, GaitOptimizationConfig

def template_factory():
    return Walker.from_jansen()  # single-leg template

config = GaitOptimizationConfig(
    walker_factory=template_factory,
    n_legs=4,
    fitness=DistanceFitness(duration=20.0),
    popsize=15,
    maxiter=30,
    seed=42,
)
result = optimize_gait(config)
print("best offsets:", result.best_offsets)
print("best score:", result.best_score)
class leggedsnake.gait_optimization.GaitOptimizationConfig(walker_factory: Callable[[], Walker], n_legs: int, fitness: DynamicFitness, world_config: WorldConfig | None = None, popsize: int = 15, maxiter: int = 30, seed: int | None = None, tol: float = 0.001, workers: int = 1, initial_offsets: list[float] | None = None)

Bases: object

Configuration for optimize_gait().

Variables:

  • walker_factory (callable) – Zero-argument callable returning a fresh single-leg Walker template. Called once per candidate evaluation so no state leaks across generations.

  • n_legs (int) – Total number of legs in the evaluated walker (template + added). The optimizer searches n_legs - 1 phase offsets.

  • fitness (DynamicFitness) – The fitness evaluator applied to each candidate walker after phase-offset assembly.

  • world_config (WorldConfig | None) – Simulation environment passed through to fitness.

  • popsize (int) – Differential-evolution population size multiplier (scipy’s popsize = population / dimension).

  • maxiter (int) – Maximum DE generations.

  • seed (int | None) – RNG seed for reproducibility.

  • tol (float) – DE convergence tolerance.

  • workers (int) – Parallel workers (1 = serial; -1 = use all cores).

  • initial_offsets (list[float] | None) – Optional warm-start — a seed member inserted into the initial population. Length must equal n_legs - 1.

__init__(walker_factory: Callable[[], Walker], n_legs: int, fitness: DynamicFitness, world_config: WorldConfig | None = None, popsize: int = 15, maxiter: int = 30, seed: int | None = None, tol: float = 0.001, workers: int = 1, initial_offsets: list[float] | None = None) → None
fitness: DynamicFitness
initial_offsets: list[float] | None = None
maxiter: int = 30
n_legs: int
popsize: int = 15
seed: int | None = None
tol: float = 0.001
walker_factory: Callable[[], Walker]
workers: int = 1
world_config: WorldConfig | None = None
class leggedsnake.gait_optimization.GaitOptimizationResult(best_offsets: list[float], best_score: float, n_evaluations: int, converged: bool, message: str, history: list[float] = <factory>)

Bases: object

Outcome of optimize_gait().

Variables:

  • best_offsets (list[float]) – Phase offsets (radians, in [0, tau)) for the highest-scoring candidate.

  • best_score (float) – Fitness value of the best candidate.

  • n_evaluations (int) – Total number of fitness evaluations the optimizer performed.

  • converged (bool) – Whether scipy reported convergence (OptimizeResult.success).

  • message (str) – Optimizer status message.

  • history (list[float]) – Best score observed after each generation (populated only when the caller supplied a generation callback).

__init__(best_offsets: list[float], best_score: float, n_evaluations: int, converged: bool, message: str, history: list[float] = <factory>) → None
best_offsets: list[float]
best_score: float
converged: bool
history: list[float]
message: str
n_evaluations: int
leggedsnake.gait_optimization.optimize_gait(config: GaitOptimizationConfig) → GaitOptimizationResult

Evolve the phase-offset sequence of a multi-leg walker.

Runs scipy’s differential evolution over the n_legs - 1 phase offsets (in radians, bounded to [0, tau)). Each candidate rebuilds a fresh walker via config.walker_factory and evaluates config.fitness; the score is negated internally because scipy minimizes.

Parameters:

config (GaitOptimizationConfig) – Search configuration.

Return type:

GaitOptimizationResult