kalix 0.2.7.dev0

Python interface for Kalix: hydrological modelling and Pixie (Gorilla-compressed) timeseries I/O

kalix (Python)

Python interface for Kalix.

Current functionality:

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

Planned:

• programmatic model manipulation and building (Model class)
• optimisation

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

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

# Build a wheel
maturin build --release

Tests

maturin develop
pytest python/tests