ReactionNetworkImporters.jl

This package provides importers to load reaction networks into Catalyst.jl ReactionSystems from several file formats. Currently, it supports loading networks in the following formats:

A subset of the BioNetGen .net file format.
Networks represented by dense or sparse substrate and product stoichiometric matrices.
Networks represented by dense or sparse complex stoichiometric and incidence matrices.

SBMLToolkit.jl provides an alternative for loading SBML files into Catalyst models, offering a much broader set of supported features. It allows the import of models that include features such as constant species, boundary condition species, events, constraint equations, and more. SBML files can be generated from many standard modeling tools, including BioNetGen, COPASI, and Virtual Cell.

Installation

To install ReactionNetworkImporters.jl, use the Julia package manager:

using Pkg
Pkg.add("ReactionNetworkImporters")

Contributing

Please refer to the SciML ColPrac: Contributor's Guide on Collaborative Practices for Community Packages for guidance on PRs, issues, and other matters relating to contributing to SciML.
See the SciML Style Guide for common coding practices and other style decisions.
There are a few community forums:
- The #diffeq-bridged and #sciml-bridged channels in the Julia Slack
- The #diffeq-bridged and #sciml-bridged channels in the Julia Zulip
- On the Julia Discourse forums
- See also SciML Community page

Examples

Loading a BioNetGen .net file

A simple network from the built-in BioNetGen bngl examples is the repressilator. The generate_network command in the bngl file outputs a reduced network description, i.e. a .net file, which can be loaded into a Catalyst ReactionSystem as:

using ReactionNetworkImporters
fname = "PATH/TO/Repressilator.net"
prnbng = loadrxnetwork(BNGNetwork(), fname)

Here BNGNetwork is a type specifying the file format that is being loaded. prnbng is a ParsedReactionNetwork structure with the following fields:

rn, a Catalyst ReactionSystem. Note this system is not marked complete by default (see the Catalyst docs for a discussion of completeness of systems).
u0, a Dict mapping initial condition symbolic variables to numeric values and/or symbolic expressions.
p, a Dict mapping parameter symbolic variables to numeric values and/or symbolic expressions.
varstonames, a Dict mapping the internal symbolic variable of a species used in the generated ReactionSystem to a String generated from the name in the .net file. This is necessary as BioNetGen can generate exceptionally long species names, involving characters that lead to malformed species names when used with Catalyst.
groupstosyms, a Dict mapping the Strings representing names for any groups defined in the BioNetGen file to the corresponding symbolic variable representing the ModelingToolkit symbolic observable associated with the group.

Given prnbng, we can construct and solve the corresponding ODE model for the reaction system by

using OrdinaryDiffEq, Catalyst
rn = complete(prnbng.rn)   # get the reaction network and mark it complete
tf = 100000.0
oprob = ODEProblem(rn, Float64[], (0.0, tf), Float64[])
sol = solve(oprob, Tsit5(), saveat = tf / 1000.0)

Note that we specify empty parameter and initial condition vectors, as these are already stored in the generated ReactionSystem, rn. A Dict mapping each symbolic species and parameter to its initial value or symbolic expression can be obtained using ModelingToolkit.defaults(rn).

See the Catalyst documentation for how to generate ODE, SDE, jump and other types of models.

Loading a matrix representation

Catalyst ReactionSystems can also be constructed from

substrate and product stoichiometric matrices.
complex stoichiometric and incidence matrices.

For example, here we both directly build a Catalyst network using the @reaction_network macro, and then show how to build the same network from these matrices using ReactionNetworkImporters:

# Catalyst network from the macro:
rs = @reaction_network testnetwork begin
    k1, 2A --> B
    k2, B --> 2A
    k3, A + B --> C
    k4, C --> A + B
    k5, 3C --> 3A
end

# network from basic stoichiometry using ReactionNetworkImporters
@parameters k1 k2 k3 k4 k5
@variables t
@species A(t) B(t) C(t)
species = [A, B, C]
pars = [k1, k2, k3, k4, k5]
substoich = [2 0 1 0 0;
             0 1 1 0 0;
             0 0 0 1 3]
prodstoich = [0 2 0 1 3;
              1 0 0 1 0;
              0 0 1 0 0]
mn = MatrixNetwork(pars, substoich, prodstoich; species = species,
                   params = pars) # a matrix network
prn = loadrxnetwork(mn) # dense version

# test the two networks are the same
@assert rs == prn.rn

# network from reaction complex stoichiometry
stoichmat = [2 0 1 0 0 3;
             0 1 1 0 0 0;
             0 0 0 1 3 0]
incidencemat = [-1 1 0 0 0;
                1 -1 0 0 0;
                0 0 -1 1 0;
                0 0 1 -1 0;
                0 0 0 0 -1;
                0 0 0 0 1]
cmn = ComplexMatrixNetwork(pars, stoichmat, incidencemat; species = species,
                           params = pars)  # a complex matrix network
prn = loadrxnetwork(cmn; name = :testnetwork)

# test the two networks are the same
@assert rs == prn.rn

The basic usages are

mn = MatrixNetwork(rateexprs, substoich, prodstoich; species = Any[],
                   params = Any[], t = nothing)
prn = loadrxnetwork(mn::MatrixNetwork)

cmn = ComplexMatrixNetwork(rateexprs, stoichmat, incidencemat; species = Any[],
                           params = Any[], t = nothing)
prn = loadrxnetwork(cmn::ComplexMatrixNetwork)

Here MatrixNetwork and ComplexMatrixNetwork are the types, which select that we are constructing a substrate/product stoichiometric matrix-based or a reaction complex matrix-based stoichiometric representation as input. See the Catalyst.jl API for more discussion on these matrix representations, and how Catalyst handles symbolic reaction rate expressions. These two types have the following fields:

rateexprs, any valid Symbolics.jl expression for the rates, or any basic number type. This can be a hard-coded rate constant like 1.0, a parameter like k1 above, or a general Symbolics expression involving parameters and species like k*A.
matrix inputs
- For MatrixNetwork
  - substoich, a number of species by number of reactions matrix, with entry (i,j) giving the stoichiometric coefficient of species i as a substrate in reaction j.
  - prodstoich, a number of species by number of reactions matrix, with entry (i,j) giving the stoichiometric coefficient of species i as a product in reaction j.
- For ComplexMatrixNetwork
  - stoichmat, the complex stoichiometry matrix defined here.
  - incidencemat, the complex incidence matrix defined here.
species, an optional vector of symbolic variables representing each species in the network. Can be constructed using the Catalyst.jl @species macro. Each species should be dependent on the same time variable (t in the example above).
parameters, a vector of symbolic variables representing each parameter in the network. Can be constructed with the ModelingToolkit.jl@parameters macro. If no parameters are used, it is an optional keyword.
t, an optional Symbolics.jl variable representing time as the independent variable of the reaction network. If not provided, Catalyst.default_t() is used to determine the default time variable.

For both input types, loadrxnetwork returns a ParsedReactionNetwork, prn, with only the field, prn.rn, filled in. prn.rn corresponds to the generated Catalyst.jl ReactionSystem that represents the network. Note, prn.rn is not marked as complete by default and must be manually completed by setting rn = complete(prn.rn) before creating an ODEProblem or such, see the Catalyst docs for details.

Dispatches are added if substoich and prodstoich both have the type SparseMatrixCSCin case of MatrixNetwork (or stoichmat and incidencemat both have the type SparseMatrixCSC in case of ComplexMatrixNetwork), in which case they are efficiently iterated through using the SparseArrays interface.

If the keyword argument species is not set, the resulting reaction network will simply name the species S1, S2,..., SN for a system with N total species. params defaults to an empty vector, so that it does not need to be set for systems with no parameters.

Reproducibility

The documentation of this SciML package was built using these direct dependencies,

Status `~/work/ReactionNetworkImporters.jl/ReactionNetworkImporters.jl/docs/Project.toml`
  [479239e8] Catalyst v15.0.0
  [e30172f5] Documenter v1.10.1
  [b4db0fb7] ReactionNetworkImporters v0.16.1 `~/work/ReactionNetworkImporters.jl/ReactionNetworkImporters.jl`

and using this machine and Julia version.

Julia Version 1.11.5
Commit 760b2e5b739 (2025-04-14 06:53 UTC)
Build Info:
  Official https://julialang.org/ release
Platform Info:
  OS: Linux (x86_64-linux-gnu)
  CPU: 4 × AMD EPYC 7763 64-Core Processor
  WORD_SIZE: 64
  LLVM: libLLVM-16.0.6 (ORCJIT, znver3)
Threads: 1 default, 0 interactive, 1 GC (on 4 virtual cores)

A more complete overview of all dependencies and their versions is also provided.

Status `~/work/ReactionNetworkImporters.jl/ReactionNetworkImporters.jl/docs/Manifest.toml`
  [47edcb42] ADTypes v1.14.0
  [a4c015fc] ANSIColoredPrinters v0.0.1
  [1520ce14] AbstractTrees v0.4.5
  [7d9f7c33] Accessors v0.1.42
  [79e6a3ab] Adapt v4.3.0
  [66dad0bd] AliasTables v1.1.3
  [ec485272] ArnoldiMethod v0.4.0
  [4fba245c] ArrayInterface v7.18.0
  [4c555306] ArrayLayouts v1.11.1
  [e2ed5e7c] Bijections v0.1.9
  [62783981] BitTwiddlingConvenienceFunctions v0.1.6
  [8e7c35d0] BlockArrays v1.6.1
  [70df07ce] BracketingNonlinearSolve v1.1.3
  [2a0fbf3d] CPUSummary v0.2.6
  [00ebfdb7] CSTParser v3.4.3
  [479239e8] Catalyst v15.0.0
  [d360d2e6] ChainRulesCore v1.25.1
  [fb6a15b2] CloseOpenIntervals v0.1.13
  [944b1d66] CodecZlib v0.7.8
  [861a8166] Combinatorics v1.0.2
⌅ [a80b9123] CommonMark v0.8.16
  [38540f10] CommonSolve v0.2.4
  [bbf7d656] CommonSubexpressions v0.3.1
  [f70d9fcc] CommonWorldInvalidations v1.0.0
  [34da2185] Compat v4.16.0
  [b152e2b5] CompositeTypes v0.1.4
  [a33af91c] CompositionsBase v0.1.2
  [2569d6c7] ConcreteStructs v0.2.3
  [187b0558] ConstructionBase v1.5.8
  [adafc99b] CpuId v0.3.1
  [a8cc5b0e] Crayons v4.1.1
  [9a962f9c] DataAPI v1.16.0
  [864edb3b] DataStructures v0.18.22
  [e2d170a0] DataValueInterfaces v1.0.0
  [2b5f629d] DiffEqBase v6.167.2
  [459566f4] DiffEqCallbacks v4.4.0
  [77a26b50] DiffEqNoiseProcess v5.24.1
  [163ba53b] DiffResults v1.1.0
  [b552c78f] DiffRules v1.15.1
  [a0c0ee7d] DifferentiationInterface v0.6.51
  [8d63f2c5] DispatchDoctor v0.4.19
  [31c24e10] Distributions v0.25.118
  [ffbed154] DocStringExtensions v0.9.4
  [e30172f5] Documenter v1.10.1
  [5b8099bc] DomainSets v0.7.15
  [7c1d4256] DynamicPolynomials v0.6.1
  [06fc5a27] DynamicQuantities v1.8.0
  [4e289a0a] EnumX v1.0.5
  [f151be2c] EnzymeCore v0.8.8
  [e2ba6199] ExprTools v0.1.10
  [55351af7] ExproniconLite v0.10.14
  [7034ab61] FastBroadcast v0.3.5
  [9aa1b823] FastClosures v0.3.2
  [a4df4552] FastPower v1.1.2
  [1a297f60] FillArrays v1.13.0
  [64ca27bc] FindFirstFunctions v1.4.1
  [6a86dc24] FiniteDiff v2.27.0
  [1fa38f19] Format v1.3.7
⌅ [f6369f11] ForwardDiff v0.10.38
  [069b7b12] FunctionWrappers v1.1.3
  [77dc65aa] FunctionWrappersWrappers v0.1.3
  [d9f16b24] Functors v0.5.2
  [46192b85] GPUArraysCore v0.2.0
  [d7ba0133] Git v1.3.1
  [c27321d9] Glob v1.3.1
  [86223c79] Graphs v1.12.1
  [34004b35] HypergeometricFunctions v0.3.28
  [b5f81e59] IOCapture v0.2.5
  [615f187c] IfElse v0.1.1
  [d25df0c9] Inflate v0.1.5
  [18e54dd8] IntegerMathUtils v0.1.2
  [8197267c] IntervalSets v0.7.10
  [3587e190] InverseFunctions v0.1.17
  [92d709cd] IrrationalConstants v0.2.4
  [82899510] IteratorInterfaceExtensions v1.0.0
  [692b3bcd] JLLWrappers v1.7.0
  [682c06a0] JSON v0.21.4
  [ae98c720] Jieko v0.2.1
⌅ [98e50ef6] JuliaFormatter v1.0.62
  [ccbc3e58] JumpProcesses v9.14.3
  [ba0b0d4f] Krylov v0.9.10
  [b964fa9f] LaTeXStrings v1.4.0
  [23fbe1c1] Latexify v0.16.7
  [10f19ff3] LayoutPointers v0.1.17
  [0e77f7df] LazilyInitializedFields v1.3.0
  [5078a376] LazyArrays v2.6.1
  [87fe0de2] LineSearch v0.1.4
  [d3d80556] LineSearches v7.3.0
  [7ed4a6bd] LinearSolve v3.7.2
  [2ab3a3ac] LogExpFunctions v0.3.29
  [d8e11817] MLStyle v0.4.17
  [1914dd2f] MacroTools v0.5.15
  [d125e4d3] ManualMemory v0.1.8
  [d0879d2d] MarkdownAST v0.1.2
  [bb5d69b7] MaybeInplace v0.1.4
  [e1d29d7a] Missings v1.2.0
  [961ee093] ModelingToolkit v9.72.0
  [2e0e35c7] Moshi v0.3.5
  [46d2c3a1] MuladdMacro v0.2.4
  [102ac46a] MultivariatePolynomials v0.5.7
  [d8a4904e] MutableArithmetics v1.6.4
  [d41bc354] NLSolversBase v7.9.1
  [77ba4419] NaNMath v1.1.3
  [8913a72c] NonlinearSolve v4.5.1
  [be0214bd] NonlinearSolveBase v1.5.2
  [5959db7a] NonlinearSolveFirstOrder v1.3.1
  [9a2c21bd] NonlinearSolveQuasiNewton v1.2.1
  [26075421] NonlinearSolveSpectralMethods v1.1.1
  [6fe1bfb0] OffsetArrays v1.16.0
  [429524aa] Optim v1.12.0
  [bac558e1] OrderedCollections v1.8.0
  [90014a1f] PDMats v0.11.34
  [d96e819e] Parameters v0.12.3
  [69de0a69] Parsers v2.8.2
  [e409e4f3] PoissonRandom v0.4.4
  [f517fe37] Polyester v0.7.16
  [1d0040c9] PolyesterWeave v0.2.2
  [85a6dd25] PositiveFactorizations v0.2.4
⌅ [aea7be01] PrecompileTools v1.2.1
  [21216c6a] Preferences v1.4.3
  [08abe8d2] PrettyTables v2.4.0
  [27ebfcd6] Primes v0.5.7
  [43287f4e] PtrArrays v1.3.0
  [1fd47b50] QuadGK v2.11.2
  [74087812] Random123 v1.7.0
  [e6cf234a] RandomNumbers v1.6.0
  [b4db0fb7] ReactionNetworkImporters v0.16.1 `~/work/ReactionNetworkImporters.jl/ReactionNetworkImporters.jl`
  [3cdcf5f2] RecipesBase v1.3.4
  [731186ca] RecursiveArrayTools v3.31.2
  [189a3867] Reexport v1.2.2
  [2792f1a3] RegistryInstances v0.1.0
  [ae029012] Requires v1.3.1
  [ae5879a3] ResettableStacks v1.1.1
  [79098fc4] Rmath v0.8.0
  [7e49a35a] RuntimeGeneratedFunctions v0.5.13
  [9dfe8606] SCCNonlinearSolve v1.0.0
  [94e857df] SIMDTypes v0.1.0
  [0bca4576] SciMLBase v2.84.0
  [19f34311] SciMLJacobianOperators v0.1.2
  [c0aeaf25] SciMLOperators v0.3.13
  [53ae85a6] SciMLStructures v1.7.0
  [efcf1570] Setfield v1.1.2
  [727e6d20] SimpleNonlinearSolve v2.2.1
  [699a6c99] SimpleTraits v0.9.4
  [a2af1166] SortingAlgorithms v1.2.1
  [0a514795] SparseMatrixColorings v0.4.18
  [276daf66] SpecialFunctions v2.5.1
  [aedffcd0] Static v1.2.0
  [0d7ed370] StaticArrayInterface v1.8.0
  [90137ffa] StaticArrays v1.9.13
  [1e83bf80] StaticArraysCore v1.4.3
  [10745b16] Statistics v1.11.1
  [82ae8749] StatsAPI v1.7.0
  [2913bbd2] StatsBase v0.34.4
  [4c63d2b9] StatsFuns v1.4.0
  [7792a7ef] StrideArraysCore v0.5.7
  [892a3eda] StringManipulation v0.4.1
  [2efcf032] SymbolicIndexingInterface v0.3.39
  [19f23fe9] SymbolicLimits v0.2.2
  [d1185830] SymbolicUtils v3.26.1
  [0c5d862f] Symbolics v6.38.0
  [3783bdb8] TableTraits v1.0.1
  [bd369af6] Tables v1.12.0
  [ed4db957] TaskLocalValues v0.1.2
  [8ea1fca8] TermInterface v2.0.0
  [1c621080] TestItems v1.0.0
  [8290d209] ThreadingUtilities v0.5.3
  [a759f4b9] TimerOutputs v0.5.28
  [0796e94c] Tokenize v0.5.29
  [3bb67fe8] TranscodingStreams v0.11.3
  [410a4b4d] Tricks v0.1.10
  [781d530d] TruncatedStacktraces v1.4.0
  [5c2747f8] URIs v1.5.2
  [3a884ed6] UnPack v1.0.2
  [1986cc42] Unitful v1.22.0
  [a7c27f48] Unityper v0.1.6
  [2e619515] Expat_jll v2.6.5+0
  [f8c6e375] Git_jll v2.49.0+0
  [1d5cc7b8] IntelOpenMP_jll v2025.0.4+0
  [94ce4f54] Libiconv_jll v1.18.0+0
  [856f044c] MKL_jll v2025.0.1+1
  [458c3c95] OpenSSL_jll v3.0.16+0
  [efe28fd5] OpenSpecFun_jll v0.5.6+0
  [f50d1b31] Rmath_jll v0.5.1+0
  [1317d2d5] oneTBB_jll v2022.0.0+0
  [0dad84c5] ArgTools v1.1.2
  [56f22d72] Artifacts v1.11.0
  [2a0f44e3] Base64 v1.11.0
  [ade2ca70] Dates v1.11.0
  [8ba89e20] Distributed v1.11.0
  [f43a241f] Downloads v1.6.0
  [7b1f6079] FileWatching v1.11.0
  [9fa8497b] Future v1.11.0
  [b77e0a4c] InteractiveUtils v1.11.0
  [4af54fe1] LazyArtifacts v1.11.0
  [b27032c2] LibCURL v0.6.4
  [76f85450] LibGit2 v1.11.0
  [8f399da3] Libdl v1.11.0
  [37e2e46d] LinearAlgebra v1.11.0
  [56ddb016] Logging v1.11.0
  [d6f4376e] Markdown v1.11.0
  [a63ad114] Mmap v1.11.0
  [ca575930] NetworkOptions v1.2.0
  [44cfe95a] Pkg v1.11.0
  [de0858da] Printf v1.11.0
  [3fa0cd96] REPL v1.11.0
  [9a3f8284] Random v1.11.0
  [ea8e919c] SHA v0.7.0
  [9e88b42a] Serialization v1.11.0
  [1a1011a3] SharedArrays v1.11.0
  [6462fe0b] Sockets v1.11.0
  [2f01184e] SparseArrays v1.11.0
  [f489334b] StyledStrings v1.11.0
  [4607b0f0] SuiteSparse
  [fa267f1f] TOML v1.0.3
  [a4e569a6] Tar v1.10.0
  [8dfed614] Test v1.11.0
  [cf7118a7] UUIDs v1.11.0
  [4ec0a83e] Unicode v1.11.0
  [e66e0078] CompilerSupportLibraries_jll v1.1.1+0
  [deac9b47] LibCURL_jll v8.6.0+0
  [e37daf67] LibGit2_jll v1.7.2+0
  [29816b5a] LibSSH2_jll v1.11.0+1
  [c8ffd9c3] MbedTLS_jll v2.28.6+0
  [14a3606d] MozillaCACerts_jll v2023.12.12
  [4536629a] OpenBLAS_jll v0.3.27+1
  [05823500] OpenLibm_jll v0.8.5+0
  [efcefdf7] PCRE2_jll v10.42.0+1
  [bea87d4a] SuiteSparse_jll v7.7.0+0
  [83775a58] Zlib_jll v1.2.13+1
  [8e850b90] libblastrampoline_jll v5.11.0+0
  [8e850ede] nghttp2_jll v1.59.0+0
  [3f19e933] p7zip_jll v17.4.0+2
Info Packages marked with ⌅ have new versions available but compatibility constraints restrict them from upgrading. To see why use `status --outdated -m`

You can also download the manifest file and the project file.