Using the Studio — VehicleLab Documentation

Three focused workspace modes

Study is the default and pairs compact configuration controls with the dominant result area. Explore replaces that workspace with range controls and sweep evidence. Compare replaces it with Baseline/Variant A setup and paired outputs. Switching modes does not create new browser routes or persistence.

Run provenance and Model & assumptions are keyboard-accessible disclosures in the workspace header. Common physical and road settings remain visible; initial state, duration, RK4 step, and detailed range guidance remain available under Advanced settings.

Working with VehicleLab projects

Open the Project disclosure in the workspace header to add an optional project name, engineering objective, and plain-text notes. Export projectdownloads a deterministic, human-readable .vehiclelab.json file for the active Study, Explore, or Compare definition. A project file records what should be run; it does not contain time-history arrays, completed metrics, plot images, or transient browser state.

Configure Study, Explore, or Compare and optionally add project details.
Choose Export project to save the definition locally.
Use New project to return to the generic Study default.
Choose Import project. VehicleLab parses and validates the complete file locally before replacing the workspace.
Rerun the restored definition to regenerate authoritative numerical evidence. Compare and Explore imports never display old result state from the previous project.

Only vehiclelab.project.v1 is supported in this release. Malformed files, unknown schemas, invalid values, and incompatible model or solver identities are rejected without modifying the current workspace. The Zhao benchmark context and its evidence link are restored when present explicitly in a supported exported benchmark project.

Export provenance downloads a compact deterministic JSON manifest with the project schema, product/model/solver identities, execution environment, Float64 precision, benchmark evidence identity where applicable, and the saved definitions. There is no project library, autosave, LocalStorage, IndexedDB, account, or cloud save in Release 0.6.

Vehicle parameters

VehicleLab uses SI units throughout. Runtime validation remains authoritative in the Zod study schema; the same typed field metadata supplies this guide and the Studio help. Non-positive masses, stiffnesses, and damping are invalid because the current equations and intended passive model require positive physical values.

Sprung mass

Body-side mass supported by this suspension corner.

Unit: kg
Accepted: >0 to 2,000 kg
Input step: 10 kg

Represents one corner share of the supported vehicle-body mass.

Unsprung mass

Wheel-side mass represented below the suspension.

Unit: kg
Accepted: >0 to 500 kg
Input step: 1 kg

Represents wheel, tire, hub, and associated moving corner mass.

Suspension stiffness

Linear spring rate between the sprung and unsprung masses.

Unit: N/m
Accepted: >0 to 500,000 N/m
Input step: 100 N/m

Relates suspension force to relative vertical displacement.

Suspension damping

Linear viscous damping across the suspension.

Unit: N·s/m
Accepted: >0 to 50,000 N·s/m
Input step: 50 N·s/m

Relates damping force to relative vertical velocity.

Tire stiffness

Linear vertical stiffness between wheel-side mass and road.

Unit: N/m
Accepted: >0 to 2,000,000 N/m
Input step: 1,000 N/m

Relates tire force to dynamic tire deflection under continuous contact.

Road inputs

FlatZero displacement throughout

Cubic smooth stepRises smoothly and remains elevated

Half-sine bumpTransient event that returns to zero

Raised-cosine bumpZero slope at onset, peak, and return

Flat road

Shape: zero displacement for the full study.

Typical use: equilibrium and free-response studies.

Timing: no event parameters; it remains at zero.

Cubic smooth step

Parameters: start time (s), amplitude (m), and rise duration (s).

Typical use: transient response followed by a new permanent road height.

Timing: the rise must finish within the study; the road does not return to zero.

Half-sine bump

Parameters: start time (s), peak amplitude (m), and bump duration (s).

Typical use: isolated transient ride excitation.

Timing: the complete bump must fit; the road returns to zero.

Raised-cosine bump

Parameters: start time (s), peak amplitude (m), and bump duration (s).

Typical use: isolated zero-slope bump excitation and the published Zhao et al. benchmark.

Timing: the road is exactly zero at both boundaries and reaches its peak at the midpoint.

Opening a published benchmark

The stable URL /studio/?benchmark=zhao-2015-passive-bumploads the source-audited Zhao et al. passive bump study and runs it automatically. A visible benchmark-context notice links to the detailed evidence page.

Reset to benchmark restores the audited parameters, road, zero state, duration, and step.
Return to generic study removes benchmark context and reruns the normal default.
Compare remains available, so Variant A can explore one physical-parameter change under the benchmark road and solver scenario.
Plots and optional motion playback work from the completed benchmark result exactly as they do for generic studies.
Unknown benchmark query values safely fall back to the generic default without a benchmark claim.
Exporting and importing the benchmark project preserves its explicit context, exact audited definition, reset behavior, and evidence link; evidence data remains built into VehicleLab rather than embedded in every project file.

Solver settings

Simulation duration: 0.01 to 30 s
Requested fixed RK4 step: 0.0001 to 0.02 s
Maximum workload: 100,001 samples
Sweep workload: 3–25 cases; 500,000 total samples
Repeatability: Deterministic for identical valid input

A smaller requested step increases both sample count and computation. If duration is not exactly divisible by the requested step, VehicleLab uses one shorter final step so the final sample lands exactly on the requested duration.

Running a study

The generic default study executes automatically when the Studio opens.
Choose Run study after editing valid inputs.
The run status reports preparation, completion, or a validation/runtime error.
The dedicated browser Web Worker executes the fixed-step study.
Choose Reset defaults to restore and rerun the generic preset.

Exploring one physical parameter

Choose Explore from the mode navigation or Study actions. Release 0.6 supports suspension damping and suspension stiffness. Enter a finite minimum, maximum, and integer case count; the minimum must be lower than the maximum and both must remain inside the same physical bounds shown for ordinary inputs. Invalid values are rejected rather than clamped.

VehicleLab includes both requested endpoints exactly and generates every other candidate in deterministic ascending order. All non-swept physical parameters, road input, initial state, duration, requested step, model, and solver come from the current Baseline and are identical for every candidate. Progress identifies the active candidate. Cancel stops work by terminating and recreating the local Worker; no simulation data is uploaded.

Run the sweep and read the canonical table of all four existing metrics.
Inspect four parameter-response plots and the RMS-acceleration-versus-suspension-travel plot. Markers are actual simulations; VehicleLab does not interpolate or optimize.
Select a candidate from a table radio control or keyboard-focusable plot marker.
Choose Use as Variant A. Only its physical configuration is copied; the Baseline and shared scenario remain unchanged.
Choose Run comparison to use the normal detailed comparison path.

Export sweep CSV downloads a deterministic UTF-8 summary containing the swept parameter and unit, all four metric values and units, schema and release identity, model, solver, execution environment, and precision. It contains no arbitrary browser state. After any input or sweep edit, “Edited — rerun required” appears while the prior completed record remains unchanged; only a fully completed rerun replaces it.

Comparing Baseline and Variant A

Choose Compare to copy the current physical parameters into Variant A. The road input, initial state, duration, RK4 step, model identity, and solver identity remain one shared scenario so both configurations receive the same excitation and numerical treatment.

Edit either physical-parameter panel.
Choose Run comparison.
Review changed parameters, neutral metric deltas, and original-channel overlays.
If an input changes afterward, the Studio reports Edited — rerun requiredwhile retaining the last complete comparison snapshot.
Choose Return to Study to leave Compare and return to the single-study workspace with the current baseline configuration.

Motion playback

Motion is hidden by default. Choose Show motion playback to reveal the schematic, then use Play/Pause, Restart, the time slider, and 0.5×, 1×, or 2× speed. Choose Hide motion playback to pause and collapse it immediately.

A completed comparison adds a Baseline/Variant A selector. Both use the same simulation time, road input, and visual scale. Movement is amplified and not drawn to geometric scale. The playback linearly interpolates between stored samples for display only; plots, metrics, and V&V evidence continue to use stored outputs. Editable inputs do not affect playback until a new completed result replaces the snapshot.

Exporting engineering evidence

Export actions appear only beside relevant completed results. Filenames use the sanitized project name, or vehiclelab when the project is untitled. CSV uses deterministic columns, candidate/sample order, UTF-8 text, CRLF line endings, and JavaScript’s round-trip-safe number representation without display rounding.

Study CSV contains time, road displacement, sprung/unsprung displacement and velocity, sprung acceleration, suspension travel, and dynamic tire deflection from the exact completed channels.
Comparison CSV aligns Baseline and Variant A channel pairs on the authoritative shared time base. Summary CSV contains changed physical parameters and the stored metric deltas, units, relative deltas, and direction.
Sweep CSV preserves canonical ascending candidate order and the existing metric/unit contract.
Export PNG on each Study, Compare, or Explore plot directly renders the authoritative arrays to a 1600 × 1000 image with curves or candidate markers, title, legend, axes, grid, and units. It does not copy uPlot, screenshot the page, resample, smooth, normalize, or change plot semantics.
Export Engineering Report generates a selectable-text A4 PDF locally from the completed immutable Study, ComparisonRecord, or SweepRecord. The report includes configuration, authoritative metrics or deltas, the same professional plot renderer, provenance, assumptions, and limitations. Zhao benchmark reports also include the numerical-reproduction evidence context.

Project JSON defines what to reproduce; CSV preserves raw numerical output; PNG is a professional engineering figure; PDF communicates the completed engineering evidence. DOCX and customizable report builders are not included.

Result provenance

Which inputs produced the visible results?

Editable controls may change after a simulation completes. The displayed “Current study” summary continues to describe the completed input snapshot that generated the visible metrics and plots. Edited values do not alter those results until you rerun. Engineering Report export follows the visible immutable record and never substitutes edited-but-unrun simulation inputs.

Data and privacy

Simulation parameters, imported project files, and generated JSON, CSV, PNG, and PDF artifacts remain in the browser. VehicleLab has no simulation/report backend, account system, or saved-project database. Cloudflare Web Analytics applies only to ordinary production page traffic; no custom simulation parameters or result channels are intentionally sent to analytics.

Read the complete privacy behavior →