Use Python 3.11–3.13 in an isolated environment. Simulation runs on the
host CPU; engine.hardware selects the GPU being modeled. A GPU serving
environment is required for collection and deployment benchmarks.
Documentation on main describes the current source. A published wheel may
predate a documented feature. Record your installed version before comparing
results or reporting a problem. For current aisim installs, use:
aisim --version
python -c 'import aisim; print(aisim.__version__)'
python -c 'import aisim, aisim._runtime; print(aisim.__file__); print(aisim._runtime.__file__)'For historical aisimulate installs, use the original Python namespace; those releases may not provide the aisim command or its new --version flag:
python -c 'import aisimulate; print(aisimulate.__version__)'
python -c 'import aisimulate, aisimulate._runtime; print(aisimulate.__file__); print(aisimulate._runtime.__file__)'The following example pins release 0.12.1. Use its
versioned documentation. Check the
PyPI release files and
GitHub releases for newer
artifacts and use the documentation associated with the selected release.
python3.13 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install 'aisimulate==0.12.1'
aisimulate --helpAn exact version pin makes the choice explicit. To discover newer published
prereleases, use python -m pip index versions --pre aisim.
python -m pip install aisim normally selects a stable release; --pre
allows prereleases. Neither command requests the latest repository source or
an internal nightly automatically.
When replacing standalone AIConfigurator, first follow the
package migration instructions
in the environment you intend to use. The aisim wheel owns both console
commands. Python imports use aisim and aisim_core; see
Python source migration for the breaking import change.
| Host | Current source wheel-build target |
|---|---|
| Linux x86-64 | manylinux_2_28_x86_64: glibc 2.28 or newer |
| Linux ARM64 | manylinux_2_28_aarch64: glibc 2.28 or newer |
| macOS Apple Silicon | macOS ARM64, deployment target 11.0 |
| macOS Intel, native Windows, musl-based Linux | No corresponding platform-wheel job |
The native wheels use cp311-abi3; the complete package still requires
Python 3.11–3.13 and compatible dependency wheels. A source build target does
not establish which artifacts were published or which dependency combinations
were tested. The platform-wheel workflow
defines build validation. Check the filenames of the release you select;
source build changes do not alter previously published wheels.
On Linux, check uname -m and ldd --version; on macOS, check uname -m and
sw_vers. To check wheel availability without compiling AISim:
python -m pip download --no-deps --only-binary=:all: \
'aisimulate==0.12.1' --dest wheel-checkThis checks only AISim's wheel, not all transitive dependencies. A missing wheel on an unlisted host does not establish source-build support there.
Current aisim wheels provide both aisim --version and aisimulate --version; these report the installed distribution as aisim VERSION. The two launchers expose the same predict, recommend, and onboard commands and options. Help and parser errors retain the invoked command name, including python -m aisim, python -m aisimulate, and supervised workers.
Current source builds aisim / aisim-core; historical published releases use
aisimulate / aisimulate-core. Changing a manifest does not publish the new
names. Use a verified aisim wheel or wait for its availability on your chosen
index before migrating.
The Python distributions install overlapping package files and console scripts.
Do not install them together. Prefer a fresh environment; for an existing
engine-only environment, remove the old distribution first, then install the
selected new wheel (or aisim==<published-version>):
python -m pip uninstall -y aisimulate && \
python -m pip install /absolute/path/to/aisim-VERSION-PLATFORM.whl && \
python -m pip check && \
aisim --help && \
aisimulate --helpAISim checks distribution metadata during import and CLI startup. If both aisim and aisimulate are installed, it raises an ImportError with repair commands before loading the native runtime. This check does not prevent pip from installing or overwriting shared files. An old distribution installed last can overwrite the legacy entry points and bypass the check through those old paths.
Use that same ordering for upgrades. To repair an environment where both distributions were installed, remove the old distribution and reinstall the exact selected wheel. Preserve the existing dependency set during this repair and validate it afterward:
python -m pip uninstall -y aisimulate && \
python -m pip install --force-reinstall --no-deps /absolute/path/to/aisim-VERSION-PLATFORM.whl && \
python -m pip checkIf pip or uv cannot uninstall the legacy distribution because its file records are missing, create a fresh environment and install the selected aisim wheel there. The in-place repair requires successful removal of the old distribution.
Uninstalling the old distribution can remove files listed in both RECORDs. Both CLI names remain available after migration. Canonical Python imports are aisim and aisim_core; aisimulate and aisimulate_core remain forwarding aliases.
Dynamo and other consumers must declare the distribution dependency
aisim before sharing the new environment. Use the matching Dynamo release
documented below and run pip check after
installing the complete environment. Skipping dependency installation is not a substitute for
updating that requirement.
For features documented on main, use a source checkout and record its commit:
git clone https://github.com/ai-dynamo/aisim.git
cd aisim
git rev-parse HEAD
uv sync --project python/aisim --extra dev
source python/aisim/.venv/bin/activate
aisim --helpTo repair an existing source-checkout environment after installing a legacy distribution, run these commands from that same checkout:
project_python="$(uv run --project python/aisim --no-sync python -c 'import sys; print(sys.executable)')" && \
uv pip uninstall --python "$project_python" aisimulate && \
uv sync --project python/aisim --extra dev --frozen --inexact --reinstall-package aisim && \
uv pip check --python "$project_python"The first command locates the checkout's existing project interpreter without syncing or importing AISim. It honors UV_PROJECT_ENVIRONMENT, including paths relative to python/aisim; otherwise, uv uses python/aisim/.venv. Keep that setting unchanged for the whole block so uninstall, sync, and check select the same environment. The sync command reinstalls this checkout and its CLI entry points using the existing lockfile, including shared files removed by the uninstall. --inexact retains unselected packages, including dependencies of other installed extras such as service or learned; the final check validates the resulting environment.
Install uv, a Rust toolchain with Cargo, and a C/C++ compiler plus platform
linker before syncing: Maturin compiles the native extension. On macOS, install
the Xcode Command Line Tools (xcode-select --install); Linux builds need
the equivalent compiler and linker tools. The workspace uses Rust edition
2024; the current macOS wheel job pins Rust 1.96.0. See the
build action for CI's
toolchain choices and DEVELOPMENT.md for validation.
Current performance data is checked-in Parquet. Git LFS is needed only for
retained legacy text assets and tests that use them. Re-run uv sync after
changes to Rust or packaging, and verify the imported paths shown above point
to the intended environment.
The nightly workflow produces a wheel
version such as 0.15.0.devYYYYMMDD, then stages artifacts to access-controlled
Artifactory through the protected release environment. The run subsequently
checks the downloaded wheel and qualifies its FPE support matrix. Use a
successful completed nightly: a successful build, staging step, or dev suffix
alone does not establish that validation completed. The nightly path is
nightly/<run_id>/, not a public PyPI release channel.
Obtain the wheel for your platform from Artifactory using your organization's
authenticated artifact access. For new runs, download the same run's nightly-dist-amd64-manifest or
nightly-dist-arm64-manifest Actions artifact. Its wheel-manifest.json identifies
the verified wheel, provenance.json, and SHA256SUMS.txt objects in Artifactory.
Fetch them with authenticated artifact access and verify the recorded sizes and
SHA-256 digests. Older runs retain these files in nightly-dist-<arch> archives;
see the handoff contract.
Verify the recorded source revision and wheel SHA-256, then install that exact
downloaded file:
python -m pip install /absolute/path/to/downloaded/aisim-VERSION-PLATFORM.whlReplace that illustrative filename with the actual wheel filename. Retain the source SHA, workflow run URL, wheel filename and SHA-256 with your results. The artifact contract describes wheel/crate versioning.
For --stack dynamo, install the AISim 0.14 RC4 and matching Dynamo 1.7 RC
wheels in a fresh Linux Python 3.12 environment, following the
root README. Keep AISim aligned with Dynamo's
declared dependency and run pip check after installation.
Planner requires additional dependencies from the same Dynamo revision as the installed wheels; see the Planner installation example.
The Dynamo deployment guide separately explains generated serving artifacts and runtime version pins. Installing a Dynamo adapter for simulation and launching a GPU serving container are different steps in that workflow.