Structure

• kalast/: Python wrapper. Provides Pythonic usage of Kalast (e.g. object references) for users less familiar with Rust. Built with maturin.

• src/: Rust core of the simulation. Written to be usable standalone by Rust users, independent of Python — the Python wrapper must not compromise its speed.

• shaders/: wgpu shaders (.wgsl) used by the rendering pipeline.

• examples/: Examples of usage of Kalast. Scripts under examples/old/ are earlier/superseded versions kept for reference, not maintained as user-facing examples.

• res/: resources folder (if missing get it from cloud-as.oma.be).

• out/: default output directory for simulation results.

Compilation

Create a virtual environment to install dependencies and compile code, I recommend astral uv for Python. Then, from within you venv, run the following.

Build the kalast rust dynamic library kalast/_rs.cpython-314-darwin.so (example for Mac).

maturin develop

Use --release for anything measured or run in earnest – debug is 2-15x slower, worst on the per-pixel frame-export loops (measured 22.6 -> 53.1 it/s at 3.1M facets with export on). Keep plain maturin develop while implementing a feature, and rebuild with --release once it works.

maturin develop --release

Beyond the default opt-level = 3 there is nothing worth adding: lto = "fat" + codegen-units = 1 was measured on this project and gave no improvement (render loop 52.7 vs 55.1 it/s, mesh load+flatten 1.07 vs 1.10 s, both inside run-to-run noise) while pushing the build from ~59 s to ~87 s. Recorded in Cargo.toml so it is not retried blindly.

Run a Python example.

python -i examples/two_spheres/main.py

Import kalast from Python and start writing your own scripts.

import kalast;