From d2f03231e7cc519c06d2494b6c6fb29c34a23c9b Mon Sep 17 00:00:00 2001 From: Torkel Date: Sun, 21 Jul 2024 17:48:56 -0400 Subject: [PATCH 1/5] init --- docs/src/api.md | 79 +++++++++++++++---- docs/src/faqs.md | 12 ++- .../chemistry_related_functionality.md | 2 +- docs/src/model_creation/dsl_advanced.md | 2 + .../spatial_reactions.jl | 5 ++ 5 files changed, 84 insertions(+), 16 deletions(-) diff --git a/docs/src/api.md b/docs/src/api.md index b259fe0b2f..113e46b978 100644 --- a/docs/src/api.md +++ b/docs/src/api.md @@ -84,6 +84,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 +172,34 @@ accessor functions. ```@docs species +Catalyst.get_species nonspecies +ModelingToolkit.parameters +ModelingToolkit.get_ps +ModelingToolkit.unknowns +ModelingToolkit.get_unknowns reactions nonreactions +Catalyst.get_rxs numspecies numparams numreactions speciesmap paramsmap -isspecies isautonomous -Catalyst.isconstant -Catalyst.isbc +ModelingToolkit.observed +ModelingToolkit.get_observed +ModelingToolkit.get_systems +``` + +## 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 reaction properties @@ -181,6 +213,26 @@ netstoichmat reactionrates ``` +## Basic species properties +The following functions permits the querying of species properties. +```@docs +isspecies +Catalyst.isconstant +Catalyst.isbc +Catalyst.isvalidreactant +``` + +## [Reaction metadata](@ref 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). @@ -307,23 +359,22 @@ 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 +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 -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. diff --git a/docs/src/faqs.md b/docs/src/faqs.md index 23c0dd7617..977c5f4bd3 100644 --- a/docs/src/faqs.md +++ b/docs/src/faqs.md @@ -58,7 +58,7 @@ like plot(sol; idxs = [A, B]) ``` -## How to disable rescaling of reaction rates in rate laws? +## [How to disable rescaling of reaction rates in rate laws?](@ref faq_combinatoric_ratelaws) As explained in the [Reaction rate laws used in simulations](@ref introduction_to_catalyst_ratelaws) section, for a reaction such as `k, 2X --> 0`, the generated rate law will rescale the rate constant, giving `k*X^2/2` instead of `k*X^2` for ODEs and `k*X*(X-1)/2` instead @@ -71,6 +71,16 @@ osys = convert(ODESystem, rn; combinatoric_ratelaws=false) Disabling these rescalings should work for all conversions of `ReactionSystem`s to other `ModelingToolkit.AbstractSystem`s. +When creating a [`ReactionSystem`](@ref) using the DSL, combinatoric rate laws can be disabled (for +the created system, and all systems derived from it) using the `@combinatoric_ratelaws` option (providing `false` as its only input): +```@example faq1 +rn = @reaction_network begin + @combinatoric_ratelaws false + k, 2X --> 0 +end +nothing # hide +``` + ## How to use non-integer stoichiometric coefficients? ```@example faq2 using Catalyst diff --git a/docs/src/model_creation/chemistry_related_functionality.md b/docs/src/model_creation/chemistry_related_functionality.md index c1f279a55d..5064208a9b 100644 --- a/docs/src/model_creation/chemistry_related_functionality.md +++ b/docs/src/model_creation/chemistry_related_functionality.md @@ -5,7 +5,7 @@ While Catalyst has primarily been designed around the modelling of biological sy - The `balance_reaction` function, which enables the user to balance a reaction so the same number of components occur on both sides. -## Modelling with compound species +## [Modelling with compound species](@id chemistry_functionality_compounds) ### Creating compound species programmatically We will first show how to create compound species through [programmatic model construction](@ref programmatic_CRN_construction), and then demonstrate using the DSL. To create a compound species, use the `@compound` macro, first designating the compound, followed by its components (and their stoichiometries). In this example, we will create a CO₂ molecule, consisting of one C atom and two O atoms. First, we create species corresponding to the components: diff --git a/docs/src/model_creation/dsl_advanced.md b/docs/src/model_creation/dsl_advanced.md index 4edd069ba0..0a443e02a2 100644 --- a/docs/src/model_creation/dsl_advanced.md +++ b/docs/src/model_creation/dsl_advanced.md @@ -464,6 +464,8 @@ rx = @reaction p, 0 --> X, [description="A production reaction"] Catalyst.getdescription(rx) ``` +A list of all available reaction metadata can be found [in the api](@ref api_rx_metadata). + ## [Working with symbolic variables and the DSL](@id dsl_advanced_options_symbolics_and_DSL) We have previously described how Catalyst represents its models symbolically (enabling e.g. symbolic differentiation of expressions stored in models). While Catalyst utilises this for many internal operation, these symbolic representations can also be accessed and harnessed by the user. Primarily, doing so is much easier during programmatic (as opposed to DSL-based) modelling. Indeed, the section on [programmatic modelling](@ref programmatic_CRN_construction) goes into more details about symbolic representation in models, and how these can be used. It is, however, also ways to utilise these methods during DSL-based modelling. Below we briefly describe two methods for doing so. diff --git a/src/spatial_reaction_systems/spatial_reactions.jl b/src/spatial_reaction_systems/spatial_reactions.jl index be9b54985a..18c2a8d8e8 100644 --- a/src/spatial_reaction_systems/spatial_reactions.jl +++ b/src/spatial_reaction_systems/spatial_reactions.jl @@ -10,6 +10,11 @@ struct EdgeParameter end Symbolics.option_to_metadata_type(::Val{:edgeparameter}) = EdgeParameter # Implements the isedgeparameter check function. +""" + isedgeparameter(p) + +Returns `true` if the parameter `p` is an edge parameter (else `false`). +""" isedgeparameter(x::Num, args...) = isedgeparameter(Symbolics.unwrap(x), args...) function isedgeparameter(x, default = false) p = Symbolics.getparent(x, nothing) From 47c37d3ee61768b71880d94fd9128b4f722a55b1 Mon Sep 17 00:00:00 2001 From: Torkel Date: Sun, 21 Jul 2024 17:49:25 -0400 Subject: [PATCH 2/5] remove docstring lacking --- docs/src/api.md | 7 ------- 1 file changed, 7 deletions(-) diff --git a/docs/src/api.md b/docs/src/api.md index 113e46b978..e6d2130b1d 100644 --- a/docs/src/api.md +++ b/docs/src/api.md @@ -174,10 +174,6 @@ accessor functions. species Catalyst.get_species nonspecies -ModelingToolkit.parameters -ModelingToolkit.get_ps -ModelingToolkit.unknowns -ModelingToolkit.get_unknowns reactions nonreactions Catalyst.get_rxs @@ -187,9 +183,6 @@ numreactions speciesmap paramsmap isautonomous -ModelingToolkit.observed -ModelingToolkit.get_observed -ModelingToolkit.get_systems ``` ## Coupled reaction/equation system properties From 27e425dc0b1bafcc72167ff3754690b612faee4b Mon Sep 17 00:00:00 2001 From: Torkel Date: Sun, 21 Jul 2024 18:04:13 -0400 Subject: [PATCH 3/5] update api docstring order --- docs/src/api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/src/api.md b/docs/src/api.md index e6d2130b1d..ac5515bb4b 100644 --- a/docs/src/api.md +++ b/docs/src/api.md @@ -175,8 +175,8 @@ species Catalyst.get_species nonspecies reactions -nonreactions Catalyst.get_rxs +nonreactions numspecies numparams numreactions From 8374ea6c3b9063db8e9219e3c23100a301c0a136 Mon Sep 17 00:00:00 2001 From: Torkel Date: Mon, 22 Jul 2024 09:52:10 -0400 Subject: [PATCH 4/5] cross reference fix --- docs/src/api.md | 2 +- docs/src/faqs.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/src/api.md b/docs/src/api.md index ac5515bb4b..f1a0884b67 100644 --- a/docs/src/api.md +++ b/docs/src/api.md @@ -215,7 +215,7 @@ Catalyst.isbc Catalyst.isvalidreactant ``` -## [Reaction metadata](@ref api_rx_metadata) +## [Reaction metadata](@id api_rx_metadata) The following functions permits the retrieval of [reaction metadata](@ref dsl_advanced_options_reaction_metadata). ```@docs Catalyst.hasnoisescaling diff --git a/docs/src/faqs.md b/docs/src/faqs.md index 977c5f4bd3..aba6e739f0 100644 --- a/docs/src/faqs.md +++ b/docs/src/faqs.md @@ -58,7 +58,7 @@ like plot(sol; idxs = [A, B]) ``` -## [How to disable rescaling of reaction rates in rate laws?](@ref faq_combinatoric_ratelaws) +## [How to disable rescaling of reaction rates in rate laws?](@id faq_combinatoric_ratelaws) As explained in the [Reaction rate laws used in simulations](@ref introduction_to_catalyst_ratelaws) section, for a reaction such as `k, 2X --> 0`, the generated rate law will rescale the rate constant, giving `k*X^2/2` instead of `k*X^2` for ODEs and `k*X*(X-1)/2` instead From f0b90e46b63fecfbc48d04cfcbae681b5ffbd5a5 Mon Sep 17 00:00:00 2001 From: Torkel Date: Mon, 22 Jul 2024 10:12:36 -0400 Subject: [PATCH 5/5] change api properties access order --- docs/src/api.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/src/api.md b/docs/src/api.md index f1a0884b67..3cc4aab2bb 100644 --- a/docs/src/api.md +++ b/docs/src/api.md @@ -195,6 +195,15 @@ 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 ```@docs ismassaction @@ -206,15 +215,6 @@ netstoichmat reactionrates ``` -## Basic species properties -The following functions permits the querying of species properties. -```@docs -isspecies -Catalyst.isconstant -Catalyst.isbc -Catalyst.isvalidreactant -``` - ## [Reaction metadata](@id api_rx_metadata) The following functions permits the retrieval of [reaction metadata](@ref dsl_advanced_options_reaction_metadata). ```@docs