Convert dir to axis (#310)

* feature: axis keyword and deprecate dir in basicoperators

* feature: axis keyword and deprecate in smoothing and derivative

* minor: Always use 2.0 instead of 2.0.0

* minor: Add spaces around markup blocks

* minor: Finished editing smoothing & derivatives block

* minor: remove whitespace

* feature: axis/axes keywords and deprecate dir/nodir in Convolve operators

* feature: axis for Diagonal and Interp

* feature: axis for FFTs and Shift

* chore: 2.0 -> 2.0.0

* minor: same pywt checking as DWT1D

* minor: dir-> axis

* feature: dir/dirs -> axis/axes in DWT operators

* chore: Remove the leftover dir(s)

* minor

* chore: is deprecated -> will be deprecated

* minor: remove useless "else"

* minor: fix merge problems

* chore: prepare for merge with upstream

* docs: Document `dir` to `axis` migration

* minor: simplify code for Sum

* bugfix: minor bug in cupy code for Restriction

* docs: Improve dir/dirs/nodir migration guide

* chore: axis=-1 where it was missed

* minor: Remove any reference to dir/dirs/nodir

* docs: Fix dir/dirs/nodir migration guide

Author: cako

MIGRATION_V1_V2.md

@@ -8,6 +8,7 @@ should be used as a checklist when converting a piece of code using PyLops from
 - Several operators have deprecated `N` as a keyword. To migrate, pass only `dims` if both `N` and `dims` are currently
   being passed. If only `N` is being passed, ensure it is being passed as a value and not a keyword argument (e.g.,
   change `Flip(N=100)` to `Flip(100)`).
+- `dir`, `dirs` and `nodir` have been deprecated in favor of `axis` and `axes`. When previously `nodir` was used, you must now provide the directions along which the operator is applied through `axes`. The default value for `axis` and `axes` are chosen to be -1 and (-2, -1), respectively, whereas the default `dir` and `dirs` was 0 and (0, 1), respectively. Be careful to check all operators where `dir`, `dirs` and `nodir` was not provided explicitly.
 - `utils.dottest`: Change `tol` into `rtol`. Absolute tolerance is now also supported via the keyword `atol`.
   When calling it with purely positional arguments, note that after `rtol` comes now first `atol` before `complexflag`.
   When using `raiseerror=True` it now emits an `AttributeError` instead of a `ValueError`.

examples/plot_causalintegration.py

@@ -112,14 +112,14 @@
 t = np.arange(nt) * dt + ot
 x = np.outer(np.sin(t), np.ones(nx))
 
-Cop = pylops.CausalIntegration((nt, nx), sampling=dt, dir=0, halfcurrent=True)
+Cop = pylops.CausalIntegration(dims=(nt, nx), sampling=dt, axis=0, halfcurrent=True)
 
 y = Cop * x.ravel()
 y = y.reshape(nt, nx)
 yn = y + np.random.normal(0, 4e-1, y.shape)
 
 # Numerical derivative
-Dop = pylops.FirstDerivative((nt, nx), dir=0, sampling=dt)
+Dop = pylops.FirstDerivative(dims=(nt, nx), axis=0, sampling=dt)
 xder = Dop * yn.ravel()
 xder = xder.reshape(nt, nx)
 

examples/plot_convolve.py

@@ -143,7 +143,7 @@
 offset = [1, 2, 1]
 
 Cop = pylops.signalprocessing.ConvolveND(
-    nx * ny * nz, h=h, offset=offset, dims=[ny, nx, nz], dirs=[0, 1, 2], dtype="float32"
+    dims=(ny, nx, nz), h=h, offset=offset, axes=(0, 1, 2), dtype="float32"
 )
 y = Cop * x.ravel()
 xinv = lsqr(Cop, y, damp=0, iter_lim=300, show=0)[0]

examples/plot_derivative.py

@@ -83,7 +83,7 @@
 A = np.zeros((nx, ny))
 A[nx // 2, ny // 2] = 1.0
 
-D1op = pylops.FirstDerivative((nx, ny), dir=0, dtype="float64")
+D1op = pylops.FirstDerivative((nx, ny), axis=0, dtype="float64")
 B = np.reshape(D1op * A.ravel(), (nx, ny))
 
 fig, axs = plt.subplots(1, 2, figsize=(10, 3))
@@ -106,7 +106,7 @@
 A = np.zeros((nx, ny))
 A[nx // 2, ny // 2] = 1.0
 
-D2op = pylops.SecondDerivative((nx, ny), dir=0, dtype="float64")
+D2op = pylops.SecondDerivative(dims=(nx, ny), axis=0, dtype="float64")
 B = np.reshape(D2op * A.ravel(), (nx, ny))
 
 fig, axs = plt.subplots(1, 2, figsize=(10, 3))
@@ -126,8 +126,8 @@
 
 ###############################################################################
 # We can also apply the second derivative to the second direction of
-# our data (``dir=1``)
-D2op = pylops.SecondDerivative((nx, ny), dir=1, dtype="float64")
+# our data (``axis=1``)
+D2op = pylops.SecondDerivative(dims=(nx, ny), axis=1, dtype="float64")
 B = np.reshape(D2op * np.ndarray.flatten(A), (nx, ny))
 
 fig, axs = plt.subplots(1, 2, figsize=(10, 3))

examples/plot_diagonal.py

@@ -95,7 +95,7 @@
 
 # 1st dim
 d = np.arange(nx)
-Dop = pylops.Diagonal(d, dims=(nx, ny), dir=0)
+Dop = pylops.Diagonal(d, dims=(nx, ny), axis=0)
 
 y = Dop * x.ravel()
 y1 = Dop.H * x.ravel()
@@ -105,7 +105,7 @@
 
 # 2nd dim
 d = np.arange(ny)
-Dop = pylops.Diagonal(d, dims=(nx, ny), dir=1)
+Dop = pylops.Diagonal(d, dims=(nx, ny), axis=1)
 
 y = Dop * x.ravel()
 y1 = Dop.H * x.ravel()

examples/plot_fft.py

@@ -74,7 +74,7 @@
 nfft = 2 ** 10
 d = np.outer(np.sin(2 * np.pi * f0 * t), np.arange(nx) + 1)
 
-FFTop = pylops.signalprocessing.FFT(dims=(nt, nx), dir=0, nfft=nfft, sampling=dt)
+FFTop = pylops.signalprocessing.FFT(dims=(nt, nx), axis=0, nfft=nfft, sampling=dt)
 D = FFTop * d.ravel()
 
 # Adjoint = inverse for FFT

examples/plot_flip.py

@@ -40,7 +40,7 @@
 # first flip the model along the first axis and then along the second axis
 nt, nx = 10, 5
 x = np.outer(np.arange(nt), np.ones(nx))
-Fop = pylops.Flip((nt, nx), dir=0)
+Fop = pylops.Flip((nt, nx), axis=0)
 y = Fop * x.ravel()
 xadj = Fop.H * y.ravel()
 y = y.reshape(nt, nx)
@@ -64,7 +64,7 @@
 
 
 x = np.outer(np.ones(nt), np.arange(nx))
-Fop = pylops.Flip((nt, nx), dir=1)
+Fop = pylops.Flip(dims=(nt, nx), axis=1)
 y = Fop * x.ravel()
 xadj = Fop.H * y.ravel()
 y = y.reshape(nt, nx)

examples/plot_restriction.py

@@ -95,7 +95,7 @@
 nxsub = int(np.round(nx * perc_subsampling))
 iava = np.sort(np.random.permutation(np.arange(nx))[:nxsub])
 
-Rop = pylops.Restriction((nx, nt), iava, dir=0, dtype="float64")
+Rop = pylops.Restriction((nx, nt), iava, axis=0, dtype="float64")
 y = (Rop * x.ravel()).reshape(nxsub, nt)
 ymask = Rop.mask(x)
 

examples/plot_roll.py

@@ -37,7 +37,7 @@
 ny, nx = 10, 5
 x = np.arange(ny * nx).reshape(ny, nx)
 
-Rop = pylops.Roll((ny, nx), dir=1, shift=-2)
+Rop = pylops.Roll(dims=(ny, nx), axis=1, shift=-2)
 
 y = Rop * x.ravel()
 xadj = Rop.H * y

examples/plot_shift.py

@@ -52,10 +52,10 @@
 
 shift = 10.5 * dt
 
-# 1st dir
+# 1st axis
 wav2d = np.outer(wav, np.ones(10))
 Op = pylops.signalprocessing.Shift(
-    (nt, 10), shift, dir=0, sampling=dt, real=True, dtype=np.float64
+    (nt, 10), shift, axis=0, sampling=dt, real=True, dtype=np.float64
 )
 wav2dshift = (Op * wav2d.ravel()).reshape(nt, 10)
 wav2dshiftback = (Op.H * wav2dshift.ravel()).reshape(nt, 10)
@@ -72,10 +72,10 @@
 axs[2].axis("tight")
 fig.tight_layout()
 
-# 2nd dir
+# 2nd axis
 wav2d = np.outer(wav, np.ones(10)).T
 Op = pylops.signalprocessing.Shift(
-    (10, nt), shift, dir=1, sampling=dt, real=True, dtype=np.float64
+    (10, nt), shift, axis=1, sampling=dt, real=True, dtype=np.float64
 )
 wav2dshift = (Op * wav2d.ravel()).reshape(10, nt)
 wav2dshiftback = (Op.H * wav2dshift.ravel()).reshape(10, nt)