Improvements to RegularGridInterpolant3D and C++ documentation #103

[florianwechsung]

• Introduces some general remarks regarding the C++ part of SIMSOPT in docs/source/cpp.rst
• Adds the ability to skip some cells in the mesh to the RegularGridInterpolant3D class
• some clean up of the C++ and some more docs of RegularGridInterpolant3D

This will close #103

[codecov]

Codecov Report

Merging #227 (ee3af97) into master (f90d8f5) will increase coverage by 0.72%.
The diff coverage is 100.00%.

@@            Coverage Diff             @@
##           master     #227      +/-   ##
==========================================
+ Coverage   90.83%   91.55%   +0.72%     
==========================================
  Files          59       62       +3     
  Lines        7733     8577     +844     
==========================================
+ Hits         7024     7853     +829     
- Misses        709      724      +15     

Flag	Coverage Δ
unittests	91.55% <100.00%> (+0.72%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

Impacted Files	Coverage Δ
src/simsopt/field/magneticfieldclasses.py	97.97% <100.00%> (+0.02%)	⬆️
src/simsopt/geo/surface.py	91.07% <100.00%> (+2.45%)	⬆️
src/simsopt/mhd/vmec.py	92.30% <0.00%> (-0.62%)	⬇️
src/simsopt/util/zoo.py	100.00% <0.00%> (ø)
src/simsopt/mhd/virtual_casing.py	98.80% <0.00%> (ø)
src/simsopt/geo/finitebuild.py	99.34% <0.00%> (ø)
src/simsopt/util/fourier_interpolation.py	100.00% <0.00%> (ø)
src/simsopt/mhd/vmec_diagnostics.py	99.35% <0.00%> (+0.14%)	⬆️
src/simsopt/field/coil.py	99.01% <0.00%> (+1.14%)	⬆️

---

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 f90d8f5...ee3af97. Read the comment docs.

[florianwechsung]

To illustrate the skip function: we previously would have to pick the bounds of the interpolation domain so that the entire domain of interest is contained. This meant that potentially we were querying the field in regions that we're not going to be interested in after all, see e.g. here

(note that the field here satisfies stellarator symmetry and 3-fold rotational symmetry).

With the new capability, we can reduce this and skip many cells, as shown here:

The effect is particularly large for strongly shaped plasmas.

Note that the strategy employed here is not perfect. Since we only check the skip function at the corners of the mesh, some cells may be skipped that still have some of the relevant domain in it, as is the case in this example for the red cell. (The blue cells are those that not skipped)

This can be avoided by defining a skip function that is somewhat pessimistic in which cells are allowed to be skipped. For example, when the skip function is defined by a signed distance function to a surface, then the threshold shouldn't be set at 0, but at some slightly larger/smaller number roughly of size ~meshsize.

[florianwechsung]

Thank you for your comments @landreman , I addressed them in the latest commit.