Merge pull request #111 from isaacsas/doc-updates

Doc updates

Author: isaacsas

src/maketype.jl

@@ -133,6 +133,15 @@ function gentypefun_exprs(name; esc_exprs=true, gen_inplace=true, gen_outofplace
     exprs
 end
 
+"""
+    addodes!(network; build_jac=true, build_symfuncs=true)
+
+Extend an `AbstractReactionNetwork` generated with the `@min_reaction_network`
+macro with everything needed to use ODE solvers.
+
+Optional kwargs can be used to disable the construction of additional ODE solver
+components.
+"""
 function addodes!(rn::DiffEqBase.AbstractReactionNetwork; kwargs...)
     @unpack reactions, syms_to_ints, params_to_ints, syms = rn
 
@@ -152,6 +161,15 @@ function addodes!(rn::DiffEqBase.AbstractReactionNetwork; kwargs...)
     nothing
 end
 
+"""
+    addsdes!(network; build_jac=true, build_symfuncs=true)
+
+Extend an `AbstractReactionNetwork` generated with the `@min_reaction_network`
+macro with everything needed to use SDE solvers.
+
+Optional kwargs can be used to disable the construction of additional SDE solver
+components.
+"""
 function addsdes!(rn::DiffEqBase.AbstractReactionNetwork)
     @unpack reactions, syms_to_ints, params_to_ints, scale_noise = rn
 
@@ -169,6 +187,30 @@ function addsdes!(rn::DiffEqBase.AbstractReactionNetwork)
     nothing
 end
 
+"""
+    addjumps!(network; build_jumps=true, build_regular_jumps=true, minimal_jumps=false)
+
+Extend an `AbstractReactionNetwork` generated with the `@min_reaction_network`
+macro with everything needed to use jump SSA solvers.
+
+Optional kwargs can be used to disable the construction of additional jump solver
+components.
+
+Keyword arguments:
+
+* `build_jumps`: if true jump rates and affects will be calculated for use in
+  DiffEqJump SSAs.
+
+* `build_regular_jumps`: if true a `RegularJump` representation of the
+  stochastic chemical kinetics model will be calculated for use in τ-leaping
+  methods.
+
+* `minimal_jumps`: if true `ConstantRate` jumps are only constructed for
+  non-mass action jumps. (Note, mass action jumps are still resolved within any
+  jump simulation. This option simply speeds up the construction of the jump
+  problem since it avoids building redundant `ConstantRate` jumps that encode
+  `MassActionJump`s, which are subsequently ignored within jump simulations.)
+""" 
 function addjumps!(rn::DiffEqBase.AbstractReactionNetwork;
                                     build_jumps=true,
                                     build_regular_jumps=true,

src/network_properties.jl

@@ -239,7 +239,7 @@ reaction with index `rxidx`. Note, for a reaction defined by
 `k*X*Y, X+Z --> 2X + Y`
 
 the expression that is returned will be `:(k*X*Y)`, while the *rate law* used in
-ODEs, SDEs and jumps would be `k*X^2*Y*Z`.
+ODEs and SDEs would be `k*X^2*Y*Z`.
 """
 function rateexpr(network, rxidx)
     network.reactions[rxidx].rate_org
@@ -424,7 +424,7 @@ end
 """
     rxtospecies_depgraph(network)
 
-Given an `AbstractReactionNetwork`, returns a Vector{Vector{Int}} mapping a
+Given an `AbstractReactionNetwork`, returns a `Vector{Vector{Int}}` mapping each
 reaction index to the indices of species that depend on it.
 """
 function rxtospecies_depgraph(network)
@@ -437,7 +437,7 @@ end
 """
     speciestorx_depgraph(network)
 
-Given an `AbstractReactionNetwork`, returns a Vector{Vector{Int}} mapping a
+Given an `AbstractReactionNetwork`, returns a `Vector{Vector{Int}}` mapping each
 species index to the indices of reactions that depend on it.
 """
 function speciestorx_depgraph(network)
@@ -459,7 +459,7 @@ end
 """
     rxtorx_depgraph(network)
 
-Given an `AbstractReactionNetwork`, returns a Vector{Vector{Int}} mapping a
+Given an `AbstractReactionNetwork`, returns a `Vector{Vector{Int}}` mapping each
 reaction index to the indices of reactions that depend on it.
 """
 function rxtorx_depgraph(network, sptorxs=speciestorx_depgraph(network))

src/reaction_network.jl

@@ -47,6 +47,14 @@ Example systems:
     probSDE = SDEProblem(rn, args...; kwargs...)
     probJump = JumpProblem(prob,aggregator::Direct,rn)
 """
+
+"""
+    @reaction_network
+
+Generates a subtype of an `AbstractReactionNetwork` that encodes a chemical
+reaction network, and complete ODE, SDE and jump representations
+of the system.
+"""
 macro reaction_network(name, ex::Expr, p...)
     coordinate(name, MacroTools.striplines(ex), p, :no___noise___scaling)
 end
@@ -63,6 +71,14 @@ macro reaction_network(ex::Expr, p...)
 end
 
 ################# query-based macros:
+
+"""
+    @min_reaction_network
+
+Generates a subtype of an `AbstractReactionNetwork` that only encodes a chemical
+reaction network. Use [`addodes!`](@ref), [`addsdes!`](@ref) or
+[`addjumps!`](@ref) to complete the network for specific problem types.
+"""
 macro min_reaction_network(name, ex::Expr, p...)
     min_coordinate(name, MacroTools.striplines(ex), p, :no___noise___scaling)
 end