GraphMakie docs update

HISTORY.md

@@ -41,7 +41,18 @@
     (k1, k2), A <--> B
   end
   ```
-
+- Catalyst's network visualization capability has shifted from using Graphviz to [GraphMakie.jl](https://graph.makie.org/stable/). To use this functionality, load the GraphMakie extension by installing `Catalyst` and `GraphMakie`, along with a Makie backend like `GLMakie`. There are two new methods for visualizing graphs: `plot_network` and `plot_complexes`, which respectively display the species-reaction graph and complex graph.
+  ```julia
+  using Catalyst, GraphMakie, GLMakie
+  brusselator = @reaction_network begin
+     A, ∅ --> X
+     1, 2X + Y --> 3X
+     B, X --> Y
+     1, X --> ∅
+  end
+  plot_network(brusselator)
+  ```
+
 ## Catalyst 14.4.1
 - Support for user-defined functions on the RHS when providing coupled equations 
   for CRNs using the @equations macro. For example, the following now works: 

Project.toml

@@ -73,7 +73,6 @@ julia = "1.10"
 [extras]
 DiffEqCallbacks = "459566f4-90b8-5000-8ac3-15dfb0a30def"
 DomainSets = "5b8099bc-c8ec-5219-889f-1d9e522a28bf"
-Graphviz_jll = "3c863552-8265-54e4-a6dc-903eb78fde85"
 LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"
 Logging = "56ddb016-857b-54e1-b83d-db4d58db5568"
 NonlinearSolve = "8913a72c-1f9b-4ce2-8d82-65094dcecaec"
@@ -97,4 +96,4 @@ Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
 Unitful = "1986cc42-f94f-5a68-af5c-568840ba703d"
 
 [targets]
-test = ["DiffEqCallbacks", "DomainSets", "Graphviz_jll", "Logging", "NonlinearSolve", "OrdinaryDiffEqBDF", "OrdinaryDiffEqDefault", "OrdinaryDiffEqRosenbrock", "OrdinaryDiffEqTsit5", "OrdinaryDiffEqVerner", "Pkg", "Plots", "Random", "SafeTestsets", "SciMLBase", "SciMLNLSolve", "StableRNGs", "StaticArrays", "Statistics", "SteadyStateDiffEq", "StochasticDiffEq", "Test", "Unitful"]
+test = ["DiffEqCallbacks", "DomainSets", "Logging", "NonlinearSolve", "OrdinaryDiffEqBDF", "OrdinaryDiffEqDefault", "OrdinaryDiffEqRosenbrock", "OrdinaryDiffEqTsit5", "OrdinaryDiffEqVerner", "Pkg", "Plots", "Random", "SafeTestsets", "SciMLBase", "SciMLNLSolve", "StableRNGs", "StaticArrays", "Statistics", "SteadyStateDiffEq", "StochasticDiffEq", "Test", "Unitful"]

docs/make.jl

@@ -1,5 +1,7 @@
 using Documenter
 using Catalyst, ModelingToolkit
+# Add packages for plotting
+using GraphMakie, GLMakie
 
 docpath = Base.source_dir()
 assetpath = joinpath(docpath, "src", "assets")
@@ -37,7 +39,9 @@ makedocs(sitename = "Catalyst.jl",
         collapselevel = 1,
         assets = ["assets/favicon.ico"],
         canonical = "https://docs.sciml.ai/Catalyst/stable/"),
-    modules = [Catalyst, ModelingToolkit],
+    modules = [Catalyst, ModelingToolkit, 
+               isdefined(Base, :get_extension) ? Base.get_extension(Catalyst, :CatalystGraphMakieExtension) :
+               Catalyst.CatalystGraphMakieExtension],
     doctest = false,
     clean = true,
     pages = pages,

docs/src/api.md

@@ -271,7 +271,7 @@ isequivalent
 ==(rn1::ReactionSystem, rn2::ReactionSystem)
 ```
 
-## Network visualization
+## [Network visualization](@id network_visualization)
 [Latexify](https://korsbo.github.io/Latexify.jl/stable/) can be used to convert
 networks to LaTeX equations by
 ```julia
@@ -292,13 +292,10 @@ displayed as the ODE form)
 
 Finally, another optional argument (`expand_functions=true`) automatically expands functions defined by Catalyst (such as `mm`). To disable this, set `expand_functions=false`.
 
-If [Graphviz](https://graphviz.org/) is installed and commandline accessible, it
-can be used to create and save network diagrams using [`Graph`](@ref) and
-[`savegraph`](@ref).
+Reaction networks can be plotted using the `GraphMakie` extension, which is loaded whenever both `Catalyst` and `GraphMakie` are loaded (note that a Makie backend, like `GLMakie`, must be loaded as well). The two functions for plotting networks are `plot_network` and `plot_complexes`, which are two distinct representations. 
 ```@docs
-Graph
-complexgraph
-savegraph
+plot_network(::ReactionSystem)
+plot_complexes(::ReactionSystem)
 ```
 
 ## [Rate laws](@id api_rate_laws)

docs/src/index.md

@@ -37,7 +37,7 @@ etc).
 - [JumpProcesses.jl](https://github.com/SciML/JumpProcesses.jl) can be used to numerically sample generated Stochastic Chemical Kinetics Jump Process models.
 - Support for [parallelization of all simulations](@ref ode_simulation_performance_parallelisation), including parallelization of [ODE simulations on GPUs](@ref ode_simulation_performance_parallelisation_GPU) using [DiffEqGPU.jl](https://github.com/SciML/DiffEqGPU.jl).
 - [Latexify](https://korsbo.github.io/Latexify.jl/stable/) can be used to [generate LaTeX expressions](@ref visualisation_latex) corresponding to generated mathematical models or the underlying set of reactions.
-- [Graphviz](https://graphviz.org/) can be used to generate and [visualize reaction network graphs](@ref visualisation_graphs) (reusing the Graphviz interface created in [Catlab.jl](https://algebraicjulia.github.io/Catlab.jl/stable/)).
+- The GraphMakie package has [Makie](https://docs.makie.org/stable/) recipes that can be used to generate and [visualize reaction network graphs](@ref visualisation_graphs) 
 - Model steady states can be [computed through homotopy continuation](@ref homotopy_continuation) using [HomotopyContinuation.jl](https://github.com/JuliaHomotopyContinuation/HomotopyContinuation.jl) (which can find *all* steady states of systems with multiple ones), by [forward ODE simulations](@ref steady_state_solving_simulation) using [SteadyStateDiffEq.jl)](https://github.com/SciML/SteadyStateDiffEq.jl), or by [numerically solving steady-state nonlinear equations](@ref steady_state_solving_nonlinear) using [NonlinearSolve.jl](https://github.com/SciML/NonlinearSolve.jl).
 [BifurcationKit.jl](https://github.com/bifurcationkit/BifurcationKit.jl) can be used to compute bifurcation diagrams of model steady states (including finding periodic orbits).
 - [DynamicalSystems.jl](https://github.com/JuliaDynamics/DynamicalSystems.jl) can be used to compute model [basins of attraction](@ref dynamical_systems_basins_of_attraction), [Lyapunov spectrums](@ref dynamical_systems_lyapunov_exponents), and other dynamical system properties.

docs/src/introduction_to_catalyst/introduction_to_catalyst.md

@@ -81,14 +81,15 @@ latexify(rn)
 ```@example tut1
 rn #hide
 ```
-Assuming [Graphviz](https://graphviz.org/) is installed and command line
-accessible, within a Jupyter notebook we can also graph the reaction network by
-```julia
-g = Graph(rn)
+Catalyst also has functionality for visualizing networks using the [Makie](https://docs.makie.org/stable/)
+plotting ecosystem. The relevant packages to load are Catalyst, GraphMakie, and a Makie backend
+such as GLMakie. Doing so and then using the `plot_network` function allows us to 
+visualize the network: 
+```@example tut1
+using Catalyst
+import GLMakie, GraphMakie
+g = plot_network(rn)
 ```
-giving
-
-![Repressilator solution](../assets/repressilator.svg)
 
 The network graph shows a variety of information, representing each species as a
 blue node, and each reaction as an orange dot. Black arrows from species to
@@ -105,8 +106,11 @@ hillr(P₂,α,K,n), ∅ --> m₃
 have rates that depend on the proteins, and hence lead to red arrows from each
 `Pᵢ`.
 
-Note, from the REPL or scripts one can always use [`savegraph`](@ref) to save
-the graph (assuming `Graphviz` is installed).
+Note, from the REPL or scripts one can always use Makie's `save` function to save
+the graph.
+```julia
+save("repressilator_graph.png", g)
+```
 
 ## Mass action ODE models
 Let's now use our `ReactionSystem` to generate and solve a corresponding mass
@@ -176,7 +180,7 @@ At this point we are all set to solve the ODEs. We can now use any ODE solver
 from within the
 [OrdinaryDiffEq.jl](https://docs.sciml.ai/DiffEqDocs/stable/solvers/ode_solve/)
 package. We'll use the recommended default explicit solver, `Tsit5()`, and then
-plot the solutions:
+plot the solutions: 
 
 ```@example tut1
 sol = solve(oprob, Tsit5(), saveat=10.0)

docs/src/model_creation/model_visualisation.md

@@ -36,43 +36,60 @@ If you wish to copy the output to your [clipboard](https://en.wikipedia.org/wiki
     For a model to be nicely displayed you have to use an IDE that actually supports this (such as a [notebook](https://jupyter.org/)). Other environments (such as [the Julia REPL](https://docs.julialang.org/en/v1/stdlib/REPL/)) will simply return the full LaTeX code which would generate the desired expression. 
 
 ## [Displaying model networks](@id visualisation_graphs)
-A network graph showing a Catalyst model's species and reactions can be displayed using the `Graph` function. This first requires [Graphviz](https://graphviz.org/) to be installed and command line accessible. Here, we first declare a [Brusselator model](@ref basic_CRN_library_brusselator) and then displays its network topology:
+Catalyst uses `GraphMakie` to display representations of chemical reaction networks, including the complex graph and the species-reaction graph (which is similar to the [Petri net](https://en.wikipedia.org/wiki/Petri_net) representation). To get started, import Catalyst and GraphMakie to load the `CatalystGraphMakieExtension` extension, and then load a Makie backend (`GLMakie` is recommended).
+
+```@example visualisation_graphs
+using Catalyst, GraphMakie
+using GLMakie
+nothing # hide
+```
+
+Let's declare a [Brusselator model](@ref basic_CRN_library_brusselator) to see this plotting functionality. The functions `plot_network` and `plot_complexes` are used to create the species-reaction and complex graphs, respectively. For a more thorough description of these two representations, please see the [network visualization](@ref network_visualization) section of the API, but the gist is that the species-reaction graph has species and reactions as nodes, and the complex graph has reaction complexes as nodes. Below we will plot the species-reaction graph using `plot_network`. 
 ```@example visualisation_graphs
-using Catalyst
 brusselator = @reaction_network begin
     A, ∅ --> X
     1, 2X + Y --> 3X
     B, X --> Y
     1, X --> ∅
 end
-Graph(brusselator)
-nothing # hide
+plot_network(brusselator)
 ```
-!["Brusselator Graph"](../assets/network_graphs/brusselator_graph.png)
 
-The network graph represents species as blue nodes and reactions as orange dots. Black arrows from species to reactions indicate substrates, and are labelled with their respective stoichiometries. Similarly, black arrows from reactions to species indicate products (also labelled with their respective stoichiometries). If there are any reactions where a species affect the rate, but does not participate as a reactant, this is displayed with a dashed red arrow. This can be seen in the following [Repressilator model](@ref basic_CRN_library_repressilator):
+The species-reaction graph (or network graph) represents species as blue nodes and reactions as green dots. Black arrows from species to reactions indicate substrates, and are labelled with their respective stoichiometries. Similarly, black arrows from reactions to species indicate products (also labelled with their respective stoichiometries). If there are any reactions where a species affect the rate, but does not participate as a reactant, this is displayed with a dashed red arrow. This can be seen in the following [Repressilator model](@ref basic_CRN_library_repressilator):
 ```@example visualisation_graphs
 repressilator = @reaction_network begin
     hillr(Z,v,K,n), ∅ --> X
     hillr(X,v,K,n), ∅ --> Y
     hillr(Y,v,K,n), ∅ --> Z
     d, (X, Y, Z) --> ∅
 end
-Graph(repressilator)
-nothing # hide
+plot_network(repressilator)
 ```
-!["Repressilator Graph"](../assets/network_graphs/repressilator_graph.png)
 
-A generated graph can be saved using the `savegraph` function:
+A generated graph can be saved using Makie's `save` function. 
 ```julia
-repressilator_graph = Graph(repressilator)
-savegraph(repressilator_graph, "repressilator_graph.png")
+repressilator_graph = plot_network(repressilator)
+save("repressilator_graph.png", repressilator_graph)
 ```
 
-Finally, a [network's reaction complexes](@ref network_analysis_reaction_complexes) (and the reactions in between these) can be displayed using the `complexgraph(brusselator)` function:
+Finally, a [network's reaction complexes](@ref network_analysis_reaction_complexes) (and the reactions in between these) can be displayed using the `plot_complexes(brusselator)` function:
 ```@example visualisation_graphs
-complexgraph(brusselator)
-nothing # hide
+plot_complexes(brusselator)
+```
+Here, reaction complexes are displayed as blue nodes, and reactions between complexes are displayed as black arrows. Edges are labeled with their rate expressions.
+
+Makie graphs can be made to be interactive, allowing one to drag nodes and edges. To do this, we retrieve the axis from the GraphMakie plot, and then register the interactions. Note that this can only be done if `GLMakie` is the installed Makie backend. See the [GraphMakie docs](https://graph.makie.org/stable/#Predefined-Interactions) for more information.  
+
+```julia
+using GLMakie
+f, ax, p = plot_network(brusselator)
+deregister_interaction!(ax, :rectanglezoom)
+register_interaction!(ax, :ndrag, NodeDrag(p))
+register_interaction!(ax, :edrag, EdgeDrag(p))
+```
+
+The equivalent of `show` for Makie plots is the `display` function. 
+```julia
+f = plot_network(brusselator)
+display(f)
 ```
-!["Repressilator Complex Graph"](../assets/network_graphs/repressilator_complex_graph.png)
-Here, reaction complexes are displayed as blue nodes, and reactions in between these as black arrows.

docs/src/model_creation/network_analysis.md

@@ -31,10 +31,10 @@ In the [Introduction to Catalyst](@ref introduction_to_catalyst)
 tutorial we showed how the above network could be visualized as a
 species-reaction graph. There, species are represented by the nodes of the graph
 and edges show the reactions in which a given species is a substrate or product.
-```julia
-g = Graph(repressilator)
+```@example s1
+using Catalyst, GraphMakie, GLMakie
+g = plot_network(repressilator)
 ```
-![Repressilator solution](../assets/repressilator.svg)
 
 We also showed in the [Introduction to Catalyst](@ref introduction_to_catalyst) tutorial that
 the reaction rate equation ODE model for the repressilator is
@@ -187,22 +187,18 @@ N == Z*B
 ```
 
 Reaction complexes give an alternative way to visualize a reaction network
-graph. Catalyst's [`complexgraph`](@ref) command will calculate the complexes of
+graph. Catalyst's [`plot_complexes`](@ref) command will calculate the complexes of
 a network and then show how they are related. For example,
-```julia
-complexgraph(rn)
+```@example s1
+using Catalyst, GraphMakie, GLMakie
+plot_complexes(rn)
 ```
-gives
-
-![Simple example complex graph](../assets/simple_complexgraph.svg)
 
 while for the repressilator we find
-```julia
-complexgraph(repressilator)
+```@example s1
+plot_complexes(repressilator)
 ```
 
-![Repressilator complex](../assets/repressilator_complexgraph.svg)
-
 Here ∅ represents the empty complex, black arrows show reactions converting
 substrate complexes into product complexes where the rate is just a number or
 parameter, and red arrows indicate the conversion of substrate complexes into
@@ -228,11 +224,10 @@ rn = @reaction_network begin
 end
 ```
 with graph
-```julia
-complexgraph(rn)
+```@example s1
+plot_complexes(rn)
 ```
 
-![network_1](../assets/complex_rn.svg)
 
 #### [Linkage classes and sub-networks of the reaction network](@id network_analysis_structural_aspects_linkage)
 The preceding reaction complex graph shows that `rn` is composed of two
@@ -260,19 +255,15 @@ subnets = subnetworks(rn)
 reactions.(subnets)
 ```
 The graphs of the reaction complexes in the two sub-networks are then
-```julia
-  complexgraph(subnets[1])
+```@example s1
+  plot_complexes(subnets[1])
 ```
 
-![subnetwork_1](../assets/complex_subnets1.svg)
-
 and,
-```julia
- complexgraph(subnets[2])
+```@example s1
+ plot_complexes(subnets[2])
 ```
 
-![subnetwork_2](../assets/complex_subnets2.svg)
-
 #### [Deficiency of the network](@id network_analysis_structural_aspects_deficiency)
 A famous theorem in Chemical Reaction Network Theory, the Deficiency Zero
 Theorem [^1], allows us to use knowledge of the net stoichiometry matrix and the
@@ -357,12 +348,10 @@ end
 reactioncomplexes(rn)
 isreversible(rn)
 ```
-```julia
-complexgraph(rn)
+```@example s1
+plot_complexes(rn)
 ```
 
-![reversibility](../assets/complex_reversibility.svg)
-
 It is evident from the preceding graph that the network is not reversible.
 However, it satisfies a weaker property in that there is a path from each
 reaction complex back to itself within its associated subgraph. This is known as

src/Catalyst.jl

@@ -145,8 +145,6 @@ include("latexify_recipes.jl")
 
 # for making and saving graphs/plots
 include("plotting.jl")
-include("graphs.jl")
-export Graph, savegraph, complexgraph
 
 # for creating compounds
 include("chemistry_functionality.jl")
@@ -168,7 +166,7 @@ export hc_steady_states
 function make_si_ode end
 export make_si_ode
 
-# GraphMakie
+# GraphMakie: functionality for plotting species-reaction graphs and complexes
 function plot_network end
 function plot_complexes end
 export plot_network, plot_complexes