leggedsnake

LeggedSnake makes the simulation of walking linkages fast and easy. We believe that building walking linkages is fun and could be useful. Our philosophy is to provide a quick way of building, optimizing and testing walking linkages.

Overview

First, you will define a linkage to be optimized. Here we use the strider linkage by Wade Wagle and Team Trotbot.

Dimensions are intentionally wrong, so that the robots fails to walk properly.

Let's take several identical linkages, and make them reproduce and evolve through many generations. Here is how it looks:

Finally, we will extract the best linkage, and here is our optimized model that does not fall.

Installation

The package is hosted on PyPi as leggedsnake, use:

pip install leggedsnake

Build from source

Download this repository and install with uv.

git clone https://github.com/hugofara/leggedsnake
cd leggedsnake
uv sync

This will create a virtual environment and install all dependencies.

Usage

First, you define the linkage you want to use. The demo script is strider.py, which demonstrates all the techniques about the Strider linkage.

In a nutshell, the two main parts are:

1. Define a Linkage.
2. Run the optimization.

Defining a Walker

You define a mechanism using pylinkage's hypergraph API: nodes (joints), edges (links), and dimensions (positions + distances).

import leggedsnake as ls
from pylinkage.hypergraph import HypergraphLinkage, Node, Edge, NodeRole
from pylinkage.dimensions import Dimensions, DriverAngle
from math import tau

# 1. Define the topology (what connects to what)
hg = HypergraphLinkage(name="MyWalker")
hg.add_node(Node("frame", role=NodeRole.GROUND))
hg.add_node(Node("frame2", role=NodeRole.GROUND))
hg.add_node(Node("crank", role=NodeRole.DRIVER))
hg.add_node(Node("upper", role=NodeRole.DRIVEN))
hg.add_node(Node("foot", role=NodeRole.DRIVEN))
hg.add_edge(Edge("frame_crank", "frame", "crank"))
hg.add_edge(Edge("frame2_upper", "frame2", "upper"))
hg.add_edge(Edge("crank_upper", "crank", "upper"))
hg.add_edge(Edge("crank_foot", "crank", "foot"))
hg.add_edge(Edge("upper_foot", "upper", "foot"))

# 2. Define the geometry (positions, link lengths, driver speed)
dims = Dimensions(
    node_positions={
        "frame": (0, 0), "frame2": (2, 0),
        "crank": (1, 0), "upper": (1, 2), "foot": (1, 3),
    },
    driver_angles={"crank": DriverAngle(angular_velocity=-tau / 12)},
    edge_distances={
        "frame_crank": 1.0, "frame2_upper": 2.24,
        "crank_upper": 2.0, "crank_foot": 3.16, "upper_foot": 1.0,
    },
)

# 3. Create the Walker and add legs
my_walker = ls.Walker(hg, dims, name="My Walker")
my_walker.add_opposite_leg(axis_x=1.0)  # mirror for left/right pair
my_walker.add_legs(1)  # add a second pair with phase offset

# 4. Launch a GUI simulation
ls.video(my_walker)

It should display something like the following.

Optimization using Genetic Algorithm (GA)

The next step is to optimize your linkage. We use a genetic algorithm here.

# Definition of an individual as (fitness, dimensions, initial coordinates)
dna = [0, list(my_walker.get_num_constraints()), list(my_walker.get_coords())]
population = 10

def total_distance(dna):
    """
    Evaluates the final horizontal position of the input linkage.

    Return final distance and initial position of joints.
    """
    # Rebuild walker from DNA
    walker = ls.Walker(hg, dims, name="candidate")
    walker.set_num_constraints(dna[1])
    walker.set_coords(dna[2])
    walker.add_legs(1)

    pos = tuple(walker.step())[-1]
    world = ls.World()
    # We handle all the conversions
    world.add_linkage(walker)
    # Simulation duration (in seconds)
    duration = 40
    steps = int(duration / ls.params["simul"]["physics_period"])
    for _ in range(steps):
        world.update()
    return world.linkages[0].body.position.x, pos


# Prepare the optimization, with any fitness_function(dna) -> score
optimizer = ls.GeneticOptimization(
        dna=dna,
        fitness=total_distance,
        max_pop=population,
)
# Run for 100 iterations, on 4 processes
optimized_walkers = optimizer.run(iters=100, processes=4)

# The following line will display the results
ls.all_linkages_video(optimized_walkers)

For 100 iterations, 10 linkages will be simulated and evaluated by fitness_function. The fittest individuals are kept and will propagate their genes (with mutations).

Now you should see something like the following.

This is a simulation from the last generation of 10 linkages. Most of them cover a larger distance (this is the target of our fitness_function).

Results

Finally, only the best linkage at index 0 may be kept.

# Results are sorted by best fitness first, 
# so we use the walker with the best score
best_dna = optimized_walkers[0]

# Change the dimensions
my_walker.set_num_constraints(best_dna[1])
my_walker.set_coords(best_dna[2])

# Once again launch the video
ls.video(my_walker)

So now it has a small ski pole, does not fall and goes much farther away!

Kinematic optimization using Particle Swarm Optimization (PSO)

You may need a kinematic optimization, depending solely on pylinkage. You should use the step and stride method from the utility module as fitness functions.

This set of rules should work well for a stride maximisation problem:

1. Rebuild the Walker with the provided set of dimensions, and do a complete turn.
2. If the Walker raises an UnbuildableError, its score is 0 (or -float('inf') if you use other evaluation functions).
3. Verify if it can pass a certain obstacle using step function. If not, its score is 0.
4. Eventually measure the length of its stride with the stride function. Return this length as its score.

Main features

We handle planar leg mechanisms in three main parts:

• Mechanism definition via pylinkage's hypergraph API (HypergraphLinkage + Dimensions), wrapped in the Walker class.
• Optional kinematic optimization with Walker.step() and pylinkage optimizers (PSO, differential evolution, multi-objective).
• Dynamic simulation with pymunk physics and genetic algorithm optimization.

Advice

Use the visualisation tools provided! The optimization tools should always give you a score with a better fitness, but it might not be what you expected. Tailor your optimization and then go for a long run will make you save a lot of time.

Do not use optimized linkages from the start! The risk is to fall too quickly into a suboptimal solution. There are several mechanisms to prevent that (starting from random position), but it can always have an impact on the rest of the optimization.

Try to minimize the number of elements in the optimizations! You can often use some linkage properties to reduce the number of simulation parameters. For instance, the Strider linkage has axial symmetry. While it is irrelevant to use this property in dynamic simulation, you can use "half" your Strider in a kinematic optimization, which is much faster.

Contribute

This project is open to contribution and actively looking for contributors. You can help making it better!

For everyone

You can drop a star, fork this project or simply share the link to your best media.

The more people get engaged into this project, the better it will develop!

For developers

You can follow the guide at CONTRIBUTING.md. Feel free to make any pull request.

Quick links

• For the documentation, check the docs at hugofara.github.io/leggedsnake!
• Source code is hosted on GitHub as HugoFara/leggedsnake
• We also provide a Python package on PyPi, test leggedsnake.
• If you just want to chill out looking at walking linkages striving to survive, join the discussions.

Contributors are welcome!