Skip to content

Commit 474b106

Browse files
sporsspors
committed
Added documentation
1 parent 1bc8bca commit 474b106

File tree

4 files changed

+164
-20
lines changed

4 files changed

+164
-20
lines changed

‎doc/usage.rst‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ Requirements
77
Obviously, you'll need Python_.
88
We normally use Python 3.x, but it *should* also work with Python 2.x.
99
NumPy_ and SciPy_ are needed for the calculations.
10-
If you also want to plot the resulting sound fields, you'll need matplotlib_.
10+
If you also want to plot the results in the examples, you'll need matplotlib_.
1111

1212
Instead of installing all of them separately, you should probably get a Python
1313
distribution that already includes everything, e.g. Anaconda_.
@@ -21,4 +21,4 @@ distribution that already includes everything, e.g. Anaconda_.
2121
How to Get Started
2222
------------------
2323

24-
Various examples are located in the directory
24+
Various examples are located in the examples directory.

‎micarray/modal/angular.py‎

Lines changed: 89 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,42 @@
55

66

77
def sht_matrix(N, azi, elev, weights=None):
8-
""" (N+1)**2 x M SHT matrix"""
8+
r"""Matrix of spherical harmonics up to order N for given angles.
9+
10+
Computes a matrix of spherical harmonics up to order :math:`N`
11+
for the given angles/grid.
12+
13+
.. math::
14+
15+
\mathbf{Y} = \left[ \begin{array}{cccccc}
16+
Y_0^0(\theta[0], \phi[0]) & Y_1^{-1}(\theta[0], \phi[0]) & Y_1^0(\theta[0], \phi[0]) & Y_1^1(\theta[0], \phi[0]) & \dots & Y_N^N(\theta[0], \phi[0]) \\
17+
Y_0^0(\theta[1], \phi[1]) & Y_1^{-1}(\theta[1], \phi[1]) & Y_1^0(\theta[1], \phi[1]) & Y_1^1(\theta[1], \phi[1]) & \dots & Y_N^N(\theta[1], \phi[1]) \\
18+
\vdots & \vdots & \vdots & \vdots & \vdots & \vdots \\
19+
Y_0^0(\theta[Q-1], \phi[Q-1]) & Y_1^{-1}(\theta[Q-1], \phi[Q-1]) & Y_1^0(\theta[Q-1], \phi[Q-1]) & Y_1^1(\theta[Q-1], \phi[Q-1]) & \dots & Y_N^N(\theta[Q-1], \phi[Q-1])
20+
\end{array} \right]
21+
22+
where
23+
24+
.. math::
25+
26+
Y_n^m(\theta, \phi) = \sqrt{\frac{2n + 1}{4 \pi} \frac{(n-m)!}{(n+m)!}} P_n^m(\cos \theta) e^{i m \phi}
27+
28+
Parameters
29+
----------
30+
N : int
31+
Maximum order.
32+
azi : (Q,) array_like
33+
Azimuth.
34+
elev : (Q,) array_like
35+
Elevation.
36+
weights : (Q,) array_like, optional
37+
Quadrature weights.
38+
39+
Returns
40+
-------
41+
Ymn : ((N+1)**2, Q) numpy.ndarray
42+
Matrix of spherical harmonics.
43+
"""
944
azi = util.asarray_1d(azi)
1045
elev = util.asarray_1d(elev)
1146
if azi.ndim == 0:
@@ -24,8 +59,26 @@ def sht_matrix(N, azi, elev, weights=None):
2459

2560

2661
def Legendre_matrix(N, ctheta):
27-
""" (N+1) x M matrix of weighted Legendre Polynominals
28-
2*n+1/4*pi * P_n(ctheta)
62+
r"""Matrix of weighted Legendre Polynominals.
63+
64+
Computes a matrix of weighted Legendre polynominals up to order N for
65+
the given angles
66+
67+
.. math::
68+
69+
L_n(\theta) = \frac{2n+1}{4 \pi} P_n(\theta)
70+
71+
Parameters
72+
----------
73+
N : int
74+
Maximum order.
75+
ctheta : (Q,) array_like
76+
Angles.
77+
78+
Returns
79+
-------
80+
Lmn : ((N+1), Q) numpy.ndarray
81+
Matrix containing Legendre polynominals.
2982
"""
3083
if ctheta.ndim == 0:
3184
M = 1
@@ -39,8 +92,23 @@ def Legendre_matrix(N, ctheta):
3992

4093

4194
def grid_equal_angle(n):
42-
""" equi_angular grid on sphere.
43-
(cf. Rafaely book, sec.3.2)
95+
"""Equi-angular sampling points on a sphere.
96+
97+
According to (cf. Rafaely book, sec.3.2)
98+
99+
Parameters
100+
----------
101+
n : int
102+
Maximum order.
103+
104+
Returns
105+
-------
106+
azi : array_like
107+
Azimuth.
108+
elev : array_like
109+
Elevation.
110+
weights : array_like
111+
Quadrature weights.
44112
"""
45113
azi = np.linspace(0, 2*np.pi, 2*n+2, endpoint=False)
46114
elev, d_elev = np.linspace(0, np.pi, 2*n+2, endpoint=False, retstep=True)
@@ -60,7 +128,22 @@ def grid_equal_angle(n):
60128

61129
def grid_gauss(n):
62130
""" Gauss-Legendre sampling points on sphere.
63-
(cf. Rafaely book, sec.3.3)
131+
132+
According to (cf. Rafaely book, sec.3.3)
133+
134+
Parameters
135+
----------
136+
n : int
137+
Maximum order.
138+
139+
Returns
140+
-------
141+
azi : array_like
142+
Azimuth.
143+
elev : array_like
144+
Elevation.
145+
weights : array_like
146+
Quadrature weights.
64147
"""
65148
azi = np.linspace(0, 2*np.pi, 2*n+2, endpoint=False)
66149
x, weights = np.polynomial.legendre.leggauss(n+1)

‎micarray/modal/radial.py‎

Lines changed: 45 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@
55

66

77
def spherical_pw(N, k, r, setup):
8-
r"""Radial coefficients for a plane wave
8+
r"""Radial coefficients for a plane wave.
99
1010
Computes the radial component of the spherical harmonics expansion of a
1111
plane wave impinging on a spherical array.
@@ -18,7 +18,7 @@ def spherical_pw(N, k, r, setup):
1818
----------
1919
N : int
2020
Maximum order.
21-
k : array_like
21+
k : (M,) array_like
2222
Wavenumber.
2323
r : float
2424
Radius of microphone array.
@@ -27,7 +27,7 @@ def spherical_pw(N, k, r, setup):
2727
2828
Returns
2929
-------
30-
numpy.ndarray
30+
bn : (M, N+1) numpy.ndarray
3131
Radial weights for all orders up to N and the given wavenumbers.
3232
"""
3333
kr = util.asarray_1d(k*r)
@@ -40,7 +40,7 @@ def spherical_pw(N, k, r, setup):
4040

4141

4242
def spherical_ps(N, k, r, rs, setup):
43-
r"""Radial coefficients for a point source
43+
r"""Radial coefficients for a point source.
4444
4545
Computes the radial component of the spherical harmonics expansion of a
4646
point source impinging on a spherical array.
@@ -53,7 +53,7 @@ def spherical_ps(N, k, r, rs, setup):
5353
----------
5454
N : int
5555
Maximum order.
56-
k : array_like
56+
k : (M,) array_like
5757
Wavenumber.
5858
r : float
5959
Radius of microphone array.
@@ -64,7 +64,7 @@ def spherical_ps(N, k, r, rs, setup):
6464
6565
Returns
6666
-------
67-
numpy.ndarray
67+
bn : (M, N+1) numpy.ndarray
6868
Radial weights for all orders up to N and the given wavenumbers.
6969
"""
7070
k = util.asarray_1d(k)
@@ -80,7 +80,7 @@ def spherical_ps(N, k, r, rs, setup):
8080

8181

8282
def weights(N, kr, setup):
83-
r"""Radial weighing functions
83+
r"""Radial weighing functions.
8484
8585
Computes the radial weighting functions for diferent array types
8686
(cf. eq.(2.62), Rafaely 2015).
@@ -95,14 +95,14 @@ def weights(N, kr, setup):
9595
----------
9696
N : int
9797
Maximum order.
98-
kr : array_like
98+
kr : (M,) array_like
9999
Wavenumber * radius.
100100
setup : {'open', 'card', 'rigid'}
101101
Array configuration (open, cardioids, rigid).
102102
103103
Returns
104104
-------
105-
numpy.ndarray
105+
bn : (M, N+1) numpy.ndarray
106106
Radial weights for all orders up to N and the given wavenumbers.
107107
108108
"""
@@ -126,7 +126,28 @@ def weights(N, kr, setup):
126126

127127

128128
def regularize(dn, a0, method):
129-
"""(cf. Rettberg, Spors : DAGA 2014)"""
129+
"""Regularization (amplitude limitation) of radial filters.
130+
131+
Amplitude limitation of radial filter coefficients, methods according
132+
to (cf. Rettberg, Spors : DAGA 2014)
133+
134+
Parameters
135+
----------
136+
dn : numpy.ndarray
137+
Values to be regularized
138+
a0 : float
139+
Parameter for regularization (not required for all methods)
140+
method : {'none', 'discard', 'softclip', 'Tikh', 'wng'}
141+
Method used for regularization/amplitude limitation
142+
(none, discard, hardclip, Tikhonov, White Noise Gain).
143+
144+
Returns
145+
-------
146+
dn : numpy.ndarray
147+
Regularized values.
148+
hn : array_like
149+
150+
"""
130151

131152
idx = np.abs(dn) > a0
132153

@@ -161,6 +182,20 @@ def regularize(dn, a0, method):
161182

162183

163184
def diagonal_mode_mat(bk):
185+
"""Diagonal matrix of radial coefficients for all modes/wavenumbers.
186+
187+
Parameters
188+
----------
189+
bk : (M, N+1) numpy.ndarray
190+
Vector containing values for all wavenumbers :math:`M` and modes up to
191+
order :math:`N`
192+
193+
Returns
194+
-------
195+
Bk : (M, (N+1)**2, (N+1)**2) numpy.ndarray
196+
Multidimensional array containing diagnonal matrices with input
197+
vector on main diagonal.
198+
"""
164199
bk = _repeat_n_m(bk)
165200
if len(bk.shape) == 1:
166201
bk = bk[np.newaxis, :]

‎micarray/util.py‎

Lines changed: 28 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,13 +3,39 @@
33

44

55
def norm_of_columns(A, p=2):
6-
"""Vector p-norm of each column."""
6+
"""Vector p-norm of each column of a matrix.
7+
8+
Parameters
9+
----------
10+
A : array_like
11+
Input matrix.
12+
p : int, optional
13+
p-th norm.
14+
15+
Returns
16+
-------
17+
array_like
18+
p-norm of each column of A.
19+
"""
720
_, N = A.shape
821
return np.asarray([linalg.norm(A[:, j], ord=p) for j in range(N)])
922

1023

1124
def coherence_of_columns(A):
12-
"""Mutual coherence of columns of A."""
25+
"""Mutual coherence of columns of A.
26+
27+
Parameters
28+
----------
29+
A : array_like
30+
Input matrix.
31+
p : int, optional
32+
p-th norm.
33+
34+
Returns
35+
-------
36+
array_like
37+
Mutual coherence of columns of A.
38+
"""
1339
A = np.asmatrix(A)
1440
_, N = A.shape
1541
A = A * np.asmatrix(np.diag(1/norm_of_columns(A)))

0 commit comments

Comments
 (0)