Metadata-Version: 2.4
Name: kalast
Version: 0.5.0
Classifier: Programming Language :: Rust
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Requires-Dist: astropy>=8.0.1
Requires-Dist: matplotlib>=3.10
Requires-Dist: numpy>=2.5
Requires-Dist: pandas>=3
Requires-Dist: pyarrow>=24
Requires-Dist: pymeshlab>=2025.7
Requires-Dist: scipy>=1.16
Requires-Dist: spiceypy>=8
Requires-Dist: symfit>=0.5
Summary: TPM for binary asteroids
Requires-Python: >=3.14.3, <3.15
Description-Content-Type: text/x-rst; charset=UTF-8

======
kalast
======

Kalast is a thermophysical model (TPM) for binary asteroids, used to simulate
images as they would be seen from a spacecraft.

Shape models are made of triangular facets. The TPM is a forward finite
difference solver of the heat conduction equation, with boundary conditions:

1. at the surface, from solar radiation, mutual heating with a secondary
   body (thermal reflection and emission), and self-heating (with extra
   constraints for neighboring facets, e.g. shadowing/visibility);
2. at depth, using either an adiabatic condition or an internal flux
   condition for larger bodies (e.g. the Moon).

The surface boundary condition only applies to airless bodies (asteroids,
moons) without an atmosphere.

The image simulator renders shape models with a customizable observer
frustrum (position/specs), to reproduce images taken from a spacecraft. It
uses a custom wgpu + shader rendering pipeline. Images can be simulated in
visible light (diffuse lighting shader) or infrared (using TPM surface
temperature output and an infrared flux simulation — emission and
reflection — based on a thermal camera's specifications, e.g. its spectral
response function).

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

.. code:: sh

    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.

.. code:: sh

    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.

.. code:: sh

    python -i examples/two_spheres/main.py

Import kalast from Python and start writing your own scripts.

.. code:: python
   
   import kalast;
