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]

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%)	⬆️

---

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?

[lheagy]

First off, thanks for all of your work on this @dccowan! This will be a valuable resource. At this stage, I have done a once-over for organization and usability, and thinking about maintenance and if we need to make updates in the future.

With respect to figures:

• could you put any notebooks / code you used to generate those figures in a repo so that we have them archived
• similarly for any hand-made figures, did you use ppt or similar? could you upload those files to the SimPEG google drive? we can create a documentation directory to keep them in

With respect to organization / find-ability of content, I made some specific suggestions, which summarize to: can we flatten the tree as much as possible. So in general, under the theory the navigation bar should be

• Page 1
  • heading 1 on page 1
  • heading 2 on page 1
  • ...
• Page 2
  • ...
• Page 3

with perhaps the exception of the final heading which groups the examples. I realize this makes the navigation bar a bit longer, but it makes it much easier to navigate + discover content. When we get the new template in place, we will have a bit more flexibility with how we show content and so should be able to collapse the whole "Theory" section which will tighten things up

[lheagy]

Could this be made one level lower? E.g. a subheading of the page, which is "Finite Volume", and then DC resistivity and FDEM under that. This way, there is only one top-level heading on the page

[lheagy]

Do you have the original notebook used to generate these figures somewhere? If we ever want / need to make updates, this would save us a lot of time to have archived (even if right now these are in a separate, small repo -- as long as we have them)

[dccowan]

I have been keeping the scripts used to make figures with the intent of archiving them eventually. But I wanted to get feedback and finalize the figures first.

[lheagy]

similarly with these figures, did you use ppt or similar to create them? Could you upload a copy to the SimPEG google drive so we have them for reference?

[lheagy]

In order to reduce the depth of the tree, I would be inclined to remove this index file and simply have Interpolation, Averaging and Differential Operators at top-level

[dccowan]

"Flattening" of the tree might come naturally when the new doc style is implemented by Joe. I wanted to leave some of the final details of this to the end because we aren't 100% sure what the final look of the website will be yet. The important thing for me is that we avoid lengthy pages and that we try to partition things into easily digestible bites.

[dccowan]

Another thing to keep in mind is that the theory section currently parallels with the tutorials section. If you flatten or rearrange the content of the theory sections, the tutorials no longer line up.

[lheagy]

Again here, I would be inclined to remove this page and bring

• Basic Inner Products
• Isotropic Constitutive Relationships
• Anisotropic Constitutive Relationships
• Inner products with differential operators (renaming from "Differential Operators" to distinguish from the "Operators" section)
• Boundary Conditions (which I think should be at top level either way)