Skip to content

Setup Particula

To run the examples from source, clone the repository and install Particula:

Terminal window
git clone https://github.com/uncscode/particula.git
cd particula
python -m pip install -e ".[extra]"

Then run your first CPU simulation.

Choose the route that matches your comfort level:


See the conda, pip, or uv guides for exact commands.

If your Python Environment is already set up, install Particula directly using one of the following methods:


uv is a fast rust-based Python package manager.

Terminal window
uv pip install particula # uv ≈ much faster pip drop‑in

with optional extras:

Terminal window
uv pip install "particula[extra]"

pip is Python’s default package manager and installs packages from the Python Package Index (PyPI).

Terminal window
pip install particula # PyPI

with optional extras:

Terminal window
pip install "particula[extra]"

conda is a cross‑platform environment & package manager; Particula is distributed via the community‑maintained conda‑forge channel.

Terminal window
conda install -c conda-forge particula

Optional extras:

Terminal window
conda install -c conda-forge particula matplotlib pandas tqdm pint

Wheels built from this source include version-matched documentation. After installing such a release with pip install particula, no checkout or network connection is needed to read or search it:

Terminal window
particula-docs
python -m particula_docs --json
rg "ParticleData" "$(python -m particula_docs)/guide"

Use the Python interpreter from your Particula environment. The locator uses only the standard library and does not import simulation code, NumPy, or Warp. The JSON output records the package version, documentation path, file count, uncompressed source size, and manifest path. bundle-manifest.json records SHA-256 hashes and byte sizes for every bundled source file.

The bundle contains docs/index.md and the guide/, theory/, contribute/, examples/, data/, and images/ trees, preserving source bytes, directory structure, and relative links between included files. Python examples remain readable source; running them may require optional dependencies and hardware. Generated API pages, caches, website builds/saved website results, and .trash/ are excluded. Links to repository tooling or rendered website resources still require those resources; this is a searchable source bundle, not a built site.

For editable installations, the locator points directly to the repository’s maintained docs/ directory, so edits appear immediately. docs/ is the only maintained documentation source; particula/docs/ is generated in temporary build staging and must not be edited. Older releases without the locator can use their matching source documentation or the online documentation after checking version compatibility.

The development package requires Python 3.12 or newer and installs NumPy, SciPy, typing extensions and Warp. CPU simulations do not require a CUDA GPU; Warp remains a declared dependency even for CPU use. A separate distribution without Warp is not currently provided.

Importing Particula leaves application logging configuration unchanged and does not create package-local log files. Configure Python logging in your application when output is wanted, for example with logging.basicConfig. The particula logger accepts application handlers and levels. Calling particula.logger_setup.setup() explicitly retains the legacy file-logging configuration and requires write access to its configured destination.