Skip to content

Commit c6bc80b

Browse files
mrava87mrava87
committed
doc: reorganized README and some of the documentation pages
1 parent 97f8f5a commit c6bc80b

File tree

3 files changed

+117
-96
lines changed

3 files changed

+117
-96
lines changed

‎README.md‎

Lines changed: 71 additions & 56 deletions
Original file line numberDiff line numberDiff line change
@@ -7,103 +7,118 @@
77
[![Slack Status](https://img.shields.io/badge/chat-slack-green.svg)](https://pylops.slack.com)
88
[![DOI](https://joss.theoj.org/papers/10.21105/joss.07512/status.svg)](https://doi.org/10.21105/joss.07512)
99

10-
## PyLops MPI
11-
pylops-mpi is a Python library built on top of [PyLops](https://pylops.readthedocs.io/en/stable/), designed to enable distributed and parallel processing of
10+
# Distributed linear operators and solvers
11+
Pylops-mpi is a Python library built on top of [PyLops](https://pylops.readthedocs.io/en/stable/), designed to enable distributed and parallel processing of
1212
large-scale linear algebra operations and computations.
1313

1414
## Installation
15-
To install pylops-mpi, you need to have MPI (Message Passing Interface) installed on your system.
15+
To install pylops-mpi, you need to have Message Passing Interface (MPI) and optionally Nvidia's Collective Communication Library (NCCL) installed on your system.
16+
1617
1. **Download and Install MPI**: Visit the official MPI website to download an appropriate MPI implementation for your system.
1718
Follow the installation instructions provided by the MPI vendor.
1819
- [Open MPI](https://www.open-mpi.org/software/ompi/v1.10/)
1920
- [MPICH](https://www.mpich.org/downloads/)
2021
- [Intel MPI](https://www.intel.com/content/www/us/en/developer/tools/oneapi/mpi-library.html#gs.10j8fx)
22+
2123
2. **Verify MPI Installation**: After installing MPI, verify its installation by opening a terminal or command prompt
2224
and running the following command:
23-
```
24-
mpiexec --version
2525
```
26-
3. **Install pylops-mpi**: Once MPI is installed and verified, you can proceed to install `pylops-mpi`.
27-
28-
You can install with `pip`:
29-
```
30-
pip install pylops-mpi
31-
```
32-
33-
You can install with `make` and `conda`:
34-
```
35-
make install_conda
36-
```
37-
Optionally, if you work with multi-GPU environment and want to use Nvidia's collective communication calls (NCCL) enabled, install your environment with
26+
mpiexec --version
27+
```
28+
29+
3. **Install pylops-mpi**: Once MPI is installed and verified, you can proceed to install `pylops-mpi` via `pip`:
30+
```
31+
pip install pylops-mpi
32+
```
33+
34+
4. (Optional) To enable the NCCL backend for multi-GPU systems, install `cupy` and `nccl` via `pip`:
3835
```
39-
make install_conda_nccl
36+
pip install cupy-cudaXx nvidia-nccl-cuX
4037
```
4138

39+
with `X=11,12`.
40+
41+
Alternatively, if the Conda package manager is used to setup the Python environment, steps 1 and 2 can be skipped and install `mpi4py` which comes with its own MPI distribution:
42+
43+
```
44+
conda install -c conda-forge mpi4py X
45+
```
46+
47+
with `X=mpich, openmpi, impi_rt, msmpi`. Similarly step 4 can be accomplished using:
48+
49+
```
50+
conda install -c conda-forge cupy nccl
51+
```
52+
53+
See the docs ([Installation](https://pylops.github.io/pylops-mpi/installation.html)) for more information.
54+
4255
## Run Pylops-MPI
4356
Once you have installed the prerequisites and pylops-mpi, you can run pylops-mpi using the `mpiexec` command.
44-
Here's an example on how to run the command:
57+
58+
Here is an example on how to run a python script called `<script_name>.py`:
4559
```
4660
mpiexec -n <NUM_PROCESSES> python <script_name>.py
4761
```
4862

49-
## Example
50-
The DistributedArray can be used to either broadcast or scatter the NumPy array across different
51-
ranks or processes.
63+
## Example: A distributed finite-difference operator
64+
The following example is a modified version of
65+
[PyLops' README](https://github.com/PyLops/pylops/blob/dev/README.md)_ starting
66+
example that can handle a 2D-array distributed across ranks over the first dimension
67+
via the `DistributedArray` object:
68+
5269
```python
70+
import numpy as np
5371
from pylops_mpi import DistributedArray, Partition
5472

55-
global_shape = (10, 5)
73+
nx, ny = 11, 21
74+
x = np.zeros((nx, ny), dtype=np.float64)
75+
x[nx // 2, ny // 2] = 1.0
5676

57-
# Initialize a DistributedArray with partition set to Broadcast
58-
dist_array_broadcast = DistributedArray(global_shape=global_shape,
59-
partition=Partition.BROADCAST)
77+
# Initialize DistributedArray with partition set to Scatter
78+
x_dist = pylops_mpi.DistributedArray.to_dist(
79+
x=x.flatten(),
80+
partition=Partition.SCATTER)
6081

61-
# Initialize a DistributedArray with partition set to Scatter
62-
dist_array_scatter = DistributedArray(global_shape=global_shape,
63-
partition=Partition.SCATTER)
64-
```
82+
# Distributed first-derivative
83+
D_op = pylops_mpi.MPIFirstDerivative((nx, ny), dtype=np.float64)
6584

66-
Additionally, the DistributedArray can be used to scatter the array along any
67-
specified axis.
85+
# y = Dx
86+
y_dist = D_op @ x
6887

69-
```python
70-
# Partition axis = 0
71-
dist_array_0 = DistributedArray(global_shape=global_shape,
72-
partition=Partition.SCATTER, axis=0)
88+
# xadj = D^H y
89+
xadj_dist = D_op.H @ y_dist
7390

74-
# Partition axis = 1
75-
dist_array_1 = DistributedArray(global_shape=global_shape,
76-
partition=Partition.SCATTER, axis=1)
91+
# xinv = D^-1 y
92+
x0_dist = pylops_mpi.DistributedArray(D_op.shape[1], dtype=np.float64)
93+
x0_dist[:] = 0
94+
xinv_dist = pylops_mpi.cgls(D_op, y_dist, x0=x0_dist, niter=10)[0]
7795
```
7896

79-
The DistributedArray class provides a `to_dist` class method that accepts a NumPy array as input and converts it into an
80-
instance of the `DistributedArray` class. This method is used to transform a regular NumPy array into a DistributedArray that can be distributed
81-
and processed across multiple nodes or processes.
97+
Note that the `DistributedArray` class provides the `to_dist` class method that accepts a NumPy array as input and converts it into an instance of the `DistributedArray` class. This method is used to transform a regular NumPy array into a DistributedArray that is distributed and processed across multiple nodes or processes.
8298

83-
```python
84-
import numpy as np
85-
np.random.seed(42)
86-
87-
dist_arr = DistributedArray.to_dist(x=np.random.normal(100, 100, global_shape),
88-
partition=Partition.SCATTER, axis=0)
89-
```
90-
The DistributedArray also provides fundamental mathematical operations, like element-wise addition, subtraction, and multiplication,
91-
as well as dot product and the [`np.linalg.norm`](https://numpy.org/doc/stable/reference/generated/numpy.linalg.norm.html) function in a distributed fashion,
92-
thus utilizing the efficiency of the MPI protocol. This enables efficient computation and processing of large-scale distributed arrays.
99+
Moreover, the `DistributedArray` class provides also fundamental mathematical operations, such as element-wise addition, subtraction, multiplication, dot product, and an equivalent of the [`np.linalg.norm`](https://numpy.org/doc/stable/reference/generated/numpy.linalg.norm.html) function that operate in a distributed fashion,
100+
thus utilizing the efficiency of the MPI/NCC; protocols. This enables efficient computation and processing of large-scale distributed arrays.
93101

94102
## Running Tests
95-
The test scripts are located in the tests folder.
103+
The MPI test scripts are located in the `tests` folder.
96104
Use the following command to run the tests:
97105
```
98-
mpiexec -n <NUM_PROCESSES> pytest --with-mpi
106+
mpiexec -n <NUM_PROCESSES> pytest tests/ --with-mpi
107+
```
108+
where the `--with-mpi` option tells pytest to enable the `pytest-mpi` plugin, allowing the tests to utilize the MPI functionality.
109+
110+
Similarly, to run the NCCL test scripts in the `tests_nccl` folder,
111+
use the following command to run the tests:
112+
```
113+
mpiexec -n <NUM_PROCESSES> pytest tests_nccl/ --with-mpi
99114
```
100-
The `--with-mpi` option tells pytest to enable the `pytest-mpi` plugin,
101-
allowing the tests to utilize the MPI functionality.
102115

103116
## Documentation
104117
The official documentation of Pylops-MPI is available [here](https://pylops.github.io/pylops-mpi/).
105118
Visit the official docs to learn more about pylops-mpi.
106119

107120
## Contributors
108121
* Rohan Babbar, rohanbabbar04
122+
* Yuxi Hong, hongyx11
109123
* Matteo Ravasi, mrava87
124+
* Tharit Tangkijwanichakul, tharittk

‎docs/source/credits.rst‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,6 @@ Contributors
44
============
55

66
* `Rohan Babbar <https://github.com/rohanbabbar04>`_, rohanbabbar04
7-
* `Matteo Ravasi <https://github.com/mrava87>`_, mrava87
87
* `Yuxi Hong <https://github.com/hongyx11>`_, hongyx11
9-
* `Carlos da Costa <https://github.com/cako>`_, cako
8+
* `Matteo Ravasi <https://github.com/mrava87>`_, mrava87
9+
* `Tharit Tangkijwanichakul <https://github.com/tharittk>`_, tharittk

‎docs/source/installation.rst‎

Lines changed: 44 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -5,18 +5,26 @@ Installation
55

66
Dependencies
77
************
8-
The PyLops-MPI project strives to create a library that is easy to install in
9-
any environment and has limited number of dependencies.
10-
Required dependencies are as follows:
8+
The minimal set of dependencies for the PyLops-MPI project is:
119

12-
* MPI(Message Passing Interface)
13-
* Python 3.8 or greater
10+
* MPI (Message Passing Interface)
11+
* Python 3.10 or greater
1412
* `NumPy <http://www.numpy.org>`_
1513
* `SciPy <http://www.scipy.org/scipylib/index.html>`_
1614
* `Matplotlib <https://matplotlib.org/>`_
1715
* `MPI4py <https://mpi4py.readthedocs.io/en/stable/>`_
1816
* `PyLops <https://pylops.readthedocs.io/en/stable/>`_
1917

18+
Additionally, to use the NCCL engine, the following additional
19+
dependencies are required:
20+
21+
* `CuPy <https://cupy.dev/>`_
22+
* `NCCL <https://docs.cupy.dev/en/stable/install.html#additional-cuda-libraries>`_
23+
24+
We highly encourage using the `Anaconda Python distribution <https://www.anaconda.com/download>`_
25+
or its standalone package manager `Conda <https://docs.conda.io/en/latest/index.html>`_. However,
26+
if this is not possible, some of the dependencies must be installed prior to installing PyLops-MPI.
27+
2028
Download and Install MPI
2129
========================
2230
Visit the official MPI website to download an appropriate MPI implementation for your system.
@@ -34,68 +42,66 @@ After installing MPI, verify its installation by opening a terminal and running
3442
3543
>> mpiexec --version
3644
37-
Fork PyLops-MPI
38-
===============
39-
Fork the `PyLops-MPI repository <https://github.com/PyLops/pylops-mpi>`_ and clone it by executing the following in your terminal:
45+
Install NCCL (optional)
46+
=======================
47+
To obtain highly-optimized performance on GPU clusters, PyLops-MPI also supports the Nvidia's collective communication calls
48+
`(NCCL) <https://developer.nvidia.com/nccl>`_. Two additional dependencies are required, CuPy and NCCL, which can be installed
49+
using `pip`:
4050

4151
.. code-block:: bash
4252
43-
>> git clone https://github.com/YOUR-USERNAME/pylops-mpi.git
53+
>> pip install cupy-cuda12x nvidia-nccl-cu12
4454
45-
We recommend installing dependencies into a separate environment.
46-
For that end, we provide a `Makefile` with useful commands for setting up the environment.
55+
.. note::
4756

48-
Enable Nvidia Collective Communication Library
49-
=======================================================
50-
To obtain highly-optimized performance on GPU clusters, PyLops-MPI also supports the Nvidia's collective communication calls
51-
`(NCCL) <https://developer.nvidia.com/nccl>`_. Two additional dependencies are required: CuPy and NCCL
57+
Replace `12x` with your CUDA version (e.g., `11x` for CUDA 11.x).
5258

53-
* `CuPy with NCCL <https://docs.cupy.dev/en/stable/install.html>`_
5459

60+
.. _UserInstall:
5561

5662
Step-by-step installation for users
5763
***********************************
5864

59-
Conda
60-
=====
61-
For a ``conda`` environment, run
62-
63-
.. code-block:: bash
64-
65-
>> make install_conda
66-
67-
This will create and activate an environment called ``pylops_mpi``, with all required dependencies.
68-
69-
Pip
70-
===
71-
If you prefer a ``pip`` installation, simply type the following command in your terminal to install the
72-
PyPI distribution:
65+
Currently PyLops-MPI can only be installed using ``pip``; simply type the following
66+
command in your terminal to install the PyPI distribution:
7367

7468
.. code-block:: bash
7569
7670
>> pip install pylops-mpi
7771
78-
When installing via pip, only required dependencies are installed.
79-
Note that, differently from the ``conda`` command, the above **will not** create a virtual environment.
80-
Make sure you create and activate your environment previously.
72+
Note that when installing via `pip`, only *required* dependencies are installed.
73+
8174

8275
.. _DevInstall:
8376

8477
Step-by-step installation for developers
8578
****************************************
8679

80+
Fork PyLops-MPI
81+
===============
82+
Fork the `PyLops-MPI repository <https://github.com/PyLops/pylops-mpi>`_ and clone it by executing the following in your terminal:
83+
84+
.. code-block:: bash
85+
86+
>> git clone https://github.com/YOUR-USERNAME/pylops-mpi.git
87+
88+
We recommend installing dependencies into a separate environment.
89+
For that end, we provide a `Makefile` with useful commands for setting up the environment.
90+
8791
Install dependencies
8892
====================
8993

90-
Conda
91-
-----
94+
Conda (recommended)
95+
-------------------
96+
9297
For a ``conda`` environment, run
9398

9499
.. code-block:: bash
95100
96101
>> make dev-install_conda
97102
98-
This will create and activate an environment called ``pylops_mpi``, with all required and optional dependencies.
103+
This will create and activate an environment called ``pylops_mpi``, with all
104+
required and optional dependencies.
99105

100106
If you want to enable `NCCL <https://developer.nvidia.com/nccl>`_ in PyLops-MPI, run this instead
101107

@@ -128,8 +134,8 @@ The `Makefile` is pre-configured with CUDA 12.x. If you use this version, run
128134
>> make dev-install_nccl
129135
130136
Otherwise, you can change the command in `Makefile` to an appropriate CUDA version
131-
i.e., If you use CUDA 11.x, change ``cupy-cuda12x`` and ``nvidia-nccl-cu12`` to ``cupy-cuda11x`` and ``nvidia-nccl-cu11``
132-
and run the command.
137+
i.e., If you use CUDA 11.x, change ``cupy-cuda12x`` and ``nvidia-nccl-cu12`` to
138+
``cupy-cuda11x`` and ``nvidia-nccl-cu11`` and run the command.
133139

134140
Run tests
135141
=========

0 commit comments

Comments
 (0)