Release 1.0.0

.circleci/config.yml

@@ -83,7 +83,7 @@ jobs:
           command: |
             pip install ".[docs]"
             cd docs/
-            make html
+            make html SPHINXOPTS="-W"
 
   test_deprecation_warnings:
     parameters:
@@ -165,43 +165,44 @@ workflows:
           matrix:
             parameters:
               version:
-                - "3.10"
                 - "3.11"
                 - "3.12"
                 - "3.13"
+                - "3.14"
 
       - ruff:
           matrix:
             parameters:
               version:
-                - "3.13"
+                - "3.14"
           requires:
             - build_and_test
 
       - test_documentation_build:
           matrix:
             parameters:
               version:
-                - "3.13"
+                - "3.14"
           requires:
             - build_and_test
 
       - test_deprecation_warnings:
           matrix:
             parameters:
               version:
-                - "3.13"
+                - "3.14"
           requires:
             - build_and_test
 
       - test_pypi_publish:
           matrix:
             parameters:
               version:
-                - "3.13"
+                - "3.14"
           requires:
             - build_and_test
 
+
   test_and_publish:
     # Test and publish on new git version tags
     # This requires its own workflow to successfully trigger the test and build
@@ -210,10 +211,10 @@ workflows:
           matrix:
             parameters:
               version:
-                - "3.10"
                 - "3.11"
                 - "3.12"
                 - "3.13"
+                - "3.14"
 
           filters:
             branches:
@@ -226,7 +227,7 @@ workflows:
           matrix:
             parameters:
               version:
-                - "3.13"
+                - "3.14"
           requires:
             - build_and_test
           filters:
@@ -240,7 +241,7 @@ workflows:
           matrix:
             parameters:
               version:
-                - "3.13"
+                - "3.14"
           requires:
             - build_and_test
           filters:
@@ -254,7 +255,7 @@ workflows:
           matrix:
             parameters:
               version:
-                - "3.13"
+                - "3.14"
           requires:
             - build_and_test
           filters:
@@ -268,7 +269,7 @@ workflows:
           matrix:
             parameters:
               version:
-                - "3.13"
+                - "3.14"
           requires:
             - build_and_test
             - ruff

.editorconfig

@@ -19,6 +19,3 @@ end_of_line = crlf
 
 [LICENSE]
 insert_final_newline = false
-
-[Makefile]
-indent_style = tab

.gitignore

@@ -111,6 +111,10 @@ venv.bak/
 # macOS
 .DS_Store
 
+# external data that is loaded from the web
+spharpy/samplings/_eqsp/samplings_extremal*
+spharpy/samplings/_eqsp/samplings_t_design*
+
 # workaround for failing test discovery in vscode
 tests/*/__init__.py
 tests/private/
@@ -120,4 +124,8 @@ docs/header.rst
 docs/_static/favicon.ico
 docs/_static/header.rst
 docs/_static/css/custom.css
+docs/_static/js/custom.js
 docs/resources/logos/pyfar_logos_fixed_size_spharpy.png
+
+# ignore plot output
+tests/test_plot_data/output/

.readthedocs.yml

@@ -20,7 +20,7 @@ sphinx:
 formats:
   - pdf
 
-# Optionally set the version of Python and requirements required to build your docs
+# use pip to install dependencies
 python:
   install:
     - method: pip

HISTORY.rst

@@ -2,6 +2,104 @@
 History
 =======
 
+1.0.0 (2026-03-16)
+------------------
+
+.. warning::
+
+    ``spharpy`` version 1.0.0 introduces several breaking changes which are not backwards compatible with prior versions.
+    These changes harmonize the package with the pyfar ecosystem. Basic functionality such as the ``Coordinates`` class are fully moved to the ``pyfar`` package which serves as a common base for all packages of the ecosystem.
+
+
+Breaking changes
+^^^^^^^^^^^^^^^^
+
+- ``RotationSH`` has been re-designed. Changes include
+
+  - ``RotationSH`` has been renamed to ``SphericalHarmonicRotation``
+  - The class no longer inherits from ``scipy.spatial.transform.Rotation``, instead it inherits from ``pyfar.Rotation``, which is based on ``scipy.spatial.transform.Rotation`` using composition. This was necessary due to the re-write of ``scipy.spatial.transform.Rotation`` in scipy v1.17.0.
+  - The class no longer stores spherical harmonic orders, instead a ``SphericalHarmonicDefinition`` object is required when calling the respective class method to calculate the spherical harmonic rotation matrix.
+
+- Removed the class ``spharpy.samplings.Coordinates``. Instead, refer to ``pyfar.Coordinates`` for storing coordinates. All functions which previously used ``spharpy.samplings.Coordinates`` now use ``pyfar.Coordinates``.
+- ``spharpy.SamplingSphere`` has been rewritten and now implements checks if
+
+  - all points are placed on the same radius, given a specified tolerance,
+  - the area weights sum correctly to the integral of the unit sphere, if they are not ``None``.
+
+- The ``indexing`` module has been removed, and the functionality has been moved to the ``spherical`` module.
+
+  - In ``spharpy.spherical.sph_identity_matrix`` the argument ``type`` has been renamed to ``matrix_type`` to avoid conflict with the built-in ``type`` function.
+
+- In the ``spherical`` module, the functions
+
+  - ``acn2nm`` and ``nm2acn`` have been renamed to ``acn_to_nm`` and ``nm_to_acn``, respectively.
+
+- The ``spharpy.plot`` module has been re-written and now has a more consistent API with the ``pyfar.plot`` module
+
+  - Added support for pyfar's plot styles.
+  - Add support for always passing and returning ``matplotlib.axes.Axes`` objects to all plotting functions, which allows for more flexible plotting and composition of plots.
+  - Always return matplotlib ``Colorbar`` and mappables for each plot, which is consistent with the ``pyfar.plot`` module.
+  - Omit the implicit interpolation of data in the map projection plots. Users should now explicitly interpolate the data to a regular grid using ``spharpy.interpolate.griddata`` or similar functions before plotting if necessary.
+
+- The ``spharpy.samplings`` module has been re-written
+
+  - ``spharpy.samplings.cube_equidistand`` has been renamed to ``spharpy.samplings.equidistant_cuboid``
+  - ``spherical_t_design`` has been renamed to ``t_design``
+  - ``equalarea`` has been renamed to ``equal_area``
+  - All functions now return a refactored ``spharpy.SamplingSphere`` object.
+  - In the ``spharpy.samplings.utils`` module, the helper functions ``cart2sph``, ``latlon2cart``, and ``sph2cart`` have been removed, since they were moved to ``pyfar``.
+  - The function ``spharpy.samplings.utils.cart2latlon`` has been refactored to use a ``pyfar.Coordinates`` (or child class) object as input instead of an array containing cartesian coordinates.
+
+Changed:
+^^^^^^^^
+
+- Removed support for Python 3.10 and earlier.
+- Require pyfar >= 0.8.0.
+- Require scipy >= 1.17.0.
+- The ``special`` and ``spatial`` sub-modules are now directly imported as ``spharpy.special`` and ``spharpy.spatial``.
+- Extended documentation and added examples for all functions in the following modules
+
+  - ``beamforming``
+  - ``spatial``
+  - ``interpolate``
+  - ``special``
+  - ``spherical``
+
+Added:
+^^^^^^
+
+- ``spharpy.SphericalHarmonicDefintion``: A class encapsulating parameters for the definition of spherical harmonics.
+- ``spharpy.SphericalHarmonics``: A class to lazily compute the spherical harmonics for a given definition and coordinates. For ``spharpy.SamplingSphere`` the class also calculates inverse basis matrices.
+- ``spharpy.SphericalHarmonicSignal``, ``spharpy.SphericalHarmonicFrequencyData``, and ``spharpy.SphericalHarmonicTimeData``: classes to store audio data in the spherical harmonic domain. These classes are derived from ``pyfar.Signal``, ``pyfar.FrequencyData``, and ``pyfar.TimeData`` respectively, and thus support all methods implemented for these classes.
+- Added support for the following parametrization of the functions for calculation of spherical harmonics defined in the ``spharpy.spherical`` module:
+
+  - normalizations (N3D, SN3D, NM, SNM, and  maxN),
+  - the Condon-Shortley phase convention,
+  - the ACN and FuMa channel ordering convention.
+
+- Added ``spharpy.spherical.renormalize`` function to convert between different spherical harmonic normalization schemes.
+- Added ``spharpy.spherical.change_channel_convention`` to convert between different channel ordering conventions.
+- Added functions ``nm_to_fuma`` and ``fuma_to_nm`` to convert to and from FuMa channel ordering
+- Shared plot preparation in the ``spharpy.plot`` module, which is used by all plot functions.
+- Tests for all plots and baseline images for manual comparison of the plots in the test suite.
+- Added the following spherical sampling grids:
+
+  - ``spharpy.samplings.lebedev``
+  - ``spharpy.samplings.equal_angle``
+  - ``spharpy.samplings.great_circle``
+  - ``spharpy.samplings.fliege``
+
+- Added a read-only property ``spharpy.SamplingSphere.quadrature`` which can be used to check if the sampling is a valid quadrature grid.
+
+Documentation
+^^^^^^^^^^^^^
+- Extended documentation and added examples for all functions in the following modules:
+  - `beamforming`,
+  - `spatial`,
+  - `interpolate`,
+  - `special`,
+  - `spherical`,
+
 0.6.3 (2026-03-16)
 ------------------
 - Remove support for Python 3.8. (PR #111)

README.md

@@ -24,7 +24,7 @@ Use pip to install spharpy
 
     pip install spharpy
 
-(Requires Python 3.10 or higher)
+(Requires Python 3.11 or higher)
 
 Audio file reading/writing is supported through [SoundFile](https://python-soundfile.readthedocs.io), which is based on
 [libsndfile](http://www.mega-nerd.com/libsndfile/). On Windows and OS X, it will be installed automatically.

docs/api_reference.rst

@@ -10,18 +10,37 @@ For examples on how to use spharpy refer to the notebooks in the
 `examples gallery`_ and the documentation on classes and modules below.
 
 
+Definitions
+-----------
+
+.. toctree::
+   :maxdepth: 1
+
+   theory/spherical_harmonic_definition
+
+
+Classes
+-------
+
+.. toctree::
+   :maxdepth: 1
+
+   classes/spharpy.spherical_harmonics
+   classes/spharpy.audio
+   classes/spharpy.coordinates
+
 Modules
 -------
 
 .. toctree::
    :maxdepth: 1
 
    modules/spharpy.beamforming
-   modules/spharpy.indexing
    modules/spharpy.interpolate
    modules/spharpy.plot
    modules/spharpy.samplings
    modules/spharpy.spatial
+   modules/spharpy.special
    modules/spharpy.spherical
    modules/spharpy.transforms
 

docs/classes/spharpy.audio.rst

@@ -0,0 +1,26 @@
+Audio (Signal, TimeData, FrequencyData)
+---------------------------------------
+.. automodule:: spharpy.classes.audio
+
+**Classes:**
+
+.. autosummary::
+
+   SphericalHarmonicFrequencyData
+   SphericalHarmonicTimeData
+   SphericalHarmonicSignal
+
+.. autoclass:: spharpy.SphericalHarmonicSignal
+   :members:
+   :undoc-members:
+   :inherited-members:
+
+.. autoclass:: spharpy.SphericalHarmonicTimeData
+   :members:
+   :undoc-members:
+   :inherited-members:
+
+.. autoclass:: spharpy.SphericalHarmonicFrequencyData
+   :members:
+   :undoc-members:
+   :inherited-members:

docs/classes/spharpy.coordinates.rst

@@ -0,0 +1,9 @@
+SamplingSphere
+--------------
+
+.. automodule:: spharpy.classes.coordinates
+
+.. autoclass:: spharpy.SamplingSphere
+   :members:
+   :undoc-members:
+   :inherited-members:

docs/classes/spharpy.spherical_harmonics.rst

@@ -0,0 +1,21 @@
+SphericalHarmonics
+------------------
+
+.. automodule:: spharpy.classes.sh
+
+**Classes:**
+
+.. autosummary::
+
+   SphericalHarmonicDefinition
+   SphericalHarmonics
+
+.. autoclass:: spharpy.SphericalHarmonicDefinition
+   :members:
+   :undoc-members:
+   :inherited-members:
+
+.. autoclass:: spharpy.SphericalHarmonics
+   :members:
+   :undoc-members:
+   :inherited-members: