Spatial modelling documentation

HISTORY.md

@@ -2,6 +2,36 @@
 
 ## Catalyst unreleased (master branch)
 
+The expansion of `ReactionSystem` models to spatial lattices have been enabled. Here follows a 
+simple example where a Brusselator model is expanded to a 20x20 grid of compartments, with diffusion
+for species X, and then simulated using ODEs. Finally, an animation of the simulation is created.
+```julia
+using Catalyst, CairoMakie, OrdinaryDiffEq
+
+# Create `LatticeReactionSystem` model.
+brusselator = @reaction_network begin
+    A, ∅ --> X
+    1, 2X + Y --> 3X
+    B, X --> Y
+    1, X --> ∅
+end
+diffusion_rx = @transport_reaction D X
+lattice = CartesianGrid((20,20))
+lrs = LatticeReactionSystem(brusselator, [diffusion_rx], lattice)
+
+# Create a spatial `ODEProblem`.
+u0 = [:X => rand(20, 20), :Y => 10.0]
+tspan = (0.0, 40.0)
+ps = [:A => 1.0, :B => 4.0, :D => 0.2]
+oprob = ODEProblem(lrs, u0, tspan, ps)
+
+# Simulate the ODE and plot the results.
+sol = solve(oprob, FBDF())
+lattice_animation(sol, :X, lrs, "brusselator.mp4")
+```
+The addition of spatial modelling in Catalyst contain a large number of new features, all which are
+described in the [corresponding documentation](https://docs.sciml.ai/Catalyst/stable/spatial_modelling/lattice_reaction_systems/).
+
 ## Catalyst 14.0.1
 Bug fix to address that independent variables, like time, should now be `@parameters` 
 according to MTKv9. Converted internal time variables to consistently use `default_t()` 

Project.toml

@@ -27,16 +27,21 @@ Unitful = "1986cc42-f94f-5a68-af5c-568840ba703d"
 
 [weakdeps]
 BifurcationKit = "0f109fa4-8a5d-4b75-95aa-f515264e7665"
+CairoMakie = "13f3f980-e62b-5c42-98c6-ff1f3baf88f0"
 HomotopyContinuation = "f213a82b-91d6-5c5d-acf7-10f1c761b327"
+GraphMakie = "1ecd5474-83a3-4783-bb4f-06765db800d2"
 StructuralIdentifiability = "220ca800-aa68-49bb-acd8-6037fa93a544"
 
 [extensions]
 CatalystBifurcationKitExtension = "BifurcationKit"
+CatalystCairoMakieExtension = "CairoMakie"
 CatalystHomotopyContinuationExtension = "HomotopyContinuation"
+CatalystGraphMakieExtension = "GraphMakie"
 CatalystStructuralIdentifiabilityExtension = "StructuralIdentifiability"
 
 [compat]
 BifurcationKit = "0.3"
+CairoMakie = "0.12"
 Combinatorics = "1.0.2"
 DataStructures = "0.18"
 DiffEqBase = "6.83.0"
@@ -45,6 +50,7 @@ DynamicPolynomials = "0.5"
 DynamicQuantities = "0.13.2"
 Graphs = "1.4"
 HomotopyContinuation = "2.9"
+GraphMakie = "0.5"
 JumpProcesses = "9.3.2"
 LaTeXStrings = "1.3.0"
 Latexify = "0.14, 0.15, 0.16"
@@ -62,12 +68,14 @@ julia = "1.10"
 
 [extras]
 BifurcationKit = "0f109fa4-8a5d-4b75-95aa-f515264e7665"
+CairoMakie = "13f3f980-e62b-5c42-98c6-ff1f3baf88f0"
 DiffEqCallbacks = "459566f4-90b8-5000-8ac3-15dfb0a30def"
 DomainSets = "5b8099bc-c8ec-5219-889f-1d9e522a28bf"
 Graphviz_jll = "3c863552-8265-54e4-a6dc-903eb78fde85"
 HomotopyContinuation = "f213a82b-91d6-5c5d-acf7-10f1c761b327"
 LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"
 Logging = "56ddb016-857b-54e1-b83d-db4d58db5568"
+GraphMakie = "1ecd5474-83a3-4783-bb4f-06765db800d2"
 NonlinearSolve = "8913a72c-1f9b-4ce2-8d82-65094dcecaec"
 OrdinaryDiffEq = "1dea7af3-3e70-54e6-95c3-0bf5283fa5ed"
 Plots = "91a5bcdd-55d7-5caf-9e0b-520d859cae80"
@@ -85,4 +93,4 @@ Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
 Unitful = "1986cc42-f94f-5a68-af5c-568840ba703d"
 
 [targets]
-test = ["BifurcationKit", "DiffEqCallbacks", "DomainSets", "Graphviz_jll", "HomotopyContinuation", "Logging", "NonlinearSolve", "OrdinaryDiffEq", "Plots", "Random", "SafeTestsets", "SciMLBase", "SciMLNLSolve", "StableRNGs", "StaticArrays", "Statistics", "SteadyStateDiffEq", "StochasticDiffEq", "StructuralIdentifiability", "Test", "Unitful"]
+test = ["BifurcationKit", "CairoMakie", "DiffEqCallbacks", "DomainSets", "Graphviz_jll", "HomotopyContinuation", "Logging", "GraphMakie", "NonlinearSolve", "OrdinaryDiffEq", "Plots", "Random", "SafeTestsets", "SciMLBase", "SciMLNLSolve", "StableRNGs", "StaticArrays", "Statistics", "SteadyStateDiffEq", "StochasticDiffEq", "StructuralIdentifiability", "Test", "Unitful"]

docs/Project.toml

@@ -9,6 +9,8 @@ Distributions = "31c24e10-a181-5473-b8eb-7969acd0382f"
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 DynamicalSystems = "61744808-ddfa-5f27-97ff-6e42cc95d634"
 GlobalSensitivity = "af5da776-676b-467e-8baf-acd8249e4f0f"
+GraphMakie = "1ecd5474-83a3-4783-bb4f-06765db800d2"
+Graphs = "86223c79-3864-5bf0-83f7-82e725a168b6"
 HomotopyContinuation = "f213a82b-91d6-5c5d-acf7-10f1c761b327"
 IncompleteLU = "40713840-3770-5561-ab4c-a76e7d0d7895"
 JumpProcesses = "ccbc3e58-028d-4f4c-8cd5-9ae44345cda5"
@@ -46,6 +48,8 @@ Distributions = "0.25"
 Documenter = "1.4.1"
 DynamicalSystems = "3.3"
 GlobalSensitivity = "2.6"
+GraphMakie = "0.5"
+Graphs = "1.11.1"
 HomotopyContinuation = "2.9"
 IncompleteLU = "0.2"
 JumpProcesses = "9.11"

docs/pages.jl

@@ -48,6 +48,13 @@ pages = Any[
             "inverse_problems/examples/ode_fitting_oscillation.md"
         ]
     ],
+    "Spatial Modelling" => Any[
+        "spatial_modelling/lattice_reaction_systems.md",
+        "spatial_modelling/lattice_simulation_structure_ interaction.md",
+        "spatial_modelling/lattice_simulation_plotting.md",
+        "spatial_modelling/spatial_ode_simulations.md",
+        "spatial_modelling/spatial_jump_simulations.md"
+    ],
     "FAQs" => "faqs.md",
     "API" => "api.md"
 ]

docs/src/api.md

@@ -297,3 +297,54 @@ validate(rs::ReactionSystem, info::String="")
 ```@docs
 symmap_to_varmap
 ```
+
+## [Spatial modelling](@id api_lattice_simulations)
+The first step of spatial modelling is to create a so-called `LatticeReactionSystem`:
+```@docs
+LatticeReactionSystem
+```
+
+The following functions can be used to querying the properties of `LatticeReactionSystem`s:
+```@docs
+reactionsystem
+spatial_reactions
+lattice
+num_verts
+num_edges
+num_species
+spatial_species
+vertex_parameters
+edge_parameters
+edge_iterator
+is_transport_system
+has_cartesian_lattice
+has_masked_lattice
+has_grid_lattice
+has_graph_lattice
+grid_size
+grid_dims
+get_lattice_graph
+```
+In addition, most accessor functions for normal `ReactionSystem`s (such as `species` and `parameters`) works when applied to `LatticeReactionSystem`s as well.
+
+The following two helper functions can be used to create non-uniform parameter values.
+```@docs
+make_edge_p_values
+make_directed_edge_values
+```
+
+The following functions can be used to access, or change, species or parameter values stored in problems, integrators, and solutions that are based on `LatticeReactionSystem`s.
+```@docs
+lat_getu
+lat_setu!
+lat_getp
+lat_setp!
+rebuild_lat_internals!
+```
+
+Finally, we provide the following helper functions to plot and animate spatial lattice simulations.
+```@docs
+lattice_plot
+lattice_animation
+lattice_kymograph
+```