Preview for 1.8 release (#208)

* Update to julia by examples to make 1.7 oriented and fix plotting

* Added 1.7 material for the essentials

* Updates on style guides

* Added additional kwarg trick

* Cleanup on geometric series

Co-authored-by: James Yu <[email protected]>

Author: jlperla

lectures/dynamic_programming/mccall_model.md

@@ -291,7 +291,8 @@ generates a sequence that converges to the fixed point.
 tags: [hide-output]
 ---
 using LinearAlgebra, Statistics
-using Distributions, Expectations, LaTeXStrings, NLsolve, Roots, Random, Plots, Parameters
+using Distributions, Expectations, LaTeXStrings
+using NLsolve, Roots, Random, Plots, Parameters
 ```
 
 ```{code-cell} julia
@@ -314,7 +315,8 @@ dist = BetaBinomial(n, 200, 100) # probability distribution
 w = range(10.0, 60.0, length = n+1) # linearly space wages
 
 using StatsPlots
-plt = plot(w, pdf.(dist, support(dist)), xlabel = "wages", ylabel = "probabilities", legend = false)
+plt = plot(w, pdf.(dist, support(dist)), xlabel = "wages",
+           ylabel = "probabilities", legend = false)
 ```
 
 We can explore taking expectations over this distribution
@@ -367,22 +369,22 @@ One approach to solving the model is to directly implement this sort of iteratio
 between successive iterates is below tol
 
 ```{code-cell} julia
-function compute_reservation_wage_direct(params; v_iv = collect(w ./(1-β)), max_iter = 500,
-                                         tol = 1e-6)
+function compute_reservation_wage_direct(params; v_iv = collect(w ./(1-β)),
+                                         max_iter = 500, tol = 1e-6)
     (;c, β, w) = params
 
     # create a closure for the T operator
     T(v) = max.(w/(1 - β), c + β * E*v) # (5) fixing the parameter values
 
-    v = copy(v_iv) # start at initial value.  copy to prevent v_iv modification
+    v = copy(v_iv) # copy to prevent v_iv modification
     v_next = similar(v)
     i = 0
     error = Inf
     while i < max_iter && error > tol
         v_next .= T(v) # (4)
         error = norm(v_next - v)
         i += 1
-        v .= v_next  # copy contents into v.  Also could have used v[:] = v_next
+        v .= v_next  # copy contents into v
     end
     # now compute the reservation wage
     return (1 - β) * (c + β * E*v) # (2)
@@ -406,17 +408,22 @@ As usual, we are better off using a package, which may give a better algorithm a
 In this case, we can use the `fixedpoint` algorithm discussed in {doc}`our Julia by Example lecture <../getting_started_julia/julia_by_example>`  to find the fixed point of the $T$ operator.  Note that below we set the parameter `m=1` for Anderson iteration rather than leaving as the default value - which fails to converge in this case.  This is still almost 10x faster than the `m=0` case, which corresponds to naive fixed-point iteration.
 
 ```{code-cell} julia
-function compute_reservation_wage(params; v_iv = collect(w ./(1-β)), iterations = 500,
-                                  ftol = 1e-6, m = 6)
+function compute_reservation_wage(params; v_iv = collect(w ./(1-β)),
+                                  iterations = 500, ftol = 1e-6, m = 1)
     (;c, β, w) = params
     T(v) = max.(w/(1 - β), c + β * E*v) # (5) fixing the parameter values
 
-    v_star = fixedpoint(T, v_iv, iterations = iterations, ftol = ftol,
-                        m = 1).zero # (5)
+    sol = fixedpoint(T, v_iv; iterations, ftol, m) # (5)
+    sol.f_converged || error("Failed to converge")
+    v_star = sol.zero
     return (1 - β) * (c + β * E*v_star) # (3)
 end
 ```
 
+Note that this checks the convergence (i.e, the `sol.f_converged`) from the fixedpoint iteration and throws an error if it fails.
+
+This coding pattern, where `expression || error("failure)` first checks the expression is true and then moves to the right hand side of the `||` or operator if it is false, is a common pattern in Julia.
+
 Let's compute the reservation wage at the default parameters
 
 ```{code-cell} julia
@@ -430,8 +437,8 @@ compute_reservation_wage(mcm()) # call with default parameters
 tags: [remove-cell]
 ---
 @testset "Reservation Wage Tests" begin
-    #test compute_reservation_wage(mcm()) ≈ 47.316499766546215
-    #test compute_reservation_wage_direct(mcm()) ≈ 47.31649975736077
+    @test compute_reservation_wage(mcm()) ≈ 47.316499766546215
+    @test compute_reservation_wage_direct(mcm()) ≈ 47.31649975736077
 end
 ```
 
@@ -445,24 +452,32 @@ $c$.
 
 ```{code-cell} julia
 grid_size = 25
-R = rand(grid_size, grid_size)
+R = zeros(grid_size, grid_size)
 
 c_vals = range(10.0, 30.0, length = grid_size)
 β_vals = range(0.9, 0.99, length = grid_size)
 
 for (i, c) in enumerate(c_vals)
     for (j, β) in enumerate(β_vals)
-        R[i, j] = compute_reservation_wage(mcm(c=c, β=β)) # change from defaults
+        R[i, j] = compute_reservation_wage(mcm(;c, β);m=0)
     end
 end
 ```
 
+Note the above is setting the `m` parameter to `0` to use naive fixed-point iteration.  This is because the Anderson iteration fails to converge in a 2 of the 25^2 cases.
+
+This demonstrates care must be used with advanced algorithms, and checking the return type (i.e., the `sol.f_converged` field) is important.
+
+
+
 ```{code-cell} julia
 ---
 tags: [remove-cell]
 ---
 @testset "Comparative Statics Tests" begin
-    #test R[4, 4] ≈ 41.15851842606614 # arbitrary reservation wage.
+    @test minimum(R) ≈ 40.39579058732559
+    @test maximum(R) ≈ 47.69960582438523
+    @test R[4, 4] ≈ 41.15851842606614 # arbitrary reservation wage.
     @test grid_size == 25 # grid invariance.
     @test length(c_vals) == grid_size && c_vals[1] ≈ 10.0 && c_vals[end] ≈ 30.0
     @test length(β_vals) == grid_size && β_vals[1] ≈ 0.9 && β_vals[end] ≈ 0.99
@@ -559,11 +574,13 @@ The big difference here, however, is that we're iterating on a single number, ra
 Here's an implementation:
 
 ```{code-cell} julia
-function compute_reservation_wage_ψ(c, β; ψ_iv = E * w ./ (1 - β), max_iter = 500,
-                                    tol = 1e-5)
+function compute_reservation_wage_ψ(c, β; ψ_iv = E * w ./ (1 - β),
+                                    iterations = 500, ftol = 1e-5, m = 1)
     T_ψ(ψ) = [c + β * E*max.((w ./ (1 - β)), ψ[1])] # (7)
     # using vectors since fixedpoint doesn't support scalar
-    ψ_star = fixedpoint(T_ψ, [ψ_iv]).zero[1]
+    sol = fixedpoint(T_ψ, [ψ_iv]; iterations, ftol, m)
+    sol.f_converged || error("Failed to converge")    
+    ψ_star = sol.zero[1]
     return (1 - β) * ψ_star # (2)
 end
 compute_reservation_wage_ψ(c, β)
@@ -574,10 +591,10 @@ You can use this code to solve the exercise below.
 Another option is to solve for the root of the  $T_{\psi}(\psi) - \psi$ equation
 
 ```{code-cell} julia
-function compute_reservation_wage_ψ2(c, β; ψ_iv = E * w ./ (1 - β), max_iter = 500,
-                                     tol = 1e-5)
+function compute_reservation_wage_ψ2(c, β; ψ_iv = E * w ./ (1 - β),
+                                     maxiters = 500, rtol = 1e-5)
     root_ψ(ψ) = c + β * E*max.((w ./ (1 - β)), ψ) - ψ # (7)
-    ψ_star = find_zero(root_ψ, ψ_iv)
+    ψ_star = find_zero(root_ψ, ψ_iv;maxiters, rtol)
     return (1 - β) * ψ_star # (2)
 end
 compute_reservation_wage_ψ2(c, β)
@@ -589,9 +606,9 @@ tags: [remove-cell]
 ---
 @testset begin
     mcmp = mcm()
-    #test compute_reservation_wage(mcmp) ≈ 47.316499766546215
-    #test compute_reservation_wage_ψ(mcmp.c, mcmp.β) ≈ 47.31649976654623
-    #test compute_reservation_wage_ψ2(mcmp.c, mcmp.β) ≈ 47.31649976654623
+    @test compute_reservation_wage(mcmp) ≈ 47.316499766546215
+    @test compute_reservation_wage_ψ(mcmp.c, mcmp.β) ≈ 47.31649976654623
+    @test compute_reservation_wage_ψ2(mcmp.c, mcmp.β) ≈ 47.31649976654623
 end
 ```
 

lectures/getting_started_julia/fundamental_types.md

@@ -234,7 +234,7 @@ x = [1, 2, 3]
 y = similar(x, 2, 2)  # make a 2x2 matrix
 ```
 
-#### Manual Array Definitions
+#### Array Definitions from Literals
 
 As we've seen, you can create one dimensional arrays from manually specified data like so
 
@@ -276,6 +276,39 @@ a = [10 20 30 40]'
 ndims(a)
 ```
 
+Note, however, that the transformed array is not a matrix but rather a special type (e.g., `adjoint(::Matrix{Int64}) with eltype Int64`).
+
+Keeping the special structure of a transposed array can let Julia use more efficient algorithms in some cases.
+
+Finally, we can see how to create multidimensional arrays from literals with the `;` separator.
+
+First, we can create a vector
+
+```{code-cell} julia
+[1; 2;]
+```
+
+Next, by appending an additional `;` we can tell it to use a 2 dimensional array
+
+```{code-cell} julia
+[1; 2;;]
+``` 
+
+Or 3 dimensions
+```{code-cell} julia
+[1; 2;;;]
+``` 
+
+Or a 1x1 matrix with a single value
+```{code-cell} julia
+[1;;]
+```
+
+Or a 2x2x1 array
+```{code-cell} julia
+[1 2; 3 4;;;]
+```
+
 ### Array Indexing
 
 We've already seen the basics of array indexing
@@ -522,7 +555,7 @@ val = [1, 2]
 y = similar(val)
 
 function f!(out, x)
-    out = [1 2; 3 4] * x   # MISTAKE! Should be .= or [:]
+    out = [1 2; 3 4] * x   # MISTAKE! Should be .=
 end
 f!(y, val)
 y
@@ -950,28 +983,29 @@ println("a = $a and b = $b")
 As well as **named tuples**, which extend tuples with names for each argument.
 
 ```{code-cell} julia
-t = (val1 = 1.0, val2 = "test")
+t = (;val1 = 1.0, val2 = "test") # ; is optional but good form
 t.val1      # access by index
-# a, b = t  # bad style, better to unpack by name
-println("val1 = $(t.val1) and val1 = $(t.val1)") # access by name
+println("val1 = $(t.val1) and val2 = $(t.val2)") # access by name
+(;val1, val2) = t  # unpacking notation (note the ;)
+println("val1 = $val1 and val2 = $val2")
 ```
 
 While immutable, it is possible to manipulate tuples and generate new ones
 
 ```{code-cell} julia
-t2 = (val3 = 4, val4 = "test!!")
+t2 = (;val3 = 4, val4 = "test!!")
 t3 = merge(t, t2)  # new tuple
 ```
 
 Named tuples are a convenient and high-performance way to manage and unpack sets of parameters
 
 ```{code-cell} julia
 function f(parameters)
-    α, β = parameters.α, parameters.β  # poor style, error prone if adding parameters
+    α, β = parameters.α, parameters.β # poor style, error prone
     return α + β
 end
 
-parameters = (α = 0.1, β = 0.2)
+parameters = (;α = 0.1, β = 0.2)
 f(parameters)
 ```
 
@@ -983,7 +1017,7 @@ function f(parameters)
     return α + β
 end
 
-parameters = (α = 0.1, β = 0.2)
+parameters = (;α = 0.1, β = 0.2)
 f(parameters)
 ```
 
@@ -999,6 +1033,15 @@ paramgen = @with_kw (α = 0.1, β = 0.2)  # create named tuples with defaults
 @show paramgen(α = 0.2, β = 0.5);
 ```
 
+Or create a function which returns the named tuple with defaults, which can also do intermediate calculations
+```{code-cell} julia
+function paramgen2(;α = 0.1, β = 0.2)
+    return (;α, β)
+end
+@show paramgen2()
+@show paramgen2(;α = 0.2)
+```
+
 An alternative approach, defining a new type using `struct` tends to be more prone to accidental misuse, and leads to a great deal of boilerplate code.
 
 For that, and other reasons of generality, we will use named tuples for collections of parameters where possible.

lectures/getting_started_julia/introduction_to_types.md

@@ -669,10 +669,9 @@ This is just one of many decisions and patterns to ensure that your code is cons
 
 The best resource is to carefully read other peoples code, but a few sources to review are
 
-* [Julia Style Guide](https://docs.julialang.org/en/v1/manual/style-guide/).
-* [Invenia Blue Style Guide](https://github.com/invenia/BlueStyle).
-* [Julia Praxis Naming Guides](https://github.com/JuliaPraxis/Naming/tree/master/guides).
-* [QuantEcon Style Guide](https://github.com/QuantEcon/lecture-source-jl/blob/master/style.md) used in these lectures.
+* [Julia Style Guide](https://docs.julialang.org/en/v1/manual/style-guide/)
+* [SciML Style Guide](https://github.com/SciML/SciMLStyle)
+* [Blue Style Guide](https://github.com/invenia/BlueStyle)
 
 Now why would we emphasize naming and style as a crucial part of the lectures?
 
@@ -693,6 +692,9 @@ Some helpful ways to think about this are
   For example, if you change notation in your model, then immediately update
   all variables in the code to reflect it.
 
+
+While variable naming takes discipline, code formatting for a specific style guide can be automated using [JuliaFormatter.jl](https://github.com/domluna/JuliaFormatter.jl) which is built into the Julia VS Code extension.
+
 #### Commenting Code
 
 One common mistake people make when trying to apply these goals is to add in a large number of comments.