Create theory section and update tutorials

[dccowan]

Goals

1. To provide general background theory for the finite volume method relevant to the discretize package.
2. To update and create tutorials which demonstrate the theory.

Access to Temporary Build

Theory sections can be accessed through a temporary website build: https://dccowan.github.io/

Theory Sections

The current theory section of the website is organized as follows. Tutorials have been developed in parallel.

• Intro to finite volume: A general landing page that offers a conceptual description of finite volume method
• Meshes: Describes meshes, where discrete variables live and demonstrates different mesh types
• Operators: Interpolation, averaging and differential operators
• Inner products: Basic, linear constitutive relations, tensor constitutive relations, differential operators, boundary conditions
• Solving PDE examples: Full derivations from PDEs to the final discrete system being solved numerically

Remaining Items and Questions

• References and bibliography: The theory section takes heavily from work published by others. We must make decisions on how we want to reference the source material.

• Balancing emphasis on theory, tutorials and API: In highlighting theory and tutorials, we do not want to diminish the presence of the API. How do we keep the API at the forefront of the website while providing easy access to tutorials and theory for those who need it?

Some Action Items

• [ ] Assemble all needed citations: Eldad Haber's book, Hyman and Shashkov, 1999 anything else?
• [ ] Decide on a bibliography and citation style

[codecov[bot]]

Codecov Report

Merging #233 (f1fe3ba) into master (e4a1717) will increase coverage by 0.09%. The diff coverage is n/a.

@@            Coverage Diff             @@
##           master     #233      +/-   ##
==========================================
+ Coverage   80.76%   80.85%   +0.09%     
==========================================
  Files          35       35              
  Lines        8704     8704              
==========================================
+ Hits         7030     7038       +8     
+ Misses       1674     1666       -8     

Impacted Files	Coverage Δ
discretize/_extensions/tree_ext.pyx	77.04% <0.00%> (+0.32%)	:arrow_up:

---

Continue to review full report at Codecov.

Legend - Click here to learn more Δ = absolute <relative> (impact), ø = not affected, ? = missing data Powered by Codecov. Last update e4a1717...f1fe3ba. Read the comment docs.

[dougoldenburg]

Interpolation 2D (a) a sentence or two describing the circular fields that are involved. (?magnetic fields from a wire?) (b) a color bar for the first two images? That will help getting a sense of dynamic range which is important for interpolation. (c) what is plotted in the third image? The code says "differences". Does the fact that the arrows all point counter-clockwise mean that "true-minus-interpolated" is always positive? A color bar would be helpful since amplitude differences will reduce as you go away from the center. In that regard, it might be informative to let the errors be plotted on a natural scale.

[dccowan]

Interpolation 2D (a) a sentence or two describing the circular fields that are involved. (?magnetic fields from a wire?) (b) a color bar for the first two images? That will help getting a sense of dynamic range which is important for interpolation. (c) what is plotted in the third image? The code says "differences". Does the fact that the arrows all point counter-clockwise mean that "true-minus-interpolated" is always positive? A color bar would be helpful since amplitude differences will reduce as you go away from the center. In that regard, it might be informative to let the errors be plotted on a natural scale.

Add a line explaining the vector field. Added colorbar. Made definition of error consistent

[dougoldenburg]

Discretize: Examples (THIS ERROR WAS FIXED): Cahn-Hilliard: tex equations are not rendering Stream Line thickness: The color image is washed out and thereby the example loses impact. What is the importance of the word "thickness"

[dougoldenburg]

Differential Operators (THIS TYPO WAS FIXED)

Overall: This is really(!) well done. Congrats!

Main point: With each of the discretizations of Div, Grad, Curl after you have shown that you can write this in a matrix vector form, can you include a short section about the dimensions of the matrices and vectors. Restricting comments to a uniform rectangular mesh in hx, hy, hz would be sufficient.

This sentence (repeated throughout the text) threw me off. Especially the word "respectively". And let 𝝓 and 𝑢 be the discrete representations of 𝜙 and 𝑢⃗ that live on the mesh (centers, nodes, edges or faces), respectively.

When I did the derivation for curl I got your result except for a minus sign. Can you please check?

[dougoldenburg]

Interpolation (THIS FIGURE WAS FIXED) have 9 nodes but plot seems only to go to 8

[dougoldenburg]

Interpolation Having distinct sections for nodal and cell centers seems to make the problem more complicated than might be needed.

What about saying that the function to be interpolated is defined at a set of nodes. Interpolation to any location within the boundaries of those points is done through linear interpolation. We are unable to extrapolate, that is, to find the value of the function at a location outside that domain.

If the nodes for interpolation coincide with the nodes of the mesh then a value can be found at any location in our "volume" If the nodes coincide with cell centers of the mesh then the values cannot be found in the first half cell and the last half cell

... or something like that....

[dougoldenburg]

Is there a sentence missing?

Also the term "Averaging Matrices" is commonly used and we should keep that and the symbol A. However, these are really interpolation matrices and since the reader has just finished "Interpolation" a sentence or two to reinforce this concept might help.

[dougoldenburg]

It worthwhile having a discussion about a uniform notation so that we keep nodes, cell centers, widths of cells, and widths between cell centers as unambiguous as possible and uniform for all of our material. You have introduced \delta x as a cell width and we usually use h.

The derivation of nodes to cell centers follows nicely from your diagram and linear interpolation. The formula from cell centers to nodes was not obvious especially since \delta x was not shown on the initial plot. Is there a reference for the formula? For me, in order to convince myself that it was correct, I rederived it and that was most easily done by introducing a slightly altered visual for the discretization. I attach that below.

[dougoldenburg]

(LINK WAS ADDED FOR KRONECKER PRODUCT)

I think this is the first time that Kronecker product has been used. ?? Wikepedia referrence? Going to 2D and working with the Kronecker product is a big leap.

What resources would be valuable for a reader?