Suspension Explorer

Appearance

Getting started (CLI) ​

While Suspension Explorer provides an interactive app for quick exploration, the core Python package offers a command line interface (CLI) for users who require more control, customization, and/or flexibility for advanced use cases.

Interactive app

The interactive app requires no installation. See Getting started for the app workflow.

When to use the CLI ​

The Python package is best-suited to users who need repeatable file-based analysis, structured exports, and who have complex sweep requirements.

The underlying core solver supports coordinated point, actuator, and element-length drivers. Eligible derived points, which are calculated from other suspension geometry rather than authored as hardpoints, can also serve as sweep targets. Solver design explains how those targets couple back to the free points and how local response derivatives are calculated.

Install the package ​

Requirements

The core package requires Python 3.12 or newer. It is not currently published to PyPI, so install it directly from the GitHub repository. A virtual environment is recommended; the examples use uv.

Create an environment ​

bash
uv venv
source .venv/bin/activate

Core library ​

Install the transport-independent solver API:

bash
uv pip install \
  "kinematics @ git+https://github.com/suspension-explorer/suspension-explorer-core.git"

The core installation includes NumPy, SciPy, and Pydantic. YAML, CLI, export, and visualization dependencies require optional extras.

CLI and file export ​

Add YAML loading and CSV/Parquet export support:

bash
uv pip install \
  "kinematics[cli] @ git+https://github.com/suspension-explorer/suspension-explorer-core.git"

CLI with visualization ​

Install the CLI plus static plotting and animation support:

bash
uv pip install \
  "kinematics[cli,viz] @ git+https://github.com/suspension-explorer/suspension-explorer-core.git"

Run a maintained example ​

Use a development checkout to run the maintained geometry and sweep examples:

bash
git clone https://github.com/suspension-explorer/suspension-explorer-core.git
cd suspension-explorer-core
just setup

The development workflow uses uv for Python environments and just for common tasks.

First, validate and render the axle at its design condition:

bash
uv run kinematics visualize \
  --geometry tests/data/axle_geometry.yaml \
  --output geometry.png

Then solve a coordinated sweep and write the result to CSV:

bash
uv run kinematics sweep \
  --geometry tests/data/axle_geometry.yaml \
  --sweep tests/data/axle_sweep.yaml \
  --out results.csv

Each output row represents one sweep step. The file includes solved point coordinates, applicable metrics, and solver information. Use a .parquet output suffix for Parquet, or add --animation-out motion.gif to render the solved motion.

Inputs ​

A CLI analysis uses two YAML documents:

  1. A geometry defines design-condition hardpoints, architecture, vehicle and axle configuration, steering, and installed mechanisms.
  2. A sweep defines one or more coordinated target motions, such as wheel-center travel and steering-rack displacement.

Targets are paired by sweep-step index; they are not expanded into a Cartesian product. Every physical actuator must be controlled exactly once. A rack-steered model therefore needs a rack target even when steering stays at its design position.

yaml
version: 1
steps: 41
targets:
  - type: point
    point: wheel_center
    side: left
    direction: { axis: z }
    mode: relative
    start: -40
    stop: 40

  - type: point
    point: wheel_center
    side: right
    direction: { axis: z }
    mode: relative
    start: -40
    stop: 40

  - type: actuator_position
    actuator: rack
    direction: { axis: y }
    mode: relative
    start: 0
    stop: 0

relative values are measured from the authored design condition. For point and actuator-position targets, absolute values are projected coordinates in the chassis-fixed frame. For element-length targets, an absolute value is the true pin-center length in millimeters.

Embed the solver ​

Applications can call kinematics.core with already-decoded mappings. This API does not depend on YAML or the filesystem:

python
from kinematics.core.analysis import analyze_sweep
from kinematics.core.input import build_suspension, build_sweep

suspension = build_suspension(geometry_data)
sweep = build_sweep(sweep_data, suspension)
analysis = analyze_sweep(suspension, sweep)

for frame in analysis.frames:
    print(frame.index, frame.positions, frame.metrics)

The structured analysis includes suspension metadata, point positions, metrics, per-frame solver information, renderer-neutral element paths, reference conditions, and diagnostics.

Reproducible installs ​

The package commands above install the current default branch. Pin a release tag or commit after .git when reproducibility matters:

bash
uv pip install \
  "kinematics[cli] @ git+https://github.com/suspension-explorer/[email protected]"

Check the suspension-explorer-core releases for the latest available version.

Next steps ​