Merge remote-tracking branch 'origin/master' into detailedbalance

Author: vyudu

HISTORY.md

@@ -2,6 +2,38 @@
 
 ## Catalyst unreleased (master branch)
 
+
+## Catalyst 14.1.1
+The expansion of `ReactionSystem` models to spatial lattices has 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 contains a large number of new features, all of 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

@@ -1,6 +1,6 @@
 name = "Catalyst"
 uuid = "479239e8-5488-4da2-87a7-35f2df7eef83"
-version = "14.0.1"
+version = "14.1.1-DEV"
 
 [deps]
 Combinatorics = "861a8166-3701-5b0c-9a16-15d98fcdc6aa"
@@ -20,29 +20,36 @@ Parameters = "d96e819e-fc66-5662-9728-84c9c7592b0a"
 Reexport = "189a3867-3050-52da-a836-e630ba90ab69"
 Requires = "ae029012-a4dd-5104-9daa-d747884805df"
 RuntimeGeneratedFunctions = "7e49a35a-f44a-4d26-94aa-eba1b4ca6b47"
+SciMLBase = "0bca4576-84f4-4d90-8ffe-ffa030f20462"
 Setfield = "efcf1570-3423-57d1-acb7-fd33fddbac46"
 SparseArrays = "2f01184e-e22b-5df5-ae63-d93ebab69eaf"
 Symbolics = "0c5d862f-8b57-4792-8d23-62f2024744c7"
 Unitful = "1986cc42-f94f-5a68-af5c-568840ba703d"
 
 [weakdeps]
 BifurcationKit = "0f109fa4-8a5d-4b75-95aa-f515264e7665"
+CairoMakie = "13f3f980-e62b-5c42-98c6-ff1f3baf88f0"
+GraphMakie = "1ecd5474-83a3-4783-bb4f-06765db800d2"
 HomotopyContinuation = "f213a82b-91d6-5c5d-acf7-10f1c761b327"
 StructuralIdentifiability = "220ca800-aa68-49bb-acd8-6037fa93a544"
 
 [extensions]
 CatalystBifurcationKitExtension = "BifurcationKit"
+CatalystCairoMakieExtension = "CairoMakie"
+CatalystGraphMakieExtension = "GraphMakie"
 CatalystHomotopyContinuationExtension = "HomotopyContinuation"
 CatalystStructuralIdentifiabilityExtension = "StructuralIdentifiability"
 
 [compat]
 BifurcationKit = "0.3"
+CairoMakie = "0.12"
 Combinatorics = "1.0.2"
 DataStructures = "0.18"
 DiffEqBase = "6.83.0"
 DocStringExtensions = "0.8, 0.9"
 DynamicPolynomials = "0.5"
 DynamicQuantities = "0.13.2"
+GraphMakie = "0.5"
 Graphs = "1.4"
 HomotopyContinuation = "2.9"
 JumpProcesses = "9.3.2"
@@ -54,6 +61,7 @@ Parameters = "0.12"
 Reexport = "0.2, 1.0"
 Requires = "1.0"
 RuntimeGeneratedFunctions = "0.5.12"
+SciMLBase = "2.46"
 Setfield = "1"
 StructuralIdentifiability = "0.5.8"
 Symbolics = "5.30.1"
@@ -62,8 +70,10 @@ 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"
+GraphMakie = "1ecd5474-83a3-4783-bb4f-06765db800d2"
 Graphviz_jll = "3c863552-8265-54e4-a6dc-903eb78fde85"
 HomotopyContinuation = "f213a82b-91d6-5c5d-acf7-10f1c761b327"
 LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"
@@ -85,4 +95,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"]

README.md

@@ -1,9 +1,9 @@
 # Catalyst.jl
 
 [![Latest Release (for users)](https://img.shields.io/badge/docs-latest_release_(for_users)-blue.svg)](https://docs.sciml.ai/Catalyst/stable/)
-[![API Latest Release (for users)](https://img.shields.io/badge/API-latest_release_(for_users)-blue.svg)](https://docs.sciml.ai/Catalyst/stable/api/catalyst_api/)
+[![API Latest Release (for users)](https://img.shields.io/badge/API-latest_release_(for_users)-blue.svg)](https://docs.sciml.ai/Catalyst/stable/api/)
 [![Master (for developers)](https://img.shields.io/badge/docs-master_branch_(for_devs)-blue.svg)](https://docs.sciml.ai/Catalyst/dev/)
-[![API Master (for developers](https://img.shields.io/badge/API-master_branch_(for_devs)-blue.svg)](https://docs.sciml.ai/Catalyst/dev/api/catalyst_api/)
+[![API Master (for developers](https://img.shields.io/badge/API-master_branch_(for_devs)-blue.svg)](https://docs.sciml.ai/Catalyst/dev/api/)
 <!--[![Join the chat at https://julialang.zulipchat.com #sciml-bridged](https://img.shields.io/static/v1?label=Zulip&message=chat&color=9558b2&labelColor=389826)](https://julialang.zulipchat.com/#narrow/stream/279055-sciml-bridged)-->
 
 [![Build Status](https://github.com/SciML/Catalyst.jl/workflows/CI/badge.svg)](https://github.com/SciML/Catalyst.jl/actions?query=workflow%3ACI)
@@ -55,7 +55,7 @@ be found in its corresponding research paper, [Catalyst: Fast and flexible model
 - Leveraging ModelingToolkit, generated models can be converted to symbolic reaction rate equation ODE models, symbolic Chemical Langevin Equation models, and symbolic stochastic chemical kinetics (jump process) models. These can be simulated using any [DifferentialEquations.jl](https://docs.sciml.ai/DiffEqDocs/stable/) [ODE/SDE/jump solver](https://docs.sciml.ai/Catalyst/stable/model_simulation/simulation_introduction/), and can be used within `EnsembleProblem`s for carrying out [parallelized parameter sweeps and statistical sampling](https://docs.sciml.ai/Catalyst/stable/model_simulation/ensemble_simulations/). Plot recipes are available for [visualization of all solutions](https://docs.sciml.ai/Catalyst/stable/model_simulation/simulation_plotting/).
 - Non-integer (e.g. `Float64`) stoichiometric coefficients [are supported](https://docs.sciml.ai/Catalyst/stable/model_creation/dsl_basics/#dsl_description_stoichiometries_decimal) for generating ODE models, and symbolic expressions for stoichiometric coefficients [are supported](https://docs.sciml.ai/Catalyst/stable/model_creation/parametric_stoichiometry/) for all system types.
 - A [network analysis suite](https://docs.sciml.ai/Catalyst/stable/model_creation/network_analysis/) permits the computation of linkage classes, deficiencies, reversibility, and other network properties.
-- [Conservation laws can be detected and utilized](https://docs.sciml.ai/Catalyst/stable/model_creation/network_analysis/#working_with_conservation_laws) to reduce system sizes, and to generate non-singular Jacobians (e.g. during conversion to ODEs, SDEs, and steady state equations).
+- [Conservation laws can be detected and utilized](https://docs.sciml.ai/Catalyst/stable/model_creation/conservation_laws/) to reduce system sizes, and to generate non-singular Jacobians (e.g. during conversion to ODEs, SDEs, and steady state equations).
 - Catalyst reaction network models can be [coupled with differential and algebraic equations](https://docs.sciml.ai/Catalyst/stable/model_creation/constraint_equations/) (which are then incorporated during conversion to ODEs, SDEs, and steady state equations).
 - Models can be [coupled with events](https://docs.sciml.ai/Catalyst/stable/model_creation/constraint_equations/#constraint_equations_events) that affect the system and its state during simulations.
 - By leveraging ModelingToolkit, users have a variety of options for generating optimized system representations to use in solvers. These include construction of [dense or sparse Jacobians](https://docs.sciml.ai/Catalyst/stable/model_simulation/ode_simulation_performance/#ode_simulation_performance_sparse_jacobian), [multithreading or parallelization of generated derivative functions](https://docs.sciml.ai/Catalyst/stable/model_simulation/ode_simulation_performance/#ode_simulation_performance_parallelisation), [automatic classification of reactions into optimized jump types for Gillespie type simulations](https://docs.sciml.ai/JumpProcesses/stable/jump_types/#jump_types), [automatic construction of dependency graphs for jump systems](https://docs.sciml.ai/JumpProcesses/stable/jump_types/#Jump-Aggregators-Requiring-Dependency-Graphs), and more.
@@ -78,11 +78,10 @@ be found in its corresponding research paper, [Catalyst: Fast and flexible model
 - [SciMLSensitivity.jl](https://github.com/SciML/SciMLSensitivity.jl) can be used to compute local sensitivities of functions containing forward model simulations.
 
 #### Features of packages built upon Catalyst
-- Catalyst [`ReactionSystem`](@ref)s can be [imported from SBML files](https://docs.sciml.ai/Catalyst/stable/model_creation/model_file_loading_and_export/#Loading-SBML-files-using-SBMLImporter.jl-and-SBMLToolkit.jl) via [SBMLImporter.jl](https://github.com/SciML/SBMLImporter.jl) and [SBMLToolkit.jl](https://github.com/SciML/SBMLToolkit.jl), and [from BioNetGen .net files](https://docs.sciml.ai/Catalyst/stable/model_creation/model_file_loading_and_export/#file_loading_rni_net) and various stoichiometric matrix network representations using [ReactionNetworkImporters.jl](https://github.com/SciML/ReactionNetworkImporters.jl).
+- Catalyst [`ReactionSystem`](@ref)s can be [imported from SBML files](https://docs.sciml.ai/Catalyst/stable/model_creation/model_file_loading_and_export/#Loading-SBML-files-using-SBMLImporter.jl-and-SBMLToolkit.jl) via [SBMLImporter.jl](https://github.com/sebapersson/SBMLImporter.jl) and [SBMLToolkit.jl](https://github.com/SciML/SBMLToolkit.jl), and [from BioNetGen .net files](https://docs.sciml.ai/Catalyst/stable/model_creation/model_file_loading_and_export/#file_loading_rni_net) and various stoichiometric matrix network representations using [ReactionNetworkImporters.jl](https://github.com/SciML/ReactionNetworkImporters.jl).
 - [MomentClosure.jl](https://github.com/augustinas1/MomentClosure.jl) allows generation of symbolic ModelingToolkit `ODESystem`s that represent moment closure approximations to moments of the Chemical Master Equation, from reaction networks defined in Catalyst.
 - [FiniteStateProjection.jl](https://github.com/kaandocal/FiniteStateProjection.jl) allows the construction and numerical solution of Chemical Master Equation models from reaction networks defined in Catalyst.
 - [DelaySSAToolkit.jl](https://github.com/palmtree2013/DelaySSAToolkit.jl) can augment Catalyst reaction network models with delays, and can simulate the resulting stochastic chemical kinetics with delays models.
-- [BondGraphs.jl](https://github.com/jedforrest/BondGraphs.jl), a package for constructing and analyzing bond graphs models, which can take Catalyst models as input.
 
 
 ## Illustrative example

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"
@@ -62,7 +66,7 @@ OptimizationOptimisers = "0.2.1"
 OrdinaryDiffEq = "6.80.1"
 Plots = "1.40"
 QuasiMonteCarlo = "0.3"
-SciMLBase = "2.39"
+SciMLBase = "2.46"
 SciMLSensitivity = "7.60"
 SpecialFunctions = "2.4"
 StaticArrays = "1.9"

docs/pages.jl

@@ -11,9 +11,11 @@ pages = Any[
         "model_creation/programmatic_CRN_construction.md",
         "model_creation/compositional_modeling.md",
         "model_creation/constraint_equations.md",
+        "model_creation/conservation_laws.md",
         "model_creation/parametric_stoichiometry.md",
         "model_creation/model_file_loading_and_export.md",
         "model_creation/model_visualisation.md",
+        "model_creation/reactionsystem_content_accessing.md",
         "model_creation/network_analysis.md",
         "model_creation/chemistry_related_functionality.md",
         "Model creation examples" => Any[
@@ -29,7 +31,10 @@ pages = Any[
         "model_simulation/simulation_structure_interfacing.md",
         "model_simulation/ensemble_simulations.md",
         "model_simulation/ode_simulation_performance.md",
-        "model_simulation/sde_simulation_performance.md"
+        "model_simulation/sde_simulation_performance.md",
+        "Model simulation examples" => Any[
+            "model_simulation/examples/periodic_events_simulation.md"
+        ]
     ],
     "Steady state analysis" => Any[
         "steady_state_functionality/homotopy_continuation.md",
@@ -48,6 +53,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

@@ -68,11 +68,12 @@ jumpsys = convert(JumpSystem, rs)
 jumpsys = complete(jumpsys)
 u₀map    = [S => 999, I => 1, R => 0]
 dprob = DiscreteProblem(jumpsys, u₀map, tspan, parammap)
-jprob = JumpProblem(jumpsys, dprob, Direct(); save_positions = (false,false))
-sol = solve(jprob, SSAStepper(), saveat = 2.0)
+jprob = JumpProblem(jumpsys, dprob, Direct())
+sol = solve(jprob, SSAStepper())
+sol = solve(jprob, SSAStepper(), seed = 1234) # hide
 p3 = plot(sol, title = "jump")
-
 plot(p1, p2, p3; layout = (3,1))
+Catalyst.PNG(plot(p1, p2, p3; layout = (3,1), fmt = :png, dpi = 200)) # hide
 ```
 
 ```@docs
@@ -84,6 +85,22 @@ Reaction
 ReactionSystem
 ```
 
+## [Options for the `@reaction_network` DSL](@id api_dsl_options)
+We have [previously described](@ref dsl_advanced_options) how options permits the user to supply non-reaction information to [`ReactionSystem`](@ref) created through the DSL. Here follows a list
+of all options currently available.
+- [`parameters`]:(@ref dsl_advanced_options_declaring_species_and_parameters) Allows the designation of a set of symbols as system parameter.
+- [`species`](@ref dsl_advanced_options_declaring_species_and_parameters): Allows the designation of a set of symbols as system species.
+- [`variables`](@ref dsl_advanced_options_declaring_species_and_parameters): Allows the designation of a set of symbols as system non-species variables.
+- [`ivs`](@ref dsl_advanced_options_ivs): Allows the designation of a set of symbols as system independent variables.
+- [`compounds`](@ref chemistry_functionality_compounds): Allows the designation of compound species.
+- [`observables`](@ref dsl_advanced_options_observables): Allows the designation of compound observables.
+- [`default_noise_scaling`](@ref simulation_intro_SDEs_noise_saling): Enables the setting of a default noise scaling expression.
+- [`differentials`](@ref constraint_equations_coupling_constraints): Allows the designation of differentials.
+- [`equations`](@ref constraint_equations_coupling_constraints): Allows the creation of algebraic and/or differential equations.
+- [`continuous_events`](@ref constraint_equations_events): Allows the creation of continuous events.
+- [`discrete_events`](@ref constraint_equations_events): Allows the creation of discrete events.
+- [`combinatoric_ratelaws`](@ref faq_combinatoric_ratelaws): Takes a single option (`true` or `false`), which sets whether to use combinatorial rate laws.
+
 ## [ModelingToolkit and Catalyst accessor functions](@id api_accessor_functions)
 A [`ReactionSystem`](@ref) is an instance of a
 `ModelingToolkit.AbstractTimeDependentSystem`, and has a number of fields that
@@ -156,18 +173,36 @@ accessor functions.
 
 ```@docs
 species
+Catalyst.get_species
 nonspecies
 reactions
+Catalyst.get_rxs
 nonreactions
 numspecies
 numparams
 numreactions
 speciesmap
 paramsmap
-isspecies
 isautonomous
+```
+
+## Coupled reaction/equation system properties
+The following system property accessor functions are primarily relevant to reaction system [coupled
+to differential and/or algebraic equations](@ref constraint_equations).
+```@docs
+ModelingToolkit.has_alg_equations
+ModelingToolkit.alg_equations
+ModelingToolkit.has_diff_equations
+ModelingToolkit.diff_equations
+```
+
+## Basic species properties
+The following functions permits the querying of species properties.
+```@docs
+isspecies
 Catalyst.isconstant
 Catalyst.isbc
+Catalyst.isvalidreactant
 ```
 
 ## Basic reaction properties
@@ -181,6 +216,17 @@ netstoichmat
 reactionrates
 ```
 
+## [Reaction metadata](@id api_rx_metadata)
+The following functions permits the retrieval of [reaction metadata](@ref dsl_advanced_options_reaction_metadata).
+```@docs
+Catalyst.hasnoisescaling
+Catalyst.getnoisescaling
+Catalyst.hasdescription
+Catalyst.getdescription
+Catalyst.hasmisc
+Catalyst.getmisc
+```
+
 ## [Functions to extend or modify a network](@id api_network_extension_and_modification)
 `ReactionSystem`s can be programmatically extended using [`ModelingToolkit.extend`](@ref) and
 [`ModelingToolkit.compose`](@ref).
@@ -297,3 +343,53 @@ 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
+Catalyst.spatial_reactions
+Catalyst.lattice
+Catalyst.num_verts
+Catalyst.num_edges
+Catalyst.num_species
+Catalyst.spatial_species
+Catalyst.vertex_parameters
+Catalyst.edge_parameters
+Catalyst.edge_iterator
+Catalyst.is_transport_system
+has_cartesian_lattice
+has_masked_lattice
+has_grid_lattice
+has_graph_lattice
+grid_size
+grid_dims
+```
+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
+```