Edit tutorial contents #253
Conversation
Improved the NetworkDynamics intro
improved section talking about how the behavour of nodes and edges can be described.
Rephrased the second part of the introduction
| Next you need to install the Julia package Revise: | ||
| ```julia-repl | ||
| import Pkg; Pkg.add("Revise") | ||
| ``` | ||
|
|
||
| Last you need to install the Julia package LiveServer: | ||
| ```julia-repl | ||
| import Pkg; Pkg.add("LiveServer") | ||
| ``` |
There was a problem hiding this comment.
Revise is only an optional development dependency, LiveServer is only necessary if you want to observe the docs locally (which most people will never do). Therefore, I'd cut this part.
If you think it would be good to point people to general usage help of Julia (so they learn about Revise, Project Environments and so on) I'd instead suggest to link out to something like https://modernjuliaworkflows.org/
docs/src/index.md
Outdated
|
|
||
| The behavior of a node or an edge can be described by algebraic equations, by differential algebraic equation (DAEs) in mass matrix form or by ordinary differential equations (ODE). | ||
| 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 network (which can be seen in Figure 1) 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 *(@Hans: can you created the graph of such a network and place in here?)* |
There was a problem hiding this comment.
hm not happy with this sentence, because Graph is the name of the mathematical structure (more or less interchangably with Network) and not just the graphical representation.
There was a problem hiding this comment.
Not entirely sure which kind of graphic you'd like here. For example you could inline the following code to create a graphplot like this:
```@example
using Graphs, GraphMakie, CairoMakie #hide
using GraphMakie.NetworkLayout #hide
CairoMakie.activate!(type="svg") #hide
g = smallgraph(:bull) #hide
fig, ax, p = graphplot(g; ilabels=["v$i" for i in 1:nv(g)], #hide
elabels=["e$i: $(e.src) ↦ $(e.dst)" for (i, e) in enumerate(edges(g))], #hide
layout=Align(Stress()), figure=(;resolution=(400,200))) #hide
ymin, ymax = extrema(last.(p[:node_pos][])) #hide
ylims!(ax, (ymin-0.11*(ymax-ymin), ymax+0.11*(ymax-ymin)))#hide
hidespines!(ax) #hide
hidedecorations!(ax) #hide
fig #hide
```
improved language and added information requests
| This example can be dowloaded as a normal Julia script [here](@__NAME__.jl). #md | ||
| (@Hans: this creates a copy of this Julia file. I am assuming you would only want the commands rather than the text. |
There was a problem hiding this comment.
Its not exactly that: the documentation uses Literate.jl. Using this setup we have essentially a template file (this file here) and base on that template file we generate the documentation markdown an the script for download.
example_template.jl ---> export as example.md
---> export as example.jl
It is possible, to filter lines. In theory, we could mark most of the lines with #src at the end.
Normally, people will look at the examples in html form online. They are not aware of this file here. This link helps them to download a jl script to try out the code localy rather than looking at the rendered version in the browser.
This setup specificially saves us from uploading near identical files, which are impossible to keep in sync. There should be only ever one source of "truth" for each example.
| # We test all ex styles #src (@Hans: can you write here what this means?) | ||
| Main.test_execution_styles(ode_prob) |
There was a problem hiding this comment.
Those two lines are more or less internal and used for the test suit. In the package tests of NetworkDynamics, each example will be run -- if an example can't be run the tests will fail. Those two lines add some extra tests for that: they test the constructed network with different parallelization schemes to make sure they all give the same results.
However, both lines should never be seen by users of the package:
| # 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 |
The #src at the end is a specific marker used to filter lines in Literate.jl.
Marking those as #src will filter both lines before exporting the md file (which will be rendered in documentation) and the "script" file, which is linked for download at the top of the page.
| ```@raw html | ||
| <img src="../assets/mathmodel.svg" width="100%"/> | ||
| ``` | ||
| @Hans: the image seems to be missing here |
There was a problem hiding this comment.
it is not visible in the markdown preview in github, because relative links work different there. But it does show up for me in the rendered documentation.
| - `VPIndex`() refers to (@Hans please fill in this with an example) | ||
| - `EPIndex`() refers to (@Hans please fill in this with an example) |
There was a problem hiding this comment.
You added those examples, neither VPIndex() nor EPIndex() are valid i think. Why would you like to include it?
[no benchmark]