lots of doc updates (woah examples)

README.md

@@ -64,4 +64,4 @@ However, the standard distutils commands also work if you're so inclined::
 
 ## Development ##
 
-Please, if you edit the code, use [PEP 8](https://www.python.org/dev/peps/pep-0008/) style. Poor style is more than just aesthetic; it tends to lead to bugs that are difficult to spot. This is sorely true when it comes to whitespace (4 spaces per indent). Check out the documentation for a more complete developer's guide (inculding exceptions to PEP 8 that are ok).
+Please, if you edit the code, use [PEP 8](https://www.python.org/dev/peps/pep-0008/) style. Poor style is more than just aesthetic; it tends to lead to bugs that are difficult to spot. Check out the documentation for a more complete developer's guide (inculding exceptions to PEP 8 that are ok).

doc/api/viscid.calculator.minvar_tools.rst

@@ -0,0 +1,7 @@
+viscid.calculator.minvar_tools module
+=====================================
+
+.. automodule:: viscid.calculator.minvar_tools
+    :members:
+    :undoc-members:
+    :show-inheritance:

doc/api/viscid.calculator.mpause.rst

@@ -0,0 +1,7 @@
+viscid.calculator.mpause module
+===============================
+
+.. automodule:: viscid.calculator.mpause
+    :members:
+    :undoc-members:
+    :show-inheritance:

doc/api/viscid.calculator.rst

@@ -9,6 +9,8 @@ Submodules
    viscid.calculator.calc
    viscid.calculator.cluster
    viscid.calculator.evaluator
+   viscid.calculator.minvar_tools
+   viscid.calculator.mpause
    viscid.calculator.necalc
    viscid.calculator.plasma
    viscid.calculator.separator

doc/api/viscid.compat.rst

@@ -8,6 +8,7 @@ Submodules
 
    viscid.compat.element_tree
    viscid.compat.ordered_dict_backport
+   viscid.compat.vimportlib
 
 Module contents
 ---------------

doc/api/viscid.compat.vimportlib.rst

@@ -0,0 +1,7 @@
+viscid.compat.vimportlib module
+===============================
+
+.. automodule:: viscid.compat.vimportlib
+    :members:
+    :undoc-members:
+    :show-inheritance:

doc/conf.py

@@ -142,17 +142,22 @@ def get_viscid_version(init_py):
                        ("Philosophy", "philosophy"),
                        ("Useful Functions", "functions"),
                        ("Plot Options", "plot_options"),
+                       ("Matplotlib Styles", "mpl_styles"),
                        ("RC file", "custom_behavior"),
                        ("Command Line Tools", "command_line"),
                        ("Developer's Guide", "dev_guide"),
                        ("Extending Readers", "extending_readers"),
                       ]
          ),
-         ("Examples", [("Plotting", "examples/plotting"),
-                       ("Slicing", "examples/slicing"),
-                       ("Calculator", "examples/calc"),
-                       ("OpenGGCM", "examples/openggcm"),
-                       ("3D Plots", "examples/mayavi_plotting"),
+         ("Examples", [("Slicing Fields", "examples/slicing"),
+                       ("Plotting Scalars", "examples/plotting_scalars"),
+                       ("Plotting Vectors", "examples/plotting_vectors"),
+                       ("Streamline and Interpolation", "examples/stream_and_interp"),
+                       ("Magnetic Topology", "examples/magnetic_topology"),
+                       ("Magnetopause", "examples/magnetopause"),
+                       ("Ionosphere", "examples/ionosphere"),
+                       ("OpenGGCM Specific", "examples/openggcm"),
+                       ("3D Plots (Mayavi)", "examples/mayavi"),
                       ]
          )
         ]

doc/dev_guide.rst

@@ -4,7 +4,7 @@ Developer's Guide
 Style
 -----
 
-Please, if you edit the code, use `PEP 8 <https://www.python.org/dev/peps/pep-0008>`_ style. Poor style is more than just aesthetic; it tends to lead to bugs that are difficult to spot. This is sorely true when it comes to whitespace (4 spaces per indent please). Here are some aspects of PEP 8 that are ok to bend:
+Please, if you edit the code, use `PEP 8 <https://www.python.org/dev/peps/pep-0008>`_ style. Poor style is more than just aesthetic; it tends to lead to bugs that are difficult to spot. Here are some aspects of PEP 8 that are ok to bend:
 
 + Lines should be less than 92 characters long, but if you're pushing over 80, then think about whether or not you're doing too much on one line.
 

doc/examples/index.rst

@@ -4,8 +4,12 @@ Examples
 .. toctree::
   :maxdepth: 2
 
-  plotting
   slicing
-  calc
+  plotting_scalars
+  plotting_vectors
+  stream_and_interp
+  magnetic_topology
+  magnetopause
+  ionosphere
   openggcm
-  mayavi_plotting
+  mayavi

doc/examples/ionosphere.rst

@@ -0,0 +1,40 @@
+Ionosphere Plots
+================
+
+.. plot::
+    :include-source:
+
+    from matplotlib import pyplot as plt
+
+    import viscid
+    from viscid.plot import mpl
+
+    iono_file = viscid.load_file(_viscid_root + '/../../sample/sample_xdmf.iof.xdmf')
+
+    fac_tot = 1e9 * iono_file["fac_tot"]
+
+    plot_args = dict(projection="polar",
+                     lin=[-300, 300],
+                     bounding_lat=35.0,
+                     drawcoastlines=True,  # for basemap only, probably will never be used
+                     title="Total FAC\n",  # make a title, or if a string, use the string as title
+                     gridec='gray',
+                     label_lat=True,
+                     label_mlt=True,
+                     colorbar=dict(pad=0.1)  # pad the colorbar away from the plot
+                    )
+
+    ax1 = plt.subplot(121, projection='polar')
+    mpl.plot(fac_tot, ax=ax1, hemisphere='north', **plot_args)
+    ax1.annotate('(a)', xy=(0, 0), textcoords="axes fraction",
+                 xytext=(-0.1, 1.0), fontsize=18)
+
+    ax2 = plt.subplot(122, projection='polar')
+    plot_args['gridec'] = False
+    mpl.plot(fac_tot, ax=ax2, hemisphere="south", style="contourf",
+             levels=50, extend="both", **plot_args)
+    ax2.annotate('(b)', xy=(0, 0), textcoords="axes fraction",
+                 xytext=(-0.1, 1.0), fontsize=18)
+
+    plt.gcf().set_size_inches(10, 5.0)
+    mpl.tighten()

doc/examples/calc.rst → doc/examples/magnetic_topology.rst

@@ -1,34 +1,5 @@
-Calculator Examples
-===================
-
-Streamlines
------------
-
-.. plot::
-    :include-source:
-
-    import numpy as np
-
-    import viscid
-    from viscid.plot import mpl
-
-    B = viscid.vlab.get_dipole(twod=True)
-    obound0 = np.array([-4, -4, -4], dtype=B.data.dtype)
-    obound1 = np.array([4, 4, 4], dtype=B.data.dtype)
-    lines, topo = viscid.calc_streamlines(B,
-                                          viscid.Line((0.2, 0.0, 0.0),
-                                                      (1.0, 0.0, 0.0), 10),
-                                          ds0=0.01, ibound=0.1, maxit=10000,
-                                          obound0=obound0, obound1=obound1,
-                                          method=viscid.EULER1,
-                                          stream_dir=viscid.DIR_BOTH,
-                                          output=viscid.OUTPUT_BOTH)
-    topo_colors = viscid.topology2color(topo)
-    mpl.plot2d_lines(lines, topo_colors, symdir='y')
-    mpl.plt.ylim(-0.5, 0.5)
-
 Magnetic Topology
------------------
+=================
 
 Magnetic topology can be determined by the end points of magnetic field lines. By default, the topology output from calc_streamlines is a bitmask of closed (1), open-north (2), open-south (4), and solar wind (8). Any value larger than 8 indicates something else happened with that field line, such as reaching maxit or max_length and ending without hitting a boundary. The topology output can be switched to the raw boundary bitmask by giving ``topo_style='generic'`` as an argument to calc_streamlines.
 

doc/examples/magnetopause.rst

@@ -0,0 +1,89 @@
+Extracting Magnetopause Information
+===================================
+
+Viscid has the ability to extract magnetopause information using :py:func:`viscid.get_mp_info`. By default, Viscid will cache the results into a set of hdf5+xdmf files so that it will not always load the larger 3d files.
+
+.. image:: ../images/mpause-000.png
+  :align: center
+
+|
+
+.. image:: ../images/mpause-001.png
+  :align: center
+
+|
+
+.. code-block:: python
+
+  import numpy as np
+  import viscid
+  from viscid.plot import mvi
+
+
+  f = viscid.load_file("$WORK/xi_fte_001/*.3d.[4050f].xdmf")
+  mp = viscid.get_mp_info(f['pp'], f['b'], f['j'], f['e_cc'], fit='mp_xloc',
+                          slc="x=6.5f:10.5f, y=-4f:4f, z=-4.8f:3f",
+                          cache=False)
+
+  y, z = mp['pp_max_xloc'].meshgrid_flat(prune=True)
+  x = mp['pp_max_xloc'].data.reshape(-1)
+
+  Y, Z = mp['pp_max_xloc'].meshgrid(prune=True)
+  x2 = viscid.paraboloid(Y, Z, *mp['paraboloid'][0])
+
+  skip = 117
+
+  # get normals from paraboloid surface
+  parab_n = viscid.paraboloid_normal(Y, Z, *mp['paraboloid'][0])
+  parab_n = parab_n.reshape(3, -1)[:, ::skip]
+
+  # get normals from minvar
+  minvar_y = Y.reshape(-1)[::skip]
+  minvar_z = Z.reshape(-1)[::skip]
+  minvar_n = np.zeros([3, len(minvar_y)])
+
+  for i in range(minvar_n.shape[0]):
+      p0 = [0.0, minvar_y[i], minvar_z[i]]
+      p0[0] = mp['pp_max_xloc']['y={0[0]}f, z={0[1]}f'.format(p0)]
+      lmn = viscid.find_minvar_lmn_around(f['b'], p0, l=2.0, n=64)
+      minvar_n[:, i] = lmn[2, :]
+
+  fig = mvi.mlab.gcf()
+  fig.scene.background = (1.0, 1.0, 1.0)
+  fig.scene.foreground = (0.05, 0.05, 0.05)
+
+  grey = (0.75, ) * 3
+  red = (1, 0, 0)
+  blue = (0, 0, 1)
+
+  mvi.mlab.points3d(x[::skip], y[::skip], z[::skip], scale_factor=0.25,
+                    color=blue)
+
+  mp_width = mp['mp_width']['x=0']
+  mp_sheath_edge = mp['mp_sheath_edge']['x=0']
+  mp_sphere_edge = mp_sheath_edge - mp_width
+
+  mvi.mlab.mesh(x2, Y, Z, scalars=mp_width.data)
+  mvi.mlab.mesh(mp_sheath_edge.data, Y, Z, opacity=0.75, color=grey)
+  mvi.mlab.mesh(mp_sphere_edge.data, Y, Z, opacity=0.75, color=grey)
+
+  mvi.mlab.quiver3d(x2.reshape(-1)[::skip],
+                    Y.reshape(-1)[::skip],
+                    Z.reshape(-1)[::skip],
+                    parab_n[0], parab_n[1], parab_n[2], color=red,
+                    mode='arrow')
+  mvi.mlab.quiver3d(x2.reshape(-1)[::skip],
+                    Y.reshape(-1)[::skip],
+                    Z.reshape(-1)[::skip],
+                    minvar_n[0], minvar_n[1], minvar_n[2], color=blue,
+                    mode='arrow')
+
+  mvi.plot_earth_3d(crd_system="gse")
+
+  mvi.resize([600, 400])
+  mvi.mlab.view(azimuth=+90.0, elevation=90.0,
+                distance=20.0, focalpoint=(5.0, 0.0, -1.0))
+  mvi.savefig("mpause-000.png")
+  mvi.mlab.view(azimuth=+90.0 - 45.0, elevation=90.0 - 25.0,
+                distance=20.0, focalpoint=(6.0, 0.0, -1.0))
+  mvi.savefig("mpause-001.png")

doc/examples/mayavi_plotting.rst → doc/examples/mayavi.rst

@@ -7,4 +7,6 @@ made by `test_mvi.py` along with some code
 .. image:: ../../tests/ref_plots/mvi-000.png
   :align: center
 
+|
+
 .. literalinclude:: ../../tests/test_mvi.py

doc/examples/openggcm.rst

@@ -34,13 +34,13 @@ Time Series
 
     openggcm.GGCMGrid.mhd_to_gse_on_read = 'auto'
 
-    f3d = viscid.load_file(_viscid_root + '/../../sample/sample_xdmf.3d.xdmf')
+    f2d = viscid.load_file(_viscid_root + '/../../sample/sample_xdmf.py_0.xdmf')
 
-    ntimes = f3d.nr_times()
+    ntimes = f2d.nr_times()
     t = [None] * ntimes
     pressure = np.zeros((ntimes,), dtype='f4')
 
-    for i, grid in enumerate(f3d.iter_times()):
+    for i, grid in enumerate(f2d.iter_times()):
         t[i] = grid.time_as_datetime()
         pressure[i] = grid['pp']['x=10.0f, y=0.0f, z=0.0f']
     plt.plot(t, pressure)
@@ -51,44 +51,3 @@ Time Series
     plt.gca().xaxis.set_major_formatter(dateFmt)
     plt.gcf().autofmt_xdate()
     plt.gca().grid(True)
-
-Ionosphere Files
-----------------
-
-.. plot::
-    :include-source:
-
-    from matplotlib import pyplot as plt
-
-    import viscid
-    from viscid.plot import mpl
-
-    iono_file = viscid.load_file(_viscid_root + '/../../sample/sample_xdmf.iof.xdmf')
-
-    fac_tot = 1e9 * iono_file["fac_tot"]
-
-    plot_args = dict(projection="polar",
-                     lin=[-300, 300],
-                     bounding_lat=35.0,
-                     drawcoastlines=True,  # for basemap only, probably will never be used
-                     title="Total FAC\n",  # make a title, or if a string, use the string as title
-                     gridec='gray',
-                     label_lat=True,
-                     label_mlt=True,
-                     colorbar=dict(pad=0.1)  # pad the colorbar away from the plot
-                    )
-
-    ax1 = plt.subplot(121, projection='polar')
-    mpl.plot(fac_tot, ax=ax1, hemisphere='north', **plot_args)
-    ax1.annotate('(a)', xy=(0, 0), textcoords="axes fraction",
-                 xytext=(-0.1, 1.0), fontsize=18)
-
-    ax2 = plt.subplot(122, projection='polar')
-    plot_args['gridec'] = False
-    mpl.plot(fac_tot, ax=ax2, hemisphere="south", style="contourf",
-             levels=50, extend="both", **plot_args)
-    ax2.annotate('(b)', xy=(0, 0), textcoords="axes fraction",
-                 xytext=(-0.1, 1.0), fontsize=18)
-
-    plt.gcf().set_size_inches(10, 5.0)
-    mpl.tighten()