Convert dir to axis

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`.
 - `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)

examples/plot_smoothing1d.py

@@ -64,7 +64,7 @@
 A = np.zeros((11, 21))
 A[5, 10] = 1
 
-Sop = pylops.Smoothing1D(nsmooth=5, dims=(11, 21), dir=0, dtype="float64")
+Sop = pylops.Smoothing1D(nsmooth=5, dims=(11, 21), axis=0, dtype="float64")
 B = np.reshape(Sop * np.ndarray.flatten(A), (11, 21))
 
 fig, axs = plt.subplots(1, 2, figsize=(10, 3))

examples/plot_stacking.py

@@ -27,8 +27,8 @@
 ###############################################################################
 # Let's start by defining two second derivatives :py:class:`pylops.SecondDerivative`
 # that we will be using in this example.
-D2hop = pylops.SecondDerivative((11, 21), dir=1, dtype="float32")
-D2vop = pylops.SecondDerivative((11, 21), dir=0, dtype="float32")
+D2hop = pylops.SecondDerivative(dims=(11, 21), axis=1, dtype="float32")
+D2vop = pylops.SecondDerivative(dims=(11, 21), axis=0, dtype="float32")
 
 ###############################################################################
 # Chaining of operators represents the simplest concatenation that
@@ -268,7 +268,7 @@
 # :py:class:`pylops.FirstDerivative` to the second dimension of the model.
 #
 # Note that for those operators whose implementation allows their application
-# to a single axis via the ``dir`` parameter, using the Kronecker product
+# to a single axis via the ``axis`` parameter, using the Kronecker product
 # would lead to slower performance. Nevertheless, the Kronecker product allows
 # any other operator to be applied to a single dimension.
 Nv, Nh = 11, 21

examples/plot_sum.py

@@ -19,7 +19,7 @@
 
 ###############################################################################
 # We can now create the operator and peform forward and adjoint
-Sop = pylops.Sum(dims=(ny, nx), dir=0)
+Sop = pylops.Sum(dims=(ny, nx), axis=0)
 
 y = Sop * x.ravel()
 xadj = Sop.H * y

examples/plot_symmetrize.py

@@ -49,7 +49,7 @@
 nt, nx = 10, 6
 x = np.outer(np.arange(nt), np.ones(nx))
 
-Sop = pylops.Symmetrize((nt, nx), dir=0)
+Sop = pylops.Symmetrize((nt, nx), axis=0)
 y = Sop * x.ravel()
 xadj = Sop.H * y.ravel()
 xinv = Sop / y
@@ -75,7 +75,7 @@
 
 
 x = np.outer(np.ones(nt), np.arange(nx))
-Sop = pylops.Symmetrize((nt, nx), dir=1)
+Sop = pylops.Symmetrize((nt, nx), axis=1)
 
 y = Sop * x.ravel()
 xadj = Sop.H * y.ravel()

examples/plot_tvreg.py

@@ -112,7 +112,7 @@
 perc_subsampling = 0.6
 nxsub = int(np.round(ny * nx * perc_subsampling))
 iava = np.sort(np.random.permutation(np.arange(ny * nx))[:nxsub])
-Rop = pylops.Restriction(ny * nx, iava, dtype=np.complex128)
+Rop = pylops.Restriction(ny * nx, iava, axis=0, dtype=np.complex128)
 Fop = pylops.signalprocessing.FFT2D(dims=(ny, nx))
 
 n = np.random.normal(0, 0.0, (ny, nx))
@@ -148,10 +148,10 @@
 
 Dop = [
     pylops.FirstDerivative(
-        (ny, nx), dir=0, edge=False, kind="backward", dtype=np.complex128
+        (ny, nx), axis=0, edge=False, kind="backward", dtype=np.complex128
     ),
     pylops.FirstDerivative(
-        (ny, nx), dir=1, edge=False, kind="backward", dtype=np.complex128
+        (ny, nx), axis=1, edge=False, kind="backward", dtype=np.complex128
     ),
 ]
 

pylops/avo/poststack.py

@@ -92,7 +92,12 @@ def _PoststackLinearModelling(
         # Create wavelet operator
         if len(wav.shape) == 1:
             Cop = _Convolve1D(
-                dims, h=wav, offset=len(wav) // 2, dir=0, dtype=dtype, **args_Convolve1D
+                dims,
+                h=wav,
+                offset=len(wav) // 2,
+                axis=0,
+                dtype=dtype,
+                **args_Convolve1D
             )
         else:
             Cop = _MatrixMult(
@@ -103,7 +108,7 @@ def _PoststackLinearModelling(
             )
         # Create derivative operator
         Dop = _FirstDerivative(
-            dims, dir=0, sampling=1.0, kind=kind, dtype=dtype, **args_FirstDerivative
+            dims, axis=0, sampling=1.0, kind=kind, dtype=dtype, **args_FirstDerivative
         )
         Pop = Cop * Dop
     return Pop
@@ -380,7 +385,7 @@ def PoststackInversion(
             elif dims == 2:
                 Regop = Laplacian((nt0, nx), dtype=PPop.dtype)
             else:
-                Regop = Laplacian((nt0, nx, ny), dirs=(1, 2), dtype=PPop.dtype)
+                Regop = Laplacian((nt0, nx, ny), axes=(1, 2), dtype=PPop.dtype)
 
             minv = RegularizedInversion(
                 PPop,
@@ -398,14 +403,14 @@ def PoststackInversion(
                 RegL2op = None
             elif dims == 2:
                 RegL1op = FirstDerivative(
-                    (nt0, nx), dir=0, kind="forward", dtype=PPop.dtype
+                    (nt0, nx), axis=0, kind="forward", dtype=PPop.dtype
                 )
                 RegL2op = SecondDerivative((nt0, nx), dir=1, dtype=PPop.dtype)
             else:
                 RegL1op = FirstDerivative(
-                    (nt0, nx, ny), dir=0, kind="forward", dtype=PPop.dtype
+                    (nt0, nx, ny), axis=0, kind="forward", dtype=PPop.dtype
                 )
-                RegL2op = Laplacian((nt0, nx, ny), dirs=(1, 2), dtype=PPop.dtype)
+                RegL2op = Laplacian((nt0, nx, ny), axes=(1, 2), dtype=PPop.dtype)
 
             if "mu" in kwargs_solver.keys():
                 mu = kwargs_solver["mu"]

pylops/avo/prestack.py

@@ -190,7 +190,7 @@ def PrestackLinearModelling(
             dims,
             h=wav,
             offset=len(wav) // 2,
-            dir=0,
+            axis=0,
             dtype=dtype,
         )
 
@@ -202,7 +202,7 @@ def PrestackLinearModelling(
         # Create derivative operator
         dimsm = list(dims)
         dimsm[1] = AVOop.npars
-        Dop = FirstDerivative(dimsm, dir=0, sampling=1.0, kind=kind, dtype=dtype)
+        Dop = FirstDerivative(dimsm, axis=0, sampling=1.0, kind=kind, dtype=dtype)
         Preop = Cop * AVOop * Dop
     return Preop
 
@@ -593,7 +593,7 @@ def PrestackInversion(
             if isinstance(epsI, (list, tuple)):
                 if len(epsI) != nm:
                     raise ValueError("epsI must be a scalar or a list of" "size nm")
-                RegI = Diagonal(np.array(epsI), dims=(nt0, nm, nspatprod), dir=1)
+                RegI = Diagonal(np.array(epsI), dims=(nt0, nm, nspatprod), axis=1)
             else:
                 RegI = epsI * Identity(nt0 * nm * nspatprod)
 
@@ -602,9 +602,9 @@ def PrestackInversion(
             if dims == 1:
                 Regop = SecondDerivative((nt0, nm), dtype=PPop.dtype)
             elif dims == 2:
-                Regop = Laplacian((nt0, nm, nx), dirs=(0, 2), dtype=PPop.dtype)
+                Regop = Laplacian((nt0, nm, nx), axes=(0, 2), dtype=PPop.dtype)
             else:
-                Regop = Laplacian((nt0, nm, nx, ny), dirs=(2, 3), dtype=PPop.dtype)
+                Regop = Laplacian((nt0, nm, nx, ny), axes=(2, 3), dtype=PPop.dtype)
             if epsI is None:
                 Regop = (Regop,)
                 epsR = (epsR,)
@@ -626,11 +626,11 @@ def PrestackInversion(
                 RegL1op = FirstDerivative(nt0 * nm, dtype=PPop.dtype)
                 RegL2op = None
             elif dims == 2:
-                RegL1op = FirstDerivative((nt0, nm, nx), dir=0, dtype=PPop.dtype)
-                RegL2op = SecondDerivative((nt0, nm, nx), dir=2, dtype=PPop.dtype)
+                RegL1op = FirstDerivative((nt0, nm, nx), axis=0, dtype=PPop.dtype)
+                RegL2op = SecondDerivative((nt0, nm, nx), axis=2, dtype=PPop.dtype)
             else:
-                RegL1op = FirstDerivative((nt0, nm, nx, ny), dir=0, dtype=PPop.dtype)
-                RegL2op = Laplacian((nt0, nm, nx, ny), dirs=(2, 3), dtype=PPop.dtype)
+                RegL1op = FirstDerivative((nt0, nm, nx, ny), axis=0, dtype=PPop.dtype)
+                RegL2op = Laplacian((nt0, nm, nx, ny), axes=(2, 3), dtype=PPop.dtype)
             if dims == 1:
                 if epsI is not None:
                     RegL2op = (RegI,)