Installation¶

Homeostat needs Python 3.11 or newer. Its dependencies are NumPy, pandas, Pydantic and PyYAML.

Install from PyPI¶

Homeostat is on PyPI. The releases are alphas for now, so ask for pre-releases:

uv add --prerelease allow "homeostat[fast]"

pip install --pre "homeostat[fast]"

The fast extra adds Numba: the engine then compiles each plant into one function and runs it hundreds of times faster, with the same results (see The step). Without it, leave out [fast].

Check the installation:

python -c "import homeostat; print(homeostat.__version__)"
homeostat --version

The homeostat command validates and runs scenarios and prints the documentation; see Working with AI assistants.

Work on the source¶

To run the examples and the tests, or to change Homeostat itself, clone the repository and let uv create the environment:

git clone https://github.com/kausalflow/homeostat
cd homeostat
uv sync
uv run pytest

The examples in examples/ then run with uv run python examples/<name>.py. See Development for the tests, the documentation and the conventions.

Reproducibility¶

The same scenario, seed, Homeostat version and NumPy version give identical data. Every run records all four in run.meta["reproducibility"], so keep NumPy pinned (for example with a lock file) when you need to regenerate a dataset exactly.