Add descriptions to plots

docs/dev/callstacks.qmd

@@ -17,12 +17,14 @@ using Random
 Random.seed!(1);
 ```
 
-The plots below show the call stack within the Julia core for several important entrypoints. The function names are colored by the script in which they are defined, and the lines between the function names have random colors to be able to differentiate between them. Solid lines refer to calls to functions defined in the same script, dashed ones to functions defined in a different script.
+The plots below show the call stack within the Julia core for several important entrypoints. The function names are colored by the script in which they are defined, and the lines between the function names have random colors to be able to differentiate between them. Solid lines refer to calls to functions defined in the same script, dashed ones to functions defined in a different script. The plots are of high resolution so zooming in to particular parts is encouraged.
 
 Note that these graphs are obtained by dynamic analysis, i.e. by running parts of the code with specific inputs. This means that there can be unshown paths through the code that are not reached for these particular inputs.
 
 ## Parameter initialization
 
+Parameter initialization is the process of reading the parameter values from the input files and storing them in data structures for easy access in the core. Most notable here is the convergence of many paths to `load_structvector` and `parse_static_and_time`, as these are needed for parameter initialization for most node types.
+
 ```{julia}
 # | code-fold: true
 using SQLite
@@ -47,7 +49,9 @@ plot_graph(
 )
 ```
 
-## `water_balance!` (The ODE system right hand side function)
+## `water_balance!`
+
+`water_balance!` is the right hand side function of the system of ODEs that is solved by the Ribasim core (for more details see [here]("../concept/eqautions.qmd#Formal-model-description")). The various `formulate_flow!` methods are for flow rates as determined by different node types.
 
 ```{julia}
 # | code-fold: true
@@ -60,6 +64,9 @@ plot_graph(graph, size = (1700, 1000), xlims = (-0.4, 4.5))
 ```
 
 ## Allocation initialization
+
+In this part of the code the data structures for allocation are set up. Most endpoints in `allocation_init.jl` set up data structures as defined in [JuMP.jl](https://jump.dev/JuMP.jl/stable/).
+
 ```{julia}
 # | code-fold: true
 toml_path = normpath(@__DIR__, "../../generated_testmodels/main_network_with_subnetworks/ribasim.toml")
@@ -72,6 +79,9 @@ plot_graph(graph, size = (1800, 1000), xlims = (-0.5, 5.5))
 ```
 
 ## Allocation run
+
+Running the allocation algorithm consists of running the optimization itself (which is handled in `JuMP.jl`), and all Ribasim functions around it are used for communicating data between the optimization problem and the physical layer, as well as gathering output data.
+
 ```{julia}
 # | code-fold: true
 model = Ribasim.Model(toml_path)
@@ -81,6 +91,8 @@ plot_graph(graph, size = (2000, 1000), xlims = (-0.4, 5.5))
 
 ## Discrete control
 
+Discrete control works by a [`FunctionCallingCallback`](https://docs.sciml.ai/DiffEqCallbacks/stable/output_saving/#DiffEqCallbacks.FunctionCallingCallback), changing parameters when a change in control state is detected (see also [here](../reference/node/discrete-control.qmd)).
+
 ```{julia}
 # | code-fold: true
 toml_path = normpath(@__DIR__, "../../generated_testmodels/pump_discrete_control/ribasim.toml")
@@ -92,6 +104,8 @@ plot_graph(graph; size = (1300, 500), prune_from = [:water_balance!], xlims = (-
 ```
 
 ## Writing output
+
+Writing output (currently) happens only after the full simulation is finished.
 ```{julia}
 # | code-fold: true
 toml_path = normpath(@__DIR__, "../../generated_testmodels/basic_transient/ribasim.toml")