SolarWindPy

A Python Library for in situ solar wind data analysis.

Quick Start

After installation, import the package and create a plasma object with sample data:

>>> import pandas as pd
>>> from solarwindpy.core.plasma import Plasma

>>> # Create sample solar wind data (3 time points)
>>> epoch = pd.date_range('2023-01-01', periods=3, freq='1h')
>>> columns = pd.MultiIndex.from_tuples([
...     ('n', '', 'p1'), ('n', '', 'a'),           # Number density
...     ('v', 'x', 'p1'), ('v', 'x', 'a'),         # Velocity components
...     ('v', 'y', 'p1'), ('v', 'y', 'a'),
...     ('v', 'z', 'p1'), ('v', 'z', 'a'),
...     ('w', 'par', 'p1'), ('w', 'par', 'a'),     # Thermal speeds
...     ('w', 'per', 'p1'), ('w', 'per', 'a'),
...     ('b', 'x', ''), ('b', 'y', ''), ('b', 'z', '')  # Magnetic field
... ], names=['M', 'C', 'S'])

>>> # Realistic solar wind values
>>> data = pd.DataFrame([
...     [5.0, 0.25, 400, 380, 10, 5, -20, -15, 30, 15, 25, 12, 3.5, -1.2, 0.8],
...     [8.0, 0.40, 450, 420, 15, 8, -25, -18, 35, 18, 28, 14, 4.1, -1.5, 1.2],
...     [7.1, 0.30, 420, 400, 12, 6, -22, -16, 32, 16, 26, 13, 3.8, -1.3, 0.9],
... ], index=epoch, columns=columns)

>>> # Create plasma object with protons and alphas
>>> plasma = Plasma(data, 'p1', 'a')

>>> # Access ion species
>>> print(plasma.species)
('a', 'p1')

>>> # Mean proton density: (5.0 + 8.0 + 7.1) / 3 = 6.7
>>> print(f"Proton density: {plasma.p1.n.mean():.1f} cm⁻³")
Proton density: 6.7 cm⁻³

See the documentation for the quickstart, usage examples and the API reference.

Installation

The supported Python versions and dependency ranges are declared in pyproject.toml (requires-python and dependencies); the PyPI page shows them for each published release.

SolarWindPy is available via PyPI and conda-forge:

User

Install from PyPI:

pip install solarwindpy

Or install from conda-forge:

conda install -c conda-forge solarwindpy

Development

1. Fork the repository and clone your fork.

2. Install development dependencies:

   git clone https://github.com/YOUR-USERNAME/SolarWindPy.git
   cd SolarWindPy
   pip install -e ".[dev]"  # Includes all dev tools

   Alternative (Conda environment):

   conda env create -f solarwindpy.yml
   conda activate solarwindpy
   pip install -e ".[dev]"

3. Run the test suite with pytest:

   pytest -q

Note: pyproject.toml is the only dependency declaration; there are no lockfiles.

4. Optionally install the pre-commit hooks:

   pre-commit install

   Each commit then runs the hooks that .pre-commit-config.yaml lists, and that file is the full list. Expect a commit that stages a .py file to run the full test suite.

5. Build the documentation and fail on warnings:

   cd docs
   make html SPHINXOPTS="-W --keep-going -n"

Code of Conduct

SolarWindPy follows the Contributor Covenant, version 2.1. See CODE_OF_CONDUCT.md. Report concerns to blaltermanphd@gmail.com.

License

SolarWindPy is licensed under a standard 3-clause BSD license. See LICENSE.

How to cite

If SolarWindPy contributes to published work, please cite it:

@software{Alterman_SolarWindPy,
  author    = {Alterman, B. L.},
  title     = {SolarWindPy},
  publisher = {Zenodo},
  doi       = {10.5281/zenodo.17042839},
  url       = {https://doi.org/10.5281/zenodo.17042839}
}

Please cite this all-versions DOI rather than a single release's DOI, and give the version you used in your text. See CITATION.rst for details. GitHub's "Cite this repository" button reads the same metadata from CITATION.cff.