Supported models

Suspension Explorer supports four main architectures. Each can be modeled as a standalone corner or as a composed two-corner axle.

See the generated suspension option tables, complete metric reference, and export column reference for the capabilities declared by the documented core version.

Model boundary

The solver models ideal rigid parts and joints. It calculates geometry and motion; it is not a compliance, load, tire, or structural analysis tool.

Locating architectures

Architecture	Model	Important limits
Double wishbone	Upper and lower wishbones locate a rigid upright around a physical steering axis.	Supports direct or pushrod-rocker actuation, the full spring selection, heave links, and every setup shim.
MacPherson strut	A lower arm and ideal telescoping strut locate the upright.	The strut is the installed spring/damper, with no separate actuation selector. Its clamp must lie on the lower-ball-joint-to-top-mount steering-axis segment within 1 mm. Toe is its only supported setup shim.
Multi-link (five-link)	Four independent locating links plus a track link or fixed toe link locate the upright.	There is no physical kingpin. Steering geometry is reported through the motion-derived *_virtual metric family, and geometrically undefined instant-center results can be empty. Pushrod and toe setup shims are supported; outboard camber shimming is not.
Semi-trailing arm	A rigid wheel carrier rotates around a horizontal, oblique pivot axis.	This model is unsteered and supports a coilover, or a pivot-mounted torsion bar with a separate damper. Shared anti-roll and heave mechanisms are not supported, and it takes no setup shims.

The corresponding geometry types are double_wishbone, macpherson, multi_link, and trailing_arm.

Corners and axles

A standalone model is authored as a left corner. A composed axle always contains two corners of the same architecture and can use either:

• Explicit left- and right-side hardpoints.
• A complete left-side definition with the right side omitted. In that case, the geometry and applicable side-local setup are mirrored through chassis Y = 0.

Steering, actuation, and springs

For double-wishbone, MacPherson, and multi-link models, wheel heading can be controlled by a translating steering rack or a fixed chassis toe link. Steering must be selected explicitly; an axle’s front or rear position does not choose it automatically. Semi-trailing-arm models are always unsteered.

Double-wishbone and multi-link corners share the composed actuation model:

• Actuation can be direct or pushrod-rocker.
• A double-wishbone pickup can mount to the lower wishbone or upright.
• A multi-link direct pickup can mount to the upright or the centerline of either lower link; a multi-link pushrod must mount to the upright.
• Springing can be omitted or supplied by a coilover or torsion bar. A torsion bar requires pushrod-rocker actuation.
• An independent linear inboard damper requires pushrod-rocker actuation and cannot be combined with a coilover.

U-bar and T-bar anti-roll mechanisms and a rocker-to-rocker heave link are available for double-wishbone and multi-link axles with pushrod-rocker actuation. Geometry is rejected when a selected mechanism combination has no implemented physical connection.

Setup shims

Setup shims describe a change made to an assembled car rather than a change to the design geometry. Each shim carries a design and a setup stack thickness in millimeters, and the solver applies the difference between them. An unchanged stack therefore has no effect, which lets a geometry record the parts it was built with and still solve at its design condition.

Shim	Available on	Applied change
Outboard camber	Double wishbone	Separates the two authored shim faces by the setup thickness, rotating the camber block about the upper ball joint and the upright about the lower ball joint.
Pushrod/pullrod	Double wishbone, multi-link	Changes the pushrod or pullrod length, which sets ride height when the rocker position is controlled.
Toe	Double wishbone, multi-link, MacPherson strut	Changes the installed track-rod or fixed-toe-link length, which changes wheel heading.

Pushrod shims require pushrod-rocker actuation; direct actuation has no pushrod or pullrod to shim. A positive value always lengthens the physical link, but whether that raises or lowers ride height, or adds toe-in or toe-out, depends on the authored mechanism geometry. The shim describes a part, not a signed metric change.

Because the model solves kinematics and not spring forces or static equilibrium, a pushrod shim sets ride height only when the rocker position is what the sweep controls, for example by holding or targeting the installed damper length. If wheel-center Z is targeted instead, that target sets ride height and the shim moves the corresponding rocker position.

On an axle, setup is authored under left_setup and, where the right-side hardpoints are given explicitly, right_setup. A mirrored right corner inherits the complete left setup. Geometry is rejected when a shim is configured on an architecture that cannot carry it.

Calculated outputs

Metric availability depends on the architecture and installed mechanisms. Current outputs include:

• Wheel travel, wheel-center position, half-track, ISO track, and track change.
• Toe angle, ISO steer angle, and camber.
• Caster, kingpin inclination, steering-axis offset, scrub radius, and mechanical trail where the architecture defines them, plus virtual equivalents where applicable.
• Instant-center geometry, swing-arm lengths, and roll center.
• Heave, suspension roll, ride-height change, and geometric anti-dive and anti-squat values.
• Damper, rocker, torsion-bar, anti-roll, and heave-link travel where installed.
• Applicable motion ratios and response derivatives.
• Solver statistics and structured diagnostics.

The primary sweep and applicable response derivatives combine analytical Jacobians, local solution-manifold tangents, and forward-mode automatic differentiation. See Solver design for the numerical architecture and its documented limits.

Explicitly outside the model

The current model does not include:

• Multibody dynamics, inertia, damping forces, applied loads, or transient behavior.
• Bushing, chassis, tire, or component compliance.
• Stress, fatigue, strength, or packaging and interference checks.
• Locating architectures other than the four listed above.
• Offset-axis MacPherson struts.
• Arbitrary mechanism combinations without an implemented physical connection.
• Whole-vehicle pitch, yaw, or longitudinal motion inferred from a single axle.

Export and visualization

The CLI can export solved positions, sweep coordinates, applicable metrics, and solver statistics to CSV or Parquet. Diagnostics are available through structured analysis results and are printed by the CLI; they are not embedded in those export files.

Static plotting and sweep animation require the optional visualization dependencies described in Getting started (CLI/Python package users).