Merge pull request #13 from VirtualPlantLab/ana-Intro_org_tutorials

Issues #2 and #9 fixed

Author: AleMorales

docs/make.jl

@@ -13,7 +13,8 @@ makedocs(;
         edit_link="master",
         assets=String[],
         collapselevel = 1,
-        footer = nothing
+        footer = nothing,
+        size_threshold = nothing
     ),
     pages=[
         "Virtual Plant Laboratory" => "index.md",
@@ -25,15 +26,18 @@ makedocs(;
             "Ray tracing" => "manual/Raytracer.md",
             "3D visualization" => "manual/Visualization.md"
         ],
-        "Tutorials" => [
-            "Algae growth" => "tutorials/algae.md",
-            "The Koch snowflake" => "tutorials/snowflakes.md",
-            "Tree" => "tutorials/tree.md",
-            "Forest" => "tutorials/forest.md",
-            "Growth forest" => "tutorials/growthforest.md",
-            "Ray-traced forest" => "tutorials/raytracedforest.md",
-            "Context sensitive rules" => "tutorials/context.md",
-            "Relational queries" => "tutorials/relationalqueries.md"
+        "Tutorials" => ["Intro" => "tutorials/intro_tut.md",
+            "Getting started with VPL" =>
+            ["Algae growth" => "tutorials/getting_started/algae.md",
+            "The Koch snowflake" => "tutorials/getting_started/snowflakes.md"],
+            "From tree to forest" =>
+            ["Tree" => "tutorials/from_tree_forest/tree.md",
+            "Forest" => "tutorials/from_tree_forest/forest.md",
+            "Growth forest" => "tutorials/from_tree_forest/growthforest.md",
+            "Ray-traced forest" => "tutorials/from_tree_forest/raytracedforest.md"],
+            "More on rules and queries" =>
+            ["Context sensitive rules" => "tutorials/more_rules_queries/context.md",
+            "Relational queries" => "tutorials/more_rules_queries/relationalqueries.md"]
         ],
         "How-to guides" => [
             "Setting up a grid cloner" => "howto/GridCloner.md"

docs/src/tutorials/forest.md …src/tutorials/from_tree_forest/forest.mddocs/src/tutorials/forest.md renamed to docs/src/tutorials/from_tree_forest/forest.md docs/src/tutorials/forest.md renamed to docs/src/tutorials/from_tree_forest/forest.md

@@ -4,6 +4,13 @@ Alejandro Morales
 
 Centre for Crop Systems Analysis - Wageningen University
 
+> ## TL;DR
+> Similar in functionality to [Tree]() tutorial with separate graphs for each tree 
+> - Modify tree parameters for each tree
+> - Multithreaded simulation (grow trees in parallel)
+> - Scene customization (e.g., add soil)
+> - Export Scenes
+
 In this example we extend the tree example into a forest, where
 each tree is described by a separate graph object and parameters driving the
 growth of these trees vary across individuals following a predefined distribution.
@@ -47,7 +54,7 @@ end
 import .TreeTypes
 ````
 
-Create geometry + color for the internodes
+Create geometry and color for the *internodes*:
 
 ````julia
 function VirtualPlantLab.feed!(turtle::Turtle, i::TreeTypes.Internode, data)
@@ -59,7 +66,7 @@ function VirtualPlantLab.feed!(turtle::Turtle, i::TreeTypes.Internode, data)
 end
 ````
 
-Create geometry + color for the leaves
+Create geometry and color for the *leaves*:
 
 ````julia
 function VirtualPlantLab.feed!(turtle::Turtle, l::TreeTypes.Leaf, data)
@@ -74,7 +81,7 @@ function VirtualPlantLab.feed!(turtle::Turtle, l::TreeTypes.Leaf, data)
 end
 ````
 
-Insertion angle for the bud nodes
+Insertion angle for the bud nodes:
 
 ````julia
 function VirtualPlantLab.feed!(turtle::Turtle, b::TreeTypes.BudNode, data)
@@ -83,7 +90,7 @@ function VirtualPlantLab.feed!(turtle::Turtle, b::TreeTypes.BudNode, data)
 end
 ````
 
-Rules
+Rules for meristem and branches:
 
 ````julia
 meristem_rule = Rule(TreeTypes.Meristem, rhs = mer -> TreeTypes.Node() +
@@ -198,7 +205,7 @@ forest = vec(create_tree.(origins, growths, budbreaks, orientations));
 
 By vectorizing `create_tree()` over the different arrays, we end up with an array
 of trees. Each tree is a different Graph, with its own nodes, rewriting rules
-and variables. This avoids having to create a large graphs to include all the
+and variables. This avoids having to create large graphs to include all the
 plants in a simulation. Below we will run a simulation, first using a sequential
 approach (i.e. using one core) and then using multiple cores in our computers (please check
 https://docs.julialang.org/en/v1/manual/multi-threading/ if the different cores are not being used
@@ -234,7 +241,7 @@ In the previous section, the simulation of growth was done sequentially, one tre
 after another (since the growth of a tree only depends on its own parameters). However,
 this can also be executed in multiple threads. In this case we use an explicit loop
 and execute the iterations of the loop in multiple threads using the macro `@threads`.
-Note that the rendering function can also be ran in parallel (i.e. the geometry will be
+Note that the rendering function can also be run in parallel (i.e. the geometry will be
 generated separately for each plant and the merge together):
 
 ````julia
@@ -260,7 +267,7 @@ render(Scene(newforest), parallel = true)
 
 # Customizing the scene
 
-Here we are going to customize the scene of our simulation by adding a horizontal tile represting soil and
+Here we are going to customize the scene of our simulation by adding a horizontal tile representing soil and
 tweaking the 3D representation. When we want to combine plants generated from graphs with any other
 geometric element it is best to combine all these geometries in a `GLScene` object. We can start the scene
 with the `newforest` generated in the above:
@@ -273,7 +280,7 @@ We can create the soil tile directly, without having to create a graph. The simp
 a special constructor `Rectangle` where one species a corner of the rectangle and two vectors defining the
 two sides of the vectors. Both the sides and the corner need to be specified with `Vec` just like in the
 above when we determined the origin of each plant. VPL offers some shortcuts: `O()` returns the origin
-(`Vec(0.0, 0.0, 0.0)`), whereas `X`, `Y` and `Z` returns the corresponding axes and you can scale them by
+(`Vec(0.0, 0.0, 0.0)`), whereas `X`, `Y` and `Z` returns the corresponding axes, and you can scale them by
 passing the desired length as input. Below, a rectangle is created on the XY plane with the origin as a
 corner and each side being 11 units long:
 
@@ -291,8 +298,8 @@ VirtualPlantLab.add!(scene, mesh = soil, color = RGB(1,1,0))
 
 We can now render the scene that combines the random forest of binary trees and a yellow soil. Notice that
 in all previous figures, a coordinate system with grids was being depicted. This is helpful for debugging
-your code but also to help setup the scene (e.g. if you are not sure how big the soil tile should be).
-Howver, it may be distracting for the visualization. It turns out that we can turn that off with
+your code but also to help set up the scene (e.g. if you are not sure how big the soil tile should be).
+However, it may be distracting for the visualization. It turns out that we can turn that off with
 `show_axes = false`:
 
 ````julia

docs/src/tutorials/growthforest.md …torials/from_tree_forest/growthforest.mddocs/src/tutorials/growthforest.md renamed to docs/src/tutorials/from_tree_forest/growthforest.md docs/src/tutorials/growthforest.md renamed to docs/src/tutorials/from_tree_forest/growthforest.md

@@ -4,6 +4,14 @@ Alejandro Morales
 
 Centre for Crop Systems Analysis - Wageningen University
 
+> ## TL;DR
+> Now we want to implement a more extended functionality of our [Forest]()!
+> - Growth rules, based on information stored in organs (dimensions, carbon assimilation)
+> - Update dimensions in function of assimilation
+> - Compute sink strength 
+> - Merge Scenes
+> - Generate forest on grid and retrieve canopy-level data (e.g., LAI)
+> 
 
 In this example we extend the binary forest example to have more complex, time-
 dependent development and growth based on carbon allocation. For simplicity, the
@@ -129,7 +137,7 @@ end
 ### Development
 
 The meristem rule is now parameterized by the initial states of the leaves and
-internodes and will only be triggered every X days where X is the plastochron.
+internodes and will only be triggered every X days, where X is the plastochron.
 
 ````julia
 # Create right side of the growth rule (parameterized by the initial states

docs/src/tutorials/raytracedforest.md …ials/from_tree_forest/raytracedforest.mddocs/src/tutorials/raytracedforest.md renamed to docs/src/tutorials/from_tree_forest/raytracedforest.md docs/src/tutorials/raytracedforest.md renamed to docs/src/tutorials/from_tree_forest/raytracedforest.md

@@ -4,8 +4,16 @@ Alejandro Morales
 
 Centre for Crop Systems Analysis - Wageningen University
 
-
-In this example we extend the forest growth model to include PAR interception a
+> ## TL;DR
+> Now we want to forest growth model that PAR interception and introduces user to the ray-tracer.
+> - Include material as a property for each object
+> - Create sky for specific conditions and locations
+> - Layer different types of radiation in sky domes (e.g., direct and diffuse)
+> - Combine graph and sky with a ray-tracer
+> - Compute growth and biomass production according to PAR interception and RUE
+> 
+
+In this example we extend the forest growth model to include PAR interception and
 radiation use efficiency to compute the daily growth rate.
 
 The following packages are needed:
@@ -27,9 +35,9 @@ Random.seed!(123456789)
 ### Node types
 
 The data types needed to simulate the trees are given in the following
-module. The difference with respec to the previous model is that Internodes and
+module. The difference with respect to the previous model is that Internodes and
 Leaves have optical properties needed for ray tracing (they are defined as
-Lambertian surfaces).
+[Lambertian surfaces](https://doi.org/10.1016/j.ecolmodel.2006.04.010)).
 
 ````julia
 # Data types
@@ -126,7 +134,7 @@ end
 ### Development
 
 The meristem rule is now parameterized by the initial states of the leaves and
-internodes and will only be triggered every X days where X is the plastochron.
+internodes and will only be triggered every X days, where X is the plastochron.
 
 ````julia
 # Create right side of the growth rule (parameterized by the initial states
@@ -227,7 +235,7 @@ end
 
 Given the scene, we can create the light sources that can approximate the solar
 irradiance on a given day, location and time of the day using the functions from
-the  package (see package documentation for details). Given the latitude,
+the package (see package documentation for details). Given the latitude,
 day of year and fraction of the day (`f = 0` being sunrise and `f = 1` being sunset),
 the function `clear_sky()` computes the direct and diffuse solar radiation assuming
 a clear sky. These values may be converted to different wavebands and units using
@@ -273,19 +281,18 @@ end
 The 3D scene and the light sources are then combined into a `RayTracer` object,
 together with general settings for the ray tracing simulation chosen via `RTSettings()`.
 The most important settings refer to the Russian roulette system and the grid
-cloner (see section on Ray Tracing for details). The settings for the Russian
+cloner (see section on [Ray tracing](https://virtualplantlab.com/dev/manual/Raytracer/)). The settings for the Russian
 roulette system include the number of times a ray will be traced
 deterministically (`maxiter`) and the probability that a ray that exceeds `maxiter`
 is terminated (`pkill`). The grid cloner is used to approximate an infinite canopy
 by replicating the scene in the different directions (`nx` and `ny` being the
 number of replicates in each direction along the x and y axes, respectively). It
 is also possible to turn on parallelization of the ray tracing simulation by
-setting `parallel = true` (currently this uses Julia's builtin multithreading
+setting `parallel = true` (currently this uses Julia's built-in multithreading
 capabilities).
 
-In addition `RTSettings()`, an acceleration structure and a splitting rule can
-be defined when creating the `RayTracer` object (see ray tracing documentation
-for details). The acceleration structure allows speeding up the ray tracing
+In addition, `RTSettings()`, an acceleration structure and a splitting rule can
+be defined when creating the `RayTracer` object. The acceleration structure allows speeding up the ray tracing
 by avoiding testing all rays against all objects in the scene.
 
 ````julia
@@ -317,7 +324,7 @@ the `power()` function returns three different values, one for each waveband,
 but they are added together as RUE is defined for total PAR.
 
 Run the ray tracer, calculate PAR absorbed per tree and add it to the daily
-total using general weighted quadrature formula
+total using general weighted quadrature formula:
 
 ````julia
 function calculate_PAR!(forest;  DOY = 182)
@@ -335,7 +342,7 @@ function calculate_PAR!(forest;  DOY = 182)
 end
 ````
 
-Reset PAR absorbed by the tree (at the start of a new day)
+Reset PAR absorbed by the tree (at the start of a new day):
 
 ````julia
 function reset_PAR!(forest)
@@ -349,7 +356,7 @@ end
 ### Growth
 
 We need some functions to compute the length and width of a leaf or internode
-from its biomass
+from its biomass.
 
 ````julia
 function leaf_dims(biomass, vars)
@@ -445,7 +452,7 @@ function grow!(tree, all_leaves, all_internodes)
 end
 ````
 
-Finally, we need to update the dimensions of the organs. The leaf dimensions are
+Finally, we need to update the dimensions of the organs. The leaf dimensions are:
 
 ````julia
 function size_leaves!(all_leaves, tvars)

docs/src/tutorials/tree.md …s/src/tutorials/from_tree_forest/tree.mddocs/src/tutorials/tree.md renamed to docs/src/tutorials/from_tree_forest/tree.md docs/src/tutorials/tree.md renamed to docs/src/tutorials/from_tree_forest/tree.md

@@ -4,6 +4,11 @@ Alejandro Morales
 
 Centre for Crop Systems Analysis - Wageningen University
 
+> ### TL;DR
+> - Define different types of nodes (introduction to name spaces)
+> - Store data in graph (plant-base) vs. in graph node (node-base)
+> - Define parameters at the graph-level and node-level
+>
 
 In this example we build a 3D representation of a binary TreeTypes. Although this will not look like a real plant, this example will help introduce additional features of VPL.
 
@@ -15,15 +20,15 @@ The model requires five types of nodes:
 
 *Node*: What is left after a meristem produces a new organ (it separates internodes). They contain no data or geometry (so also a point) but are required to keep the branching structure of the tree as well as connecting leaves.
 
-*Bud*: These are dormant meristems associated to tree nodes. When they are activated, they become an active meristem that produces a branch. They contain no data or geometry but they change the orientation of the turtle.
+*Bud*: These are dormant meristems associated to tree nodes. When they are activated, they become an active meristem that produces a branch. They contain no data or geometry, but they change the orientation of the turtle.
 
-*BudNode*: The node left by a bud after it has been activated. They contain no data or geometry but they change the orientation of the turtle.
+*BudNode*: The node left by a bud after it has been activated. They contain no data or geometry, but they change the orientation of the turtle.
 
 *Leaf*: These are the nodes associated to leaves in the TreeTypes. They are represented by ellipses with a particular orientation and insertion angle. The insertion angle is assumed constant, but the orientation angle varies according to an elliptical phyllotaxis rule.
 
-In this first simple model, only internodes grow over time according to a relative growth rate, whereas leaves are assumed to be of fixed sized determined at their creation. For simplicity, all active meristems will produce an phytomer (combination of node, internode, leaves and buds) per time step. Bud break is assumed stochastic, with a probability that increases proportional to the number of phytomers from the apical meristem (up to 1). In the following tutorials, these assumptions are replaced by more realistic models of light interception, photosynthesis, etc.
+In this first simple model, only internodes grow over time according to a relative growth rate, whereas leaves are assumed to be of fixed sized determined at their creation. For simplicity, all active meristems will produce a phytomer (combination of node, internode, leaves and buds) per time step. Bud break is assumed stochastic, with a probability that increases proportional to the number of phytomers from the apical meristem (up to 1). In the following tutorials, these assumptions are replaced by more realistic models of light interception, photosynthesis, etc.
 
-In order to simulate growth of the 3D binary tree, we need to define a parameter describing the relative rate at which each internode elongates in each iteration of the simulation, a coefficient to compute the probability of bud break as well as the insertion and orientation angles of the leaves. We could stored these values as global constants, but VPL offers to opportunity to store them per plant. This makes it easier to manage multiple plants in the same simulation that may belong to different species, cultivars, ecotypes or simply to simulate plant-to-plant variation. Graphs in VPL can store an object of any user-defined type that will me made accessible to graph rewriting rules and queries. For this example, we define a data type `treeparams` that holds the relevant parameters. We use `Base.@kwdef` to assign default values to all parameters and allow to assign them by name.
+In order to simulate growth of the 3D binary tree, we need to define a parameter describing the relative rate at which each internode elongates in each iteration of the simulation, a coefficient to compute the probability of bud break as well as the insertion and orientation angles of the leaves. We could store these values as global constants, but VPL offers to opportunity to store them per plant. This makes it easier to manage multiple plants in the same simulation that may belong to different species, cultivars, ecotypes or simply to simulate plant-to-plant variation. Graphs in VPL can store an object of any user-defined type that will be made accessible to graph rewriting rules and queries. For this example, we define a data type `treeparams` that holds the relevant parameters. We use `Base.@kwdef` to assign default values to all parameters and allow to assign them by name.
 
 ````julia
 using VirtualPlantLab
@@ -91,7 +96,7 @@ function VirtualPlantLab.feed!(turtle::Turtle, b::TreeTypes.BudNode, vars)
 end
 ````
 
-The growth rule for a branch within a tree is simple: a phytomer (or basic unit of morphology) is composed of a node, a leaf, a bud node, an internode and an active meristem at the end. Each time step, the meristem is replaced by a new phytomer, allowing for developmemnt within a branch.
+The growth rule for a branch within a tree is simple: a phytomer (or basic unit of morphology) is composed of a node, a leaf, a bud node, an internode and an active meristem at the end. Each time step, the meristem is replaced by a new phytomer, allowing for the development within a branch.
 
 ````julia
 meristem_rule = Rule(TreeTypes.Meristem, rhs = mer -> TreeTypes.Node() +
@@ -152,7 +157,7 @@ function elongate!(tree, query)
 end
 ````
 
-Note that we use `vars` on the `Graph` object to extract the object that was stored inside of it. Also, as this function will modify the graph which is passed as input, we append an `!` to the name (this not a special syntax of the language, its just a convention in the Julia community). Also, in this case, the query object is kept separate from the graph. We could have also stored it inside the graph like we did for the parameter `growth`. We could also have packaged the graph and the query into another type representing an individual TreeTypes. This is entirely up to the user and indicates that a model can be implemented in many differences ways with VPL.
+Note that we use `vars` on the `Graph` object to extract the object that was stored inside of it. Also, as this function will modify the graph which is passed as input, we append an `!` to the name (this not a special syntax of the language, it's just a convention in the Julia community). Also, in this case, the query object is kept separate from the graph. We could have also stored it inside the graph like we did for the parameter `growth`. We could also have packaged the graph and the query into another type representing an individual TreeTypes. This is entirely up to the user and indicates that a model can be implemented in many differences ways with VPL.
 
 Simulating the growth a tree is a matter of elongating the internodes and applying the rules to create new internodes: