Atlas Engine

Atlas is a C++20 particle simulation engine for rarefied-gas flows using direct simulation Monte Carlo (DSMC). It runs on CPUs through TBB or NVIDIA GPUs through CUDA. The Python package exposes the same core simulation objects, while the native Interactive subsystem provides JSONL control and OpenGL rendering.

Atlas includes:

• hard-sphere, variable hard sphere (VHS), and variable soft sphere (VSS) collision models;
• analytic shapes and OBJ triangle meshes;
• configurable particle sources, generators, colliders, and sinks;
• per-particle and per-cell state with protobuf snapshots;
• owned NumPy snapshots through the Python binding;
• native headless simulation control and real-time particle rendering.

Choose a workflow

Clone the repository with its build dependencies:

git clone --recurse-submodules https://github.com/Wontae-Lee/atlas-engine-dev.git
cd atlas-engine-dev

If the repository is already cloned, initialize dependencies with git submodule update --init --recursive.

Docker

Build and run the bundled Python cylinder case on TBB:

docker build --target tbb -t atlas:tbb .
docker run --rm atlas:tbb \
    python /opt/atlas/examples/python/main.py cylinder 40

For CUDA, the host needs an NVIDIA driver and NVIDIA Container Toolkit:

docker build --target cuda -t atlas:cuda .
docker run --rm --gpus all atlas:cuda \
    python /opt/atlas/examples/python/main.py cylinder 40

The runtime images also contain the native Interactive executables. Published image tags, Ubuntu variants, GPU/display access, and development images are covered by the Docker guide.

Python

Atlas is distributed as atlas-engine and imported as atlas. A local TBB source installation on Ubuntu needs a C++ toolchain, CMake, Ninja, TBB, and Python development headers:

sudo apt-get update
sudo apt-get install -y build-essential cmake ninja-build git libtbb-dev python3-dev python3-venv
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install . -C cmake.define.ATLAS_DEVICE_SYSTEM=TBB

Select an installed engine before importing native classes, then construct and advance the core objects directly:

import atlas
import numpy as np

atlas.set_default_engine("tbb")
from atlas import Float3, Fluid, System, Universe

fluid = Fluid.from_arrays(
    np.array([[0.25, 0.5, 0.5]], dtype=np.float32),
    np.array([[1.0, 0.0, 0.0]], dtype=np.float32),
)
universe = Universe(Float3(0), Float3(1), cell_size=0.5)
universe.set_state(
    "number_particle", np.zeros(universe.cell_count, dtype=np.float32)
)
system = System(fluid, universe, dt=0.01)

for _ in range(10):
    system.update()

print(system.fluid.positions())

Run the maintained DSMC case with:

python examples/python/main.py cylinder 40

Engine selection, wheel construction, NumPy ownership, and binding layout are documented in the Python guide.

C++

Build and run the native cylinder example with the TBB backend:

cmake --preset tbb-gcc-release -DATLAS_EXAMPLES=ON
cmake --build build/tbb-gcc-release --target atlas_example
./build/tbb-gcc-release/examples/cpp/atlas_example cylinder 40

Use the cuda-release preset for the CUDA backend. Atlas public C++ types are in the atlas:: namespace and can be included through <atlas/atlas.h>. The examples guide explains the entry points, templates, and case layout.

Interactive

The headless atlas-interactive executable accepts newline-delimited JSON commands and can initialize a simulation from a JSON case:

cmake -S . -B build/interactive-headless-tbb -G Ninja \
    -DATLAS_DEVICE_SYSTEM=TBB \
    -DATLAS_INTERACTIVE=ON \
    -DATLAS_INTERACTIVE_RENDERING=OFF \
    -DATLAS_PYTHON=OFF \
    -DATLAS_EXAMPLES=OFF \
    -DATLAS_BENCHMARKS=OFF
cmake --build build/interactive-headless-tbb --target atlas-interactive-app
./build/interactive-headless-tbb/src/interactive/atlas-interactive \
    --config examples/interactive/cases/cylinder.json

For the native OpenGL window:

sudo apt-get install -y libgl1-mesa-dev libglew-dev libglfw3-dev libglm-dev
cmake --preset tbb-application-release
cmake --build build/tbb-application-release --target atlas-interactive-example
./build/tbb-application-release/examples/interactive/atlas-interactive-example cylinder 40

With rendering enabled, atlas-interactive accepts render_open and render_close JSONL commands for an existing session. Closing the window leaves that session alive. The Interactive guide documents configuration, commands, rendering, and backend state transfer.

Documentation

• Examples and adding a case
• Python binding
• Interactive execution and rendering
• Docker images
• Core architecture
• Core modules
• Build and contributor documentation
• CI behavior
• Release operations

Citation and license

If you use Atlas in research, cite the version used for your results. CITATION.cff contains the citation metadata for the current release. The concept DOI covers all releases.

Atlas is licensed under GPL-3.0-or-later.