Trajectory Generation

Relevant source files

Purpose and Scope

This page documents the trajectory generation system, which runs a policy-controlled simulation and records the complete state evolution for analysis and visualization. The system includes the primary JavaScript generation script generateTrajectory.js and a Python implementation test_trajectory.py. These tools create a sequence of step files containing position, velocity, muscle activation, and policy trace data. For information about the trajectory data format, see 9.3 Trajectory Data Format For information about rendering trajectories to video, see 9.2 Trajectory Rendering

Overview

The trajectory generation system executes a neural network policy-controlled simulation and captures the complete state at each timestep. The primary script is test/nn/generateTrajectory.js11-70 which orchestrates the simulation loop and outputs structured data files. This data serves two purposes:

Regression testing: Validating that physics simulation and policy behavior remain consistent across code changes test/nn/trajectory.test.js11-47
Visualization: Providing frame-by-frame data for rendering videos of creature behavior.

The trajectory generator is implemented as a Node.js script that uses the algovivo JavaScript API with WebAssembly physics simulation. A mirrored Python implementation exists for use with the native C++ library utils/py/test/trajectory/test_trajectory.py9-45

Sources: test/nn/generateTrajectory.js11-70 test/nn/trajectory.test.js11-47 utils/py/test/trajectory/test_trajectory.py9-45

Command-Line Interface

The JavaScript trajectory generation script test/nn/generateTrajectory.js11-70 accepts the following arguments via argparse test/nn/generateTrajectory.js12-17:

Argument	Default	Description
`--mesh-filename`	`test/nn/data/mesh.json`	Path to mesh configuration file containing vertex positions, muscles, triangles test/nn/generateTrajectory.js13
`--policy-filename`	`test/nn/data/policy.json`	Path to policy data file containing neural network weights and parameters test/nn/generateTrajectory.js14
`-o`, `--output-dirname`	`trajectory.out`	Directory where trajectory step files will be written test/nn/generateTrajectory.js15
`--steps`	`100`	Number of simulation steps to generate test/nn/generateTrajectory.js16

Usage Example

Sources: test/nn/generateTrajectory.js12-17

Initialization Phase

Diagram: Trajectory Generation Initialization Sequence

The initialization phase in test/nn/generateTrajectory.js11-42 performs the following operations:

Argument Parsing

Command-line arguments are parsed using ArgumentParser test/nn/generateTrajectory.js12-17 This configures input file paths, output directory, and step count.

Parallel Asset Loading

Three resources are loaded concurrently using Promise.all test/nn/generateTrajectory.js21-25:

WebAssembly Instance: loadWasm() compiles the WASM binary containing physics simulation code test/nn/generateTrajectory.js22
Mesh Data: JSON file containing initial vertex positions, muscle definitions, triangles, and material properties test/nn/generateTrajectory.js23
Policy Data: JSON file with trained neural network weights (fc1, fc2) and control parameters (min_a, max_abs_da, center_vertex_id, forward_vertex_id) test/nn/generateTrajectory.js24

System Configuration

The System constructor is called with the WebAssembly instance test/nn/generateTrajectory.js27 The system is then configured with mesh geometry using system.set() test/nn/generateTrajectory.js29-35

Policy Initialization

An MLPPolicy instance is created with a reference to the system and active: true test/nn/generateTrajectory.js36-39 The policy.loadData() method loads the trained weights into the underlying nn.Sequential model algovivo/nn/MLPPolicy.js109-121

Sources: test/nn/generateTrajectory.js11-42 algovivo/nn/MLPPolicy.js109-121

Trajectory Generation Loop

Diagram: Trajectory Generation Loop Execution Flow

The generation loop test/nn/generateTrajectory.js45-65 executes for the specified number of steps, performing the following operations at each iteration:

Pre-Step State Capture

Before advancing the simulation, the script captures the current state (pos0, vel0, a0) by calling toArray() on the system tensors test/nn/generateTrajectory.js47-51

Policy Execution with Tracing

The policy computes muscle activation updates using a trace object to capture intermediate values test/nn/generateTrajectory.js53-54 The trace object is populated by MLPPolicy.step() algovivo/nn/MLPPolicy.js92-97 with:

policyInput: The constructed input vector (projected positions/velocities) algovivo/nn/MLPPolicy.js95
policyOutput: The raw neural network output before clamping algovivo/nn/MLPPolicy.js96

Physics Integration

The system advances one timestep using system.step() test/nn/generateTrajectory.js55 This triggers the optimization-based integration in the core.

Post-Step State Capture and File Output

After the physics step, updated states and policy traces are captured test/nn/generateTrajectory.js57-61 Each step's data is written to a numbered JSON file in the output directory test/nn/generateTrajectory.js63-64

Sources: test/nn/generateTrajectory.js45-65 algovivo/nn/MLPPolicy.js92-97

Component Integration

Diagram: Component Integration and Data Flow

The trajectory generator interfaces with core components:

System Component

The System class provides state access via tensor properties (pos0, vel0, a) and advances simulation via system.step() test/nn/generateTrajectory.js48-55

MLPPolicy Component

The MLPPolicy class algovivo/nn/MLPPolicy.js8-129 handles:

Input Projection: Calls make_neural_policy_input in WASM to project vertex data relative to a reference frame defined by centerVertexId and forwardVertexId algovivo/nn/MLPPolicy.js58-68
Inference: Uses an nn.Sequential model consisting of Linear, ReLU, and Tanh layers algovivo/nn/MLPPolicy.js39-45
Activation Update: Modifies system.a by adding the model output da and clamping to [minA, 1.0] algovivo/nn/MLPPolicy.js101-106

Validation Checks

The system is validated by test/nn/trajectory.test.js, which ensures determinism: replaying a trajectory from saved pos0 and a0 yields identical results to the saved pos1 and a1 test/nn/trajectory.test.js31-46

Sources: test/nn/generateTrajectory.js27-55 algovivo/nn/MLPPolicy.js8-129 test/nn/trajectory.test.js31-46

Output Structure

After execution, the output directory contains sequentially numbered JSON files test/nn/generateTrajectory.js63:

trajectory.out/
├── 0.json      # Step 0: pos0, vel0, a0, pos1, vel1, a1, policy_input, policy_output
├── 1.json      # Step 1
└── ...

Console output tracks progress (e.g., 1 / 100), and the final message indicates completion test/nn/generateTrajectory.js46-67

Sources: test/nn/generateTrajectory.js46-67