Skip to content

Latest commit

 

History

History
207 lines (161 loc) · 10.7 KB

installation.md

File metadata and controls

207 lines (161 loc) · 10.7 KB

Install AISim

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.

Choose a package and matching documentation

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__)'

Published packages

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 --help

An 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.

Platform matrix

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-check

This 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.

Migrate to the renamed distribution

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 --help

AISim 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 check

If 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.

Use current source

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 --help

To 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.

Use an internal nightly

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.whl

Replace 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.

Optional Dynamo integration

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.