3D solar-physics visualization for MHD datasets
pyvisual is developed and maintained by Predictive Science Inc. (PSI). It wraps PyVista's Plotter class with specialized capabilities
for visualizing solar and magnetohydrodynamic (MHD) model output defined on
spherical coordinate systems. The package is tightly coupled to the PSI data
ecosystem and is tuned for use with psi-io and mapflpy.
- Spherical-coordinate rendering — meshes and coordinate arrays in (r, \theta, \phi) are converted to Cartesian automatically before being passed to the VTK render pipeline.
- Structured-grid slices — add 1-D line slices, 2-D surface slices, and 3-D volume slices directly from independent axis arrays.
- Fieldline rendering — visualize open/closed magnetic fieldline topology with polarity coloring or random hue assignment.
- Observer controls — set and query camera position, focal point, position angle, and line-of-sight field-of-view in spherical coordinates.
- Solar geometry primitives — Sun sphere, concentric shells, planar discs, Thomson sphere, and lon/lat grid lines.
- Mesh arithmetic —
SphericalMeshandCartesianMeshsupport the full NumPy arithmetic operator suite and__array_ufunc__so expressions likenp.log10(mesh)return a new mesh of the same type. - PSI HDF support — load model data directly from HDF4/HDF5 files written
by the MAS code via
psi-io.
Core dependencies (NumPy, PyVista, psi-io, SunPy, Astropy) are installed automatically:
pip install pyvisualOptional extras:
pip install "pyvisual[hdf4]" # HDF4 file support via pyhdf
pip install "pyvisual[interp]" # scipy interpolation utilities
pip install "pyvisual[tracing]" # mapflpy fieldline tracing
pip install "pyvisual[data]" # pooch asset fetching + matplotlib
pip install "pyvisual[all]" # everythingDevelopment install:
git clone https://bitbucket.org/predsci/pyvisual.git
cd pyvisual
pip install -e ".[all]"import pyvisual as pv
import numpy as np
pl = pv.Plot3d()
# Add the Sun (radius 1 R☉, centred at the origin)
pl.add_sun()
# Add a 2-D equatorial slice at r = [1, 5] R☉, θ = π/2
r = np.linspace(1, 5, 50)
t = np.array([np.pi / 2]) # fix colatitude at the equator
p = np.linspace(0, 2 * np.pi, 200)
pl.add_2d_slice(r, t, p)
# Add lon/lat grid lines just above the Sun's surface
pl.add_longlat_lines(lat_deg=30, lon_deg=30, radius=1.01)
pl.show()Plot3d extends pyvista.Plotter through four mixin classes:
Two structured-grid mesh classes carry PSI HDF data and plug directly into
Plot3d.add_mesh:
SphericalMesh(pyvista.RectilinearGrid) — stores data on an (r, \theta, \phi) grid; axes are accessible as.r,.t,.p.CartesianMesh(pyvista.StructuredGrid) — stores data on an (x, y, z) grid; supports the same arithmetic interface.
Full API reference, gallery examples, and guides are published at:
https://predsci.com/doc/pyvisual/
To build the documentation locally:
pip install "pyvisual[docs]"
cd docs && make html
# output: docs/_build/html/index.html# Linting
ruff check .
# Type checking
mypy .
# Tests
pytest
pytest --cov # with coverage reportSolar model data is stored in HDF4 or HDF5 files written in Fortran-order array layout. The PSI conventions for these files are documented at:
Spherical coordinates follow the PSI (r, \theta, \phi) convention — radius, colatitude, longitude — which differs from the physics (r, \phi, \theta) convention used in some other codes.
Apache License 2.0. See LICENSE.txt for details.
- Ryder Davidson — Predictive Science Inc.
- Cooper Downs — Predictive Science Inc.
- Andres Reyes — Predictive Science Inc.