From 73b80db177f46e6d1b7bcc1ca897c1d0dfd3f52d Mon Sep 17 00:00:00 2001 From: ChrisRackauckas-Claude Date: Wed, 8 Jul 2026 04:59:45 -0400 Subject: [PATCH] Document exported Catalyst APIs Co-Authored-By: Chris Rackauckas --- docs/make.jl | 20 +++ docs/pages.jl | 3 +- docs/src/api/core_api.md | 19 +++ docs/src/api/network_analysis_api.md | 4 + docs/src/api/reexports_api.md | 65 ++++++++++ src/Catalyst.jl | 116 ++++++++++++++++++ src/dsl.jl | 18 ++- src/network_analysis.jl | 32 ++++- src/reactionsystem.jl | 5 +- .../spatial_reactions.jl | 41 ++++++- 10 files changed, 312 insertions(+), 11 deletions(-) create mode 100644 docs/src/api/reexports_api.md diff --git a/docs/make.jl b/docs/make.jl index e9d15219fa..96c962b061 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -1,8 +1,25 @@ using Documenter using Catalyst, ModelingToolkitBase, SymbolicIndexingInterface +using JumpProcesses, SciMLBase # Add packages for plotting using GraphMakie, CairoMakie +const Symbolics = Catalyst.Symbolics +const SymbolicUtils = Catalyst.SymbolicUtils +const UnPack = Catalyst.UnPack + +function loaded_module(name::String) + loaded = Base.loaded_modules isa Function ? Base.loaded_modules() : Base.loaded_modules + for (pkgid, mod) in loaded + pkgid.name == name && return mod + end + error("Module $name was not loaded") +end + +const BipartiteGraphs = loaded_module("BipartiteGraphs") +const CommonSolve = loaded_module("CommonSolve") +const TermInterface = loaded_module("TermInterface") + docpath = Base.source_dir() assetpath = joinpath(docpath, "src", "assets") cp(joinpath(docpath, "Manifest.toml"), joinpath(assetpath, "Manifest.toml"), force = true) @@ -40,6 +57,9 @@ makedocs(sitename = "Catalyst.jl", assets = ["assets/favicon.ico"], canonical = "https://docs.sciml.ai/Catalyst/stable/"), modules = [Catalyst, ModelingToolkitBase, SymbolicIndexingInterface, + BipartiteGraphs, CommonSolve, + JumpProcesses, SciMLBase, + Symbolics, SymbolicUtils, SymbolicUtils.Code, TermInterface, UnPack, Base.get_extension(Catalyst, :CatalystGraphMakieExtension)], doctest = false, clean = true, diff --git a/docs/pages.jl b/docs/pages.jl index 9e80f95acf..1c92a86a56 100644 --- a/docs/pages.jl +++ b/docs/pages.jl @@ -81,7 +81,8 @@ pages = Any[ "FAQs" => "faqs.md", "API" => Any[ "api/core_api.md", - "api/network_analysis_api.md" + "api/network_analysis_api.md", + "api/reexports_api.md" ], "Developer Documentation" => "devdocs/dev_guide.md" ] diff --git a/docs/src/api/core_api.md b/docs/src/api/core_api.md index d843df48fe..90fc627858 100644 --- a/docs/src/api/core_api.md +++ b/docs/src/api/core_api.md @@ -70,12 +70,16 @@ Catalyst.PNG(plot(p1, p2, p3; layout = (3,1), fmt = :png, dpi = 200)) # hide ``` ```@docs +default_t +default_time_deriv @reaction_network @network_component make_empty_network @reaction +@species Reaction ReactionSystem +isspatial ``` ## [Options for the `@reaction_network` DSL](@id api_dsl_options) @@ -281,6 +285,8 @@ Reaction networks can be plotted using the `GraphMakie` extension, which is load ```@docs plot_network(::ReactionSystem) plot_complexes(::ReactionSystem) +plot_network +plot_complexes ``` ## [Rate laws](@id api_rate_laws) @@ -304,6 +310,9 @@ ss_ode_model sde_model jump_model hybrid_model +HybridProblem +hc_steady_states +make_si_ode ModelingToolkitBase.mtkcompile set_default_noise_scaling ``` @@ -317,6 +326,8 @@ iscompound components coefficients component_coefficients +balance_reaction +balance_system ``` ## Unit validation @@ -336,6 +347,8 @@ Catalyst.UnitValidationError The first step of spatial modelling is to create a so-called `DiscreteSpaceReactionSystem`: ```@docs DiscreteSpaceReactionSystem +TransportReaction +@transport_reaction ``` The following functions can be used to querying the properties of `DiscreteSpaceReactionSystem`s: @@ -351,6 +364,7 @@ Catalyst.vertex_parameters Catalyst.edge_parameters Catalyst.edge_iterator Catalyst.is_transport_system +isedgeparameter has_cartesian_dspace has_masked_dspace has_grid_dspace @@ -381,3 +395,8 @@ dspace_plot dspace_animation dspace_kymograph ``` + +## Reaction system serialisation +```@docs +save_reactionsystem +``` diff --git a/docs/src/api/network_analysis_api.md b/docs/src/api/network_analysis_api.md index bd7d9084b5..9b67ccd5c3 100644 --- a/docs/src/api/network_analysis_api.md +++ b/docs/src/api/network_analysis_api.md @@ -15,6 +15,8 @@ conservationlaws conservedquantities conservedequations conservationlaw_constants +steady_state_jac +steady_state_stability ReactionComplexElement ReactionComplex reactioncomplexmap @@ -28,6 +30,8 @@ adjacencymat laplacianmat massactionvector linkageclasses +stronglinkageclasses +terminallinkageclasses deficiency linkagedeficiencies satisfiesdeficiencyone diff --git a/docs/src/api/reexports_api.md b/docs/src/api/reexports_api.md new file mode 100644 index 0000000000..9ddfdbc2a5 --- /dev/null +++ b/docs/src/api/reexports_api.md @@ -0,0 +1,65 @@ +# Re-exported upstream API +```@meta +CurrentModule = Catalyst +``` + +Catalyst re-exports selected public APIs from upstream SciML and symbolic +computing packages for modeling convenience. The source-site docstrings for +these names are rendered below from their defining modules. + +## ModelingToolkitBase +```@autodocs; canonical=false +Modules = [ModelingToolkitBase] +Public = true +Private = false +``` + +## Symbolics +```@autodocs; canonical=false +Modules = [Symbolics] +Public = true +Private = false +``` + +## SymbolicUtils +```@autodocs; canonical=false +Modules = [SymbolicUtils, SymbolicUtils.Code] +Public = true +Private = false +``` + +## SciMLBase +```@autodocs; canonical=false +Modules = [SciMLBase] +Public = true +Private = false +``` + +## JumpProcesses +```@autodocs; canonical=false +Modules = [JumpProcesses] +Public = true +Private = false +``` + +## Other re-exports +```@meta +CurrentModule = Main +``` + +```@docs; canonical=false +BipartiteGraphs.BipartiteGraph +CommonSolve.solve +TermInterface.arguments +TermInterface.iscall +TermInterface.operation +TermInterface.sorted_arguments +UnPack.@pack! +UnPack.@unpack +``` + +```@autodocs; canonical=false +Modules = [UnPack] +Public = true +Private = false +``` diff --git a/src/Catalyst.jl b/src/Catalyst.jl index 65542edd63..0bcf532577 100644 --- a/src/Catalyst.jl +++ b/src/Catalyst.jl @@ -61,9 +61,41 @@ import SymbolicUtils: getmetadata, hasmetadata, setmetadata import SciMLPublic: @public # globals for the modulate +""" + default_time_deriv() + +Return Catalyst's default time derivative operator. + +This is the derivative with respect to [`default_t`](@ref), and is useful when +programmatically constructing equations involving time derivatives. + +# Examples +```julia +t = default_t() +D = default_time_deriv() +@species X(t) +eq = D(X) ~ -X +``` +""" function default_time_deriv() return ModelingToolkitBase.D_nounits end + +""" + default_t() + +Return Catalyst's default independent time variable. + +Use this when programmatically declaring species or constructing +[`ReactionSystem`](@ref)s so that the independent variable matches Catalyst's +DSL defaults. + +# Examples +```julia +t = default_t() +@species X(t) +``` +""" function default_t() return ModelingToolkitBase.t_nounits end @@ -177,15 +209,99 @@ export steady_state_stability, steady_state_jac ### Extensions ### # HomotopyContinuation +""" + hc_steady_states(rs::ReactionSystem, ps; filter_negative = true, neg_thres = -1e-15, u0 = [], kwargs...) + +Find steady states of a [`ReactionSystem`](@ref) using HomotopyContinuation.jl. + +This extension function is available after loading HomotopyContinuation.jl. +`ps` supplies parameter values, `u0` supplies initial conditions needed for +systems with conservation laws, and extra keyword arguments are passed to +HomotopyContinuation's solver. + +# Examples +```julia +using Catalyst, HomotopyContinuation + +rs = @reaction_network begin + k1, Y --> 2X + k2, 2X --> X + Y + k3, X + Y --> Y + k4, X --> 0 +end +hc_steady_states(rs, [:k1 => 8.0, :k2 => 2.0, :k3 => 1.0, :k4 => 1.5]) +``` +""" function hc_steady_states end export hc_steady_states # StructuralIdentifiability +""" + make_si_ode(rs::ReactionSystem; measured_quantities = [], known_p = [], + ignore_no_measured_warn = false, remove_conserved = true) + +Convert a [`ReactionSystem`](@ref) to the ODE representation used by +StructuralIdentifiability.jl. + +This extension function is available after loading StructuralIdentifiability.jl. +`measured_quantities` lists measured species or equations, `known_p` lists +parameters treated as known, and `remove_conserved` controls conservation-law +elimination before conversion. + +# Examples +```julia +using Catalyst, StructuralIdentifiability + +rs = @reaction_network begin + (p, d), 0 <--> X +end +make_si_ode(rs; measured_quantities = [:X], known_p = [:p]) +``` +""" function make_si_ode end export make_si_ode # GraphMakie: functionality for plotting species-reaction graphs and complexes +""" + plot_network(rn::ReactionSystem; kwargs...) + +Plot the species-reaction graph of `rn`. + +This extension function is available after loading GraphMakie.jl and +NetworkLayout.jl. Keyword arguments are forwarded to the GraphMakie plotting +recipe. + +# Examples +```julia +using Catalyst, GraphMakie, CairoMakie + +rn = @reaction_network begin + k, A --> B +end +plot_network(rn) +``` +""" function plot_network end + +""" + plot_complexes(rn::ReactionSystem; show_rate_labels = false, kwargs...) + +Plot the reaction-complex graph of `rn`. + +This extension function is available after loading GraphMakie.jl and +NetworkLayout.jl. Set `show_rate_labels = true` to label graph edges by their +reaction rates. + +# Examples +```julia +using Catalyst, GraphMakie, CairoMakie + +rn = @reaction_network begin + k, A --> B +end +plot_complexes(rn) +``` +""" function plot_complexes end export plot_network, plot_complexes diff --git a/src/dsl.jl b/src/dsl.jl index 88a2c8b6c3..cd4469377e 100644 --- a/src/dsl.jl +++ b/src/dsl.jl @@ -14,7 +14,23 @@ const option_keys = (:species, :parameters, :variables, :discretes, :ivs, :compo ### `@species` Macro ### -# The @species macro, basically a copy of the @variables macro. +""" + @species xs... + +Declare symbolic variables as Catalyst species. + +`@species` accepts the same declaration syntax as ModelingToolkit's +`@variables`, including defaults, metadata, and array declarations. Declared +species carry Catalyst species metadata and can be used when programmatically +constructing [`Reaction`](@ref)s or [`ReactionSystem`](@ref)s. + +# Examples +```julia +t = default_t() +@species S(t) I(t) R(t) +@species (X(t))[1:3] [description = "state vector"] +``` +""" macro species(ex...) return Symbolics.parse_vars(:variables, Real, ex, tospecies) end diff --git a/src/network_analysis.jl b/src/network_analysis.jl index 277319fe9d..0b2440272b 100644 --- a/src/network_analysis.jl +++ b/src/network_analysis.jl @@ -565,9 +565,22 @@ linkageclasses(incidencegraph) = Graphs.connected_components(incidencegraph) """ stronglinkageclasses(rn::ReactionSystem) - Return the strongly connected components of a reaction network's incidence graph (i.e. sub-groups of reaction complexes such that every complex is reachable from every other one in the sub-group). -""" +Return the strongly connected components of a reaction network's incidence +graph. + +Each returned vector contains the indices of reaction complexes for which every +complex in the component is reachable from every other complex in that +component. +# Examples +```julia +rn = @reaction_network begin + (k1, k2), A <--> B + k3, B --> C +end +stronglinkageclasses(rn) +``` +""" function stronglinkageclasses(rn::ReactionSystem) nps = get_networkproperties(rn) if isempty(nps.stronglinkageclasses) @@ -581,9 +594,20 @@ stronglinkageclasses(incidencegraph) = Graphs.strongly_connected_components(inci """ terminallinkageclasses(rn::ReactionSystem) - Return the terminal strongly connected components of a reaction network's incidence graph (i.e. sub-groups of reaction complexes that are 1) strongly connected and 2) every outgoing reaction from a complex in the component produces a complex also in the component). -""" +Return the terminal strong linkage classes of a reaction network. + +A terminal linkage class is strongly connected and has no outgoing reaction to a +complex outside the class. +# Examples +```julia +rn = @reaction_network begin + (k1, k2), A <--> B + k3, B --> C +end +terminallinkageclasses(rn) +``` +""" function terminallinkageclasses(rn::ReactionSystem) nps = get_networkproperties(rn) if isempty(nps.terminallinkageclasses) diff --git a/src/reactionsystem.jl b/src/reactionsystem.jl index 8db6feb94c..21f029400b 100644 --- a/src/reactionsystem.jl +++ b/src/reactionsystem.jl @@ -1077,7 +1077,10 @@ end """ isspatial(rn::ReactionSystem) -Returns whether `rn` has any spatial independent variables (i.e. is a spatial network). +Return whether `rn` is a spatial reaction system. + +Returns `true` when `rn` has spatial independent variables, and `false` +otherwise. """ isspatial(rn::ReactionSystem) = !isempty(get_sivs(rn)) diff --git a/src/spatial_reaction_systems/spatial_reactions.jl b/src/spatial_reaction_systems/spatial_reactions.jl index 89757a82f9..e1223f322f 100644 --- a/src/spatial_reaction_systems/spatial_reactions.jl +++ b/src/spatial_reaction_systems/spatial_reactions.jl @@ -13,7 +13,11 @@ Symbolics.option_to_metadata_type(::Val{:edgeparameter}) = EdgeParameter """ isedgeparameter(p) -Returns `true` if the parameter `p` is an edge parameter (else `false`). +Return whether `p` is marked as an edge parameter. + +Edge parameters vary by edge in a [`DiscreteSpaceReactionSystem`](@ref). +Returns `true` when the symbolic parameter carries edge-parameter metadata, and +`false` otherwise. """ isedgeparameter(x::Num, args...) = isedgeparameter(unwrap(x), args...) function isedgeparameter(x, default = false) @@ -25,8 +29,23 @@ end ### Transport Reaction Structures ### -# A transport reaction. These are simple to handle, and should cover most types of spatial reactions. -# Only permit constant rates (possibly consisting of several parameters). +""" + TransportReaction(rate, species) + +Create a spatial transport reaction for `species` with transport rate `rate`. + +`rate` may contain parameters but not species or other non-parameter symbolic +variables. Transport reactions are used by [`DiscreteSpaceReactionSystem`](@ref) +to move a species between neighboring compartments or graph vertices. + +# Examples +```julia +t = default_t() +@species X(t) +@parameters D +tr = TransportReaction(D, X) +``` +""" struct TransportReaction <: AbstractSpatialReaction """The rate function (excluding mass action terms). Currently, only constants supported""" rate::Any @@ -42,7 +61,21 @@ struct TransportReaction <: AbstractSpatialReaction end end -# Macro for creating a `TransportReaction`. +""" + @transport_reaction rate species + +Create a [`TransportReaction`](@ref) and mark symbols in `rate` as edge parameters. + +The macro declares any parameter symbols appearing in `rate`, declares `species` +as a Catalyst species using [`default_t`](@ref), and returns the resulting +transport reaction. + +# Examples +```julia +tr = @transport_reaction D X +tr2 = @transport_reaction D1 + D2 X +``` +""" macro transport_reaction(rateex::ExprValues, species::ExprValues) make_transport_reaction(striplines(rateex), species) end