GitHub

Main API

Reaction Systems

This section describes the FSPSystem struct, a thin wrapper around Catalyst's ReactionSystem for use with this package.

FiniteStateProjection.FSPSystem — Type
FSPSystem(rs::Catalyst.ReactionSystem, [ih]; combinatoric_ratelaw = true)

Represent a Catalyst reaction system as a finite state projection (FSP) system. FSPSystem stores the reaction system, an index handler describing the state-array layout, and generated rate functions used to construct ODE and steady-state problems.

Fields

  • rs: Underlying Catalyst reaction system.
  • ih: Index handler defining the FSP state-array layout.
  • rfs: Generated reaction-rate functions in the index-handler representation.

Arguments

  • rs: Catalyst reaction system without subsystems.
  • ih: Index handler for the FSP state array. By default, DefaultIndexHandler uses Catalyst's species order.

Keyword Arguments

  • combinatoric_ratelaw: Whether to use combinatoric jump rate laws.

Examples

using Catalyst

rn = @reaction_network begin
    birth, 0 --> A
    death, A --> 0
end
fsp = FSPSystem(rn)
source

Creating ODE systems

The following methods convert a reaction network into a system of ODEs representing the time-dependent FSP. This package provides a flexible way to represent the FSP in memory via index handlers, see [Index Handlers] for more information.

Base.convert — Method
Base.convert(::Type{ODEFunction}, sys::FSPSystem)

Return an ODEFunction defining the right-hand side of the CME.

Creates an ODEFunction for use with DifferentialEquations. This is where most of the work in the package happens; for best performance it is suggested to build an ODEFunction once for a given reaction system and reuse it instead of directly converting a reaction system to an ODEProblem (which implicitly calls this function).

source
SciMLBase.ODEProblem — Method
SciMLBase.ODEProblem(sys::FSPSystem, u0, tmax[, p])

Return an ODEProblem for use in DifferentialEquations. This function implicitly calls convert(ODEFunction, sys). It is usually more efficient to create an ODEFunction first and then use that to create ODEProblems.

source

Steady-State Problems

Computing steady-state distributions can be done using the SteadyStateDiffEq.jl package. At the moment FiniteStateProjection.jl adjusts the rate matrix so that reactions leaving the truncated state space have propensity 0. Pass a SteadyState instance to the conversion methods to request this steady-state formulation.

FiniteStateProjection.SteadyState — Type
struct SteadyState end

Marker type used to select the steady-state formulation of the Chemical Master Equation. Passing a SteadyState() instance to the conversion and matrix-building methods requests the right-hand side in which transitions out of the truncated state space are dropped (their propensity is set to zero), as required for solving for the stationary distribution rather than the time-dependent one.

It is used as a dispatch tag by Base.convert(::Type{ODEFunction}, ::FSPSystem, ::SteadyState), SparseArrays.SparseMatrixCSC(::FSPSystem, ::NTuple, ps, ::SteadyState) and SciMLBase.SteadyStateProblem(::FSPSystem, u0, p).

Usage

Pass SteadyState() as the final argument to SparseMatrixCSC, or construct a SteadyStateProblem from an FSPSystem.

Examples

julia > SteadyState()
SteadyState()
source
Base.convert — Method
Base.convert(::Type{ODEFunction}, sys::FSPSystem, ::SteadyState)

Return an ODEFunction defining the right-hand side of the CME, for use with SteadyStateProblems.

source

Reexported model-definition and problem interface

The documented workflow starts from a Catalyst reaction network and ends in a SciML problem:

using FiniteStateProjection
using OrdinaryDiffEq

rn = @reaction_network begin
    σ, 0 --> A
    d, A --> 0
end

sys = FSPSystem(rn)
prob = ODEProblem(sys, u0, (0, 10.0), ps)
sol = solve(prob, Vern7())

using FiniteStateProjection brings the names that workflow touches into scope. FiniteStateProjection only reexports them — they are owned and documented upstream, at the links below.

  • Defining and inspecting the reaction network, owned by Catalyst: @reaction_network, ReactionSystem (the type FSPSystem wraps), and the accessors species, numspecies and reactions, which give the number and order of the state-space dimensions a truncation has to cover
  • Building the problem, owned by SciMLBase and CommonSolve: ODEProblem, SteadyStateProblem, ODEFunction, solve. FiniteStateProjection defines the FSPSystem methods of the first three, documented above.

Anything else from Catalyst must be imported from Catalyst directly. In particular, FiniteStateProjection does not reexport Catalyst's symbolic model-building surface (@species, @parameters, @variables, @reaction, Reaction, network-composition and analysis functions), nor the other problem types Catalyst exposes (SDEProblem, JumpProblem, DiscreteProblem), none of which the finite state projection uses. Solver algorithms are not reexported either — solve(prob, Vern7()) still needs OrdinaryDiffEq, and SparseMatrixCSC for the matrix conversions comes from the SparseArrays standard library.