| Name | libucxx-cu11 JSON |
| Version |
0.40.0
JSON |
| download |
| home_page | None |
| Summary | Python Bindings for the Unified Communication X library (UCX) |
| upload_time | 2024-10-10 15:29:21 |
| maintainer | None |
| docs_url | None |
| author | NVIDIA Corporation |
| requires_python | None |
| license | BSD-3-Clause |
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# UCXX
UCXX is an object-oriented C++ interface for UCX, with native support for Python bindings.
## Building
### Environment setup
Before starting it is necessary to have the necessary dependencies installed. The simplest way to get started is to install [Miniforge](https://github.com/conda-forge/miniforge) and then to create and activate an environment with the provided development file, for CUDA 11.x:
```
$ conda env create -n ucxx -f conda/environments/all_cuda-118_arch-x86_64.yaml
```
Or for CUDA 12.x:
```
$ conda env create -n ucxx -f conda/environments/all_cuda-125_arch-x86_64.yaml
```
And then activate the newly created environment:
```
$ conda activate ucxx
```
#### Faster conda dependency resolution
The procedure aforementioned should complete without issues, but it may be slower than necessary. One alternative to speed up dependency resolution is to install [mamba](https://mamba.readthedocs.io/en/latest/) before creating the new environment. After installing Miniforge, mamba can be installed with:
```
$ conda install -c conda-forge mamba
```
After that, one can proceed as before, but simply replacing `conda` with `mamba` in the environment creation command:
```
$ mamba env create -n ucxx -f conda/environments/all_cuda-118_arch-x86_64.yaml
$ conda activate ucxx
```
### Convenience Script
For convenience, we provide the `./build.sh` script. By default, it will build and install both C++ and Python libraries. For a detailed description on available options please check `./build.sh --help`.
Building C++ and Python libraries manually is also possible, see instructions on building [C++](#c) and [Python](#python).
Additionally, there is a `./build_and_run.sh` script that will call `./build.sh` to build everything as well as running C++ and Python tests and a few benchmarks. Similarly, details on existing options can be queried with `./build_and_run.sh`.
### C++
To build and install C++ library to `${CONDA_PREFIX}`, with both Python and RMM support, as well as building all tests run:
```
mkdir cpp/build
cd cpp/build
cmake .. -DCMAKE_INSTALL_PREFIX=${CONDA_PREFIX} \
-DBUILD_TESTS=ON \
-DCMAKE_BUILD_TYPE=Release \
-DUCXX_ENABLE_PYTHON=ON \
-DUCXX_ENABLE_RMM=ON
make -j install
```
### Python
```
cd python
python setup.py install
```
## Running benchmarks
### C++
Currently there is only one C++ benchmark with few options. It can be found under `cpp/build/benchmarks/ucxx_perftest` and for a full list of options `--help` argument can be used.
The benchmark is composed of two processes: a server and a client. The server must not specify an IP address or hostname and will bind to all available interfaces, whereas the client must specify the IP address or hostname where the server can be reached.
Below is an example of running a server first, followed by the client connecting to the server on the `localhost` (`127.0.0.1`). Both processes specify a list of parameters, which are the message size in bytes (`-s 8388608`), that allocations should be reused (`-r`), the number of iterations to perform (`-n 10`) and the progress mode (`-m polling`).
```
$ UCX_TCP_CM_REUSEADDR=y ./benchmarks/ucxx_perftest -s 800000000 -r -n 10 -m polling &
$ ./benchmarks/ucxx_perftest -s 800000000 -r -n 10 -m polling 127.0.0.1
```
It is recommended to use `UCX_TCP_CM_REUSEADDR=y` when binding to interfaces with TCP support to prevent waiting for the process' `TIME_WAIT` state to complete, which often takes 60 seconds after the server has terminated.
### Python
Benchmarks are available for both the Python "core" (synchronous) API and the "high-level" (asynchronous) API.
#### Synchronous
```python
# Thread progress without delayed notification NumPy transfer, 100 iterations
# of single buffer with 100 bytes
python -m ucxx.benchmarks.send_recv \
--backend ucxx-core \
--object_type numpy \
--n-iter 100 \
--n-bytes 100
# Blocking progress without delayed notification RMM transfer between GPUs 0
# and 3, 100 iterations of 2 buffers (using multi-buffer interface) each with
# 1 MiB
python -m ucxx.benchmarks.send_recv \
--backend ucxx-core \
--object_type rmm \
--server-dev 0 \
--client-dev 3 \
--n-iter 100 \
--n-bytes 100 \
--progress-mode blocking
```
#### Asynchronous
```python
# NumPy transfer, 100 iterations of 8 buffers (using multi-buffer interface)
# each with 100 bytes
python -m ucxx.benchmarks.send_recv \
--backend ucxx-async \
--object_type numpy \
--n-iter 100 \
--n-bytes 100 \
--n-buffers 8
# RMM transfer between GPUs 0 and 3, 100 iterations of 2 buffers (using
# multi-buffer interface) each with 1 MiB
python -m ucxx.benchmarks.send_recv \
--backend ucxx-async \
--object_type rmm \
--server-dev 0 \
--client-dev 3 \
--n-iter 100 \
--n-bytes 1MiB \
--n-buffers 2
# Polling progress mode without delayed notification NumPy transfer,
# 100 iterations of single buffer with 1 MiB
UCXPY_ENABLE_DELAYED_SUBMISSION=0 \
python -m ucxx.benchmarks.send_recv \
--backend ucxx-async \
--object_type numpy \
--n-iter 100 \
--n-bytes 1MiB \
--progress-mode polling
```
## Logging
Logging is independently available for both C++ and Python APIs. Since the Python interface uses the C++ backend, C++ logging can be enabled when running Python code as well.
### C++
The C++ interface reuses the UCX logger and provides the same log levels and can be enabled via the `UCXX_LOG_LEVEL` environment variable. However, it will not enable UCX logging, one must still set `UCX_LOG_LEVEL` for UCX logging. A few examples are below:
```
# Request trace log level
UCXX_LOG_LEVEL=TRACE_REQ
# Debug log level
UCXX_LOG_LEVEL=DEBUG
```
### Python
The UCXX Python interface uses the `logging` library included in Python. The only used levels currently are `INFO` and `DEBUG`, and can be enabled via the `UCXPY_LOG_LEVEL` environment variable. A few examples are below:
```
# Enable Python info log level
UCXPY_LOG_LEVEL=INFO
# Enable Python debug log level, UCXX request trace log level and UCX data log level
UCXPY_LOG_LEVEL=DEBUG UCXX_LOG_LEVEL=TRACE_REQ UCX_LOG_LEVEL=DATA
```
Raw data
{
"_id": null,
"home_page": null,
"name": "libucxx-cu11",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": null,
"author": "NVIDIA Corporation",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/d2/15/3c7898bd97fcfb736f3c79d4088d435024c2b8754857235a95fe95d7b6a5/libucxx_cu11-0.40.0.tar.gz",
"platform": null,
"description": "# UCXX\n\nUCXX is an object-oriented C++ interface for UCX, with native support for Python bindings.\n\n## Building\n\n### Environment setup\n\nBefore starting it is necessary to have the necessary dependencies installed. The simplest way to get started is to install [Miniforge](https://github.com/conda-forge/miniforge) and then to create and activate an environment with the provided development file, for CUDA 11.x:\n\n```\n$ conda env create -n ucxx -f conda/environments/all_cuda-118_arch-x86_64.yaml\n```\n\nOr for CUDA 12.x:\n\n```\n$ conda env create -n ucxx -f conda/environments/all_cuda-125_arch-x86_64.yaml\n```\n\nAnd then activate the newly created environment:\n\n```\n$ conda activate ucxx\n```\n\n#### Faster conda dependency resolution\n\nThe procedure aforementioned should complete without issues, but it may be slower than necessary. One alternative to speed up dependency resolution is to install [mamba](https://mamba.readthedocs.io/en/latest/) before creating the new environment. After installing Miniforge, mamba can be installed with:\n\n```\n$ conda install -c conda-forge mamba\n```\n\nAfter that, one can proceed as before, but simply replacing `conda` with `mamba` in the environment creation command:\n\n```\n$ mamba env create -n ucxx -f conda/environments/all_cuda-118_arch-x86_64.yaml\n$ conda activate ucxx\n```\n\n### Convenience Script\n\nFor convenience, we provide the `./build.sh` script. By default, it will build and install both C++ and Python libraries. For a detailed description on available options please check `./build.sh --help`.\n\nBuilding C++ and Python libraries manually is also possible, see instructions on building [C++](#c) and [Python](#python).\n\nAdditionally, there is a `./build_and_run.sh` script that will call `./build.sh` to build everything as well as running C++ and Python tests and a few benchmarks. Similarly, details on existing options can be queried with `./build_and_run.sh`.\n\n### C++\n\nTo build and install C++ library to `${CONDA_PREFIX}`, with both Python and RMM support, as well as building all tests run:\n\n```\nmkdir cpp/build\ncd cpp/build\ncmake .. -DCMAKE_INSTALL_PREFIX=${CONDA_PREFIX} \\\n -DBUILD_TESTS=ON \\\n -DCMAKE_BUILD_TYPE=Release \\\n -DUCXX_ENABLE_PYTHON=ON \\\n -DUCXX_ENABLE_RMM=ON\nmake -j install\n```\n\n### Python\n\n```\ncd python\npython setup.py install\n```\n\n## Running benchmarks\n\n### C++\n\nCurrently there is only one C++ benchmark with few options. It can be found under `cpp/build/benchmarks/ucxx_perftest` and for a full list of options `--help` argument can be used.\n\nThe benchmark is composed of two processes: a server and a client. The server must not specify an IP address or hostname and will bind to all available interfaces, whereas the client must specify the IP address or hostname where the server can be reached.\n\nBelow is an example of running a server first, followed by the client connecting to the server on the `localhost` (`127.0.0.1`). Both processes specify a list of parameters, which are the message size in bytes (`-s 8388608`), that allocations should be reused (`-r`), the number of iterations to perform (`-n 10`) and the progress mode (`-m polling`).\n\n```\n$ UCX_TCP_CM_REUSEADDR=y ./benchmarks/ucxx_perftest -s 800000000 -r -n 10 -m polling &\n$ ./benchmarks/ucxx_perftest -s 800000000 -r -n 10 -m polling 127.0.0.1\n```\n\nIt is recommended to use `UCX_TCP_CM_REUSEADDR=y` when binding to interfaces with TCP support to prevent waiting for the process' `TIME_WAIT` state to complete, which often takes 60 seconds after the server has terminated.\n\n### Python\n\nBenchmarks are available for both the Python \"core\" (synchronous) API and the \"high-level\" (asynchronous) API.\n\n#### Synchronous\n\n```python\n# Thread progress without delayed notification NumPy transfer, 100 iterations\n# of single buffer with 100 bytes\npython -m ucxx.benchmarks.send_recv \\\n --backend ucxx-core \\\n --object_type numpy \\\n --n-iter 100 \\\n --n-bytes 100\n\n# Blocking progress without delayed notification RMM transfer between GPUs 0\n# and 3, 100 iterations of 2 buffers (using multi-buffer interface) each with\n# 1 MiB\npython -m ucxx.benchmarks.send_recv \\\n --backend ucxx-core \\\n --object_type rmm \\\n --server-dev 0 \\\n --client-dev 3 \\\n --n-iter 100 \\\n --n-bytes 100 \\\n --progress-mode blocking\n```\n\n#### Asynchronous\n\n```python\n# NumPy transfer, 100 iterations of 8 buffers (using multi-buffer interface)\n# each with 100 bytes\npython -m ucxx.benchmarks.send_recv \\\n --backend ucxx-async \\\n --object_type numpy \\\n --n-iter 100 \\\n --n-bytes 100 \\\n --n-buffers 8\n\n# RMM transfer between GPUs 0 and 3, 100 iterations of 2 buffers (using\n# multi-buffer interface) each with 1 MiB\npython -m ucxx.benchmarks.send_recv \\\n --backend ucxx-async \\\n --object_type rmm \\\n --server-dev 0 \\\n --client-dev 3 \\\n --n-iter 100 \\\n --n-bytes 1MiB \\\n --n-buffers 2\n\n# Polling progress mode without delayed notification NumPy transfer,\n# 100 iterations of single buffer with 1 MiB\nUCXPY_ENABLE_DELAYED_SUBMISSION=0 \\\n python -m ucxx.benchmarks.send_recv \\\n --backend ucxx-async \\\n --object_type numpy \\\n --n-iter 100 \\\n --n-bytes 1MiB \\\n --progress-mode polling\n```\n\n## Logging\n\nLogging is independently available for both C++ and Python APIs. Since the Python interface uses the C++ backend, C++ logging can be enabled when running Python code as well.\n\n### C++\n\nThe C++ interface reuses the UCX logger and provides the same log levels and can be enabled via the `UCXX_LOG_LEVEL` environment variable. However, it will not enable UCX logging, one must still set `UCX_LOG_LEVEL` for UCX logging. A few examples are below:\n\n```\n# Request trace log level\nUCXX_LOG_LEVEL=TRACE_REQ\n\n# Debug log level\nUCXX_LOG_LEVEL=DEBUG\n```\n\n### Python\n\nThe UCXX Python interface uses the `logging` library included in Python. The only used levels currently are `INFO` and `DEBUG`, and can be enabled via the `UCXPY_LOG_LEVEL` environment variable. A few examples are below:\n\n```\n# Enable Python info log level\nUCXPY_LOG_LEVEL=INFO\n\n# Enable Python debug log level, UCXX request trace log level and UCX data log level\nUCXPY_LOG_LEVEL=DEBUG UCXX_LOG_LEVEL=TRACE_REQ UCX_LOG_LEVEL=DATA\n```\n",
"bugtrack_url": null,
"license": "BSD-3-Clause",
"summary": "Python Bindings for the Unified Communication X library (UCX)",
"version": "0.40.0",
"project_urls": {
"Homepage": "https://github.com/rapidsai/ucxx"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "d2153c7898bd97fcfb736f3c79d4088d435024c2b8754857235a95fe95d7b6a5",
"md5": "b943b5623763e05de170a0de4399f223",
"sha256": "ec3b38bd6349bdd2df2856838b2cda9ac2cc7283977e6e3a9f02228032476fea"
},
"downloads": -1,
"filename": "libucxx_cu11-0.40.0.tar.gz",
"has_sig": false,
"md5_digest": "b943b5623763e05de170a0de4399f223",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 2909,
"upload_time": "2024-10-10T15:29:21",
"upload_time_iso_8601": "2024-10-10T15:29:21.760267Z",
"url": "https://files.pythonhosted.org/packages/d2/15/3c7898bd97fcfb736f3c79d4088d435024c2b8754857235a95fe95d7b6a5/libucxx_cu11-0.40.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-10 15:29:21",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "rapidsai",
"github_project": "ucxx",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "libucxx-cu11"
}
