add history, enable docs, and stuff to api.

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, GLMakie, 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, "brusselator.mp4", lrs)
+```
+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
 
 #### Breaking changes

docs/pages.jl

@@ -47,14 +47,13 @@ pages = Any[
             "inverse_problems/examples/ode_fitting_oscillation.md"
         ]
     ],
-    # Uncomment (and move the docs from unpublished to src) once v14 have been released.
-    # "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"
-    # ],
+    "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

@@ -296,4 +296,48 @@ validate(rs::ReactionSystem, info::String="")
 ## Utility functions
 ```@docs
 symmap_to_varmap
+```
+
+## [Spatial modelling](@id api_lattice_simulations)
+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!
+```
+
+The following functions can be used to create plots or animations of spatial simulations.
+```@docs
+lattice_animation
 ```

docs/unpublished/spatial_modelling/spatial_ode_simulations.md → docs/src/spatial_modelling/spatial_ode_simulations.md

@@ -2,7 +2,7 @@
 Our [introduction to spatial lattice simulations](@ref spatial_lattice_modelling_intro) has already provided an extensive description of how to simulate `LatticeReactionSystem`s using ODEs. Further tutorials have also shown how to [retrieve values from simulations](@ref lattice_simulation_structure_interaction_simulation_species), or how to [plot them](@ref lattice_simulation_plotting). Here we will build on this, primarily discussing strategies for increasing ODE simulation performance. This is especially important for spatial simulations, as these typically are more computationally demanding as compared to non-spatial ones. While focusing on non-spatial simulations, this [ODE performance tutorial](@ref ode_simulation_performance) can also be useful to read.
 
 ## [Solver selection for spatial ODE simulations](@id spatial_lattice_ode_simulations_solvers)
-Previously we have described [how to select ODE solvers, and how this can impact simulation performance](@ref ode_simulation_performance_solvers). This is especially relevant for spatial simulations. For stiff problems, `FBDF` is a good first solver to try.
+Previously we have described [how to select ODE solvers, and how this can impact simulation performance](@ref ode_simulation_performance_solvers). This is especially relevant for spatial simulations. For stiff problems, `FBDF` is a good first solver to try. For non-stiff problems, `ROCK2` is instead a good first alternative. However, it is still worthwhile to explore a range of alternative solvers.
 
 ## [Jacobian options for spatial ODE simulations](@id spatial_lattice_ode_simulations_jacobians)
 We have previously described how, when [implicit solvers are used to solve stiff ODEs](@ref ode_simulation_performance_stiffness), the [strategy for computing the system Jacobian](@ref ode_simulation_performance_jacobian) is important. This is especially the case for spatial simulations, where the Jacobian often is large and highly sparse. Catalyst implements special methods for spatial Jacobians. To utilise these, provide the `jac = true` argument to your `ODEProblem` when it is created (if `jac = false`, which is the default, [*automatic differentiation*](https://en.wikipedia.org/wiki/Automatic_differentiation) will be used for Jacobian computation). Here we simulate a [Brusselator](@ref basic_CRN_library_brusselator) while designating to use Catalyst's computed Jacobian: