Environment Setup - FASTSim Documentation

A few options exist for environment setup:

Pixi (recommended)
Anaconda
Custom

1. Pixi¶

Pixi is a tool that ensures environment hygiene and reproducibility. FASTSim has an established setup for Pixi that you can take advantage of to quickly get started.

Pixi Installation¶

Full installation instructions are available in the pixi docs: https://pixi.prefix.dev/latest/installation/

After installation, confirm pixi is available in a fresh terminal:

pixi --version

Environment Installation¶

From the repository root, install FASTSim and development dependencies:

pixi install -e dev

The dev environment installs all tools (Rust compiler, maturin, pytest, ruff, docs, and LSP packages) and uses a debug Cargo profile for fast incremental rebuilds. Other available environments:

Environment	Purpose	Cargo profile
`default`	Install from source, optimized for runtime	release
`build`	CI: rust checks + python tests	debug
`release`	Publish step (twine)	release
`docs`	Build and serve documentation	release
`dev`	Day-to-day iteration (direnv default)	debug

Running Tests¶

Use the check task to run the full local check suite (version consistency, cargo fmt --check, cargo test, a debug-profile maturin build, and pytest with nbmake using pytest-xdist):

pixi run check

All tasks:

Task	What it does
`check`	Full developer check suite (runs `check-versions`, `rust-check`, `py-build`, and `py-test-xdist`)
`rust-check`	`cargo fmt --check` + `cargo test`
`py-build`	`maturin develop --uv --profile dev` (fast debug build)
`py-build-release`	`maturin develop --uv --release` (explicit release build)
`py-test`	`pytest -v` inside the `build` env (serial), with notebook coverage
`py-test-xdist`	`pytest -v -n auto --dist=loadscope` inside the `build` env for parallel tests, with notebook coverage
`docs`	Start a live-reloading Jupyter Book server
`build-docs`	Full docs build (strict, HTML)

Environment Usage¶

To use the environment in a terminal:

Run individual commands:

pixi run -e dev <command>

Or, activate an interactive shell:

pixi shell -e dev

See the Pixi documentation or run pixi --help for more usage information. The direnv tool automates launching a shell for you, and FASTSim has a preconfigured .envrc file.

direnv: Automatic Environment Activation¶

If you use direnv, you can auto-load the pixi dev environment when entering this repository.

Setup:

Install direnv: https://direnv.net/docs/installation.html
Enable the hook for your shell (see direnv docs).
Allow direnv to run .envrc:
```
direnv allow
```

After that, entering the directory will auto-activate the pixi dev environment. Messages about environment variables can be suppressed by creating ~/.config/direnv/direnv.toml containing the line:

hide_env_diff = true

2. Anaconda¶

Anaconda users can easily install Rust using the conda-forge rust package

Create a new environment with Python and Rust (e.g. named fastsim)
```
conda create --name fastsim python=3.12 rust -c conda-forge
```
Activate the new environment
```
conda activate fastsim
```
From the repository root, install FASTSim and development dependencies:
```
pip install --upgrade pip
pip install --group dev -e .
```

Note

This section suggests dependencies independent of the pyproject.toml, so may become outdated.

As of writing, a way to build an Anaconda environment from pixi.lock using the conda-lockfiles plugin is nearly supported:

conda install --name base conda-forge::conda-lockfiles

conda env create --name fastsim --file pixi.lock

However, this plugin only supports pixi.lock version 6, while version 7 released in May 2026.

Output:

PluginError: Failed to parse environment specification from file: field 'version': Input should be less than or equal to 6

Relevant links:

3. Custom¶

If you do not want to use Pixi or Anaconda, install Rust and Python dependencies manually.

Install Rust system-wide: https://www.rust-lang.org/tools/install
Create and activate a Python environment (using your environment manager of choice).
From the repository root, install FASTSim and development dependencies:
```
pip install --group dev -e .
```