PlasmaPy v2023.10.0 (2023-10-20)

Backwards Incompatible Changes

• Renamed the plasmapy.dispersion.dispersionfunction module to plasmapy.dispersion.dispersion_functions. Both of plasma_dispersion_func and plasma_dispersion_func_deriv are temporarily still available, but will issue a PlasmaPyFutureWarning and will be removed in a subsequent release. (#2271)

• Removed the lite-functions for plasma_dispersion_func and plasma_dispersion_func_deriv. Instead, the performance of the original functions has been improved by using a try and except block instead of having multiple if statements to check for preconditions. (#2361)

• Providing a real number to the charge parameter in CustomParticle will now result in a InvalidParticleError instead of a deprecation warning. Now, charge must be a Quantity with units of electrical charge. To express the charge as a multiple of the elementary charge, provide a real number to the Z parameter instead. (#2369)

Features

• Added the HarrisSheet class to calculate magnetic field, current density, and plasma pressure for 1D Harris sheets. (#2068)

• Added module plasmapy.dispersion.analytical.mhd_waves_ with classes for storing and calculating parameters of magnetohydrodynamic waves. (#2206)

• Added the plasmapy.analysis.time_series.conditional_averaging module including the ConditionalEvents class for calculating the conditional average and variance of time series. (#2275)

• Added the ForceFreeFluxRope class to calculate magnetic field for the Lundquist solution for force-free cylindrical equilibria. (#2289)

Bug Fixes

• Fixed a bug that had been causing incorrect results in temp_ratio. (#2248)

• Enabled the time_step parameter in ExcessStatistics class to be a Quantity with a unit. (#2300)

Improved Documentation

• Updated the code contribution workflow in the Contributor Guide to describe how to use git pull. (#2193)

• Expanded the troubleshooting section of the Documentation Guide to describe how to resolve warnings related to documents not being included in any toctrees. (#2257)

• Added a step to the code contribution workflow about using git status to verify that there have been no changes to tracked files before creating and switching to a new branch. (#2263)

• Added a page to the Contributor Guide about pre-commit, including how to troubleshoot test failures. (#2265)

• Added CONTRIBUTING.md to PlasmaPy’s GitHub repository. This page refers contributors to PlasmaPy’s Contributor Guide. (#2266)

• Enabled the sphinx.ext.duration extension to show the times required to process different pages during documentation builds. (#2268)

• Enabled the sphinx.ext.viewcode extension for adding links in the documentation to pages containing the source code. (#2269)

• Moved definitions of certain reStructuredText substitutions from docs/common_links.rst to the file docs/contributing/doc_guide.rst in order to speed up the documentation build (see #2277). (#2272)

• Implemented sphinxcontrib-globalsubs to enable global reStructuredText substitutions to be used throughout the documentation, and moved the definition of substitutions from docs/common_links.rst to the global_substitutions dict in docs/_global_substitutions.py. (#2281)

• Changed from astropy import units as u to import astropy.units as u and from astropy import constants as const to import astropy.constants as const throughout the code in order to increase consistency of import statements. (#2282)

• Added and applied nbqa-ruff to our suite of pre-commit hooks so that ruff can perform code quality checks on our example notebooks. (#2302)

• Renamed docs/cff_to_rst.py to docs/_cff_to_rst.py, and updated the functionality contained within that file for converting author information in CITATION.cff into a reStructuredText author list to be included in the documentation. (#2307)

• Fixed broken hyperlinks and reStructuredText references. (#2308)

• Replaced from plasmapy.particles import * in docs/notebooks/getting_started/particles.ipynb with imports of the actual functions and classes that were used. (#2311)

• Applied minor refactorings and formatting improvements to docs/notebooks/dispersion/stix_dispersion.ipynb. (#2312)

• Updated the Coding Guide by discussing when to use aliases and applied the :py: role so that in-line code gets formatted the same as Python code blocks. (#2324)

• Updated the docstrings and type hint annotations in plasmapy.formulary.lengths. (#2356)

• Refactored docs/conf.py to improve organization. (#2363)

• Updated the narrative documentation on particle objects to include CustomParticle, DimensionlessParticle, and ParticleList objects. (#2377)

Trivial/Internal Changes

• Modernized MANIFEST.in. (#2189)

• Applied automated refactorings from Sourcery. (#2219)

• Distributions defined in the distribution module will now raise a ValueError for an improper units parameter. (#2229)

• Added “decorators” section to the Coding Guide. (#2231)

• Improved the error message issued by Alfven_speed when the argument provided to density has a physical type of number density and ion is not provided. (#2262)

• Exposed plasmapy.dispersion.analytical and plasmapy.dispersion.numerical to the plasmapy.dispersion namespace. (#2271)

• Expanded the ruff settings to include more linter rules. (#2295)

• Added ruff linter rules that check for print and pprint, as the logging library is generally preferred for production code. (#2296)

• Updated and corrected author information in CITATION.cff. (#2307)

• Reduced the number of warnings emitted by plasmapy.particles during tests by decorating test functions with pytest.mark.filterwarnings. (#2314)

• Fixed a pytest deprecation warning that had been issued by plasmapy.utils._pytest_helpers/pytest_helpers.run_test so that None is no longer passed to the pytest.warns context manager. (#2314)

• Changed the default configuration for pytest so that if a test is marked as expected to fail actually passes, then that test will issue an error to indicate that the pytest.mark.xfail mark can be removed. (#2315)

• Added a weekly linkcheck test that verifies that hyperlinks in the documentation are up-to-date. (#2328)

• Enabled validate_quantities() to accept annotations of the form u.Quantity[u.m], where we have previously run import astropy.units as u. (#2346)

• Both plasma_dispersion_func and plasma_dispersion_func_deriv now allow inf and nan arguments without raising a ValueError. (#2361)

• Modified the charge_number attribute of CustomParticle to return a real number rather than a dimensionless Quantity. (#2377)

• Made minor updates to plasmapy/__init__.py, including to the top-level package docstring. (#2378)

• Improved the consistency and specificity of the names of various GitHub Actions. (#2379)

• Added a pre-commit hook to validate GitHub Actions. (#2380)