Merge branch 'lecture_09' of https://github.com/JuliaTeachingCTU/Scientific-Programming-in-Julia into lecture_09

Author: pevnak

.gitignore

@@ -1,3 +1,9 @@
+*.log
+*.aux
+*.nav
+*.out
+*.snm
+*.toc
 *.swp
 
 /Manifest.toml

docs/make.jl

@@ -83,6 +83,8 @@ lecture_07 = [
 
 lecture_08 = [
     "Lecture" => "./lecture_08/lecture.md"
+    "Lab" => "./lecture_08/lab.md"
+    "Homework" => "./lecture_08/hw.md"
 ]
 
 lecture_09 = [

docs/src/lecture_04/hw.md

@@ -1,4 +1,4 @@
-# Homework 4: More Unit Tests
+# [Homework 4: More Unit Tests](@id hw4)
 
 
 In this homework you will finish writing your unit tests for your `Ecosystem.jl`.

docs/src/lecture_07/hw.md

@@ -1,5 +1,13 @@
 # [Homework 7: Creating world in 3 days/steps](@id hw07)
 
+## How to submit
+Put all the code of inside `hw.jl`. Zip only this file (not its parent folder) and upload it to BRUTE. You should assume that only
+```julia
+using Ecosystem
+using Ecosystem.EcosystemCore
+```
+will be put before your file is executed, but do not include them in your solution. The version of `Ecosystem` pkg and consequently `EcosystemCore` should be the same as in [HW4](@ref hw4).
+
 ```@raw html
 <div class="admonition is-category-homework">
 <header class="admonition-header">Homework (2 points)</header>
@@ -17,7 +25,7 @@ end
 `@add` should not be treated as a macro, but rather just as a syntax, that can be easily matched.
 
 As this is not a small task let's break it into 3 steps
-1. Define method `default_config(::Type{T})` for each `T` in `Grass, Wolf,...`, which returns a tuple of default parameters for that particular agent.
+1. Define method `default_config(::Type{T})` for each `T` in `Grass, Wolf,...`, which returns a named tuple of default parameters for that particular agent (you can choose the default values however you like).
 2. Define method `_add_agents(max_id, count::Int, species::Type{<:Species})` and `_add_agents(max_id, count::Int, species::Type{<:AnimalSpecies}, sex::Type{<:Sex})` that return an array of `count` agents of species `species` with `id` going from `max_id+1` to `max_id+count`. Default parameters should be constructed with `default_config`.
 3. Define the underlying function `_ecosystem(ex)`, which parses the block expression and creates a piece of code that constructs the world.
 

docs/src/lecture_07/lab.md

@@ -1,11 +1,11 @@
 # [Lab 07: Macros](@id macro_lab)
-A little reminder from the lecture, a macro in its essence is a function, which 
+A little reminder from the [lecture](@ref macro_lecture), a macro in its essence is a function, which 
 1. takes as an input an expression (parsed input)
 2. modifies the expressions in arguments
 3. inserts the modified expression at the same place as the one that is parsed.
 
 In this lab we are going to use what we have learned about manipulation of expressions and explore avenues of where macros can be useful
-- convenience (`@repeat n code`, `@show`)
+- convenience (`@repeat`, `@show`)
 - performance critical code generation (`@poly`)
 - alleviate tedious code generation (`@species`, `@eats`)
 - just as a syntactic sugar (`@ecosystem`)
@@ -43,10 +43,10 @@ Testing it gives us the expected behavior
 @myshow xx = 1 + 1
 xx                  # should be defined
 ```
-In this "simple" example, we had to use the following concepts mentioned already in the lecture:
-- `QuoteNode(ex)` is used to wrap the expression inside another layer of quoting, such that when it is interpolated into `:()` it stays being a piece of code instead of the value it represents - **TRUE QUOTING**
-- `esc(ex)` is used in case that the expression contains an assignment, that has to be evaluated in the top level module `Main` (we are `esc`aping the local context) - **ESCAPING**
-- `$(QuoteNode(ex))` and `$(esc(ex))` is used to evaluate an expression into another expression. **INTERPOLATION**
+In this "simple" example, we had to use the following concepts mentioned already in the [lecture](@ref macro_lecture):
+- `QuoteNode(ex)` is used to wrap the expression inside another layer of quoting, such that when it is interpolated into `:()` it stays being a piece of code instead of the value it represents - [**TRUE QUOTING**](@ref lec7_quotation)
+- `esc(ex)` is used in case that the expression contains an assignment, that has to be evaluated in the top level module `Main` (we are `esc`aping the local context) - [**ESCAPING**](@ref lec7_hygiene)
+- `$(QuoteNode(ex))` and `$(esc(ex))` is used to evaluate an expression into another expression. [**INTERPOLATION**](@ref lec7_quotation)
 - `local value = ` is used in order to return back the result after evaluation
 
 Lastly, let's mention that we can use `@macroexpand` to see how the code is manipulated in the `@myshow` macro
@@ -83,7 +83,9 @@ _repeat(3, :(println("Hello!"))) # testing "macro" without defining it
 ```
 
 **HINTS**:
-- use `$` interpolation into a for loop expression
+- use `$` interpolation into a for loop expression; for example given `ex = :(1+x)` we can interpolate it into another expression `:($ex + y)` -> `:(1 + x + y)`
+- if unsure what gets interpolated use round brackets `:($(ex) + y)`
+- macro is a function that *creates* code that does what we want
 
 **BONUS**:
 What happens if we call `@repeat 3 x = 2`? Is `x` defined?
@@ -123,12 +125,14 @@ Ideally we would like write some macro `@poly` that takes a polynomial in a math
 *Example usage*:
 ```julia
 p = @poly x 3x^2+2x^1+10x^0  # the first argument being the independent variable to match
+p(2) # return the value
 ```
 
 However in order to make this happen, let's first consider much simpler case of creating the same but without the need for parsing the polynomial as a whole and employ the fact that macro can have multiple arguments separated by spaces.
 
 ```julia
 p = @poly 3 2 10
+p(2)
 ```
 
 ```@raw html
@@ -138,10 +142,29 @@ p = @poly 3 2 10
 ```
 Create macro `@poly` that takes multiple arguments and creates an anonymous function that constructs the unrolled code. Instead of directly defining the macro inside the macro body, create helper function `_poly` with the same signature that can be reused outside of it.
 
+Recall Horner's method polynomial evaluation from previous [labs](@ref horner):
+```julia
+function polynomial(a, x)
+    accumulator = a[end] * one(x)
+    for i in length(a)-1:-1:1
+        accumulator = accumulator * x + a[i]
+        #= accumulator = muladd(x, accumulator, a[i]) =# # equivalent
+    end
+    accumulator  
+end
+```
+
 **HINTS**:
 - you can use `muladd` function as replacement for `ac * x + a[i]`
-- the expression should be built incrementally by nesting (try to write out the Horner's method[^1] to see it)
-- the order of coefficients has different order than in previous labs
+- think of the `accumulator` variable as the mathematical expression that is incrementally built (try to write out the Horner's method[^1] to see it)
+- you can nest expression arbitrarily
+- the order of coefficients has different order than in previous labs (going from )
+- use `evalpoly` to check the correctness
+```julia
+using Test
+p = @poly 3 2 10
+@test p(2) == evalpoly(2, [10,2,3]) # reversed coefficients
+```
 
 [^1]: Explanation of the Horner schema can be found on [https://en.wikipedia.org/wiki/Horner%27s\_method](https://en.wikipedia.org/wiki/Horner%27s_method).
 ```@raw html
@@ -151,6 +174,7 @@ Create macro `@poly` that takes multiple arguments and creates an anonymous func
 ```
 
 ```@repl lab07_poly
+using InteractiveUtils #hide
 macro poly(a...)
     return _poly(a...)
 end
@@ -182,7 +206,7 @@ Moving on to the first/harder case, where we need to parse the mathematical expr
 ```
 Create macro `@poly` that takes two arguments first one being the independent variable and second one being the polynomial written in mathematical notation. As in the previous case this macro should define an anonymous function that constructs the unrolled code. 
 ```julia
-julia> p = @poly x 3x^2 + 2x^1 + 10x^0  # the first argument being the independent variable to match
+julia> p = @poly x 3x^2+2x^1+10x^0  # the first argument being the independent variable to match
 ```
 
 **HINTS**:
@@ -262,7 +286,6 @@ end
 ```
 Let's test it.
 ```@repl lab07_poly
-using InteractiveUtils #hide
 p = @poly x 3x^2+2x^1+ 10
 p(2) == evalpoly(2, [10,2,3])
 @code_lowered p(2) # can show the generated code
@@ -357,6 +380,9 @@ Unfortunately the current version of `Ecosystem` and `EcosystemCore`, already co
         string.(hcat(["🌍", animal_species...], vcat(permutedims(species), em)))
     end
     eating_matrix()
+     🌍  🐑  🐺  🌿  🍄
+     🐑  ❌  ❌  ✅  ✅
+     🐺  ✅  ❌  ❌  ❌
     ```
 
 ```@raw html
@@ -369,14 +395,24 @@ Based on the following example syntax,
 @species Plant Broccoli 🥦
 @species Animal Rabbit 🐇
 ```
-write macro `@species` inside `Ecosystem` pkg, which defines the abstract type, its show function and exports the type.
-
-Define first helper function `_species` to inspect the macro's output. This is indispensable, as we are defining new types/constants and thus we would otherwise encountered errors during repeated evaluation (though only if the type signature changed).
+write macro `@species` inside `Ecosystem` pkg, which defines the abstract type, its show function and exports the type. For example `@species Plant Broccoli 🥦` should generate code:
+```julia
+abstract type Broccoli <: PlantSpecies end
+Base.show(io::IO,::Type{Broccoli}) = print(io,"🥦")
+export Broccoli
+```
+Define first helper function `_species` to inspect the macro's output. This is indispensable, as we are defining new types/constants and thus we may otherwise encounter errors during repeated evaluation (though only if the type signature changed).
+```julia
+_species(:Plant, :Broccoli, :🥦)
+_species(:Animal, :Rabbit, :🐇)
+```
 
 **HINTS**:
 - use `QuoteNode` in the show function just like in the `@myshow` example
-- ideally these changes should be made inside the modified `Ecosystem` pkg provided in the lab (though not everything can be refreshed with `Revise`)
+- escaping `esc` is needed for the returned in order to evaluate in the top most module (`Ecosystem`/`Main`)
+- ideally these changes should be made inside the modified `Ecosystem` pkg provided in the lab (though not everything can be refreshed with `Revise`) - there is a file `ecosystem_macros.jl` just for this purpose
 - multiple function definitions can be included into a `quote end` block
+- interpolation works with any expression, e.g. `$(typ == :Animal ? AnimalSpecies : PlantSpecies)`
 
 **BONUS**:
 Based on `@species` define also macros `@animal` and `@plant` with two arguments instead of three, where the species type is implicitly carried in the macro's name.
@@ -432,8 +468,9 @@ Define macro `@eats` inside `Ecosystem` pkg that assigns particular species thei
 where `Grass => 0.5` defines the behavior of the `eat!` function. The coefficient is used here as a multiplier for the energy balance, in other words the `Rabbit` should get only `0.5` of energy for a piece of `Grass`.
 
 **HINTS**:
-- ideally these changes should be made inside the modified `Ecosystem` pkg provided in the lab (though not everything can be refreshed with `Revise`)
-- you can create an empty `quote end` block with `code = Expr(:block)` and push new expressions incrementally
+- ideally these changes should be made inside the modified `Ecosystem` pkg provided in the lab (though not everything can be refreshed with `Revise`) - there is a file `ecosystem_macros.jl` just for this purpose
+- escaping `esc` is needed for the returned in order to evaluate in the top most module (`Ecosystem`/`Main`)
+- you can create an empty `quote end` block with `code = Expr(:block)` and push new expressions into its `args` incrementally
 - use dispatch to create specific code for the different combinations of agents eating other agents (there may be catch in that we have to first `eval` the symbols before calling in order to know if they are animals or plants)
 
 !!! note "Reminder of `EcosystemCore` `eat!` and `eats` functionality"
@@ -512,10 +549,10 @@ _eats(species, foodlist)
 ```
 
 ---
-# Resources
+## Resources
 - macros in Julia [documentation](https://docs.julialang.org/en/v1/manual/metaprogramming/#man-macros)
 
-## `Type{T}` type selectors
+### `Type{T}` type selectors
 We have used `::Type{T}` signature[^2] at few places in the `Ecosystem` family of packages (and it will be helpful in the HW as well), such as in the `show` methods
 ```julia
 Base.show(io::IO,::Type{World}) = print(io,"🌍")

docs/src/lecture_07/lecture.md

@@ -164,7 +164,7 @@ end
 
 Observe that macro dispatch is based on the types of AST that are handed to the macro, not the types that the AST evaluates to at runtime.
 
-## Notes on quotation
+## [Notes on quotation](@id lec7_quotation)
 In the previous lecture we have seen that we can *quote a block of code*, which tells the compiler to treat the input as a data and parse it. We have talked about three ways of quoting code.
 1.  `:(quoted code)`
 2. Meta.parse(input_string)
@@ -239,7 +239,7 @@ Instead, when a macro is given an expression with $ in it, it assumes you're goi
 	run(`touch $(filename)`)
 	```
 
-## Macro hygiene
+## [Macro hygiene](@id lec7_hygiene)
 Macro hygiene is a term coined in 1986. The problem it addresses is following: if you're automatically generating code, it's possible that you will introduce variable names in your generated code that will clash with existing variable names in the scope in which a macro is called. These clashes might cause your generated code to read from or write to variables that you should not be interacting with. A macro is hygienic when it does not interact with existing variables, which means that when macro is evaluated, it should not have any effect on the surrounding code. 
 
 By default, all macros in Julia are hygienic which means that variables introduced in the macro have automatically generated names, where Julia ensures they will not collide with user's variable. These variables are created by `gensym` function / macro. 

docs/src/lecture_08/Makefile

@@ -0,0 +1,10 @@
+graphs:
+	pdflatex graphdiff_6.tex
+	pdflatex graphdiff_7.tex
+	pdflatex graphdiff_9.tex
+	pdflatex graphdiff_14.tex
+	pdf2svg graphdiff_6.pdf graphdiff_6.svg
+	pdf2svg graphdiff_7.pdf graphdiff_7.svg
+	pdf2svg graphdiff_9.pdf graphdiff_9.svg
+	pdf2svg graphdiff_14.pdf graphdiff_14.svg
+	rm graphdiff_6.pdf graphdiff_7.pdf graphdiff_9.pdf graphdiff_14.pdf

docs/src/lecture_08/Manifest.toml

@@ -188,6 +188,12 @@ git-tree-sha1 = "8756f9935b7ccc9064c6eef0bff0ad643df733a3"
 uuid = "1a297f60-69ca-5386-bcde-b61e274b549b"
 version = "0.12.7"
 
+[[FiniteDifferences]]
+deps = ["ChainRulesCore", "LinearAlgebra", "Printf", "Random", "Richardson", "StaticArrays"]
+git-tree-sha1 = "c56a261e1a5472f20cbd7aa218840fd203243319"
+uuid = "26cc04aa-876d-5657-8c51-4c34ba976000"
+version = "0.12.19"
+
 [[FixedPointNumbers]]
 deps = ["Statistics"]
 git-tree-sha1 = "335bfdceacc84c5cdf16aadc768aa5ddfc5383cc"
@@ -411,9 +417,9 @@ uuid = "8f399da3-3557-5675-b5ff-fb832c97cbdb"
 
 [[Libffi_jll]]
 deps = ["Artifacts", "JLLWrappers", "Libdl", "Pkg"]
-git-tree-sha1 = "761a393aeccd6aa92ec3515e428c26bf99575b3b"
+git-tree-sha1 = "0b4a5d71f3e5200a7dff793393e09dfc2d874290"
 uuid = "e9f186c6-92d2-5b65-8a66-fee21dc1b490"
-version = "3.2.2+0"
+version = "3.2.2+1"
 
 [[Libgcrypt_jll]]
 deps = ["Artifacts", "JLLWrappers", "Libdl", "Libgpg_error_jll", "Pkg"]
@@ -467,6 +473,13 @@ version = "1.3.5"
 deps = ["Libdl"]
 uuid = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"
 
+
+[[LittleCMS_jll]]
+deps = ["Artifacts", "JLLWrappers", "JpegTurbo_jll", "Libdl", "Libtiff_jll", "Pkg"]
+git-tree-sha1 = "110897e7db2d6836be22c18bffd9422218ee6284"
+uuid = "d3a379c0-f9a3-5b72-a4c0-6bf4d2e8af0f"
+version = "2.12.0+0"
+
 [[LogExpFunctions]]
 deps = ["ChainRulesCore", "ChangesOfVariables", "DocStringExtensions", "InverseFunctions", "IrrationalConstants", "LinearAlgebra"]
 git-tree-sha1 = "be9eef9f9d78cecb6f262f3c10da151a6c5ab827"
@@ -539,6 +552,13 @@ git-tree-sha1 = "7937eda4681660b4d6aeeecc2f7e1c81c8ee4e2f"
 uuid = "e7412a2a-1a6e-54c0-be00-318e2571c051"
 version = "1.3.5+0"
 
+
+[[OpenJpeg_jll]]
+deps = ["Artifacts", "JLLWrappers", "Libdl", "Libtiff_jll", "LittleCMS_jll", "Pkg", "libpng_jll"]
+git-tree-sha1 = "76374b6e7f632c130e78100b166e5a48464256f8"
+uuid = "643b3616-a352-519d-856d-80112ee9badc"
+version = "2.4.0+0"
+
 [[OpenLibm_jll]]
 deps = ["Artifacts", "Libdl"]
 uuid = "05823500-19ac-5b8b-9628-191a04bc5112"
@@ -606,6 +626,13 @@ git-tree-sha1 = "0d185e8c33401084cab546a756b387b15f76720c"
 uuid = "91a5bcdd-55d7-5caf-9e0b-520d859cae80"
 version = "1.23.6"
 
+
+[[Poppler_jll]]
+deps = ["Artifacts", "Cairo_jll", "Fontconfig_jll", "Glib_jll", "JLLWrappers", "JpegTurbo_jll", "Libdl", "Libtiff_jll", "OpenJpeg_jll", "Pkg", "libpng_jll"]
+git-tree-sha1 = "e11443687ac151ac6ef6699eb75f964bed8e1faa"
+uuid = "9c32591e-4766-534b-9725-b71a8799265b"
+version = "0.87.0+2"
+
 [[Preferences]]
 deps = ["TOML"]
 git-tree-sha1 = "00cfd92944ca9c760982747e9a1d0d5d86ab1e5a"
@@ -664,6 +691,13 @@ git-tree-sha1 = "4036a3bd08ac7e968e27c203d45f5fff15020621"
 uuid = "ae029012-a4dd-5104-9daa-d747884805df"
 version = "1.1.3"
 
+
+[[Richardson]]
+deps = ["LinearAlgebra"]
+git-tree-sha1 = "e03ca566bec93f8a3aeb059c8ef102f268a38949"
+uuid = "708f8203-808e-40c0-ba2d-98a6953ed40d"
+version = "1.4.0"
+
 [[SHA]]
 uuid = "ea8e919c-243c-51af-8825-aaa63cd721ce"
 
@@ -758,10 +792,30 @@ version = "1.6.0"
 deps = ["ArgTools", "SHA"]
 uuid = "a4e569a6-e804-4fa4-b0f3-eef7a1d5b13e"
 
+
+[[Tectonic]]
+deps = ["Pkg"]
+git-tree-sha1 = "acf12eccb390a78653ee805cd527898f01f78a85"
+uuid = "9ac5f52a-99c6-489f-af81-462ef484790f"
+version = "0.6.1"
+
 [[Test]]
 deps = ["InteractiveUtils", "Logging", "Random", "Serialization"]
 uuid = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
 
+
+[[TikzGraphs]]
+deps = ["LaTeXStrings", "LightGraphs", "TikzPictures"]
+git-tree-sha1 = "48932ba660bc8cefc0aa9519ba79d63082aea892"
+uuid = "b4f28e30-c73f-5eaf-a395-8a9db949a742"
+version = "1.2.0"
+
+[[TikzPictures]]
+deps = ["LaTeXStrings", "Poppler_jll", "Requires", "Tectonic"]
+git-tree-sha1 = "a08671c0979063a437378f6410bb75a465f3cd1c"
+uuid = "37f6aa50-8035-52d0-81c2-5a1d08754b2d"
+version = "3.4.1"
+
 [[URIs]]
 git-tree-sha1 = "97bbe755a53fe859669cd907f2d96aee8d2c1355"
 uuid = "5c2747f8-b7ea-4ff2-ba2e-563bfd36b1d4"

docs/src/lecture_08/Project.toml

@@ -1,6 +1,9 @@
 [deps]
 ChainRules = "082447d4-558c-5d27-93f4-14fc19e9eca2"
+FiniteDifferences = "26cc04aa-876d-5657-8c51-4c34ba976000"
 GraphRecipes = "bd48cda9-67a9-57be-86fa-5b3c104eda73"
 LightGraphs = "093fc24a-ae57-5d10-9952-331d41423f4d"
 Plots = "91a5bcdd-55d7-5caf-9e0b-520d859cae80"
+TikzGraphs = "b4f28e30-c73f-5eaf-a395-8a9db949a742"
+TikzPictures = "37f6aa50-8035-52d0-81c2-5a1d08754b2d"
 Zygote = "e88e6eb3-aa80-5325-afca-941959d7151f"