Document exported Catalyst APIs

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,

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"
 ]

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
+```

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

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
+```

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
 

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