Merge pull request #245 from PlasmaControl/plot_kwargs

Documents kwargs for plotting functions and adds sensible kwargs to those that were lacking them (such as figsize)
 - Document kwargs, according to [matplotlib-style documentation](https://stackoverflow.com/questions/62511086/how-to-document-kwargs-according-to-numpy-style-docstring)
 - add kwargs to plotting functions missing sensible/useful kwargs
 - add check for unused kwargs to most plotting functions
 - add plot comparisons to artifact uploaded to github 
 - bump `pytest-mpl` version to fix [bug](matplotlib/pytest-mpl#171) where if `unittest.TestCase` is used, it did not actually run those tests correctly 

resolves #178 , #244

Author: dpanici

.github/workflows/pytest.yml

@@ -39,12 +39,14 @@ jobs:
         run: |
           pwd
           lscpu
-          python -m pytest --durations=0 --cov-report xml:cov.xml --cov-config=setup.cfg --cov=desc/ --mpl
-      - name: save coverage file
+          python -m pytest --durations=0 --cov-report xml:cov.xml --cov-config=setup.cfg --cov=desc/ --mpl --mpl-results-path=mpl_results.html --mpl-generate-summary=html
+      - name: save coverage file and plot comparison results
         uses: actions/upload-artifact@v2
         with:
           name: my-artifact
-          path: ./cov.xml
+          path: |
+            ./cov.xml
+            ./mpl_results.html
       - name: Upload coverage
         uses: codecov/codecov-action@v2
         with:

desc/plotting.py

@@ -18,7 +18,7 @@ pylint >= 2.12.2
 pytest >= 5.0.0
 pytest-cov >= 2.6.0
 codecov
-pytest-mpl == 0.16.0
+pytest-mpl == 0.16.1
 pytest-benchmark
 markupsafe==2.0.1
 nbmake

devtools/dev-requirements.txt

@@ -116,9 +116,9 @@ The parameter vector :math:`\mathbf{c}` contains the spectral coefficients of th
 .. math::
   \mathbf{c} = [R^b_{mn} \\ Z^b_{mn} \\ p_l \\ \iota_l \\ \psi_a]^T
 
-The equations :math:`\mathbf{f}` are the force error residuals at a series of collocation points, as well as additional equations to enforce the boundary condition: 
+The equations :math:`\mathbf{f}` are the force error residuals at a series of collocation points: 
 
 .. math::
-  \mathbf{f} = [f_\rho \\ f_\beta \\ BC]^T
+  \mathbf{f} = [f_\rho \\ f_\beta]^T
 
-DESC allows flexibility in the choice of optimization algorithm used to solve this system of equations; popular approaches include Newton-Raphson methods and least-squares minimization. 
+DESC allows flexibility in the choice of optimization algorithm used to solve this system of equations; popular approaches include Newton-Raphson methods and least-squares minimization (as the collocation grids are often oversampled, which has been found to improve convergence and robustness). 

docs/theory_general.rst

@@ -27,36 +27,43 @@
     DoubleFourierSeries,
     FourierZernikeBasis,
 )
-from desc.equilibrium import EquilibriaFamily
+from desc.equilibrium import EquilibriaFamily, Equilibrium
 from desc.coils import FourierXYZCoil, CoilSet
 
 
+def test_kwarg_warning(DummyStellarator):
+    eq = Equilibrium.load(load_from=str(DummyStellarator["output_path"]))
+    with pytest.raises(AssertionError):
+        fig, ax = plot_1d(eq, "p", not_a_kwarg=True)
+    return None
+
+
 @pytest.mark.mpl_image_compare(tolerance=50)
 def test_1d_p(SOLOVEV):
     eq = EquilibriaFamily.load(load_from=str(SOLOVEV["desc_h5_path"]))[-1]
-    fig, ax = plot_1d(eq, "p")
+    fig, ax = plot_1d(eq, "p", figsize=(4, 4))
     return fig
 
 
 @pytest.mark.mpl_image_compare(tolerance=50)
 def test_1d_dpdr(SOLOVEV):
     eq = EquilibriaFamily.load(load_from=str(SOLOVEV["desc_h5_path"]))[-1]
-    fig, ax = plot_1d(eq, "p_r")
+    fig, ax = plot_1d(eq, "p_r", figsize=(4, 4))
     return fig
 
 
 @pytest.mark.mpl_image_compare(tolerance=50)
 def test_1d_iota(SOLOVEV):
     eq = EquilibriaFamily.load(load_from=str(SOLOVEV["desc_h5_path"]))[-1]
     grid = LinearGrid(rho=0.5, theta=100, zeta=0.0)
-    fig, ax = plot_1d(eq, "iota", grid=grid)
+    fig, ax = plot_1d(eq, "iota", grid=grid, figsize=(4, 4))
     return fig
 
 
 @pytest.mark.mpl_image_compare(tolerance=50)
 def test_1d_logpsi(SOLOVEV):
     eq = EquilibriaFamily.load(load_from=str(SOLOVEV["desc_h5_path"]))[-1]
-    fig, ax = plot_1d(eq, "psi", log=True)
+    fig, ax = plot_1d(eq, "psi", log=True, figsize=(4, 4))
     return fig
 
 
@@ -65,30 +72,30 @@ def test_2d_logF(SOLOVEV):
     # plot test is inconsistent
     eq = EquilibriaFamily.load(load_from=str(SOLOVEV["desc_h5_path"]))[-1]
     grid = LinearGrid(rho=100, theta=100, zeta=0.0)
-    fig, ax = plot_2d(eq, "|F|", log=True, grid=grid)
+    fig, ax = plot_2d(eq, "|F|", log=True, grid=grid, figsize=(4, 4))
     return fig
 
 
 @pytest.mark.mpl_image_compare(tolerance=50)
 def test_2d_g_tz(SOLOVEV):
     eq = EquilibriaFamily.load(load_from=str(SOLOVEV["desc_h5_path"]))[-1]
     grid = LinearGrid(rho=0.5, theta=100, zeta=100)
-    fig, ax = plot_2d(eq, "sqrt(g)", grid=grid)
+    fig, ax = plot_2d(eq, "sqrt(g)", grid=grid, figsize=(4, 4))
     return fig
 
 
 @pytest.mark.mpl_image_compare(tolerance=50)
 def test_2d_g_rz(SOLOVEV):
     eq = EquilibriaFamily.load(load_from=str(SOLOVEV["desc_h5_path"]))[-1]
     grid = LinearGrid(rho=100, theta=0.0, zeta=100)
-    fig, ax = plot_2d(eq, "sqrt(g)", grid=grid)
+    fig, ax = plot_2d(eq, "sqrt(g)", grid=grid, figsize=(4, 4))
     return fig
 
 
 @pytest.mark.mpl_image_compare(tolerance=50)
 def test_2d_lambda(SOLOVEV):
     eq = EquilibriaFamily.load(load_from=str(SOLOVEV["desc_h5_path"]))[-1]
-    fig, ax = plot_2d(eq, "lambda")
+    fig, ax = plot_2d(eq, "lambda", figsize=(4, 4))
     return fig
 
 
@@ -215,42 +222,42 @@ def test_plot_comparison_no_theta(DSHAPE):
 @pytest.mark.mpl_image_compare(tolerance=50)
 def test_plot_con_basis(SOLOVEV):
     eq = EquilibriaFamily.load(load_from=str(SOLOVEV["desc_h5_path"]))[-1]
-    fig, ax = plot_2d(eq, "e^rho", component="R")
+    fig, ax = plot_2d(eq, "e^rho", component="R", figsize=(4, 4))
     return fig
 
 
 @pytest.mark.mpl_image_compare(tolerance=50)
 def test_plot_cov_basis(SOLOVEV):
     eq = EquilibriaFamily.load(load_from=str(SOLOVEV["desc_h5_path"]))[-1]
-    fig, ax = plot_2d(eq, "e_rho")
+    fig, ax = plot_2d(eq, "e_rho", figsize=(4, 4))
     return fig
 
 
 @pytest.mark.mpl_image_compare(tolerance=50)
 def test_plot_magnetic_tension(SOLOVEV):
     eq = EquilibriaFamily.load(load_from=str(SOLOVEV["desc_h5_path"]))[-1]
-    fig, ax = plot_2d(eq, "|(B*grad)B|")
+    fig, ax = plot_2d(eq, "|(B*grad)B|", figsize=(4, 4))
     return fig
 
 
 @pytest.mark.mpl_image_compare(tolerance=50)
 def test_plot_magnetic_pressure(SOLOVEV):
     eq = EquilibriaFamily.load(load_from=str(SOLOVEV["desc_h5_path"]))[-1]
-    fig, ax = plot_2d(eq, "|grad(|B|^2)|/2mu0")
+    fig, ax = plot_2d(eq, "|grad(|B|^2)|/2mu0", figsize=(4, 4))
     return fig
 
 
 @pytest.mark.mpl_image_compare(tolerance=50)
 def test_plot_gradpsi(SOLOVEV):
     eq = EquilibriaFamily.load(load_from=str(SOLOVEV["desc_h5_path"]))[-1]
-    fig, ax = plot_2d(eq, "|grad(rho)|")
+    fig, ax = plot_2d(eq, "|grad(rho)|", figsize=(4, 4))
     return fig
 
 
 @pytest.mark.mpl_image_compare(tolerance=55)
 def test_plot_normF_2d(SOLOVEV):
     eq = EquilibriaFamily.load(load_from=str(SOLOVEV["desc_h5_path"]))[-1]
-    fig, ax = plot_2d(eq, "|F|", norm_F=True)
+    fig, ax = plot_2d(eq, "|F|", norm_F=True, figsize=(4, 4))
     return fig
 
 
@@ -284,7 +291,7 @@ def test_plot_grid_linear(self):
     @pytest.mark.mpl_image_compare(tolerance=50)
     def test_plot_grid_quad(self):
         grid = QuadratureGrid(L=10, M=10, N=1)
-        fig, ax = plot_grid(grid)
+        fig, ax = plot_grid(grid, figsize=(6, 6))
         return fig
 
     @pytest.mark.mpl_image_compare(tolerance=50)
@@ -381,7 +388,7 @@ def test_plot_boozer_modes(SOLOVEV):
 @pytest.mark.mpl_image_compare(tolerance=50)
 def test_plot_boozer_surface(SOLOVEV):
     eq = EquilibriaFamily.load(load_from=str(SOLOVEV["desc_h5_path"]))[-1]
-    fig, ax = plot_boozer_surface(eq)
+    fig, ax = plot_boozer_surface(eq, figsize=(4, 4))
     return fig