Fill in the rest

core/src/Ribasim.jl

@@ -14,29 +14,33 @@ For more granular access, see:
 """
 module Ribasim
 
-# The BMI is a standard for interacting with a Ribasim model,
-# see the docs: https://ribasim.org/dev/bmi.html
-import BasicModelInterface as BMI
-
-# The optimization backend of JuMP
-import HiGHS
-import IterTools
-
-# Modeling language for Mathematical Optimization.
-# Used for allocation, see the docs: https://ribasim.org/dev/allocation.html
-import JuMP
-import LoggingExtras
-import TranscodingStreams
+# Algorithms for solving ODEs.
+using OrdinaryDiffEq: OrdinaryDiffEq, OrdinaryDiffEqRosenbrockAdaptiveAlgorithm, get_du
 
-# Convenience macro to change an immutable field of an object
-using Accessors: @set
-using Arrow: Arrow, Table
-using CodecZstd: ZstdCompressor
+# Interface for defining and solving the ODE problem of the physical layer.
+using SciMLBase:
+    init,
+    solve!,
+    step!,
+    check_error!,
+    SciMLBase,
+    ReturnCode,
+    successful_retcode,
+    CallbackSet,
+    ODEFunction,
+    ODEProblem,
+    ODESolution,
+    VectorContinuousCallback,
+    get_proposed_dt
 
-# Convenience wrapper around arrays, divides vectors in
-# separate sections which can be indexed individually.
-# Used for e.g. basin forcing and the state vector.
-using ComponentArrays: ComponentVector, Axis
+# PreallocationTools is used because the RHS function (water_balance!) gets called with different input types
+# for u, du:
+# - Float64 for normal calls
+# - Dual numbers for automatic differentiation with ForwardDiff
+# - GradientTracer for automatic Jacobian sparsity detection with SparseConnectivityTracer
+# The computations inside the rhs go trough preallocated arrays of the required type which are created by LazyBufferCache.
+# Retrieving a cache from a LazyBufferCache looks like indexing: https://docs.sciml.ai/PreallocationTools/stable/#LazyBufferCache
+using PreallocationTools: LazyBufferCache
 
 # Interpolation functionality, used for e.g.
 # basin profiles and TabulatedRatingCurve. See also the node
@@ -48,9 +52,39 @@ using DataInterpolations:
     derivative,
     integral,
     AbstractInterpolation
-using Dates: Dates, DateTime, Millisecond, @dateformat_str
+
+# Modeling language for Mathematical Optimization.
+# Used for allocation, see the docs: https://ribasim.org/dev/allocation.html
+import JuMP
+# The optimization backend of JuMP.
+import HiGHS
+
+# The BMI is a standard for interacting with a Ribasim model,
+# see the docs: https://ribasim.org/dev/bmi.html
+import BasicModelInterface as BMI
+
+# Reading and writing optionally compressed Arrow tables
+using Arrow: Arrow, Table
+import TranscodingStreams
+using CodecZstd: ZstdCompressor
+# Reading GeoPackage files, which are SQLite databases with spatial data
+using SQLite: SQLite, DB, Query, esc_id
 using DBInterface: execute
 
+# Logging to both the console and a file
+using Logging: with_logger, @logmsg, LogLevel, AbstractLogger
+import LoggingExtras
+using TerminalLoggers: TerminalLogger
+
+# Convenience wrapper around arrays, divides vectors in
+# separate sections which can be indexed individually.
+# Used for e.g. Basin forcing and the state vector.
+using ComponentArrays: ComponentVector, Axis
+
+# Date and time handling; externally we use the proleptic Gregorian calendar,
+# internally we use a Float64; seconds since the start of the simulation.
+using Dates: Dates, DateTime, Millisecond, @dateformat_str
+
 # Callbacks are used to trigger function calls at specific points in the similation.
 # E.g. after each timestep for discrete control,
 # or at each saveat for saving storage and flow results.
@@ -61,15 +95,9 @@ using DiffEqCallbacks:
     SavedValues,
     SavingCallback
 
-# Convenience type for enumeration, used for e.g. node types
-using EnumX: EnumX, @enumx
-
-# Graphs is for the graph representation of the model.
+# The network defined by the Node and Edge table is converted to a graph internally.
 using Graphs:
     DiGraph, Edge, edges, inneighbors, nv, outneighbors, induced_subgraph, is_connected
-using Legolas: Legolas, @schema, @version, validate, SchemaVersion, declared
-using Logging: with_logger, @logmsg, LogLevel, AbstractLogger
-
 # Convenience functionality built on top of Graphs. Used to store e.g. node and edge metadata
 # alongside the graph. Extra metadata is stored in a NamedTuple retrieved as graph[].
 using MetaGraphsNext:
@@ -81,44 +109,27 @@ using MetaGraphsNext:
     outneighbor_labels,
     inneighbor_labels
 
-# Algorithms for solving ODEs. See also config.jl
-using OrdinaryDiffEq: OrdinaryDiffEq, OrdinaryDiffEqRosenbrockAdaptiveAlgorithm, get_du
+# Improved enumeration type compared to Base, used for e.g. node types.
+using EnumX: EnumX, @enumx
 
-# PreallocationTools is used because the rhs function (water_balance!) gets called with different input types
-# for u, du:
-# - Float64 for normal calls
-# - Dual numbers for automatic differentiation with ForwardDiff
-# - GradientTracer for automatic Jacobian sparsity detection with SparseConnectivityTracer
-# The computations inside the rhs go trough preallocated arrays of the required type which are created by LazyBufferCache.
-# Retrieving a cache from a LazyBufferCache looks like indexing: https://docs.sciml.ai/PreallocationTools/stable/#LazyBufferCache
-using PreallocationTools: LazyBufferCache
+# Easily change an immutable field of an object.
+using Accessors: @set
 
-# Base functionality for defining and solving the ODE problem of the physical layer.
-using SciMLBase:
-    init,
-    solve!,
-    step!,
-    check_error!,
-    SciMLBase,
-    ReturnCode,
-    successful_retcode,
-    CallbackSet,
-    ODEFunction,
-    ODEProblem,
-    ODESolution,
-    VectorContinuousCallback,
-    get_proposed_dt
-using SQLite: SQLite, DB, Query, esc_id
+# Iteration utilities, used to partition and group tables.
+import IterTools
 
-# Convenience wrapper around a vector of structs to easily retrieve the same field from all elements
-using StructArrays: StructVector
+# Define and validate the schemas of the input tables.
+using Legolas: Legolas, @schema, @version, validate, SchemaVersion, declared
+
+# Tables interface that works with either SQLite or Arrow tables.
 using Tables: Tables, AbstractRow, columntable
-using TerminalLoggers: TerminalLogger
+
+# Wrapper around a vector of structs to easily retrieve the same field from all elements.
+using StructArrays: StructVector
+
+# TODO remove, not used
 using TimerOutputs: TimerOutputs, TimerOutput, @timeit_debug
 
-# Lightweight package for automatically detecting the sparsity pattern of the Jacobian of
-# water_balance! through operator overloading
-using SparseConnectivityTracer: TracerSparsityDetector, jacobian_sparsity, GradientTracer
 export libribasim
 
 const to = TimerOutput()