Summary of Outcomes

Distilled from the brainstorming notes below. These are the decisions we landed on, ready to be turned into GitHub issue specs.

General principles

• Chaining is preferred. State-modifying functions return the model object itself so calls can be strung together (e.g. my_model.run().get_outputs()). Accessor functions are used to pull data out.
• The model resets cleanly on each run. Clearing internal state every run is a hard requirement (needed for calibration). No locking mechanism; the onus is on the user to retrieve outputs before making further modifications.
• Pandas data structures for outputs. A single requested output returns a pd.Series (preserves the index); multiple outputs return a pd.DataFrame.
• Consistent time precision. DataFrames are written internally with dates at "s" (second) precision, since Kalix supports timesteps down to 1 second (but no smaller). Can be converted to "ns" downstream if needed.
• Two ways to build a model: load from a file, or construct/modify entirely in Python via the API (new model + load string/snippet + patch).
• Editing via INI patches. Modifications are applied by passing an INI snippet to patch(), which updates the relevant parts of the DOM and re-parses/re-validates the whole model. Crude relative to dedicated accessors, but robust, powerful, and requires no extra maintenance as the model object grows richer. Accessors may come later.
• Note: bulum will eventually need to be extended to accept sub-daily timesteps.

Agreed function signatures

Loading & constructing models

import kalix

# Load a model directly from a file
my_model = kalix.load_file("model_file.ini")

# Create an empty model, then populate it
my_model = kalix.new_model()
my_model.load_file("model_file.ini")

# Load a full model from a string
my_model.load_string(whole_model_string)

# Load a partial model (snippet) from a string
my_model.load_string(snippet_string, snippet=True)

Running simulations

# run() returns the model (to support chaining), NOT results directly
my_model.run()

# Retrieve outputs after running
results_df = my_model.run().get_outputs()

Accessing outputs

# All outputs -> pd.DataFrame
results_df = my_model.get_outputs()

# Single output -> pd.Series (index preserved)
x = my_model.get_outputs("node.my_dam.volume")

# Multiple outputs -> pd.DataFrame
y = my_model.get_outputs(["node.my_dam.volume", "node.my_dam.level"])

Building & modifying models

Models are edited by applying an INI snippet via patch(). The snippet is merged into the DOM and the whole model is re-parsed and re-validated.