DOC: Include examples (and example documentation) for sphinx-gallery

Author: ryder-davidson

README.rst

@@ -59,4 +59,4 @@ or `contact <https://www.predsci.com/portal/contact.php>`_ Predictive Science In
 `Predictive Science Inc. <https://predsci.com>`_ |
 `Repository <https://github.com/predsci/pyvisual>`_ |
 `Documentation <https://predsci.com/doc/pyvisual>`_ |
-`Distribution <https://pypi.org/project/pyvisual>`_
+`Distribution <https://pypi.org/project/psi-pyvisual>`_

docs/source/guide/index.rst

@@ -1,11 +1,29 @@
 User Guide
 ==========
 
-To get started with **pyvisual**, please refer to the following sections:
+.. grid:: 3
+   :gutter: 2
+   :class-container: sd-mt-4
 
-.. toctree::
+   .. grid-item-card:: Installation
+      :link: installation
+      :link-type: doc
+      :text-align: center
+
+      Installation instructions, including recommended virtual environment setup
+      and required/optional dependencies.
 
-   installation
-   overview
+   .. grid-item-card:: Overview
+      :link: overview
+      :link-type: doc
+      :text-align: center
 
+      Overview of the package structure, design principles, and core classes — with
+      a focus on the :class:`~pyvisual.core.plot3d.Plot3d` class and its mixin components.
+
+.. toctree::
+    :hidden:
+    :maxdepth: 2
 
+    installation
+    overview

docs/source/guide/installation.rst

@@ -3,19 +3,112 @@
 Installation
 ============
 
+.. attention::
+
+    We highly recommend using a virtual environment to manage your
+    Python packages and avoid conflicts with other projects. For
+    the best results, we recommend using ``conda`` – *via* Miniforge
+    (preferred), Miniconda, or Anaconda – to create and manage
+    your virtual environments.
+
+To get started with **pyvisual**, you can install it directly from PyPI:
+
+.. code-block:: bash
+
+    pip install psi-pyvisual
+
 Requirements
 ------------
 
 **pyvisual** requires Python 3.10 or later and runs on Linux and macOS.
-The core dependencies — :mod:`numpy`, :mod:`pyvista`, :mod:`psi_io`,
-:mod:`sunpy`, and :mod:`astropy` — are installed automatically.
+
+Core Dependencies
+^^^^^^^^^^^^^^^^^
+
+The following packages are installed automatically:
+
+.. list-table::
+   :header-rows: 1
+   :widths: 18 12 70
+
+   * - Package
+     - Min. version
+     - Role in **pyvisual**
+   * - `NumPy <https://numpy.org/doc/stable/>`_
+     - —
+     - Array operations underpinning all coordinate transforms, mesh
+       construction, and data manipulation throughout the library.
+   * - `PyVista <https://docs.pyvista.org/>`_
+     - —
+     - 3-D rendering engine.  **pyvisual** subclasses
+       :class:`pyvista.Plotter` and uses PyVista mesh types
+       (:class:`~pyvista.PolyData`, :class:`~pyvista.StructuredGrid`,
+       :class:`~pyvista.RectilinearGrid`) as the primary data containers
+       for all visualizations.
+   * - `psi-io <https://predsci.com/doc/psi-io/guide/index.html>`_
+     - 2.0.6
+     - PSI library for reading HDF4/HDF5 model output files.  Provides
+       :func:`~psi_io.read_hdf_by_index` for loading subsets of coronal
+       data arrays by index, and is required for all examples that use
+       real PSI MAS model data.
+   * - `SunPy <https://docs.sunpy.org/>`_
+     - —
+     - Solar physics toolkit used for coordinate frame transformations
+       (e.g. Heliocentric Earth Ecliptic and Carrington frames) and
+       spacecraft ephemeris calculations that drive the observer
+       positioning utilities.
+   * - `Astropy <https://docs.astropy.org/>`_
+     - —
+     - Astronomical units, time handling, and coordinate infrastructure
+       underlying SunPy's frame system; used indirectly via SunPy for
+       JPL Horizons queries and observer geometry.
+
+Optional Dependencies
+^^^^^^^^^^^^^^^^^^^^^
+
+Install these via extras (see `Standard Install`_ below):
+
+.. list-table::
+   :header-rows: 1
+   :widths: 18 12 70
+
+   * - Package
+     - Min. version
+     - Role in **pyvisual**
+   * - `pyhdf <https://pypi.org/project/pyhdf/>`_
+     - 0.11.6
+     - HDF4 file support.  Required when PSI model data is stored in the
+       legacy ``.hdf`` format rather than HDF5.  Enabled by the
+       ``hdf4`` extra.
+   * - `SciPy <https://docs.scipy.org/doc/scipy/>`_
+     - —
+     - Interpolation routines for regridding or resampling data onto
+       non-native coordinate grids.  Enabled by the ``interp`` extra
+       (also pulled in by ``data``).
+   * - `mapflpy <https://predsci.com/doc/mapflpy/>`_
+     - 1.1.9
+     - PSI library for tracing magnetic fieldlines on spherical grids.
+       Provides :func:`~mapflpy.scripts.run_forward_tracing` and
+       :func:`~mapflpy.scripts.run_fwdbwd_tracing`, which feed directly
+       into :meth:`~pyvisual.core.mixins.StackMeshMixin.add_fieldlines`.
+       Enabled by the ``tracing`` extra.
+   * - `Pooch <https://www.fatiando.org/pooch/latest/>`_
+     - —
+     - Asset fetching and caching.  Powers
+       :func:`~pyvisual.utils.data.fetch_datasets`, which downloads
+       sample PSI MAS model files to ``~/.cache/psi/`` on first use.
+       Enabled by the ``data`` extra.
+   * - `Matplotlib <https://matplotlib.org/stable/>`_
+     - —
+     - Colour maps and scalar-bar rendering used internally by PyVista.
+       Pulled in automatically by the ``data`` extra.
 
 Standard Install
 ----------------
 
 Install the latest release from PyPI::
 
-    pip install pyvisual
+    pip install psi-pyvisual
 
 To include support for reading HDF4 files (``pyhdf``), fieldline tracing
 (``mapflpy``), scipy-based interpolation, or the data-fetching utilities,
@@ -38,7 +131,7 @@ use the relevant extras:
 
 Install one or more extras with::
 
-    pip install "pyvisual[hdf4,tracing]"
+    pip install "psi-pyvisual[hdf4,tracing]"
 
 Development Install
 -------------------

docs/source/guide/overview.rst

@@ -10,8 +10,8 @@ and maintained by `Predictive Science Inc. (PSI) <https://www.predsci.com/>`_ an
 is tightly coupled to the PSI data ecosystem — in particular
 `psi-io <https://predsci.com/doc/psi-io/guide/index.html>`_ (HDF4/HDF5 file I/O)
 and `mapflpy <https://predsci.com/doc/mapflpy/>`_ (magnetic fieldline tracing).
-Any rectilinear grid defined in spherical coordinates is compatible with the API,
-regardless of whether it originates from a PSI model.
+With that said, any rectilinear grid defined in spherical coordinates is compatible
+with the API.
 
 .. attention::
 
@@ -41,8 +41,24 @@ Cartesian frame (``'cartesian'``)
     Accepted aliases include ``'xyz'``, ``'cart'``, ``'rectilinear'``, and any
     permutation of the individual axis letters.
 
-Conversion between the two frames is handled transparently — methods that accept a
-``frame`` argument convert to Cartesian before passing data to PyVista.
+.. note::
+
+   **pyvisual** is principally concerned with rendering rectilinear spherical grids,
+   *viz.* those produced by PSI's MAS code; more specificially, this package is
+   designed to facilitate the visualization of such datasets by converting these
+   structured :math:`(r, \theta, \phi)` grids into the native Cartesian coordinate
+   system used by PyVista and VTK for rendering.
+
+   The coordinate system of the :class:`~pyvista.Plotter` is always a Cartesian
+   coordinate system in the Heliographic Carrington frame. Input data (however)
+   is generally expected to be in the spherical frame, and the API provides utilities for
+   converting between the two.
+
+   The spherical frame is used for all observer controls,
+   reference geometry, and mesh construction; the Cartesian frame is used for all
+   rendering and camera manipulation. The API abstracts away the details of converting
+   between the two, but it is important to understand the distinction when working with
+   the package.
 
 The Plotter: ``Plot3d``
 -----------------------
@@ -97,7 +113,27 @@ Mesh Classes
 ------------
 
 Two mesh classes are provided for loading and manipulating model data before
-adding it to a plotter.
+adding it to a plotter. These classes can be instantiated from an HDF file
+path, from raw coordinate and data arrays, or from an existing PyVista dataset.
+
+.. note::
+
+   When instantiating from an HDF filepath, the :mod:`psi-io` library is used
+   to read the file and extract the coordinate and data arrays by index.
+   As such, the file must be in a format compatible with :mod:`psi-io` (e.g. HDF4 with
+   Fortran-order arrays, or HDF5 with the same structure).
+
+   *It is generally
+   recommended to explicitly load the data arrays to ensure that the scales
+   and data-values are properly interpreted, rather than relying on the mesh
+   classes to infer them from the file.*
+
+The motivation behind these classes is to provide a convenient container for solar
+physics model data that can make full use of the powerful PyVista/VTK
+`Filters <https://docs.pyvista.org/api/core/filters.html>`_ (along with a few
+additional "filters" provided by **pyvisual** in the
+:class:`~pyvisual.core.mesh3d.CartesianMeshFilters` and
+:class:`~pyvisual.core.mesh3d.SphericalMeshFilters` mixin classes).
 
 :class:`~pyvisual.core.mesh3d.SphericalMesh`
     Wraps :class:`pyvista.RectilinearGrid` with a spherical-frame tag. Can be
@@ -111,6 +147,25 @@ adding it to a plotter.
     The Cartesian counterpart, wrapping :class:`pyvista.StructuredGrid`. It shares
     the same operator API as :class:`~pyvisual.core.mesh3d.SphericalMesh`.
 
+.. note::
+
+   The general motivation behind the latter class (in contrast to the :class:`~pyvisual.core.mesh3d.SphericalMesh`
+   class) is to facilitate the use of PyVista/VTK's
+   `filters <https://docs.pyvista.org/api/core/filters>`_ on spherical grids that have
+   been converted to Cartesian coordinates. This :func:`~pyvisual.utils.geometry.spherical_to_cartesian`
+   transformation yeilds topological structured meshes that are, nevertheless, not composed
+   of monotonically increasing coordinate arrays. Therefore, the grid's internal structure
+   has to be stored explicitly *viz.* through a :class:`pyvista.StructuredGrid` rather than a
+   :class:`pyvista.RectilinearGrid`.
+
+.. warning::
+
+   The consequence of the above note is that the point arrays of this class are
+   derived from a :func:`~numpy.meshgrid`-like Cartesian product of the input scales,
+   and are not stored as the three separate 1-D arrays that are typical of rectilinear grids.
+   As such, these grids can be substantially more memory-intensive than their
+   :class:`~pyvisual.core.mesh3d.SphericalMesh` counterparts.
+
 Both classes are available from the top-level package::
 
     from pyvisual import SphericalMesh, CartesianMesh

docs/source/index.rst

@@ -17,9 +17,51 @@ Because **pyvisual** renders through `PyVista <https://docs.pyvista.org/>`_ and
 it is strongly recommended to familiarise yourself with the PyVista documentation to
 get the most out of the package.
 
+**pyvisual** is in active development. Although the existing API will remain unchanged,
+additional quality-of-life improvements are forthcoming. Please direct any comments,
+concerns, or issues to the Predictive Science Inc. research team via the distro `Issue Tracker
+<https://github.com/predsci/pyvisual/issues>`_ or
+`contact form <https://www.predsci.com/portal/contact.php>`_.
+
+.. attention::
+
+   Please be aware that **pyvisual** is available through the Python Package Index (PyPI) as
+   ``psi-pyvisual``. Further installation instructions are available in the
+   `User Guide <https://predsci.com/doc/pyvisual/guide/index.html>`_.
+
+.. grid:: 3
+   :gutter: 2
+   :class-container: sd-mt-4
+
+   .. grid-item-card:: User Guide
+      :link: guide/index
+      :link-type: doc
+      :text-align: center
+
+      Installation instructions, coordinate conventions, and an architectural
+      overview of the :class:`~pyvisual.core.plot3d.Plot3d` class and its
+      mixin components.
+
+   .. grid-item-card:: Examples
+      :link: gallery/index
+      :link-type: doc
+      :text-align: center
+
+      Worked examples covering basic scenes, slicing, fieldlines, observer
+      controls, and the mesh class API — organized by functional area.
+
+   .. grid-item-card:: API Reference
+      :link: api/index
+      :link-type: doc
+      :text-align: center
+
+      Full API documentation for all public classes, methods, functions,
+      and type aliases auto-generated from source docstrings.
+
 .. toctree::
     :hidden:
+    :maxdepth: 2
 
-    API <api/index>
     Guide <guide/index>
-    Examples <gallery/index>
+    Examples <gallery/index>
+    API <api/index>

examples/01_getting_started/p03_loading_data.py

@@ -0,0 +1,80 @@
+"""
+Loading and Plotting MHD Data
+==============================
+
+This example introduces the two steps needed to go from a PSI data file to a
+rendered scene:
+
+1. **Fetching a dataset** — :func:`~pyvisual.utils.data.fetch_datasets`
+   downloads (or retrieves from cache) a version-pinned HDF5 file from the
+   PSI asset server and returns its local path.
+2. **Reading the data** — :func:`~psi_io.read_hdf_by_index` loads the array
+   values and the three coordinate grids :math:`(r, \\theta, \\phi)` from the
+   file.  Passing ``None`` for a dimension selects its full extent; passing an
+   integer index fixes that dimension to a single grid point.
+
+The dataset used here is the radial magnetic field :math:`B_r` from a
+Thermo 2 steady-state coronal simulation for Carrington Rotation 2282
+(CR 2282), covering the domain :math:`r \\in [1,\\,30]\\,R_\\odot`.
+"""
+
+from psi_io import read_hdf_by_index
+from pyvisual import Plot3d
+from pyvisual.utils.data import fetch_datasets
+
+# %%
+# Fetching a Dataset
+# ------------------
+#
+# :func:`~pyvisual.utils.data.fetch_datasets` accepts a *domain* identifier
+# (``'cor'`` for the coronal domain, ``'hel'`` for heliospheric) and a
+# *variable* name.  It returns a :class:`~collections.namedtuple` whose fields
+# are named ``"{domain}_{variable}"``.  The first call downloads the file to
+# the local cache; subsequent calls return the cached copy immediately without
+# hitting the network.
+
+datasets = fetch_datasets("cor", "br")
+br_file = datasets.cor_br
+
+# %%
+# Reading a 2-D Radial Slice
+# --------------------------
+#
+# :func:`~psi_io.read_hdf_by_index` reads the HDF5 file and returns
+# ``(data, r, t, p)`` — the scalar array followed by the three coordinate
+# vectors.  Index arguments control which portion of the grid is loaded:
+#
+# - ``None`` — load the full extent of that dimension.
+# - An integer ``i`` — fix that dimension to the ``i``-th grid point
+#   (1-based), collapsing it to a length-1 array.
+#
+# Here the colatitude is fixed at index 71 (the equatorial plane,
+# :math:`\theta_{71} \approx \pi/2`), while :math:`r` and :math:`\phi`
+# span their full extents.  The result is a 2-D surface in the equatorial
+# plane colored by :math:`B_r`.
+
+data, r, t, p = read_hdf_by_index(br_file, None, 71, None)
+
+plotter = Plot3d()
+plotter.show_axes()
+plotter.add_sun()
+plotter.add_2d_slice(r, t, p, data, cmap='seismic', clim=(-1, 1),
+                     show_scalar_bar=True)
+plotter.show()
+
+# %%
+# Scaling by :math:`r^2`
+# -----------------------
+#
+# The radial magnetic field falls off geometrically as :math:`1/r^2` with
+# distance.  Multiplying by :math:`r^2` removes this trend and reveals the
+# longitudinal structure of open-field regions at all radii — a common
+# diagnostic in solar wind modeling.  Because ``r`` is a plain NumPy array,
+# the scaling is a single element-wise operation before passing to the plotter.
+
+plotter = Plot3d()
+plotter.show_axes()
+plotter.add_sun()
+plotter.add_2d_slice(r, t, p, data * r ** 2, cmap='seismic', clim=(-1, 1),
+                     show_scalar_bar=True)
+plotter.show()