BMI docs page

docs/contribute/bmi.md

@@ -0,0 +1,44 @@
+# Basic Model Interface (BMI)
+
+For runtime data exchange and coupling with other kernels, the Julia kernel is wrapped in a Python API (`ribasim_api`) which implements the Basic Modelling Interface [BMI](https://bmi-spec.readthedocs.io/en/latest/).
+
+## Functions
+
+The following functions are available to interact with the Ribasim model"
+
+signature                 | description
+------------------------- | -------------
+`initialize(config_path)` | Initialize a model from the path to the TOML configuration file
+`finalize()`              | Write all results to the configured files
+`get_current_time()`      | Get the current time of the Ribasim simulation
+`get_end_time()`          | Get the final time of the Ribasim simulation in seconds
+`get_start_time()`        | Get the start time of the Ribasim simulation (`0.0`)
+`get_time_step()`         | Get the proposed next internal Ribasim timestep
+`get_time_units()`        | Get the time unit (`s`)
+`get_value_ptr(string)`   | Get the pointer to a Ribasim internal array (see below)
+`update()`                | Set a single Ribasim internal time step
+`update_until(time)`      | Set Ribasim internal timesteps until the specified time
+
+Depending on what is specified in the Ribasim TOML configuration file, Ribasim can internally have adaptive (non-constant) timesteps. `update_until` will always try to progress the Ribasim simulation to exactly the time specified. This however can fail for algorithms that only support a fixed timestep if that timestep does not fit into the interval until the specified time an integer amount of times.
+
+## Data pointers
+
+The following internal array data is exposed via the BMI using `get_value_ptr(string)`:
+
+string                          | meaning                                | type    | unit         | sorted by
+------------------------------- | -------------------------------------- | ------- | ------------ | ----------
+`basin.storage`                 | storage per basin                      | Float64 | $m^3$        | basin node ID
+`basin.level`                   | level per basin                        | Float64 | $m$          | basin node ID
+`basin.infiltration`            | infiltration per basin                 | Float64 | $m^3 s^{-1}$ | basin node ID
+`basin.drainage`                | drainage per basin                     | Float64 | $m^3 s^{-1}$ | basin node ID
+`basin.infiltration_integrated` | time integrated infiltration per basin | Float64 | $m^3$        | basin node ID
+`basin.drainage_integrated`     | time integrated drainage per basin     | Float64 | $m^3$        | basin node ID
+`basin.subgrid_level`           | subgrid level                          | Float64 | $m$          | subgrid ID
+`user_demand.demand`            | demand per node ID per priority        | Float64 | $m^3 s^{-1}$ | user_demand node ID, priority index
+`user_demand.realized`          | time integrated intake flow per user   | Float64 | $m^3$        | user_demand node ID
+
+Additional notes:
+
+- `user_demand.demand` yields the only 2D array, the other arrays are 1D. This array is indexed as `(node_idx, priority_idx)`
+- The index of e.g. basins and user demand nodes needs to be inferred from the Ribasim input. The same holds for `priority_idx`, which is global over all subnetworks
+- The `*_integrated` values are integrated from the start of the simulation onward. It might be beneficial to reset this to $0$ at certain times for long simulations to avoid loss of accuracy.

docs/contribute/index.qmd

@@ -4,7 +4,7 @@ title: "Contributing"
 
 Ribasim welcomes contributions.
 
-There is developer documentation for the [Julia core](core.qmd), [Python tooling](python.qmd), and the [QGIS plugin](qgis.qmd).
+There is developer documentation for the [Julia core](core.qmd), the [Basic Model Interface (BMI)](bmi.qmd), [Python tooling](python.qmd), and the [QGIS plugin](qgis.qmd).
 A guide on how to add a new node type to both is written in [adding node types](addnode.qmd).
 [Release process](release.qmd) describes the steps to follow when creating a new Ribasim release.