kalix (Python)

Python interface for Kalix.

Current functionality:

  • run simulations from INI model files (in-process, no separate CLI binary)
  • run parameter optimisations from config files (in-process)
  • read and write Pixie files (.pxt, .pxb)

Planned:

  • programmatic model manipulation and building (a stateful Model class)
  • richer optimisation control (progress callbacks, in-memory configs)

Design

The package binds the Rust engine directly via PyO3 rather than driving the engine's stdio session protocol (which exists to serve KalixIDE). This keeps the Python surface free to grow in whatever direction suits Python workflows, independent of the GUI's needs.

The current functions are deliberately stateless and mirror the two main CLI subcommands — simulate and optimise — so that moving from the command line to Python feels the same: point at files, get results back. A stateful Model object (load → mutate → run → inspect, all in memory) is the natural next layer and is planned, but the file-to-result convenience functions are expected to remain useful indefinitely.

Install

pip install kalix

Usage

Run a simulation

import kalix

kalix.simulate("model.ini", output_file="results.pxb")
df = kalix.read_pixie("results.pxb")
print(df.head())

The Python equivalent of kalix sim model.ini -o results.pxb, but in-process — no separate CLI binary required. Output format is inferred from the extension (.pxb for the Pixie pair, .csv for CSV).

Both outputs are keyword-only, and at least one is required:

# Outputs + mass-balance report
kalix.simulate("model.ini", output_file="results.pxb", mass_balance="mb.txt")

# Mass-balance only
kalix.simulate("model.ini", mass_balance="mb.txt")

Run an optimisation

import kalix

result = kalix.optimise("calibration.ini", model_file="initial_model.ini", save_model="final_model.ini")

print(result["best_objective"])      # lower is better
print(result["parameters"])          # {"node.my_sac.uzfwm": 42.7, ...}
print(result["optimised_model_ini"]) # string copy of the final model ini

The Python equivalent of kalix optimise calibration.ini, but in-process. The config .ini defines the algorithm, calibration terms, objective expression, parameter bounds, and termination criteria. Unlike simulate, optimise returns a result dictionary:

key meaning
best_objective best objective value found (lower is better)
n_evaluations number of function evaluations performed
success whether the optimiser terminated successfully
message the optimiser's termination message
parameters optimised parameters as {target: physical_value}
optimised_model_ini the optimised model serialised back to an INI string

Two keyword-only options mirror the CLI's flags:

# Override the config's model_file (CLI: positional [model_file])
kalix.optimise("calibration.ini", model_file="other_model.ini")

# Also write the optimised model to disk (CLI: -s/--save-model)
kalix.optimise("calibration.ini", save_model="tuned.ini")

Paths inside the config (model_file, each term's observed_file) are resolved relative to the current working directory, exactly as the CLI does. If the config specifies an output_file, a results summary is written there too.

Read / write Pixie files

df = kalix.read_pixie("results.pxb")
print(df.head())

kalix.write_pixie("out.pxb", df)

The DataFrame index is a UTC DatetimeIndex; each column is one timeseries.

read_pixie accepts either extension (or no extension) and finds both files:

kalix.read_pixie("results.pxb")  # same as
kalix.read_pixie("results.pxt")  # same as
kalix.read_pixie("results")

write_pixie prefers a tz-aware DatetimeIndex, but will try to coerce other inputs (emitting a UserWarning when it does):

  • a naive DatetimeIndex is localised to UTC;
  • a default RangeIndex(0, n, 1) triggers promotion of the zeroth column to the index (and drops it from the body);
  • any other non-DatetimeIndex is passed through pd.to_datetime(..., utc=True).

Integer and float dtypes are never auto-interpreted as datetimes (this would silently misread values as epoch nanoseconds). Set a DatetimeIndex explicitly in those cases.

Building from source

Requires Rust (1.70+) and maturin.

# Editable install for development
cd python
maturin develop --release
# uv run maturin develop --release --uv

# Build a wheel
maturin build --release
# uv run maturin build --release -- uv

Tests

Running tests directly

maturin develop
pytest python/tests

Alternatively with uv:

uv run maturin develop --uv
uv run pytest

Running tests with tox

Tox is configured to test against multiple Python versions (3.9-3.14):

# Run tests in development environment (fast, uses current Python)
uv run tox -e dev

# Run tests against all configured Python versions
uv run tox

# Run tests for specific Python version
uv run tox -e py312

# List all available test environments
uv run tox list

# Run tests in parallel
uv run tox -p auto

Project links

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (0.4.4)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for chasodh from gravatar.com chasodh

Credits

Author: Kalix contributors

License expression

MPL-2.0
View SPDX License List

Requires

Python >=3.9

Provides Extra

test

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

kalix-0.4.0.tar.gz (4.2 MB view details)

Uploaded Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

kalix-0.4.0-cp39-abi3-win_amd64.whl (778.8 kB view details)

Uploaded CPython 3.9+Windows x86-64

kalix-0.4.0-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (891.9 kB view details)

Uploaded CPython 3.9+manylinux: glibc 2.17+ x86-64

kalix-0.4.0-cp39-abi3-macosx_11_0_arm64.whl (782.2 kB view details)

Uploaded CPython 3.9+macOS 11.0+ ARM64

File details

Details for the file kalix-0.4.0.tar.gz.

File metadata

  • Download URL: kalix-0.4.0.tar.gz
  • Upload date:
  • Size: 4.2 MB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.14

File hashes

Hashes for kalix-0.4.0.tar.gz
Algorithm Hash digest
SHA256 5d5330a139621dc2b64f0c0e1246f6ed91e325974a34780abd929d05f8cd8588
MD5 67669aaaf7448a28376a9e738ced0c89
BLAKE2b-256 262782d94f2bf43122bcc7b34a384c5226ac4a0bd0fc547f5a642caed48f1660

See more details on using hashes here.

Provenance

The following attestation bundles were made for kalix-0.4.0.tar.gz:

Publisher: release.yml on chasegan/Kalix

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file kalix-0.4.0-cp39-abi3-win_amd64.whl.

File metadata

  • Download URL: kalix-0.4.0-cp39-abi3-win_amd64.whl
  • Upload date:
  • Size: 778.8 kB
  • Tags: CPython 3.9+, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.14

File hashes

Hashes for kalix-0.4.0-cp39-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 e0271fa228ba1bf8d46a4ae918bdbb6bd4e647ad588e5d90d4be1d50336be052
MD5 d046f99b3b2609325b223e4f7fc8799c
BLAKE2b-256 6b73c5f50ad48e57dcfb823602902fda63186f4cbdf86d641a96025bbc906710

See more details on using hashes here.

Provenance

The following attestation bundles were made for kalix-0.4.0-cp39-abi3-win_amd64.whl:

Publisher: release.yml on chasegan/Kalix

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file kalix-0.4.0-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for kalix-0.4.0-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 7c054558fb9875097cf2e6acf28cec51bd57e134bfd6ddb5609523efb5c7daa0
MD5 f3a4bd2932ed97644bb4ac087bfa3148
BLAKE2b-256 b599086f811820afe33a43f7e766e5f214dcd709f0e1668151f4a2006b78f305

See more details on using hashes here.

Provenance

The following attestation bundles were made for kalix-0.4.0-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl:

Publisher: release.yml on chasegan/Kalix

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file kalix-0.4.0-cp39-abi3-macosx_11_0_arm64.whl.

File metadata

  • Download URL: kalix-0.4.0-cp39-abi3-macosx_11_0_arm64.whl
  • Upload date:
  • Size: 782.2 kB
  • Tags: CPython 3.9+, macOS 11.0+ ARM64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.14

File hashes

Hashes for kalix-0.4.0-cp39-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 bea318673a57972228946cc78f27f478392cd8ae8ad1d908af949348c85dcf7e
MD5 17e2d96e44f072627bdf2b22124444ed
BLAKE2b-256 4d2fede799ffdc8e122ccdd34551ebae3026086fc27c0c7cc433013f4ffdbd9e

See more details on using hashes here.

Provenance

The following attestation bundles were made for kalix-0.4.0-cp39-abi3-macosx_11_0_arm64.whl:

Publisher: release.yml on chasegan/Kalix

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

0.4.4

4 files

0.4.3

4 files

0.4.2

4 files

0.4.1

4 files

This release

0.4.0 This release

4 files

0.3.6

4 files

0.3.5

4 files

0.3.3

4 files

0.3.2

4 files

0.3.1

4 files

0.3.0

4 files

Pre-release

0.3.0.dev1

4 files

0.2.9

4 files

0.2.8

4 files

0.2.7

4 files

Pre-release

0.2.7.dev0

4 files

0.2.6

4 files

0.2.5

4 files

Pre-release

0.2.4.dev3

4 files

Pre-release

0.2.4.dev2

4 files

Pre-release

0.2.4.dev1

4 files

0.2.3

4 files

Pre-release

0.2.3.dev5

4 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page