Train an SNN, step by step

This is the complete loop for training a spiking neural network controller against a live world model through the simulation gym, from first session to a certified result. The observation contract was co-designed for SNNs: sensor channels are bounded scalars that map naturally onto input spike rates, and collisions arrive as discrete spikes, not dense reward.

0. What you need

A Train bearer key (provisioned per partner).
The gym endpoint URL for your key.
Optional, for offline pre-training: the recorded episode dataset (JSONL, same observation schema; controllers trained on recordings plug straight into the live loop).

1. Create a gym session

curl -s -X POST $RUNNER_URL/v1/sim/sessions \
  -H "Authorization: Bearer $TRAIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"world": "epuck", "camera": 0, "terminal_collision": false}'
# → {"session_id": "…", "world": "epuck", "camera": 0}

world: robot or epuck (e-puck front-sensor-pair convention matches the proximity contract).
camera: 0 if your SNN only consumes proximity; observations get smaller and faster.
terminal_collision: false is training semantics: collisions are countable spikes and the run continues (the contact engine re-arms after a cooldown). Set true for game-style terminal episodes.

Each session holds a real world-model GPU stream. Create only as many parallel environments as your session budget allows, and DELETE every session when you are done; an orphaned session keeps billing wall-time.

2. The control loop

One step per control tick; the response is the post-action observation.

import requests

S = requests.Session()
S.headers["Authorization"] = f"Bearer {KEY}"

sid = S.post(f"{URL}/v1/sim/sessions",
             json={"world": "epuck", "camera": 0}).json()["session_id"]

obs = S.get(f"{URL}/v1/sim/sessions/{sid}/obs").json()
while True:
    # 1) encode: bounded scalars -> input spike rates
    left_rate  = obs["proximity"]["left"]    # 0 = clear … 1 = contact range
    right_rate = obs["proximity"]["right"]
    pain_spike = obs["collision"]            # True exactly once per hit

    # 2) run your SNN for the tick window; decode motor populations
    wheels = my_snn.tick(left_rate, right_rate, pain_spike)   # e.g. {"left": 0.8, "right": 0.3}

    # 3) act, SNN-native differential drive (or discrete `action`)
    obs = S.post(f"{URL}/v1/sim/sessions/{sid}/step",
                 json={"wheels": wheels, "holdMs": 300}).json()

    if obs["done"]:
        obs = S.post(f"{URL}/v1/sim/sessions/{sid}/reset").json()

Contract details that matter for spiking controllers:

wheels is the SNN-native command: differential velocities from your motor populations, quantized server-side onto the world’s drive (the response echoes applied_action). Discrete action also works.
collision is edge-triggered: true exactly once per hit, derived from a monotonic counter, so a spike between two reads is never missed. Use it as your punishment or terminal signal; collision_count is the running total.
holdMs (60–2000, default 300) is your control tick: how long the command holds before the observation is read. Match it to your SNN’s simulation window.
sensor_age_ms reports how stale proximity/labels are relative to the camera frame. Cloud-detector worlds run ≈500–1000 ms behind, local-detector worlds tens of ms; discount or compensate in your dynamics.
Reward is yours to shape client-side. The observation gives you survival time (t_ms), collision spikes, and proximity margins.

3. Pre-train offline (optional but recommended)

The dataset exporter emits recorded episodes as JSONL in exactly the same observation schema, so you can warm up your encoder and controller on recordings (imitation, STDP pre-exposure, calibration of input scaling) before spending live GPU sessions. Ask us for the current vetted dataset release with your key.

4. Scale up

Sessions on one runner are serialized; parallel training uses several runner instances. Coordinate the parallel-session count with us; it maps 1:1 onto GPU streams (your budget).
Keep episodes honest: don’t sense or score the first frames right after a reset (world-model settle). The physics exam has no settle window (it senses from tick 0), so never make your controller depend on blindness.

5. Evaluate and certify

Gym telemetry (t_ms, collision_count) is self-reported training signal, not certification. When your controller is worth a claim:

Benchmark in the gym

Freeze the weights, run a fixed episode battery (same worlds, same settings), and record survival + collision stats.

Certify your trained SNN

Package it as a Python module (reset/act over the same obs dict) and submit it to the frozen Webots exam: your own architecture, sandboxed, no 9-float restriction. The verdict is comparable to the whole program history because everything except the policy slot stays frozen.

Transfer showcase

A trained SNN can drive a live hosted world client-side (the SNN transfer demo): the same brain, unmodified, in a world it never trained in.

Timings and budget summary

Item	Value
Control tick (`holdMs`)	60–2000 ms, default 300 ms
Sensor lag (`sensor_age_ms`)	tens of ms (local detector) … ≈1 s (cloud)
Session cost	one GPU stream per session, billed by wall-time
Sessions per runner	serialized (1 active); parallelism = more runners

​0. What you need

​1. Create a gym session

​2. The control loop

​3. Pre-train offline (optional but recommended)

​4. Scale up

​5. Evaluate and certify

​Timings and budget summary

0. What you need

1. Create a gym session

2. The control loop

3. Pre-train offline (optional but recommended)

4. Scale up

5. Evaluate and certify

Timings and budget summary