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

You do not need to install anything to use the interactive app; see Getting started for more details.

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

Installing the package is relatively straightforward.

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

uv venv
source .venv/bin/activate

Core library

Install the transport-independent solver API:

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

This installs NumPy, SciPy, and Pydantic. It does not include YAML, CLI, export, or visualization dependencies.

CLI and file export

Add YAML loading and CSV/Parquet export support:

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:

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

Run a maintained example

For the quickest CLI path, use a development checkout. This gives you known-good geometry and sweep files alongside the solver:

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:

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

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

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.

Understand the two 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.

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:

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:

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

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

Next steps

• Read Supported models before authoring a new architecture.
• Check the Coordinate system before entering hardpoints.
• Read Solver design for the core’s constraint and derivative architecture.
• Browse the maintained example files for complete corner and axle definitions.