DistributedArray -> DistArray ++

Author: mikaem

docs/source/global.rst

@@ -11,7 +11,10 @@ global shape :math:`(512, 1024, 2048)`. To lift this array into RAM requires
 machine. If, however, you have access to a distributed architecture, you can
 split the array up and share it between, e.g., four CPUs (most supercomputers
 have either 2 or 4 GB of memory per CPU), which will only need to
-hold 2 GBs of the global array each.
+hold 2 GBs of the global array each. Moreover, many algorithms with varying
+degrees of locality can take advantage of the distributed nature of the array
+to compute local array pieces concurrently, effectively exploiting multiple
+processor resources.
 
 There are several ways of distributing a large multidimensional
 array. Two such distributions for our three-dimensional global array
@@ -55,7 +58,7 @@ classes in the :mod:`.pencil` module:
     * :class:`.Transfer`
 
 These classes are the low-level backbone of the higher-level :class:`.PFFT` and
-:class:`.DistributedArray` classes. To use these low-level classes
+:class:`.DistArray` classes. To use these low-level classes
 directly is not recommended and usually not necessary. However, for
 clarity we start by describing how these low-level classes work together.
 
@@ -64,9 +67,9 @@ distributed along axis 0. With a high level API we could then simply
 do::
 
     import numpy as np
-    from mpi4py_fft import DistributedArray
+    from mpi4py_fft import DistArray
     N = (8, 8)
-    a = DistributedArray(N, [0, 1])
+    a = DistArray(N, [0, 1])
 
 where the ``[0, 1]`` list decides that the first axis can be distributed,
 whereas the second axis is using one processor only and as such is
@@ -119,7 +122,7 @@ can only be distributed with
 one processor group. If we wanted to distribute the second axis instead
 of the first, then we would have done::
 
-    a = DistributedArray(N, [1, 0])
+    a = DistArray(N, [1, 0])
 
 With the low-level approach we would have had to use ``axis=0`` in the
 creation of ``p0``, as well as ``[1, 0]`` in the creation of ``subcomm``.
@@ -136,11 +139,11 @@ the value of each processors rank (note that it would also work to follow the
 low-level approach and use ``a0``)::
 
     import numpy as np
-    from mpi4py_fft import DistributedArray
+    from mpi4py_fft import DistArray
     from mpi4py import MPI
     comm = MPI.COMM_WORLD
     N = (8, 8)
-    a = DistributedArray(N, [0, 1])
+    a = DistArray(N, [0, 1])
     a[:] = comm.Get_rank()
     print(a.shape)
 
@@ -293,11 +296,11 @@ processor groups, respectively. On the other hand, if you can get away with it,
 or if you do not have access to a great number of processors, then fewer groups
 are usually found to be faster for the same number of processors in total.
 
-We can implement the global redistribution using the high-level :class:`.DistributedArray`
+We can implement the global redistribution using the high-level :class:`.DistArray`
 class::
 
     N = (8, 8, 8, 8)
-    a3 = DistributedArray(N, [0, 0, 0, 1])
+    a3 = DistArray(N, [0, 0, 0, 1])
     a2 = a3.redistribute(2)
     a1 = a2.redistribute(1)
     a0 = a1.redistribute(0)

docs/source/indices.rst

@@ -3,4 +3,4 @@ Indices and tables
 
 * :ref:`genindex`
 * :ref:`modindex`
-* :ref:`search`
+* :ref:`search`

docs/source/installation.rst

@@ -133,4 +133,4 @@ This test-suit is run automatically on every commit to github, see, e.g.,
 .. _numpy: https://www.numpy.org
 .. _numba: https://www.numba.org
 .. _conda-build: https://conda.io/docs/commands/build/conda-build.html
-.. _pypi: https://pypi.org/project/shenfun/
+.. _pypi: https://pypi.org/project/shenfun/

docs/source/introduction.rst

@@ -1,7 +1,8 @@
 Introduction
 ============
 
-The Python package mpi4py-fft is a tool primarily for working with Fast
+The Python package `mpi4py-fft`_
+is a tool primarily for working with Fast
 Fourier Transforms (FFTs) of (large) multidimensional arrays. There is really
 no limit as to how large the arrays can be, just as long as there is sufficient
 computing powers available. Also, there are no limits as to how transforms can
@@ -15,7 +16,7 @@ the main modules:
 
     * :mod:`.mpifft`
     * :mod:`.pencil`
-    * :mod:`.distributedarray`
+    * :mod:`.distarray`
     * :mod:`.libfft`
     * :mod:`.fftw`
 
@@ -28,7 +29,7 @@ However, this module is rarely used on its own, unless one simply needs to do
 global redistributions without any transforms at all. The :mod:`.pencil` module
 is used heavily by the :class:`.PFFT` class.
 
-The :mod:`.distributedarray` module contains classes for simply distributing
+The :mod:`.distarray` module contains classes for simply distributing
 multidimensional arrays, with no regards to transforms. The distributed arrays
 created from the classes here can very well be used in any MPI application that
 requires a large multidimensional distributed array.
@@ -42,3 +43,5 @@ because `pyfftw <https://github.com/pyFFTW/pyFFTW>`_ does not include support
 for real-to-real transforms. Through the interface in :mod:`.fftw` we can do
 here, in Python, pretty much everything that you can do in the original
 FFTW library.
+
+.. _`mpi4py-fft`: https://bitbucket.org/mpi4py/mpi4py-fft

docs/source/io.rst

@@ -16,12 +16,12 @@ reads data in parallel. A simple example of usage is::
 
     from mpi4py import MPI
     import numpy as np
-    from mpi4py_fft import PFFT, HDF5File, NCFile, newDarray
+    from mpi4py_fft import PFFT, HDF5File, NCFile, newDistArray
 
     N = (128, 256, 512)
     T = PFFT(MPI.COMM_WORLD, N)
-    u = newDarray(T, forward_output=False)
-    v = newDarray(T, forward_output=False, val=2)
+    u = newDistArray(T, forward_output=False)
+    v = newDistArray(T, forward_output=False, val=2)
     u[:] = np.random.random(N)
 
     fields = {'u': [u], 'v': [v]}
@@ -43,8 +43,8 @@ The stored dataarrays can be retrieved later on::
 
     f0 = HDF5File('h5test.h5', T, mode='r')
     f1 = NCFile('nctest.nc', T, mode='r')
-    u0 = newDarray(T, forward_output=False)
-    u1 = newDarray(T, forward_output=False)
+    u0 = newDistArray(T, forward_output=False)
+    u1 = newDistArray(T, forward_output=False)
     f0.read(u0, 'u', 0)
     f0.read(u1, 'u', 1)
     f1.read(u0, 'u', 0)
@@ -165,4 +165,4 @@ generate the files using::
     generate_xdmf('variousfields.h5', order='visit')
 
 because for some reason Paraview and Visit require the mesh in the xdmf-files
-to be stored in opposite order.
+to be stored in opposite order.

docs/source/mpi4py_fft.rst

@@ -38,10 +38,10 @@ mpi4py\_fft.pencil module
     :undoc-members:
     :show-inheritance:
 
-mpi4py\_fft.distributedarray module
+mpi4py\_fft.distarray module
 -----------------------------------
 
-.. automodule:: mpi4py_fft.distributedarray
+.. automodule:: mpi4py_fft.distarray
     :members:
     :undoc-members:
     :show-inheritance:

docs/source/parallel.rst

@@ -18,7 +18,7 @@ the following code snippet::
 
     import numpy as np
     from mpi4py import MPI
-    from mpi4py_fft import PFFT, newDarray
+    from mpi4py_fft import PFFT, newDistArray
     N = np.array([128, 128, 128], dtype=int)
     fft = PFFT(MPI.COMM_WORLD, N, axes=(0, 1, 2), dtype=np.float, slab=True)
 
@@ -47,7 +47,7 @@ With data aligned in axis 0, we can perform the final transform
 Assume now that all the code in this section is stored to a file named
 ``pfft_example.py``, and add to the above code::
 
-    u = newDarray(fft, False)
+    u = newDistArray(fft, False)
     u[:] = np.random.random(u.shape).astype(u.dtype)
     u_hat = fft.forward(u)
     uj = np.zeros_like(u)
@@ -63,8 +63,8 @@ should raise no exception, and the output should be::
 
 This shows that the first index has been shared between the two processors
 equally. The array ``u`` thus corresponds to :math:`u_{j_0/P,j_1,j_2}`. Note
-that the :func:`.newDarray` function returns a :class:`.DistributedArray`
-object, which in turn is a subclassed Numpy ndarray. The :func:`.newDarray`
+that the :func:`.newDistArray` function returns a :class:`.DistArray`
+object, which in turn is a subclassed Numpy ndarray. The :func:`.newDistArray`
 function uses ``fft`` to determine the size and type of the created distributed
 array, i.e., (64, 128, 128) and ``np.float`` for both processors.
 The ``False`` argument indicates that the shape
@@ -80,7 +80,7 @@ The output array will be distributed in axis 1, so the output array
 shape should be (128, 64, 65) on each processor. We check this by adding
 the following code and rerunning::
 
-    u_hat = newDarray(fft, True)
+    u_hat = newDistArray(fft, True)
     print(MPI.COMM_WORLD.Get_rank(), u_hat.shape)
 
 leading to an additional print of::
@@ -147,7 +147,7 @@ with real-to-complex transforms like this::
     idct = functools.partial(idctn, type=3)
     transforms = {(0,): (rfftn, irfftn), (1, 2): (dct, idct)}
     r2c = PFFT(MPI.COMM_WORLD, N, axes=((0,), (1, 2)), transforms=transforms)
-    u = newDarray(r2c, False)
+    u = newDistArray(r2c, False)
     u[:] = np.random.random(u.shape).astype(u.dtype)
     u_hat = r2c.forward(u)
     uj = np.zeros_like(u)
@@ -170,7 +170,7 @@ A parallel transform object can be created and tested as::
     fft = PFFT(MPI.COMM_WORLD, N, ((0,), (1, 2), (3, 4)), slab=True,
                transforms={(1, 2): (dctn, idctn), (3, 4): (dstn, idstn)})
 
-    A = newDarray(fft, False)
+    A = newDistArray(fft, False)
     A[:] = np.random.random(A.shape)
     C = fftw.aligned_like(A)
     B = fft.forward(A)
@@ -190,11 +190,11 @@ in the PFFT calling::
 
     import numpy as np
     from mpi4py import MPI
-    from mpi4py_fft import PFFT, newDarray
+    from mpi4py_fft import PFFT, newDistArray
 
     N = np.array([128, 128, 128], dtype=int)
     fft = PFFT(MPI.COMM_WORLD, N, axes=(0, 1, 2), dtype=np.float)
-    u = newDarray(fft, False)
+    u = newDistArray(fft, False)
     u[:] = np.random.random(u.shape).astype(u.dtype)
     u_hat = fft.forward(u)
     uj = np.zeros_like(u)
@@ -327,22 +327,22 @@ With mpi4py-fft we can compute this convolution using the ``padding`` keyword
 of the :class:`.PFFT` class::
 
     import numpy as np
-    from mpi4py_fft import PFFT, newDarray
+    from mpi4py_fft import PFFT, newDistArray
     from mpi4py import MPI
 
     comm = MPI.COMM_WORLD
     N = (128, 128)   # Global shape in physical space
     fft = PFFT(comm, N, padding=[1.5, 1.5], dtype=np.complex)
 
     # Create arrays in normal spectral space
-    a_hat = newDarray(fft, True)
-    b_hat = newDarray(fft, True)
+    a_hat = newDistArray(fft, True)
+    b_hat = newDistArray(fft, True)
     a_hat[:] = np.random.random(a_hat.shape) + np.random.random(a_hat.shape)*1j
     b_hat[:] = np.random.random(a_hat.shape) + np.random.random(a_hat.shape)*1j
 
     # Transform to real space with padding
-    a = newDarray(fft, False)
-    b = newDarray(fft, False)
+    a = newDistArray(fft, False)
+    b = newDistArray(fft, False)
     assert a.shape == (192//comm.Get_size(), 192)
     a = fft.backward(a_hat, a)
     b = fft.backward(b_hat, b)

examples/darray.py

@@ -1,13 +1,13 @@
 import numpy as np
 from mpi4py import MPI
 from mpi4py_fft.pencil import Subcomm
-from mpi4py_fft.distributedarray import DistributedArray, newDarray, Function
+from mpi4py_fft.distarray import DistArray, newDistArray, Function
 from mpi4py_fft.mpifft import PFFT
 
-# Test DistributedArray. Start with alignment in axis 0, then tranfer to 1 and
+# Test DistArray. Start with alignment in axis 0, then tranfer to 1 and
 # finally to 2
 N = (16, 14, 12)
-z0 = DistributedArray(N, dtype=np.float, alignment=0)
+z0 = DistArray(N, dtype=np.float, alignment=0)
 z0[:] = np.random.randint(0, 10, z0.shape)
 s0 = MPI.COMM_WORLD.allreduce(np.sum(z0))
 z1 = z0.redistribute(2)
@@ -17,7 +17,7 @@
 assert s0 == s1 == s2
 
 fft = PFFT(MPI.COMM_WORLD, darray=z2, axes=(0, 2, 1))
-z3 = newDarray(fft, forward_output=True)
+z3 = newDistArray(fft, forward_output=True)
 z2c = z2.copy()
 fft.forward(z2, z3)
 fft.backward(z3, z2)
@@ -28,11 +28,11 @@
 
 print(z3.local_slice(), z3.substart, z3.commsizes)
 
-v0 = newDarray(fft, forward_output=False, rank=1)
+v0 = newDistArray(fft, forward_output=False, rank=1)
 #v0 = Function(fft, forward_output=False, rank=1)
 v0[:] = np.random.random(v0.shape)
 v0c = v0.copy()
-v1 = newDarray(fft, forward_output=True, rank=1)
+v1 = newDistArray(fft, forward_output=True, rank=1)
 
 for i in range(3):
     v1[i] = fft.forward(v0[i], v1[i])
@@ -53,13 +53,13 @@
 
 
 N = (6, 6, 6)
-z = DistributedArray(N, dtype=float, alignment=0)
+z = DistArray(N, dtype=float, alignment=0)
 z[:] = MPI.COMM_WORLD.Get_rank()
 g = z.get_global_slice((0, slice(None), 0))
 if MPI.COMM_WORLD.Get_rank() == 0:
     print(g)
 
-z2 = DistributedArray(N, dtype=float, alignment=2)
+z2 = DistArray(N, dtype=float, alignment=2)
 z.redistribute(darray=z2)
 
 g = z2.get_global_slice((0, slice(None), 0))
@@ -72,7 +72,7 @@
     assert abs(s0-s1) < 1e-12
 
 N = (3, 3, 6, 6, 6)
-z2 = DistributedArray(N, dtype=float, val=1, alignment=2, rank=2)
+z2 = DistArray(N, dtype=float, val=1, alignment=2, rank=2)
 z2[:] = MPI.COMM_WORLD.Get_rank()
 z1 = z2.redistribute(1)
 z0 = z1.redistribute(0)

examples/spectral_dns_solver.py

@@ -10,7 +10,7 @@
 from time import time
 import numpy as np
 from mpi4py import MPI
-from mpi4py_fft import PFFT, newDarray
+from mpi4py_fft import PFFT, newDistArray
 
 # Set viscosity, end time and time step
 nu = 0.000625
@@ -28,18 +28,18 @@
 FFT_pad = FFT
 
 # Declare variables needed to solve Navier-Stokes
-U = newDarray(FFT, False, rank=1)       # Velocity
-U_hat = newDarray(FFT, rank=1)          # Velocity transformed
-P = newDarray(FFT, False)               # Pressure (scalar)
-P_hat = newDarray(FFT)                  # Pressure transformed
-U_hat0 = newDarray(FFT, rank=1)         # Runge-Kutta work array
-U_hat1 = newDarray(FFT, rank=1)         # Runge-Kutta work array
+U = newDistArray(FFT, False, rank=1)       # Velocity
+U_hat = newDistArray(FFT, rank=1)          # Velocity transformed
+P = newDistArray(FFT, False)               # Pressure (scalar)
+P_hat = newDistArray(FFT)                  # Pressure transformed
+U_hat0 = newDistArray(FFT, rank=1)         # Runge-Kutta work array
+U_hat1 = newDistArray(FFT, rank=1)         # Runge-Kutta work array
 a = [1./6., 1./3., 1./3., 1./6.]        # Runge-Kutta parameter
 b = [0.5, 0.5, 1.]                      # Runge-Kutta parameter
-dU = newDarray(FFT, rank=1)             # Right hand side of ODEs
-curl = newDarray(FFT, False, rank=1)
-U_pad = newDarray(FFT_pad, False, rank=1)
-curl_pad = newDarray(FFT_pad, False, rank=1)
+dU = newDistArray(FFT, rank=1)             # Right hand side of ODEs
+curl = newDistArray(FFT, False, rank=1)
+U_pad = newDistArray(FFT_pad, False, rank=1)
+curl_pad = newDistArray(FFT_pad, False, rank=1)
 
 def get_local_mesh(FFT, L):
     """Returns local mesh."""

examples/transforms.py

@@ -1,7 +1,7 @@
 import functools
 import numpy as np
 from mpi4py import MPI
-from mpi4py_fft import PFFT, DistributedArray
+from mpi4py_fft import PFFT, DistArray
 from mpi4py_fft.fftw import dctn, idctn
 
 # Set global size of the computational box
@@ -17,16 +17,16 @@
 
 assert fft.axes == pfft.axes
 
-u = DistributedArray(pfft=fft, forward_output=False)
+u = DistArray(pfft=fft, forward_output=False)
 u[:] = np.random.random(u.shape).astype(u.dtype)
 
-u_hat = DistributedArray(pfft=fft, forward_output=True)
+u_hat = DistArray(pfft=fft, forward_output=True)
 u_hat = fft.forward(u, u_hat)
 uj = np.zeros_like(u)
 uj = fft.backward(u_hat, uj)
 assert np.allclose(uj, u)
 
-u_padded = DistributedArray(pfft=pfft, forward_output=False)
+u_padded = DistArray(pfft=pfft, forward_output=False)
 uc = u_hat.copy()
 u_padded = pfft.backward(u_hat, u_padded)
 u_hat = pfft.forward(u_padded, u_hat)