Turn off code execution

Author: AleMorales

docs/src/howto/Materials.md

@@ -1,12 +1,19 @@
 
 
-````@example Forest
-#= Forest
+# Forest
 
-Alejandro Morales
+Alejandro Morales & Ana Ernst
 
 Centre for Crop Systems Analysis - Wageningen University
 
+> ## TL;DR
+> Similar in functionality to [Tree](https://virtualplantlab.com/dev/tutorials/from_tree_forest/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.
@@ -15,7 +22,7 @@ This tutorial requires using the Distributions.jl package:
 The data types, rendering methods and growth rules are the same as in the binary
 tree example:
 
-=#
+```julia
 using VirtualPlantLab
 using Distributions, Plots, ColorTypes
 import GLMakie
@@ -104,7 +111,7 @@ end
 branch_rule = Rule(TreeTypes.Bud,
             lhs = prob_break,
             rhs = bud -> TreeTypes.BudNode() + TreeTypes.Internode() + TreeTypes.Meristem())
-````
+```
 
 The main difference with respect to the tree is that several of the parameters
 will vary per TreeTypes. Also, the location of the tree and initial orientation of
@@ -116,19 +123,19 @@ of each tree and rotates it.
 (ii) Wrap the axiom, rules and the creation of the graph into a function that
 takes the required parameters as inputs.
 
-````@example Forest
+```julia
 function create_tree(origin, growth, budbreak, orientation)
     axiom = T(origin) + RH(orientation) + TreeTypes.Internode() + TreeTypes.Meristem()
     tree =  Graph(axiom = axiom, rules = (meristem_rule, branch_rule),
                   data = TreeTypes.treeparams(growth = growth, budbreak = budbreak))
     return tree
 end
-````
+```
 
 The code for elongating the internodes to simulate growth remains the same as for
 the binary tree example
 
-````@example Forest
+```julia
 getInternode = Query(TreeTypes.Internode)
 
 function elongate!(tree, query)
@@ -149,53 +156,53 @@ function simulate(tree, query, nsteps)
     end
     return new_tree
 end
-````
+```
 
 Let's simulate a forest of 10 x 10 trees with a distance between (and within) rows
 of 2 meters. First we generate the original positions of the trees. For the
 position we just need to pass a `Vec` object with the x, y, and z coordinates of
 the location of each TreeTypes. The code below will generate a matrix with the coordinates:
 
-````@example Forest
+```julia
 origins = [Vec(i,j,0) for i = 1:2.0:20.0, j = 1:2.0:20.0]
-````
+```
 
 We may assume that the initial orientation is uniformly distributed between 0 and 360 degrees:
 
-````@example Forest
+```julia
 orientations = [rand()*360.0 for i = 1:2.0:20.0, j = 1:2.0:20.0]
-````
+```
 
 For the `growth` and `budbreak` parameters we will assumed that they follow a
 LogNormal and Beta distribution, respectively. We can generate random
 values from these distributions using the `Distributions` package. For the
 relative growth rate:
 
-````@example Forest
+```julia
 growths = rand(LogNormal(-2, 0.3), 10, 10)
 histogram(vec(growths))
 savefig("growths.png") ## hide
-````
+```
 
 ![](growths.png)
 
 And for the budbreak parameter:
 
-````@example Forest
+```julia
 budbreaks = rand(Beta(2.0, 10), 10, 10)
 histogram(vec(budbreaks))
 savefig("budbreaks.png") ## hide
-````
+```
 
 ![](budbreaks.png)
 
 Now we can create our forest by calling the `create_tree` function we defined earlier
 with the correct inputs per tree:
 
-````@example Forest
+```julia
 forest = vec(create_tree.(origins, growths, budbreaks, orientations));
 nothing #hide
-````
+```
 
 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
@@ -210,29 +217,29 @@ as you may need to change some settings in your computer).
 We can simulate the growth of each tree by applying the method `simulate` to each
 tree, creating a new version of the forest (the code below is an array comprehension)
 
-````@example Forest
+```julia
 newforest = [simulate(tree, getInternode, 2) for tree in forest];
 nothing #hide
-````
+```
 
 And we can render the forest with the function `render` as in the binary tree
 example but passing the whole forest at once
 
-````@example Forest
+```julia
 pl = render(Scene(newforest))
 GLMakie.save("newforest1.png", pl) ## hide
-````
+```
 
 ![](newforest1.png)
 
 If we iterate 4 more iterations we will start seeing the different individuals
 diverging in size due to the differences in growth rates
 
-````@example Forest
+```julia
 newforest = [simulate(tree, getInternode, 15) for tree in newforest];
 pl = render(Scene(newforest))
 GLMakie.save("newforest2.png", pl) ## hide
-````
+```
 
 ![](newforest2.png)
 
@@ -245,21 +252,21 @@ and execute the iterations of the loop in multiple threads using the macro `@thr
 Note that the rendering function can also be ran in parallel (i.e. the geometry will be
 generated separately for each plant and the merge together):
 
-````@example Forest
+```julia
 using Base.Threads
 newforest = deepcopy(forest)
 @threads for i in 1:length(forest)
     newforest[i] = simulate(forest[i], getInternode, 6)
 end
 pl = render(Scene(newforest, parallel = true))
 GLMakie.save("newforest3.png", pl) ## hide
-````
+```
 
 ![](newforest3.png)
 
 An alternative way to perform the simulation is to have an outer loop for each timestep and an internal loop over the different trees. Although this approach is not required for this simple model, most FSP models will probably need such a scheme as growth of each individual plant will depend on competition for resources with neighbouring plants. In this case, this approach would look as follows:
 
-````@example Forest
+```julia
 newforest = deepcopy(forest)
 for step in 1:15
     @threads for i in 1:length(newforest)
@@ -268,7 +275,7 @@ for step in 1:15
 end
 pl = render(Scene(newforest, parallel = true))
 GLMakie.save("newforest4.png", pl) ## hide
-````
+```
 
 ![](newforest4.png)
 
@@ -279,10 +286,10 @@ tweaking the 3D representation. When we want to combine plants generated from gr
 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:
 
-````@example Forest
+```julia
 scene = Scene(newforest);
 nothing #hide
-````
+```
 
 We can create the soil tile directly, without having to create a graph. The simplest approach is two use
 a special constructor `Rectangle` where one species a corner of the rectangle and two vectors defining the
@@ -292,28 +299,28 @@ above when we determined the origin of each plant. VPL offers some shortcuts: `O
 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:
 
-````@example Forest
+```julia
 soil = Rectangle(length = 21.0, width = 21.0)
 rotatey!(soil, pi/2)
 VirtualPlantLab.translate!(soil, Vec(0.0, 10.5, 0.0))
-````
+```
 
 We can now add the `soil` to the `scene` object with the `add!` function.
 
-````@example Forest
+```julia
 VirtualPlantLab.add!(scene, mesh = soil, colors = 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
 `axes = false`:
 
-````@example Forest
+```julia
 pl = render(scene, axes = false)
 GLMakie.save("newforest5.png", pl) ## hide
-````
+```
 
 ![](newforest5.png)
 
@@ -323,11 +330,11 @@ we can run the `save_scene` function on the object returned from `render`. The a
 `render` to increase the number of pixels in the final image. A helper function `calculate_resolution` is provided to
 compute the resolution from a physical width and height in cm and a dpi (e.g., useful for publications and posters):
 
-````@example Forest
+```julia
 res = calculate_resolution(width = 16.0, height = 16.0, dpi = 1_000)
 output = render(scene, axes = false, size = res)
 export_scene(scene = output, filename = "nice_trees.png")
-````
+```
 
 ---