BobSim

BobSim runs vehicle response studies, performance envelopes, and lap simulations. It uses KinPy for suspension geometry, DynPy for 3/6/10/14DOF dynamics, and BobLib for Modelica multibody dynamics. The browser app and make targets configure runs and display results.

Documentation: bobdyn.com. For this checkout, see docs. Contributor instructions are in AGENTS.md.

Repository Layout

• engines/: sibling kinpy, dynpy, and boblib physics tools.
• simulations/: response studies, envelopes, and laps.
• optimization/: sweeps, setup solving, and trade studies across simulations.
• common/: vehicle I/O, templates, plotting, reporting, and packaging.
• visualization/: replay data and scene capture.
• app/: browser UI for vehicle setup, simulation, and results.
• tests/: unit and regression tests.
• vehicle.yml: vehicle input for Python workflows. Modelica studies use generated BobLib records. make sync-vehicle checks that the records match the YAML.

App Quick Start

Initialize the BobLib submodule:

make init

Build the Docker development image:

make docker-build

Show the available targets:

make help

The Docker image is based on OpenModelica and installs the Python dependencies from requirements.txt.

Start the BobSim app:

make app

Then open http://127.0.0.1:8765. The app runs in Docker and uses the image's OpenModelica, so the app's simulations need no local install. Use make app APP_PORT=8766 for another port, or make app RUN= to run it on the host.

The app supports vehicle editing, Modelica record generation, simulation runs, logs, and saved results. Builds and results are generated locally and excluded from Git.

Desktop Packaging

Build the BobSim desktop deploy artifact:

make deploy

Deploy builds the desktop wrapper with the Python backend bundled. It does not package simulation executables, reports, or app caches. The app generates those on the user's machine. Deploy outputs are written under common/deploy/dist/BobSim/.

Package the current local artifact for release:

make deploy-package DEPLOY_VERSION=2026.06.27

Clean, build, package, and optionally upload the current machine's native release artifact:

python common/deploy/deploy.py --release --install-deps --version 2026.06.27
python common/deploy/deploy.py --release --install-deps --version 2026.06.27 --upload-release

PyInstaller deploy artifacts are built per operating system. A local Linux build creates the Linux executable. Windows and macOS release assets are generated by the Release Builds GitHub Actions workflow when a v* tag is pushed or when the workflow is run manually. The release source and build tooling live on main. Generated .exe, .app, .zip, .tar.gz, and checksum files are attached to the GitHub Release and excluded from Git.

To generate a platform asset from another machine:

git fetch --tags
git checkout v2026.06.27
python -m pip install --upgrade pip
python -m pip install -r requirements.txt -r common/deploy/requirements.txt
python common/deploy/deploy.py --release --version 2026.06.27 --upload-release

Uploading requires the GitHub CLI (gh) to be installed and authenticated.

Release Checks

Run lint, type checks, and tests:

make ci

This runs:

• make lint
• make typecheck
• make test

GitHub Actions runs lint, type checks, and tests natively. A separate container job checks OpenModelica and DOE tooling. Full MBD baseline simulations run separately.

Run the full StandardSim baseline explicitly when you need to refresh or review simulation artifacts:

make regression-baseline

Simulation Commands

Target prefix	Workflow
standard-*	BobLib MBD response and four-post studies
reduced-*	DynPy transient response and correlation
envelope-*	DynPy quasi-steady GGV and YMD maps
lap-*	QSS racing-line optimization and transient laps
opt-*	Parameter sweeps, setup solving, and vehicle comparisons

make help lists all targets. Reduced transients use REDUCED_DOF=3|6|10|14. Envelope configs select generation.model_dof. Lap runs use LAP_DOF=3|6|10|14.

MBD Response Studies

Run all MBD response studies:

make standard-eval-all

That target builds missing executables, then runs RampSteerEval, SteadyStateEval, TransientEval, and FourPostEval.

Run individual studies:

make standard-eval-ramp-steer
make standard-eval-steady-state
make standard-eval-transient

make standard-eval-four-post

Build-only targets are also available:

make standard-build
make standard-build-four-post

Reports and metric CSVs are written under simulations/mbd/generated_results/.

Design of Experiments

Sample vehicle parameters and compare their performance metrics:

make opt-standard DOE_METHOD=lhs DOE_SAMPLES=3

That builds and runs FourPostEval if needed, then samples, compiles, simulates, and aggregates the variants. Reverse lookup against the aggregated table:

make opt-search METRICS="SteadyStateEval_understeer_gradient_deg_per_g=0.05" SEARCH_TOP=5

To validate the pipeline without an OpenModelica toolchain:

make opt-doe-smoke

See docs/doe-reverse-engineering.md for the sweep configuration and how to read a search result.

Cleanup

Remove local Python/tool caches:

make clean

Remove generated files for a workflow:

make clean-app
make clean-visual
make clean-lap
make clean-standard
make clean-envelope
make clean-opt
make clean-all