Merge pull request #77 from QuantEcon/caching

jlperla · web-flow · commit 93125a5f6d93 · 2021-08-18T14:42:59.000-07:00
Caching for inplace stuff
diff --git a/lectures/software_engineering/tools_editors.md b/lectures/software_engineering/tools_editors.md
@@ -18,26 +18,72 @@ kernelspec:
 </div>
 ```
 
-# Julia Tools and Editors
+# Visual Studio Code and other Julia Tools
 
 ```{contents} Contents
 :depth: 2
 ```
 
-Co-authored with Arnav Sood
+While Jupyter notebooks are a great way to get started with the language, eventually you will want to use more powerful tools.  Visual Studio Code (VS Code) in particular, is the most popular open source editor for programming, and has a huge set of extensions and strong industry support.
 
-While Jupyter notebooks are a great way to get started with the language, eventually you will want to use more powerful tools.
+While you can use source code control, run terminals/REPLs, without VS Code, we will concentrate on using it as a full IDE for all of these features.
 
-We'll discuss a few of them here, such as
+## Installing VS Code
 
-* Text editors like Atom, which come with rich Julia support for debugging, documentation, git integration, plotting and inspecting data, and code execution.
-* The Julia REPL, which has specialized modes for package management, shell commands, and help.
+To install VS Code and the Julia Extension,
+
+1. Follow the instructions for setting up Julia {ref}`on your local computer <jl_jupyterlocal>`.
+2. Install [VS Code](https://code.visualstudio.com/) for your platform and open it
+3. Install the [VS Code Julia](https://marketplace.visualstudio.com/items?itemName=julialang.language-julia) extension
+   - After installation of VS Code, you should be able to choose `Install` on the webpage of any extensions and it will open on your desktop.
+   - Otherwise, open the extensions with `<Ctrl-Shift-X>` or selecting extensions in the left-hand side of the VS Code window.  Then search for `Julia` in the Marketplace
+
+See the [Julia VS Code Documentation](https://www.julia-vscode.org/docs/dev/gettingstarted/#Installation-and-Configuration-1) for more details.
+
+If you have done a typical Julia installation, then this may be all that is needed and no configuration may be necessary.  However, if you have installed Julia in a non-standard location you may need to manually set the executable path.  See [here](https://www.julia-vscode.org/docs/dev/gettingstarted/#Configuring-the-Julia-extension-1) for instructions if it errors when starting Julia terminals.
+
+### Optional Extensions
+
+While not required for these lectures, consider installing the following extensions.  As before, you can search for them on the Marketplace or choose `Install` from the webpages themselves.
+
+1. [Jupyter](https://marketplace.visualstudio.com/items?itemName=ms-toolsai.jupyter): VS Code increasingly supports Jupyter notebooks directly, and this extension provides the ability to open and edit `.ipynb` notebook files wihtout running `jupyter lab`, etc.
+1. [GitLens](https://marketplace.visualstudio.com/items?itemName=eamodio.gitlens): An extension that provides an enormous amount of detail on exact code changes within github repositories (e.g., seamless information on the time and individual who [last modified](https://marketplace.visualstudio.com/items?itemName=eamodio.gitlens#current-line-blame-) each line of code)
+2. [GitHub Pull Requests and Issues](https://marketplace.visualstudio.com/items?itemName=GitHub.vscode-pull-request-github): while VS Code supports the git {doc}`version control <../software_engineering/version_control>` natively, these extension provides additional features for working with repositories on GitHub itself.
+3. [Markdown All in One](https://marketplace.visualstudio.com/items?itemName=yzhang.markdown-all-in-one): For editing the markdown format, such as `README.md` and similar files.
+4. Finally, VS Code is an excellent latex editor.  To install support,
+   - Install a recent version of miktex or texlive for your platform
+   - Install [LaTeX Workshop](https://marketplace.visualstudio.com/items?itemName=James-Yu.latex-workshop)
+   - Optionally install [Code Spell Checker](https://marketplace.visualstudio.com/items?itemName=streetsidesoftware.code-spell-checker) for spell checking
+   - See [documentation](https://github.com/James-Yu/LaTeX-Workshop#manual). The easiest use is to put the magic comment `!TEX program = pdflatex` at the top of a `.tex` file.
+   - 
+
+
+See the [VS Code documentation](https://code.visualstudio.com/docs/getstarted/userinterface) for an introduction.  
+
+A key feature is the [Command Palette](https://code.visualstudio.com/docs/getstarted/userinterface#_command-palette), which can be accessed with `<Ctrl+Shift+P>`.
+
+```{figure} [/_static/figures/juno-standard-layout.png](https://code.visualstudio.com/assets/docs/getstarted/userinterface/commands.png)
+:width: 50%
+```
+
+With this, you can type partial strings for different commands and it helps you to find features of vscode and its extensions.  This is so common that in these notes we
+denote opening the command palette and searching for a command with things like `> Julia: Start REPL` , etc.  You will only need to type part of the string, and the command palette remembers
+your most commonly used 
+
+
+### Optional Extensions and Settings 
+
+
+Open the settings, either with `> Preferences: User Settings` (recall this can be found with the palette and `<Ctrl-Shift-P>`) or with the menu.
+
+As a few optional suggestions for working with the settings,
+
+- In the settings, search for `Tab Size` and you should find `Editor: Tab Size` which you can modify to 4.
+- Search for `quick open` and change `Workbench > Editor: Enable Preview from Quick Open` and consider setting it to false, though this is a matter of personal taste.
+- Finally, if you are on Windows, search for `eol` and change `Files: Eol` to be `\n`.
 
-Note that we assume you've already completed the {doc}`getting started <../getting_started_julia/getting_started>` and {doc}`interacting with Julia <../getting_started_julia/julia_environment>` lectures.
 
-## Preliminary Setup
 
-Follow the instructions for setting up Julia {ref}`on your local computer <jl_jupyterlocal>`.
 
 (repl_main)=
 ## The REPL
@@ -120,72 +166,6 @@ The most feature-rich one for Julia development is [Atom](https://atom.io/), wit
 
 There are several reasons to use a text editor like Atom, including
 
-* Git integration (more on this in the {doc}`next lecture <../software_engineering/version_control>`).
-* Painless inspection of variables and data.
-* Easily run code blocks, and drop in custom snippets of code.
-* Integration with Julia documentation and plots.
-
-### Installation and Configuration
-
-#### Installing Atom
-
-1. Download and Install Atom from the [Atom website](https://atom.io/).
-1. (Optional, but recommended): Change default Atom settings
-    * Use `Ctrl-,` to get the `Settings` pane
-    * Choose the `Packages` tab
-    * Type `line-ending-selector` into the Filter and then click "Settings" for that package
-        * Change the default line ending to `LF` (only necessary on Windows)
-    * Choose the Editor tab
-        * Turn on `Soft Wrap`
-        * Set the `Tab Length` default to `4`
-
-#### Installing Juno
-
-1. Use `Ctrl-,` to get the Settings pane.
-1. Go to the `Install` tab.
-1. Type `uber-juno` into the search box and then click Install on the package that appears.
-1. Wait while Juno installs dependencies.
-1. When it asks you whether or not to use the standard layout, click `yes`.
-
-At that point, you should see a built-in REPL at the bottom of the screen and be able to start using Julia and Atom.
-
-(atom_troubleshooting)=
-#### Troubleshooting
-
-Sometimes, Juno will fail to find the Julia executable (say, if it's installed somewhere nonstandard, or you have multiple).
-
-To do this
-1. `Ctrl-,` to get Settings pane, and select the Packages tab.
-2. Type in `julia-client` and choose Settings.
-3. Find the Julia Path, and fill it in with the location of the Julia binary.
-
-* To find the binary, you could run `Sys.BINDIR` in the REPL, then add in an additional `/julia` to the end of the screen.
-* e.g. `C:\Users\YOURUSERNAME\AppData\Local\Julia-1.0.1\bin\julia.exe` on Windows as `/Applications/Julia-1.0.app/Contents/Resources/julia/bin/julia` on OSX.
-
-> 
-
-See the [setup instructions for Juno](http://docs.junolab.org/latest/man/installation.html)  if you have further issues.
-
-If you upgrade Atom and it breaks Juno, run the following in a terminal.
-
-```{code-block} none
-apm uninstall ink julia-client
-apm install ink julia-client
-```
-
-If you aren't able to install `apm` in your PATH, you can do the above by running the following in PowerShell:
-
-```{code-block} none
-cd $ENV:LOCALAPPDATA/atom/bin
-```
-
-Then navigating to a folder like `C:\Users\USERNAME\AppData\Local\atom\bin` (which will contain the `apm` tool), and running:
-
-```{code-block} none
-./apm uninstall ink julia-client
-./apm install ink julia-client
-```
-
 (upgrading_julia)=
 #### Upgrading Julia
 
diff --git a/lectures/tools_and_techniques/numerical_linear_algebra.md b/lectures/tools_and_techniques/numerical_linear_algebra.md
@@ -54,7 +54,7 @@ The theme of this lecture, and numerical linear algebra in general, comes down t
 ---
 tags: [hide-output]
 ---
-using LinearAlgebra, Statistics, BenchmarkTools, SparseArrays, Random
+using LinearAlgebra, Statistics, BenchmarkTools, SparseArrays, Random, Parameters
 Random.seed!(42);  # seed random numbers for reproducibility
 ```
 
@@ -980,6 +980,78 @@ A[2,1] = 100.0
 But again, you will often find that doing `@view` leads to slower code.  Benchmark
 instead, and generally rely on it for large matrices and for contiguous chunks of memory (e.g., columns rather than rows).
 
+## Patterns for Preallocated Caches of Results
+
+When the matrices and vectors get large, it can reach a point where it is important to cache the results and reduce allocations.  In general, this should only be attempted when the vectors are large and they would otherwise need to be reallocated many times.
+
+One approach is to create a {doc}`custom type<../getting_started_julia/introduction_to_types>` to hold the results, being very careful to ensure that the type is concrete.
+
+
+```{code-cell} julia
+struct MyResults{T}
+    x::Array{T,1}
+    A::Array{T,2}
+end
+MyResults(N) = MyResults(Array{Float64,1}(undef, N), Array{Float64,2}(undef, N, N))    
+
+#Support for inplace copying
+import Base.copy!
+function copy!(dst::MyResults, src::MyResults)
+    dst.x .= src.x
+    dst.A .= src.A
+end
+```
+
+The above code is an **immutable** structure for holding the `x` and `A` buffers.  The fact that it is immutable ensures that the `x` vector itself cannot be changed (even if the values within `x` can be).  This can help ensure that you do not accidentally reallocate and assign a new vector to `x`.
+
+The only other code is an implementation of the in-place `copy!` function, which will allow us to copy all of the results as required by some algorithms.
+
+To create a contrived algorithm, see the following code:
+
+```{code-cell} julia
+# By convention, name has ! to denote mutating, and mutate first argument
+function calculate_results!(results, val, params)
+    @unpack N, b, C = params
+    B = rand(N,N)  # Contrived.  Assume complicated
+    lmul!(val, B)  # val * B -> B inplace, no allocation
+    mul!(results.A, B, C) #   B * C -> results.A
+    ldiv!(results.x, factorize(results.A), b)  # x = A \ b inplace
+end
+
+# Some iterative algorithm
+function iterate_values(vals, params)    
+    @unpack N = params
+    
+    # preallocate
+    results = MyResults(N)
+    prev_results = MyResults(N)
+    norms = similar(vals)
+        
+    for (i, val) in enumerate(vals)
+        calculate_results!(results, val, params)
+        norms[i] = norm(results.x- prev_results.x)            
+        println("|x_new - x_old| = ", norms[i])
+        copy!(prev_results, results)
+    end
+    return norms
+end
+
+params = (N = 5, C = rand(5,5), b = rand(5))
+vals = range(0.0, 1.0, length = 10)
+iterate_values(vals, params)
+```
+
+A few points:
+- This creates an inplace function, `calculate_results!`, which modifies the results given a value and parameters.
+- Within the function, it attemmpts to use inplace versions of the operations where possible, which can help cut down on other allocations
+- The iteration simply goes through a list of values, calls the `calculate_results!` and then checks how the `results.x` has changed with a norm.
+- Finally, the iteration copys the new results into the previous ones.  This ensure that only a single copy is required for comparison.
+
+
+
+This approach can be very helpful for large matrices and arrays, but should be used judiciously and only after {doc}`profiling<../software_engineering/need_for_speed>`  .
+
+
 ## Exercises
 
 ### Exercise 1
