Update SBMLImporter tutorial

docs/Project.toml

@@ -37,6 +37,8 @@ OrdinaryDiffEqTsit5 = "b1df2697-797e-41e3-8120-5422d3b24e4a"
 OrdinaryDiffEqVerner = "79d7bb75-1356-48c1-b8c0-6832512096c2"
 Plots = "91a5bcdd-55d7-5caf-9e0b-520d859cae80"
 QuasiMonteCarlo = "8a4e6c94-4038-4cdc-81c3-7e6ffdb2a71b"
+ReactionNetworkImporters = "b4db0fb7-de2a-5028-82bf-5021f5cfa881"
+SBMLImporter = "210efffb-c3c8-456d-a807-6f55560b12fe"
 SciMLBase = "0bca4576-84f4-4d90-8ffe-ffa030f20462"
 SciMLSensitivity = "1ed8b502-d754-442c-8d5d-10ac956f44a1"
 SpecialFunctions = "276daf66-3868-5448-9aa4-cd146d93841b"

docs/pages.jl

@@ -15,7 +15,7 @@ pages = Any[
     "model_creation/conservation_laws.md",
     "model_creation/parametric_stoichiometry.md",
     "model_creation/functional_parameters.md",
-    # "model_creation/model_file_loading_and_export.md", Wait for new SBMImporter and ReactionNetworkImporters versions
+    "model_creation/model_file_loading_and_export.md",
     "model_creation/model_visualisation.md",
     "model_creation/reactionsystem_content_accessing.md",
     "model_creation/chemistry_related_functionality.md",

docs/old_files/unused_tutorials/model_file_loading_and_export.md → docs/src/model_creation/model_file_loading_and_export.md

@@ -16,7 +16,7 @@ Pkg.add("SBMLImporter")
 </details>
 ```
   \
-  
+
 Catalyst stores chemical reaction network (CRN) models in `ReactionSystem` structures. This tutorial describes how to load such `ReactionSystem`s from, and save them to, files. This can be used to save models between Julia sessions, or transfer them from one session to another. Furthermore, to facilitate the computation modelling of CRNs, several standardised file formats have been created to represent CRN models (e.g. [SBML](https://sbml.org/)). This enables CRN models to be shared between different software and programming languages. While Catalyst itself does not have the functionality for loading such files, we will here (briefly) introduce a few packages that can load different file types to Catalyst `ReactionSystem`s.
 
 ## [Saving Catalyst models to, and loading them from, Julia files](@id model_file_import_export_crn_serialization)
@@ -46,33 +46,34 @@ cc_loaded # hide
 Here, `include` is used to execute the Julia code from any file. This means that `save_reactionsystem` actually saves the model as executable code which re-generates the exact model which was saved (this is the reason why we use the ".jl" extension for the saved file). Indeed, we can confirm this if we check what is printed in the file:
 ```
 let
+# Serialised using Catalyst version v1.12.5.
 
 # Independent variable:
-@parameters t
+@independent_variables t
 
 # Parameters:
-ps = @parameters kB kD kP
+ps = @parameters k₁ k₂ k₃
 
 # Species:
-sps = @species S(t) E(t) SE(t) P(t)
+sps = @species S₁(t) C(t) S₁C(t) S₂(t) CP(t) P(t)
 
 # Reactions:
 rxs = [
-    Reaction(kB, [S, E], [SE], [1, 1], [1]),
-    Reaction(kD, [SE], [S, E], [1], [1, 1]),
-    Reaction(kP, [SE], [P, E], [1], [1, 1])
+	Reaction(k₁, [S₁, C], [S₁C], [1, 1], [1]),
+	Reaction(k₂, [S₁C, S₂], [CP], [1, 1], [1]),
+	Reaction(k₃, [CP], [C, P], [1], [1, 1])
 ]
 
 # Declares ReactionSystem model:
-rs = ReactionSystem(rxs, t, sps, ps; name = Symbol("##ReactionSystem#12592"))
+rs = ReactionSystem(rxs, t, sps, ps; name = Symbol("##ReactionSystem#288"))
 complete(rs)
 
 end
 ```
 !!! note
     The code that `save_reactionsystem` prints uses [programmatic modelling](@ref programmatic_CRN_construction) to generate the written model.
 
-In addition to transferring models between Julia sessions, the `save_reactionsystem` function can also be used or print a model to a text file where you can easily inspect its components.
+In addition to transferring models between Julia sessions, the `save_reactionsystem` function can also be used to print a model to a text file where you can easily inspect its components.
 
 ## [Loading and saving arbitrary Julia variables using Serialization.jl](@id model_file_import_export_julia_serialisation)
 Julia provides a general and lightweight interface for loading and saving Julia structures to and from files that it can be good to be aware of. It is called [Serialization.jl](https://docs.julialang.org/en/v1/stdlib/Serialization/) and provides two functions, `serialize` and `deserialize`. The first allows us to write a Julia structure to a file. E.g. if we wish to save a parameter set associated with our model, we can use
@@ -92,55 +93,56 @@ loaded_sol # hide
 A general-purpose format for storing CRN models is so-called .net files. These can be generated by e.g. [BioNetGen](https://bionetgen.org/). The [ReactionNetworkImporters.jl](https://github.com/SciML/ReactionNetworkImporters.jl) package enables the loading of such files to Catalyst `ReactionSystem`. Here we load a [Repressilator](@ref basic_CRN_library_repressilator) model stored in the "repressilator.net" file:
 ```julia
 using ReactionNetworkImporters
-prn = loadrxnetwork(BNGNetwork(), "repressilator.net")
+rn = loadrxnetwork(BNGNetwork(), "repressilator.net")
 ```
-Here, .net files not only contain information regarding the reaction network itself, but also the numeric values (initial conditions and parameter values) required for simulating it. Hence, `loadrxnetwork` generates a `ParsedReactionNetwork` structure, containing all this information. You can access the model as `prn.rn`, the initial conditions as `prn.u0`, and the parameter values as `prn.p`. Furthermore, these initial conditions and parameter values are also made [*default* values](@ref dsl_advanced_options_default_vals) of the model.
-
-A parsed reaction network's content can then be provided to various problem types for simulation. E.g. here we perform an ODE simulation of our repressilator model:
+Here, .net files not only contain information regarding the reaction network itself, but also the numeric values (initial conditions and parameter values) required for simulating it. The `loadrxnetwork` function loads the model as a normal `ReactionSystem` structure, but saves the initial conditions and parameter values as [*default* values](@ref dsl_advanced_options_default_vals) that are automatically accounted for in simulations. The loaded model can be provided to various problem types for simulation. E.g. here we perform an ODE simulation of our repressilator model:
 ```julia
 using Catalyst, OrdinaryDiffEqDefault, Plots
 tspan = (0.0, 10000.0)
-oprob = ODEProblem(prn.rn, Float64[], tspan, Float64[])
+oprob = ODEProblem(rn, Float64[], tspan, Float64[])
 sol = solve(oprob)
 plot(sol; idxs = [:mTetR, :mLacI, :mCI])
 ```
 ![Repressilator Simulation](../assets/repressilator_sim_ReactionNetworkImporters.svg)
 
-Note that, as all initial conditions and parameters have default values, we can provide empty vectors for these into our `ODEProblem`.
-
+Note that, as all initial conditions and parameters have default values, we can provide empty vectors for these into our `ODEProblem`. To load these values from the model, the `get_u0_map(rn)` and `get_parameter_map(rn)` functions can be used.
 
 !!! note
     It should be noted that .net files support a wide range of potential model features, not all of which are currently supported by ReactionNetworkImporters. Hence, there might be some .net files which `loadrxnetwork` will not be able to load.
 
 A more detailed description of ReactionNetworkImporter's features can be found in its [documentation](https://docs.sciml.ai/ReactionNetworkImporters/stable/).
 
-## [Loading SBML files using SBMLImporter.jl and SBMLToolkit.jl](@id model_file_import_export_sbml)
-The Systems Biology Markup Language (SBML) is the most widespread format for representing CRN models. Currently, there exist two different Julia packages, [SBMLImporter.jl](https://github.com/sebapersson/SBMLImporter.jl) and [SBMLToolkit.jl](https://github.com/SciML/SBMLToolkit.jl), that are able to load SBML files to Catalyst `ReactionSystem` structures. SBML is able to represent a *very* wide range of model features, with both packages supporting most features. However, there exist SBML files (typically containing obscure model features such as events with time delays) that currently cannot be loaded into Catalyst models.
+## [Loading SBML files using SBMLImporter.jl](@id model_file_import_export_sbml)
+The Systems Biology Markup Language (SBML) is the most widespread format for representing CRN models. Here, the [SBMLImporter.jl](https://github.com/sebapersson/SBMLImporter.jl) package is able to load SBML files to Catalyst `ReactionSystem` structures. SBML is able to represent a *very* wide range of model features, with SBMLImporter supporting most features. However, there exist SBML files (typically containing obscure model features such as events with time delays) that currently cannot be loaded into Catalyst models.
 
-SBMLImporter's `load_SBML` function can be used to load SBML files. Here, we load a [Brusselator](@ref basic_CRN_library_brusselator) model stored in the "brusselator.xml" file:
+SBMLImporter's `load_SBML` function can be used to load SBML files. Here, we load a
+[Brusselator](@ref basic_CRN_library_brusselator) model stored in the "brusselator.xml"
+file:
 ```julia
 using SBMLImporter
-prn, cbs = load_SBML("brusselator.xml", massaction = true)
+rn, cbs = load_SBML("brusselator.xml", massaction = true)
 ```
-Here, while [ReactionNetworkImporters generates a `ParsedReactionSystem` only](@ref model_file_import_export_sbml_rni_net), SBMLImporter generates a `ParsedReactionSystem` (here stored in `prn`) and a [so-called `CallbackSet`](https://docs.sciml.ai/DiffEqDocs/stable/features/callback_functions/#CallbackSet) (here stored in `cbs`). While `prn` can be used to create various problems, when we simulate them, we must also supply `cbs`. E.g. to simulate our brusselator we use:
+
+`load_SBML` returns two outputs: a `ReactionSystem` (`rn`) and a `CallbackSet` (`cbs`). The `CallbackSet` contains SBML events and callbacks generated from any SBML `piecewise` expressions. While `rn` can be used to create problems, when we simulate them, we must also supply `cbs`. The SBML file also contains simulation initial condition and parameter values. These are saved within the `rn` and can be extracted using the `get_u0_map` and `get_parameter_map` functions. Here we simulate the loaded brusselator model, providing `u0`, `ps`, and `cb` as described.
 ```julia
 using Catalyst, OrdinaryDiffEqDefault, Plots
 tspan = (0.0, 50.0)
-oprob = ODEProblem(prn.rn, prn.u0, tspan, prn.p)
+u0 = get_u0_map(rn)
+ps = get_parameter_map(rn)
+oprob = ODEProblem(rn, u0, tspan, ps)
 sol = solve(oprob; callback = cbs)
 plot(sol)
 ```
+
 ![Brusselator Simulation](../assets/brusselator_sim_SBMLImporter.svg)
 
-Note that, while ReactionNetworkImporters adds initial condition and species values as default to the imported model, SBMLImporter does not do this. These must hence be provided to the `ODEProblem` directly.
+!!! note 
+    While ReactionNetworkImporters saves parameters (`ps`) and species values (`u0`) as default to the imported model, SBMLImporter does not do this. These must hence be explicitly loaded through `get_u0_map` and `get_parameter_map` and then provided to the `ODEProblem`.
 
 A more detailed description of SBMLImporter's features can be found in its [documentation](https://sebapersson.github.io/SBMLImporter.jl/stable/).
 
 !!! note
-    The `massaction = true` option informs the importer that the target model follows mass-action principles. When given, this enables SBMLImporter to make appropriate modifications to the model (which are important for e.g. jump simulation performance).
-
-### [SBMLImporter and SBMLToolkit](@id model_file_import_export_package_alts)
-Above, we described how to use SBMLImporter to import SBML files. Alternatively, SBMLToolkit can be used instead. It has a slightly different syntax, which is described in its [documentation](https://github.com/SciML/SBMLToolkit.jl), and does not support as wide a range of SBML features as SBMLImporter. A short comparison of the two packages can be found [here](https://github.com/sebapersson/SBMLImporter.jl?tab=readme-ov-file#differences-compared-to-sbmltoolkit). Generally, while they both perform well, we note that for *jump simulations* SBMLImporter is preferable (its way for internally representing reaction event enables more performant jump simulations).
+    The `massaction = true` option informs the importer that the target model follows mass-action principles. When given, this enables SBMLImporter to make appropriate modifications to the model (which are important for jump simulation performance).
 
 ## [Loading models from matrix representation using ReactionNetworkImporters.jl](@id model_file_import_export_matrix_representations)
 While CRN models can be represented through various file formats, they can also be represented in various matrix forms. E.g. a CRN with $m$ species and $n$ reactions (and with constant rates) can be represented with either
@@ -155,32 +157,23 @@ The advantage of these forms is that they offer a compact and very general way t
 ---
 ## [Citations](@id petab_citations)
 If you use any of this functionality in your research, [in addition to Catalyst](@ref doc_index_citation), please cite the paper(s) corresponding to whichever package(s) you used:
-```
+```bibtex
 @software{2022ReactionNetworkImporters,
   author       = {Isaacson, Samuel},
   title        = {{ReactionNetworkImporters.jl}},
   howpublished = {\url{https://github.com/SciML/ReactionNetworkImporters.jl}},
   year         = {2022}
 }
 ```
-```
-@software{2024SBMLImporter,
-  author       = {Persson, Sebastian},
-  title        = {{SBMLImporter.jl}},
-  howpublished = {\url{https://github.com/sebapersson/SBMLImporter.jl}},
-  year         = {2024}
-}
-```
-```
-@article{LangJainRackauckas+2024,
-    url = {https://doi.org/10.1515/jib-2024-0003},
-    title = {SBMLToolkit.jl: a Julia package for importing SBML into the SciML ecosystem},
-    title = {},
-    author = {Paul F. Lang and Anand Jain and Christopher Rackauckas},
-    pages = {20240003},
-    journal = {Journal of Integrative Bioinformatics},
-    doi = {doi:10.1515/jib-2024-0003},
-    year = {2024},
-    lastchecked = {2024-06-02}
+```bibtex
+@article{PEtabBioinformatics2025,
+  title={PEtab.jl: advancing the efficiency and utility of dynamic modelling},
+  author={Persson, Sebastian and Fr{\"o}hlich, Fabian and Grein, Stephan and Loman, Torkel and Ognissanti, Damiano and Hasselgren, Viktor and Hasenauer, Jan and Cvijovic, Marija},
+  journal={Bioinformatics},
+  volume={41},
+  number={9},
+  pages={btaf497},
+  year={2025},
+  publisher={Oxford University Press}
 }
 ```