Installation

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:

pip install psi-pyvisual

To run the Examples suite, include the following add-ons:

pip install psi-pyvisual[tracing,data]

Requirements#

pyvisual requires Python 3.10 or later and runs on Linux and macOS.

Core Dependencies#

The following packages are installed automatically:

Package	Min. version	Role in pyvisual
NumPy	2.1.0	Array operations underpinning all coordinate transforms, mesh construction, and data manipulation throughout the library.
PyVista	0.46.0	3-D rendering engine. pyvisual subclasses `pyvista.Plotter` and uses PyVista mesh types (`PolyData`, `StructuredGrid`, `RectilinearGrid`) as the primary data containers for all visualizations.
psi-io	2.0.6	PSI library for reading HDF4/HDF5 model output files. Provides e.g. `read_hdf_by_index()` for loading subsets of HDF datasets by index (without having to load the entire file into memory), and is required for all examples that use PSI’s MAS model data.
SunPy	6.0.3	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	6.1.3	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):

Package	Min. version	Role in pyvisual
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	—	Interpolation routines for regridding or resampling data onto non-native coordinate grids. Enabled by the `interp` extra (also pulled in by `data`).
mapflpy	1.1.9	PSI library for tracing magnetic fieldlines on spherical grids. Provides `run_forward_tracing()` and `run_fwdbwd_tracing()`, which feed directly into `add_fieldlines()`. Enabled by the `tracing` extra.
Pooch	1.8.2	Asset fetching and caching. Powers `fetch_datasets()`, which downloads sample PSI MAS model files to `~/.cache/psi/` on first use. Enabled by the `data` extra.
Matplotlib	3.10.7	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 psi-pyvisual

To include support for reading HDF4 files (pyhdf), fieldline tracing (mapflpy), scipy-based interpolation, or the data-fetching utilities, use the relevant extras:

Extra	What it adds
`hdf4`	HDF4 file support via `pyhdf`
`interp`	Interpolation utilities via `scipy`
`tracing`	Magnetic fieldline tracing via `mapflpy`
`data`	Asset fetching via `pooch`; also installs `scipy` and `matplotlib`

Install one or more extras with:

pip install "psi-pyvisual[hdf4,tracing]"

Development Install#

Clone the repository and install in editable mode with all optional dependencies:

git clone https://github.com/predsci/pyvisual.git
cd pyvisual
pip install -e ".[all]"

Verify the installation by importing the package:

python -c "import pyvisual; print(pyvisual.__version__)"

Development tools#

Command	Purpose
`ruff check .`	Linting
`mypy .`	Type checking
`pytest`	Test suite
`pytest --cov`	Tests with coverage report
`cd docs && make html`	Build HTML documentation