Skip to content

Commit 68fce1e

Browse files
vyuduvyudu
committed
up
1 parent c7eac51 commit 68fce1e

File tree

2 files changed

+404
-0
lines changed

2 files changed

+404
-0
lines changed

‎docs/src/api/core_api.md

Lines changed: 367 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,367 @@
1+
# [Catalyst.jl API](@id api)
2+
```@meta
3+
CurrentModule = Catalyst
4+
```
5+
6+
## Reaction network generation and representation
7+
Catalyst provides the [`@reaction_network`](@ref) macro for generating a
8+
complete network, stored as a [`ReactionSystem`](@ref), which in turn is
9+
composed of [`Reaction`](@ref)s. `ReactionSystem`s can be converted to other
10+
`ModelingToolkit.AbstractSystem`s, including a `ModelingToolkit.ODESystem`,
11+
`ModelingToolkit.SDESystem`, or `ModelingToolkit.JumpSystem`.
12+
13+
When using the [`@reaction_network`](@ref) macro, Catalyst will automatically
14+
attempt to detect what is a species and what is a parameter. Everything that
15+
appear as a substrate or product in some reaction will be treated as a species,
16+
while all remaining symbols will be considered parameters (corresponding to
17+
those symbols that only appear within rate expressions and/or as stoichiometric
18+
coefficients). I.e. in
19+
```julia
20+
rn = @reaction_network begin
21+
k*X, Y --> W
22+
end
23+
```
24+
`Y` and `W` will all be classified as chemical species, while `k` and `X` will
25+
be classified as parameters.
26+
27+
The [`ReactionSystem`](@ref) generated by the [`@reaction_network`](@ref) macro
28+
is a `ModelingToolkit.AbstractSystem` that symbolically represents a system of
29+
chemical reactions. In some cases it can be convenient to bypass the macro and
30+
directly generate a collection of symbolic [`Reaction`](@ref)s and a
31+
corresponding [`ReactionSystem`](@ref) encapsulating them. Below we illustrate
32+
with a simple SIR example how a system can be directly constructed, and
33+
demonstrate how to then generate from the [`ReactionSystem`](@ref) and solve
34+
corresponding chemical reaction ODE models, chemical Langevin equation SDE
35+
models, and stochastic chemical kinetics jump process models.
36+
37+
```@example ex1
38+
using Catalyst, OrdinaryDiffEqTsit5, StochasticDiffEq, JumpProcesses, Plots
39+
t = default_t()
40+
@parameters β γ
41+
@species S(t) I(t) R(t)
42+
43+
rxs = [Reaction(β, [S,I], [I], [1,1], [2])
44+
Reaction(γ, [I], [R])]
45+
@named rs = ReactionSystem(rxs, t)
46+
rs = complete(rs)
47+
48+
u₀map = [S => 999.0, I => 1.0, R => 0.0]
49+
parammap = [β => 1/10000, γ => 0.01]
50+
tspan = (0.0, 250.0)
51+
52+
# solve as ODEs
53+
odesys = convert(ODESystem, rs)
54+
odesys = complete(odesys)
55+
oprob = ODEProblem(odesys, u₀map, tspan, parammap)
56+
sol = solve(oprob, Tsit5())
57+
p1 = plot(sol, title = "ODE")
58+
59+
# solve as SDEs
60+
sdesys = convert(SDESystem, rs)
61+
sdesys = complete(sdesys)
62+
sprob = SDEProblem(sdesys, u₀map, tspan, parammap)
63+
sol = solve(sprob, EM(), dt=.01, saveat = 2.0)
64+
p2 = plot(sol, title = "SDE")
65+
66+
# solve as jump process
67+
jumpsys = convert(JumpSystem, rs)
68+
jumpsys = complete(jumpsys)
69+
u₀map = [S => 999, I => 1, R => 0]
70+
dprob = DiscreteProblem(jumpsys, u₀map, tspan, parammap)
71+
jprob = JumpProblem(jumpsys, dprob, Direct())
72+
sol = solve(jprob)
73+
sol = solve(jprob; seed = 1234) # hide
74+
p3 = plot(sol, title = "jump")
75+
plot(p1, p2, p3; layout = (3,1))
76+
Catalyst.PNG(plot(p1, p2, p3; layout = (3,1), fmt = :png, dpi = 200)) # hide
77+
```
78+
79+
```@docs
80+
@reaction_network
81+
@network_component
82+
make_empty_network
83+
@reaction
84+
Reaction
85+
ReactionSystem
86+
```
87+
88+
## [Options for the `@reaction_network` DSL](@id api_dsl_options)
89+
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
90+
of all options currently available.
91+
- [`parameters`]:(@ref dsl_advanced_options_declaring_species_and_parameters) Allows the designation of a set of symbols as system parameter.
92+
- [`species`](@ref dsl_advanced_options_declaring_species_and_parameters): Allows the designation of a set of symbols as system species.
93+
- [`variables`](@ref dsl_advanced_options_declaring_species_and_parameters): Allows the designation of a set of symbols as system non-species variables.
94+
- [`ivs`](@ref dsl_advanced_options_ivs): Allows the designation of a set of symbols as system independent variables.
95+
- [`compounds`](@ref chemistry_functionality_compounds): Allows the designation of compound species.
96+
- [`observables`](@ref dsl_advanced_options_observables): Allows the designation of compound observables.
97+
- [`default_noise_scaling`](@ref simulation_intro_SDEs_noise_saling): Enables the setting of a default noise scaling expression.
98+
- [`differentials`](@ref constraint_equations_coupling_constraints): Allows the designation of differentials.
99+
- [`equations`](@ref constraint_equations_coupling_constraints): Allows the creation of algebraic and/or differential equations.
100+
- [`continuous_events`](@ref constraint_equations_events): Allows the creation of continuous events.
101+
- [`discrete_events`](@ref constraint_equations_events): Allows the creation of discrete events.
102+
- [`combinatoric_ratelaws`](@ref faq_combinatoric_ratelaws): Takes a single option (`true` or `false`), which sets whether to use combinatorial rate laws.
103+
104+
## [ModelingToolkit and Catalyst accessor functions](@id api_accessor_functions)
105+
A [`ReactionSystem`](@ref) is an instance of a
106+
`ModelingToolkit.AbstractTimeDependentSystem`, and has a number of fields that
107+
can be accessed using the Catalyst API and the [ModelingToolkit.jl Abstract
108+
System
109+
Interface](https://docs.sciml.ai/ModelingToolkit/stable/basics/AbstractSystem/).
110+
Below we overview these components.
111+
112+
There are three basic sets of convenience accessors that will return information
113+
either from a top-level system, the top-level system and all sub-systems that
114+
are also `ReactionSystem`s (i.e. the full reaction-network), or the top-level
115+
system, all subs-systems, and all constraint systems (i.e. the full model). To
116+
retrieve info from just a base [`ReactionSystem`](@ref) `rn`, ignoring
117+
sub-systems of `rn`, one can use the ModelingToolkit accessors (these provide
118+
direct access to the corresponding internal fields of the `ReactionSystem`)
119+
120+
* `ModelingToolkit.get_unknowns(rn)` is a vector that collects all the species
121+
defined within `rn`, ordered by species and then non-species variables.
122+
* `Catalyst.get_species(rn)` is a vector of all the species variables in the system. The
123+
entries in `get_species(rn)` correspond to the first `length(get_species(rn))`
124+
components in `get_unknowns(rn)`.
125+
* `ModelingToolkit.get_ps(rn)` is a vector that collects all the parameters
126+
defined *within* reactions in `rn`.
127+
* `ModelingToolkit.get_eqs(rn)` is a vector that collects all the
128+
[`Reaction`](@ref)s and `Symbolics.Equation` defined within `rn`, ordering all
129+
`Reaction`s before `Equation`s.
130+
* `Catalyst.get_rxs(rn)` is a vector of all the [`Reaction`](@ref)s in `rn`, and
131+
corresponds to the first `length(get_rxs(rn))` entries in `get_eqs(rn)`.
132+
* `ModelingToolkit.get_iv(rn)` is the independent variable used in the system
133+
(usually `t` to represent time).
134+
* `ModelingToolkit.get_systems(rn)` is a vector of all sub-systems of `rn`.
135+
* `ModelingToolkit.get_defaults(rn)` is a dictionary of all the default values
136+
for parameters and species in `rn`.
137+
138+
The preceding accessors do not allocate, directly accessing internal fields of
139+
the `ReactionSystem`.
140+
141+
To retrieve information from the full reaction network represented by a system
142+
`rn`, which corresponds to information within both `rn` and all sub-systems, one
143+
can call:
144+
145+
* `ModelingToolkit.unknowns(rn)` returns all species *and variables* across the
146+
system, *all sub-systems*, and all constraint systems. Species are ordered
147+
before non-species variables in `unknowns(rn)`, with the first `numspecies(rn)`
148+
entries in `unknowns(rn)` being the same as `species(rn)`.
149+
* [`species(rn)`](@ref) is a vector collecting all the chemical species within
150+
the system and any sub-systems that are also `ReactionSystems`.
151+
* `ModelingToolkit.parameters(rn)` returns all parameters across the
152+
system, *all sub-systems*, and all constraint systems.
153+
* `ModelingToolkit.equations(rn)` returns all [`Reaction`](@ref)s and all
154+
`Symbolics.Equations` defined across the system, *all sub-systems*, and all
155+
constraint systems. `Reaction`s are ordered ahead of `Equation`s with the
156+
first `numreactions(rn)` entries in `equations(rn)` being the same as
157+
`reactions(rn)`.
158+
* [`reactions(rn)`](@ref) is a vector of all the `Reaction`s within the system
159+
and any sub-systems that are also `ReactionSystem`s.
160+
161+
These accessors will generally allocate new arrays to store their output unless
162+
there are no subsystems. In the latter case the usually return the same vector
163+
as the corresponding `get_*` function.
164+
165+
Below we list the remainder of the Catalyst API accessor functions mentioned
166+
above.
167+
168+
## Basic system properties
169+
See [Programmatic Construction of Symbolic Reaction Systems](@ref
170+
programmatic_CRN_construction) for examples and [ModelingToolkit and Catalyst
171+
Accessor Functions](@ref api_accessor_functions) for more details on the basic
172+
accessor functions.
173+
174+
```@docs
175+
species
176+
Catalyst.get_species
177+
nonspecies
178+
reactions
179+
Catalyst.get_rxs
180+
nonreactions
181+
numspecies
182+
numparams
183+
numreactions
184+
speciesmap
185+
paramsmap
186+
isautonomous
187+
```
188+
189+
## Coupled reaction/equation system properties
190+
The following system property accessor functions are primarily relevant to reaction system [coupled
191+
to differential and/or algebraic equations](@ref constraint_equations).
192+
```@docs
193+
ModelingToolkit.has_alg_equations
194+
ModelingToolkit.alg_equations
195+
ModelingToolkit.has_diff_equations
196+
ModelingToolkit.diff_equations
197+
```
198+
199+
## Basic species properties
200+
The following functions permits the querying of species properties.
201+
```@docs
202+
isspecies
203+
Catalyst.isconstant
204+
Catalyst.isbc
205+
Catalyst.isvalidreactant
206+
```
207+
208+
## Basic reaction properties
209+
```@docs
210+
ismassaction
211+
dependents
212+
dependants
213+
substoichmat
214+
prodstoichmat
215+
netstoichmat
216+
reactionrates
217+
```
218+
219+
## [Reaction metadata](@id api_rx_metadata)
220+
The following functions permits the retrieval of [reaction metadata](@ref dsl_advanced_options_reaction_metadata).
221+
```@docs
222+
Catalyst.hasnoisescaling
223+
Catalyst.getnoisescaling
224+
Catalyst.hasdescription
225+
Catalyst.getdescription
226+
Catalyst.hasmisc
227+
Catalyst.getmisc
228+
```
229+
230+
## [Functions to extend or modify a network](@id api_network_extension_and_modification)
231+
`ReactionSystem`s can be programmatically extended using [`ModelingToolkit.extend`](@ref) and
232+
[`ModelingToolkit.compose`](@ref).
233+
234+
```@docs
235+
setdefaults!
236+
ModelingToolkit.extend
237+
ModelingToolkit.compose
238+
Catalyst.flatten
239+
```
240+
241+
## Network comparison
242+
```@docs
243+
==(rn1::Reaction, rn2::Reaction)
244+
isequivalent
245+
==(rn1::ReactionSystem, rn2::ReactionSystem)
246+
```
247+
248+
## [Network visualization](@id network_visualization)
249+
[Latexify](https://korsbo.github.io/Latexify.jl/stable/) can be used to convert
250+
networks to LaTeX equations by
251+
```julia
252+
using Latexify
253+
latexify(rn)
254+
```
255+
An optional argument, `form` allows using `latexify` to display a reaction
256+
network's ODE (as generated by the reaction rate equation) or SDE (as generated
257+
by the chemical Langevin equation) form:
258+
```julia
259+
latexify(rn; form=:ode)
260+
```
261+
```julia
262+
latexify(rn; form=:sde)
263+
```
264+
(As of writing this, an upstream bug causes the SDE form to be erroneously
265+
displayed as the ODE form)
266+
267+
Finally, another optional argument (`expand_functions=true`) automatically expands functions defined by Catalyst (such as `mm`). To disable this, set `expand_functions=false`.
268+
269+
Reaction networks can be plotted using the `GraphMakie` extension, which is loaded whenever all of `Catalyst`, `GraphMakie`, and `NetworkLayout` are loaded (note that a Makie backend, like `CairoMakie`, must be loaded as well). The two functions for plotting networks are `plot_network` and `plot_complexes`, which are two distinct representations.
270+
```@docs
271+
plot_network(::ReactionSystem)
272+
plot_complexes(::ReactionSystem)
273+
```
274+
275+
## [Rate laws](@id api_rate_laws)
276+
As the underlying [`ReactionSystem`](@ref) is comprised of `ModelingToolkit`
277+
expressions, one can directly access the generated rate laws, and using
278+
`ModelingToolkit` tooling generate functions or Julia `Expr`s from them.
279+
```@docs
280+
oderatelaw
281+
jumpratelaw
282+
mm
283+
mmr
284+
hill
285+
hillr
286+
hillar
287+
```
288+
289+
## Transformations
290+
```@docs
291+
Base.convert
292+
JumpInputs
293+
ModelingToolkit.structural_simplify
294+
set_default_noise_scaling
295+
```
296+
297+
## Chemistry-related functionalities
298+
Various functionalities primarily relevant to modelling of chemical systems (but potentially also in biology).
299+
```@docs
300+
@compound
301+
@compounds
302+
iscompound
303+
components
304+
coefficients
305+
component_coefficients
306+
```
307+
308+
## Unit validation
309+
```@docs
310+
validate(rx::Reaction; info::String = "")
311+
validate(rs::ReactionSystem, info::String="")
312+
```
313+
314+
## Utility functions
315+
```@docs
316+
symmap_to_varmap
317+
```
318+
319+
## [Spatial modelling](@id api_lattice_simulations)
320+
The first step of spatial modelling is to create a so-called `LatticeReactionSystem`:
321+
```@docs
322+
LatticeReactionSystem
323+
```
324+
325+
The following functions can be used to querying the properties of `LatticeReactionSystem`s:
326+
```@docs
327+
reactionsystem
328+
Catalyst.spatial_reactions
329+
Catalyst.lattice
330+
Catalyst.num_verts
331+
Catalyst.num_edges
332+
Catalyst.num_species
333+
Catalyst.spatial_species
334+
Catalyst.vertex_parameters
335+
Catalyst.edge_parameters
336+
Catalyst.edge_iterator
337+
Catalyst.is_transport_system
338+
has_cartesian_lattice
339+
has_masked_lattice
340+
has_grid_lattice
341+
has_graph_lattice
342+
grid_size
343+
grid_dims
344+
```
345+
In addition, most accessor functions for normal `ReactionSystem`s (such as `species` and `parameters`) works when applied to `LatticeReactionSystem`s as well.
346+
347+
The following two helper functions can be used to create non-uniform parameter values.
348+
```@docs
349+
make_edge_p_values
350+
make_directed_edge_values
351+
```
352+
353+
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.
354+
```@docs
355+
lat_getu
356+
lat_setu!
357+
lat_getp
358+
lat_setp!
359+
rebuild_lat_internals!
360+
```
361+
362+
Finally, we provide the following helper functions to plot and animate spatial lattice simulations.
363+
```@docs
364+
lattice_plot
365+
lattice_animation
366+
lattice_kymograph
367+
```

0 commit comments

Comments
 (0)