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:
@@ -202,6 +202,7 @@ workflows:
           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

.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

docs/api_reference.rst

@@ -10,18 +10,26 @@ For examples on how to use spharpy refer to the notebooks in the
 `examples gallery`_ and the documentation on classes and modules below.
 
 
+Classes
+-------
+
+.. toctree::
+   :maxdepth: 1
+
+   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.coordinates.rst

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

docs/conf.py

@@ -12,8 +12,7 @@
 import shutil
 import numpy as np
 sys.path.insert(0, os.path.abspath('..'))
-
-import spharpy  # noqa
+import spharpy  # noqa: E402
 
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
@@ -37,10 +36,6 @@
 # package
 autodoc_default_options = {'autosummary': True}
 
-# show the code of plots that follows the command .. plot:: based on the
-# package matplotlib.sphinxext.plot_directive
-plot_include_source = True
-
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 
@@ -84,12 +79,19 @@
 # If true, '()' will be appended to :func: etc. cross-reference text.
 add_function_parentheses = False
 
+# If true, '()' will be appended to :func: etc. cross-reference text.
+add_function_parentheses = False
+
 # If true, `todo` and `todoList` produce output, else they produce nothing.
 todo_include_todos = False
 
 # default language for highlighting in source code
 highlight_language = "python3"
 
+# show the code of plots that follows the command .. plot:: based on the
+# package matplotlib.sphinxext.plot_directive
+plot_include_source = True
+
 # intersphinx mapping
 intersphinx_mapping = {
     'numpy': ('https://numpy.org/doc/stable/', None),

docs/modules/spharpy.indexing.rst → docs/modules/spharpy.special.rst

@@ -1,7 +1,7 @@
-spharpy.indexing
-================
+spharpy.special
+---------------
 
-.. automodule:: spharpy.indexing
+.. automodule:: spharpy.special
    :members:
    :special-members: __init__
    :undoc-members:

examples/general_beamforming_weights.ipynb

@@ -7,6 +7,7 @@
    "outputs": [],
    "source": [
     "import numpy as np\n",
+    "import pyfar as pf\n",
     "import spharpy\n",
     "import matplotlib.pyplot as plt\n",
     "from matplotlib.collections import LineCollection\n",
@@ -51,7 +52,9 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# Analytic Plane Wave"
+    "# Beamforming\n",
+    "\n",
+    "The directional component of a plane wave can be expanded as a Fourier series using the spherical harmonics."
    ]
   },
   {
@@ -61,17 +64,10 @@
    "outputs": [],
    "source": [
     "N = 7\n",
-    "doa = spharpy.samplings.Coordinates(-1,0,0)\n",
+    "doa = pf.Coordinates(-1,0,0)\n",
     "p_nm = spharpy.spherical.spherical_harmonic_basis_real(N, doa)"
    ]
   },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "# Beamforming"
-   ]
-  },
   {
    "cell_type": "code",
    "execution_count": null,
@@ -80,7 +76,7 @@
    "source": [
     "n_dirs = 1024\n",
     "azi = np.linspace(0, 2*np.pi, n_dirs)\n",
-    "steering_directions = spharpy.samplings.Coordinates.from_spherical(np.ones(n_dirs), np.ones(n_dirs)*np.pi/2, azi)\n",
+    "steering_directions = pf.Coordinates.from_spherical_colatitude(azi, np.ones(n_dirs)*np.pi/2, 1)\n",
     "Y_steering = spharpy.spherical.spherical_harmonic_basis_real(N, steering_directions)"
    ]
   },
@@ -220,7 +216,7 @@
    "source": [
     "h_n = spharpy.beamforming.normalize_beamforming_weights(\n",
     "    hann(2*(N+1)+1)[N+1:-1], N)\n",
-    "h_nm = spharpy.indexing.sph_identity_matrix(N).T @ h_n\n",
+    "h_nm = spharpy.spherical.sph_identity_matrix(N).T @ h_n\n",
     "hanning = np.squeeze(Y_steering @ np.diag(h_nm) @ p_nm.T)"
    ]
   },

examples/plane_wave_decomposition.ipynb

@@ -7,7 +7,7 @@
    "outputs": [],
    "source": [
     "import spharpy\n",
-    "from spharpy.samplings import Coordinates\n",
+    "from pyfar import Coordinates\n",
     "import numpy as np\n",
     "import matplotlib.pyplot as plt\n",
     "from matplotlib.colorbar import Colorbar\n",
@@ -66,7 +66,7 @@
     "plt.figure(figsize=(16, 4))\n",
     "ax = plt.subplot(1, 2, 1)\n",
     "n_max = 4\n",
-    "mask = spharpy.spherical.nm2acn(np.arange(0, n_max+1), np.zeros(n_max+1))\n",
+    "mask = spharpy.spherical.nm_to_acn(np.arange(0, n_max+1), np.zeros(n_max+1))\n",
     "ax.plot(kr, 10*np.log10(np.abs(np.diagonal(B_open, axis1=1, axis2=2)[:, mask])))\n",
     "plt.grid(True)\n",
     "ax.set_ylabel('Magnitude in dB')\n",
@@ -75,7 +75,7 @@
     "ax.set_title('Open Sphere')\n",
     "ax.set_ylim((-20, 15))\n",
     "ax = plt.subplot(1, 2, 2)\n",
-    "mask = spharpy.spherical.nm2acn(np.arange(0, n_max+1), np.zeros(n_max+1))\n",
+    "mask = spharpy.spherical.nm_to_acn(np.arange(0, n_max+1), np.zeros(n_max+1))\n",
     "ax.plot(kr, 10*np.log10(np.abs(np.diagonal(B_rigid, axis1=1, axis2=2)[:, mask])))\n",
     "plt.grid(True)\n",
     "ax.set_ylabel('Magnitude in dB')\n",
@@ -100,7 +100,7 @@
     "\n",
     "p_nm = B @ plane_wave_density.T.conj()\n",
     "\n",
-    "sphere = spharpy.samplings.hyperinterpolation(30)\n",
+    "sphere = spharpy.samplings.hyperinterpolation(n_max=30)\n",
     "Y_sphere = spharpy.spherical.spherical_harmonic_basis(n_max, sphere)\n",
     "\n",
     "p_sphere =  np.squeeze(Y_sphere @ p_nm)"
@@ -130,7 +130,7 @@
     "\n",
     "$$ \\mathbf{a}(k) = \\frac{4\\pi}{(N+1)^2}\\mathbf{Y_s}^H \\mathbf{B}^{-1} \\mathbf{p_{nm}}$$\n",
     "\n",
-    "with the steering matrix $ \\mathbf{Y_s} $"
+    "with the steering matrix $\\mathbf{Y_s}$"
    ]
   },
   {
@@ -151,7 +151,7 @@
    "outputs": [],
    "source": [
     "plt.figure(figsize=(10, 4))\n",
-    "spharpy.plot.contour(steering_directions, np.abs(plane_wave_density))"
+    "spharpy.plot.contour_map(steering_directions, np.abs(plane_wave_density), projection='mollweide')"
    ]
   }
  ],
@@ -174,7 +174,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.9.10"
+   "version": "3.9.16"
   }
  },
  "nbformat": 4,

examples/spherical_harmonics.ipynb

@@ -7,7 +7,7 @@
    "outputs": [],
    "source": [
     "import spharpy\n",
-    "from spharpy.samplings import Coordinates\n",
+    "from pyfar import Coordinates\n",
     "import numpy as np\n",
     "import matplotlib.pyplot as plt\n",
     "import matplotlib as mpl\n",
@@ -24,7 +24,7 @@
     "    fig = plt.figure(figsize=(12, 8))\n",
     "    gs = plt.GridSpec(4, 5, height_ratios=[1, 1, 1, 0.1], width_ratios=[1, 1, 1, 1, 1])\n",
     "    for acn in range((n_max+1)**2):\n",
-    "        n, m = spharpy.spherical.acn2nm(acn)\n",
+    "        n, m = spharpy.spherical.acn_to_nm(acn)\n",
     "        idx_m = int(np.floor(n_max/2+1)) + m\n",
     "        ax = plt.subplot(gs[n, idx_m], projection='3d')\n",
     "        balloon = spharpy.plot.balloon_wireframe(sampling, Y[:, acn], phase=True, colorbar=False, ax=ax)\n",
@@ -76,7 +76,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "sampling = spharpy.samplings.equalarea(25, condition_num=np.inf)\n",
+    "sampling = spharpy.samplings.equal_area(25, condition_num=np.inf)\n",
     "plt.figure(figsize=(7, 7))\n",
     "spharpy.plot.scatter(sampling)"
    ]
@@ -188,7 +188,7 @@
    "outputs": [],
    "source": [
     "n_points = 128\n",
-    "circle = Coordinates.from_spherical(np.ones(n_points), np.full(n_points, np.pi/2), np.linspace(0, 2*np.pi, n_points))\n",
+    "circle = Coordinates.from_spherical_colatitude(np.linspace(0, 2*np.pi, n_points), np.pi/2, 1)\n",
     "Y_real_circle = spharpy.spherical.spherical_harmonic_basis_real(n_max, circle)"
    ]
   },
@@ -277,7 +277,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# Gradient of the Spherical Harmonics\n",
+    "## Gradient of the Spherical Harmonics\n",
     "\n",
     "The gradient of the spherical harmonics on the unit sphere can be written as,\n",
     "\n",
@@ -290,7 +290,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## Gradient of the Complex-Valued Spherical Harmonics"
+    "### Gradient of the Complex-Valued Spherical Harmonics"
    ]
   },
   {
@@ -325,7 +325,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## Gradient of the Real-Valued Spherical Harmonics"
+    "### Gradient of the Real-Valued Spherical Harmonics"
    ]
   },
   {

pyproject.toml

@@ -26,10 +26,10 @@ classifiers = [
 ]
 dependencies = [
     'numpy>=1.22',
-    'scipy',
+    'scipy>=1.15',
     'urllib3',
     'matplotlib>=3.10.3',
-    'pyfar<0.8.0',
+    'pyfar>=0.7.3,<0.8.0',
     'pytz',
 ]
 
@@ -80,6 +80,7 @@ find = {}  # Scan the project directory with the default parameters
 exclude = [
     ".git",
     "docs",
+    "examples",
 ]
 line-length = 79
 lint.ignore = [
@@ -93,23 +94,23 @@ lint.ignore = [
     "PT018",  # Assertion should be broken down into multiple parts
     "PT019",  # Fixture `_` without value is injected as parameter
     # add more ignores, to match flake8 rules
-    "D417",
+    #"D417",
 ]
 lint.select = [
-    # "B",      # bugbear extension
-    # "ARG",    # Remove unused function/method arguments
+    "ARG",    # Remove unused function/method arguments
+    "B",      # bugbear extension
     "C4",     # Check for common security issues
-    # "E",      # PEP8 errors
-    # "F",      # Pyflakes
-    # "W",      # PEP8 warnings
-    # "D",      # Docstring guidelines
+    "E",      # PEP8 errors
+    "F",      # Pyflakes
+    "W",      # PEP8 warnings
+    "D",      # Docstring guidelines
     "NPY",    # Check all numpy related deprecations
     "D417",   # Missing argument descriptions in the docstring
-    # "PT",     # Pytest style
-    # "A",      # Avoid builtin function and type shadowing
-    # "ERA",    # No commented out code
+    "PT",     # Pytest style
+    "A",      # Avoid builtin function and type shadowing
+    "ERA",    # No commented out code
     "NPY",    # Check all numpy related deprecations
-    # "COM",    # trailing comma rules
+    "COM",    # trailing comma rules
     "I002",   # missing required import
     "TID252", # Use absolute over relative imports
     "FIX",    # Code should not contain FIXME, TODO, etc