itermediate state

Author: Est

docs/examples/getting_started_with_network_dynamics.jl

@@ -175,8 +175,9 @@ by the authors of `DifferentialEquations.jl` for most non-stiff problems.
 =#
 ode_prob = ODEProblem(nd, x0, (0.0, 2.0))
 
-# We test all ex styles #src (@Hans: can you write here what this means?)
-Main.test_execution_styles(ode_prob)
+# We test all ex styles #src
+Main.test_execution_styles(ode_prob) #src
+
 
 # Solve the simulation commend
 sol = solve(ode_prob, Tsit5());
@@ -216,7 +217,7 @@ nd_2 = Network(g, nd_diffusion_vertex_2, nd_diffusion_edge_2)
 # x ~ N(0,1)^2; ϕ ~ N(0,1)
 x0_2 = vec(transpose([randn(rng, N) .^ 2 randn(rng, N)]))
 ode_prob_2 = ODEProblem(nd_2, x0_2, (0.0, 3.0))
-Main.test_execution_styles(ode_prob_2)
+Main.test_execution_styles(ode_prob_2) #src
 sol_2 = solve(ode_prob_2, Tsit5());
 
 
@@ -253,7 +254,6 @@ To study the asymptotic behaviour of the system it suffices to analyze the eigen
 
 #=
 # Putting it all together
-We begin by loading the necessary packages.
 =#
 
 using Graphs
@@ -297,7 +297,7 @@ nd = Network(g, nd_diffusion_vertex, nd_diffusion_edge)
 rng = StableRNG(1)
 x0 = randn(rng, N)
 ode_prob = ODEProblem(nd, x0, (0.0, 2.0))
-Main.test_execution_styles(ode_prob)
+Main.test_execution_styles(ode_prob) #src
 sol = solve(ode_prob, Tsit5());
 nothing #hide #md
 plot(sol; idxs=vidxs(nd, :, :), fmt=:png)
@@ -309,7 +309,7 @@ nd_diffusion_edge_2 = EdgeModel(; g=AntiSymmetric(diffusionedge_g!), outsym=[:fl
 nd_2 = Network(g, nd_diffusion_vertex_2, nd_diffusion_edge_2)
 x0_2 = vec(transpose([randn(rng, N) .^ 2 randn(rng, N)]))
 ode_prob_2 = ODEProblem(nd_2, x0_2, (0.0, 3.0))
-Main.test_execution_styles(ode_prob_2)
+Main.test_execution_styles(ode_prob_2) #src
 sol_2 = solve(ode_prob_2, Tsit5());
 plot(sol_2; idxs=vidxs(nd_2, :, :x), fmt=:png)
 plot(sol_2; idxs=eidxs(nd_2, :, :flow_x), fmt=:png)

docs/examples/heterogeneous_system.jl

@@ -1,13 +1,13 @@
 #=
 # Modeling a heterogeneous system
 
-This example can be dowloaded as a normal Julia script [here](@__NAME__.jl). #md
+This example can be downloaded as a normal Julia script [here](@__NAME__.jl). #md
 
-One of the main purposes of NetworkDynamics.jl is to facilitate
-modeling coupled systems with heterogenities. This means that
-components can differ in their parameters as well as in their dynamics.
+One of the main purposes of NetworkDynamics.jl is to facilitate the
+modeling systems whose components can differ in their parameters as well as their dynamics.
+These are known as Coupled systems with heterogeneities.
 
-## Heterogenous parameters
+## Heterogeneous parameters
 
 We start by setting up a simple system of Kuramoto oscillators.
 =#

docs/src/index.md

@@ -1,17 +1,20 @@
 # NetworkDynamics
 
-*NetworkDynamics.jl* is a package to simulate dynamical systems within complex networks. It provides an interface 
+The *NetworkDynamics.jl* package simulates dynamical systems within complex networks. It provides an interface 
 between the [Graphs.jl](https://github.com/JuliaGraphs/Graphs.jl) and the 
 [DifferentialEquations.jl](https://github.com/SciML/DifferentialEquations.jl) packages and facilitates the simulation of 
-highly efficient dynamic networks by describing the local dynamics on the edges and vertices of the graph.
+highly efficient dynamic networks by describing the local dynamics on the edges and vertices of the network graph.
 
 !!! note
+    ** Complex Networks in a glance **
     Complex network systems are composed by the entities that comprise them (the nodes) and the relationships that connect
-    each entity with one another (the edges). The graphical depictions of such networks are called graphs. The simplest
-    The mathematical structure (used more or less interchangeably with Network) is also called [Graph](https://en.wikipedia.org/wiki/Graph_theory).
-    The network (which can be seen in the figure below) is composed of two entities (so two nodes) who are only connected to each other.
-    This connection between the two is the edge of the system. Complex networks are composed of multiple nodes and edges,
-    with most nodes connected to multiple other nodes with multiple edges
+    each entity with one another (the edges). The mathematical structure (used more or less interchangeably with 
+    Network) is called [Graph](https://en.wikipedia.org/wiki/Graph_theory). The graphical depictions of such 
+    networks are also called graphs. You will see both usages in this guide.
+    A network (which can be seen in the figure below) is composed of nodes (v1 to v5) who are connected to each other. 
+    The lines connecting the nodes with each other ( e1: 1-->2, e2: 1-->3, e3: 2-->3, e4: 2-->4, e5: 3-->5) are called 
+    edges. Complex networks are composed of multiple nodes and edges, with most nodes connected to multiple other nodes
+    with multiple edges
 
 ```@example
 using Graphs, GraphMakie, CairoMakie #hide
@@ -27,31 +30,22 @@ hidespines!(ax) #hide
 hidedecorations!(ax) #hide
 fig #hide
 ```
-
-The behavior of a node or an edge can be described through the use of (a) algebraic equations, (b) differential algebraic 
-equation (DAEs) in mass matrix form or c) ordinary differential equations (ODE). 
-
-The core of the package is the function [`Network`](@ref). It accepts the functions describing the local dynamics on the
-edges and nodes of the graph `g` as inputs, and returns a composite function compatible with the 
-DifferentialEquations.jl calling syntax.
-
-```julia
-nd = Network(g, vertex_dynamics,  edge_dynamics)
-nd(dx, x, p, t)
-```
+(@Hans after rereading the text I realised that the information about the core of the package and the behaviours of the 
+nodes and edges does not belong in the introduction but rather in the mathematical model, so I moved it. If you are ok)
+with this just delete this comment)
 
 Main features:
 - Clear separation of local dynamics and topology: you can easily change the topology of your system or switch out 
-- dynamic components.
+  dynamic components)
 - High performance when working with heterogeneous models: you can have different local dynamics in different parts of 
-- your network.
+  your network)
 - [Symbolic Indexing](@ref) into solutions and states: NetworkDynamics keeps track of the states of each individual 
-- subsystem.
+  subsystem.
 - Diverse execution schemes: NetworkDynamics exploits the known interdependencies between components to auto 
-- parallelize execution, even on GPUs!
+  parallelize execution, even on GPUs!
 - Equation based models: you can model local dynamics using 
-- [ModelingToolkit.jl](https://docs.sciml.ai/ModelingToolkit/dev/) and them combine them into larger networks by using 
-- `NetworkDynamics.jl`!
+  [ModelingToolkit.jl](https://docs.sciml.ai/ModelingToolkit/dev/) and them combine them into larger networks using 
+  `NetworkDynamics.jl`!
 
 
 ## Where to begin?

docs/src/mathematical_model.md

@@ -1,41 +1,50 @@
 # Mathematical Model
-The basic mathematical model of `NetworkDynamics.jl` splits the system in two parts: the vertex and
-the edge components.
 
-The main goal of `NetworkDynamics.jl` is to express the overall network dynamics as a
-[Differential-Algebraic-Equation (DAE)](https://mathworld.wolfram.com/Differential-AlgebraicEquation.html)
+The core of the `NetworkDynamics.jl` package is the [`Network`](@ref) function. It accepts the functions describing the 
+local dynamics on the edges and nodes of the graph `g` as inputs, and returns a composite function compatible with the 
+DifferentialEquations.jl syntax.
 
+```julia
+nd = Network(g, vertex_dynamics,  edge_dynamics)
+nd(dx, x, p, t)
+```
+
+The local dynamics on the edges and nodes of the graph can be described through the use of (a) algebraic equations, 
+(b) differential algebraic equation (DAEs) in mass matrix form or (c) ordinary differential equations (ODE). The 
+`NetworkDynamics.jl` package uses [Differential-Algebraic-Equation (DAE)](https://mathworld.wolfram.com/Differential-AlgebraicEquation.html)
+to express the overall network dynamics:
 ```math
 M\,\frac{\mathrm{d}}{\mathrm{d}t}u = f^{\mathrm{nw}}(u, p, t)
 ```
 where $M$ is a (possibly singular) mass matrix, $u$ is the internal state vector of the system, $p$ are the parameters
-and $t$ is the time.
-To make this compatible with the solvers used in `OrdinaryDiffEq.jl`, the generated
-[`Network`](@ref) object is a callable object
+and $t$ is the time. To make this compatible with the solvers used in `OrdinaryDiffEq.jl`, the generated
+[`Network`](@ref) object is a callable object:
 ```
 nw(du, u, p, t) # mutates du as an "output"
 ```
-which represents the right-hand-side (RHS) of the equation above. The mass-matrix $m$ is stored in the `Network` object as well.
-
-Instead of defining $f^{\mathrm{nw}}$ by hand, `ND.jl` helps you to build it automatically based on a list of 
-decentralized nodal and edge dynamics, the so-called `VertexModel` and `EdgeModel` objects. Each component model 
-$\mathrm c$ is modeled as a general input-output-system:
+which represents the right-hand-side (RHS) of the equation above. The mass-matrix $m$ is stored in the `Network` object 
+as well.
 
+Each component model $\mathrm c$ is modeled as a general input-output-system:
 ```math
 \begin{aligned}
 M_{\mathrm c}\,\frac{\mathrm{d}}{\mathrm{d}t}x_{\mathrm c} &= f^{\mathrm c}(x^{\mathrm c}, i_{\mathrm c}, p_{\mathrm c}, t)\\
 y^{\mathrm c} &= g^{\mathrm c}(x^\mathrm{c}, i_{\mathrm c}, p_{\mathrm c}, t)
 \end{aligned}
 ```
-
 where $M_{\mathrm{c}}$ is the component mass matrix, $x^{\mathrm c}$ are the component states, $i^{\mathrm c}$ are the
-***inputs*** of the component and $y^{\mathrm c}$ is the ***output*** of the component.
-If $\mathrm{dim}(x^{\mathrm{c}}) = 0$, the number of internal states is 0.
+***inputs*** of the component and $y^{\mathrm c}$ is the ***output*** of the component. If
+$\mathrm{dim}(x^{\mathrm{c}}) = 0$, the number of internal states is 0.
+
+The mathematical model of `NetworkDynamics.jl` splits the network system in two parts: the vertex and
+the edge components (the nodes and edges, respectively). Instead of defining the $f^{\mathrm{nw}}$ by hand, `ND.jl`
+builds it automatically based on a list of decentralized nodal and edge dynamics that you need to provide, 
+the so-called `VertexModel` and `EdgeModel` objects.
 
 In the context of the network, the **output of the edges are flow variables** and the **outputs of vertices are 
-potential variables**.
-When the node and edge models are placed on a graph, the inputs and outputs ware connected: the nodes receive the output of the
-adjacent edges as inputs and the edges receive the output of the adjecent nodes as inputs.
+potential variables**. When the node and edge models are placed on a graph, the inputs and outputs ware connected: 
+the nodes receive the output of the adjacent edges as inputs and the edges receive the output of the adjecent nodes as 
+inputs.
 
 Thus, the *flow* on the edges depends on the *potentials* at both ends as inputs. The *potentials* of the nodes depend on the 
 incoming *flows* from all connected edges as an input. (Here, flow and potentials are meant in a conceptional and not 
@@ -45,6 +54,8 @@ necessarily physical way.)
 <img src="../assets/mathmodel.svg" width="100%"/>
 ```
 
+
+
 ## Vertex Models
 ```@raw html
 <img src="../assets/nodemodel.svg" width="100%"/>

docs/src/symbolic_indexing.md

@@ -1,24 +1,21 @@
 # Symbolic Indexing
 
-Using SciML's [`SymbolicIndexingInterface.jl`](https://github.com/SciML/SymbolicIndexingInterface.jl), `ND.jl` provides numerous methods to access and change variables and parameters.
-
-!!! details "Setup code to make following examples work"
-    ```@example si
-    using NetworkDynamics
-    using Graphs
-    using OrdinaryDiffEqTsit5
-    using Plots
-    ```
+By using SciML's [`SymbolicIndexingInterface.jl`](https://github.com/SciML/SymbolicIndexingInterface.jl), `ND.jl` 
+provides numerous methods to access and change variables and parameters.
 
 ## Provide Symbol Names
 When constructing component models, you can pass symbolic names using the `sym` and `psym` keywords.
 ```@example si
+using NetworkDynamics
+using Graphs
+using OrdinaryDiffEqTsit5
+using Plots
 function _edgef!(e, v_s, v_d, (K,), t)
     e .= K * (v_s[1] .- v_d[1])
 end
 edgef = EdgeModel(;g=AntiSymmetric(_edgef!), outsym=[:flow], psym=[:K=>1])
 ```
-Here we created a static diffusion edge with suitable variable and parameter names.
+Here we create a static diffusion edge with suitable variable and parameter names.
 Similarly, we define the diffusion vertex with symbolic names.
 ```@example si
 function _vertexf!(dv, v, esum, p, t)
@@ -30,12 +27,11 @@ vertexf = VertexModel(f=_vertexf!, g=1, sym=[:storage])
 
 ## Fundamental Symbolic Indices
 The default types for this access are the types [`VIndex`](@ref), [`EIndex`](@ref), [`VPIndex`](@ref) and [`EPIndex`](@ref).
-Each of those symbolic indices consists of 2 elements: a reference to the network component and a reference to the symbol within that component.
+Each of those symbolic indices consists of 2 elements: a reference to the network component and a reference to the 
+symbol within that component.
 As such: 
 - `VIndex(2, :x)` refers to variable with symbolic name `:x` in vertex number 2.
 - `EPIndex(4, 2)` refers to the *second* parameter of the edge component for the 4th edge.
-- `VPIndex`() refers to (@Hans please fill in this with an example)
-- `EPIndex`() refers to (@Hans please fill in this with an example)
 
 !!! details "Setup code to make following examples work"
     ```@example si
@@ -55,7 +51,8 @@ plot(sol; idxs=[VIndex(1, :storage), VIndex(5,:storage)]) # plot storage of two
 ```
 
 ## Generate Symbolic Indices
-Often, you need many individual symbolic indices. To achieve this you can use the helper methods [`vidxs`](@ref), [`eidxs`](@ref), [`vpidxs`](@ref) and [`epidxs`](@ref). With their help you can generate arrays of symbolic indices:
+Often, you need many individual symbolic indices. To achieve this you can use the helper methods [`vidxs`](@ref), 
+[`eidxs`](@ref), [`vpidxs`](@ref) and [`epidxs`](@ref). With their help you can generate arrays of symbolic indices:
 
 ```@example si
 vidxs(nw, :, :storage) # get variable "storage" for all vertices
@@ -100,7 +97,8 @@ in these flat arrays corresponds exactly to the order returned by [`variable_sym
 
 !!! note
     The `NWState` and `NWParameter` wrappers can be constructed from various objects.
-    For example, within a callback you might construct `p = NWParameter(integrator)` to then change the parameters of the network within the callback.
+    For example, within a callback you might construct `p = NWParameter(integrator)` to then change the parameters of 
+the network within the callback.
 
 
 ## Observables
@@ -113,7 +111,8 @@ It is also possible to define additional Observables manually by using the `obss
 on the `EdgeModel`/`VertexModel` constructors.
 When building models using ModelingToolkit, the reduced algebraic states will be preserved automatically as observables.
 
-Observables can be accessed like any other state. For example, the flows in the network don't show up in the state array but can be accessed in all the ways discussed above. 
+Observables can be accessed like any other state. For example, the flows in the network don't show up in the state array 
+but can be accessed in all the ways discussed above. 
 For example:
 ```@example si
 plot(sol; idxs=eidxs(nw, :, :flow))
@@ -130,7 +129,8 @@ For example, we can directly plot the storage difference with respect to storage
 plot(sol; idxs=@obsex(vidxs(nw,:,:storage) .- VIndex(1,:storage)))
 ```
 
-Other examples include calculating the magnitude and argument of complex values that are modeled using real and imaginary parts.
+Other examples include calculating the magnitude and argument of complex values that are modeled using real and 
+imaginary parts.
 ```
 @obsex mag = sqrt(VIndex(1, :u_r)^2 + VIndex(2, :u_i)^2)
 ```