From 554f1cb15e9e66104dbabc305bc704a55becc4e5 Mon Sep 17 00:00:00 2001
From: Klaus Reuter <khr@mpcdf.mpg.de>
Date: Fri, 3 Dec 2021 10:17:50 +0100
Subject: [PATCH] final polishing from my side
---
ARTICLE.md | 91 ++++++++++++++++++++++++++++++++-----------
README.md | 6 +--
pyproject.toml | 5 +--
setup.py | 4 +-
src/cumsum/cumsum.cpp | 4 +-
5 files changed, 78 insertions(+), 32 deletions(-)
diff --git a/ARTICLE.md b/ARTICLE.md
index 1c4bfb2..5894ef8 100644
--- a/ARTICLE.md
+++ b/ARTICLE.md
@@ -2,64 +2,111 @@
## Introduction
-With the rising popularity and success of the Python programming language, it has become increasingly important for computational scientists to be able to make their software available to the Python ecosystem. However, exposing compiled extensions from C/C++ to Python has often been cumbersome, error prone and technically challenging in the past, given the plethora of compilers, libraries and relevant target platforms developers have to deal with.
-The present article introduces the combination of two packages that promise to make this daunting task much easier and more stable.
-First, the [Pybind11](https://github.com/pybind/pybind11) header-only library provides a convenient approach to generate Python bindings for (existing or newly developed) C++ code.
-Second, the [sciki-build](https://github.com/scikit-build/scikit-build) package can be used to bridge Python's `setuptools` with [CMake](https://cmake.org/), leveraging the power of CMake for the build process of the Python extension.
-As a result, CMake's features such as, e.g., discovering and linking of numerical libraries, dependency management, choice of build-generators, or even cross-compilation can easily be exploited from within the build process of the Python extension.
-One key advantage is that the file 'setup.py' stays minimal and simple, and the aforementioned complexities are handled by CMake.
+With the rising popularity of the Python programming language it has become increasingly important for computational scientists to be able to make their software easily available to the Python ecosystem and community.
+Historically, exposing compiled extensions from C/C++ to Python has often been cumbersome, error prone and technically challenging, given the plethora of compilers, libraries and relevant target platforms developers have to deal with.
+The present article introduces a combination of two Python packages that promise to make this daunting task much easier and more stable.
+First, the [Pybind11](https://github.com/pybind/pybind11) header-only library provides a convenient approach to generate Python bindings for existing or newly developed C++ code.
+Second, the [scikit-build](https://github.com/scikit-build/scikit-build) package can be used to bridge Python's `setuptools` with [CMake](https://cmake.org/), leveraging the power of CMake for the build process of the Python extension.
+As a result, CMake's native features such as, e.g., discovering and linking of numerical libraries, dependency management, support of various build-generators, or even cross-compilation can easily be taken advantage of during the build process of the Python extension.
+A key advantage is that the file 'setup.py' stays minimal and simple, instead the aforementioned complexities are handled by CMake.
## Basic Usage
-The basic usage of pybind11 in combination with scikit-build will be demonstrated in the following using a simple Python extension package that can be accessed [here](sebak/pybind11-hello-world).
+The basic usage of pybind11 in combination with scikit-build is demonstrated below by means of a simple Python extension package.
+The code example can be obtained from [MPCDF GitLab](https://gitlab.mpcdf.mpg.de/sebak/pybind11-hello-world).
-## pybind11 hello-world
+### Interfacing Python/NumPy with C++ using pybind11
-pybind11 is a header-only library that provides conversion from C++ types to Python. The following C++ file demonstrates its use in combination with NumPy arrays.
+pybind11 is a header-only library that provides conversion from C/C++ types to Python, and vice versa.
+The following C++ Python extension module 'cumsum' demonstrates its use in combination with NumPy arrays.
```c++
-// paste cumsum once ready
+// Python example module 'cumsum'
+#include <numeric>
+#include <functional>
+#include <pybind11/pybind11.h>
+#include <pybind11/numpy.h>
+
+namespace py = pybind11;
+
+// numpy-like cumulative sum, taking a NumPy array as input and returning a NumPy array
+py::array_t<double> cumsum(py::array_t<double> a)
+{
+ // obtain information about the n-d input array
+ auto shape = a.request().shape;
+ size_t count = std::accumulate(shape.begin(), shape.end(), 1, std::multiplies<size_t>());
+ // create output NumPy array
+ py::array_t<double> b(count);
+ // obtain raw pointers
+ double * a_p = (double*) a.request().ptr;
+ double * b_p = (double*) b.request().ptr;
+ // compute cumulative sum into b
+ double cs = 0.0;
+ for (size_t i = 0; i<count; ++i) {
+ cs += a_p[i];
+ b_p[i] = cs;
+ }
+ return b;
+}
+
+PYBIND11_MODULE(cumsum, m) {
+ m.doc() = "pybind11 cumulative sum example"; // module docstring
+ m.def("cumsum", &cumsum, // third parameter is the function docstring
+ "return the cumulative sum of a double-precision numpy array");
+}
+```
+
+The 'cumsum' example module could finally be used and tested as follows:
+
+```python
+import numpy as np
+import cumsum
+a = np.random.rand(20)
+b = cumsum.cumsum(a)
+c = np.cumsum(a)
+assert(np.allclose(b, c))
```
In order for this example to be compiled, the pybind11 headers (as any other potential dependency) must be available. pybind11 can be installed in [several ways](https://pybind11.readthedocs.io/en/stable/installing.html), and it natively supports various [build systems](https://pybind11.readthedocs.io/en/stable/compiling.html#compiling).
However using scikit-build provides a particularly easy approach which is shown in the following.
-## build with scikit-learn
+### build with scikit-learn
-scikit-build provides a drop-in replacement for the `setuptools.setup` function that can be used in a project's `setup.py` via
+The package scikit-build provides a drop-in replacement for the `setuptools.setup` function that can be used in a project's `setup.py` via
```python
from skbuild import setup
```
-Beside the standard setuptools options, it provides [extra options](https://scikit-build.readthedocs.io/en/latest/usage.html#scikit-build-options) to control the CMake build. In addition, a `CMakeLists.txt` file must be available in the top-level directory of the project such as, e.g.,
+Beside the standard setuptools options, it provides [extra options](https://scikit-build.readthedocs.io/en/latest/usage.html#scikit-build-options) to control the CMake build.
+In addition, a minimal `CMakeLists.txt` file must be available in the top-level directory of the project, e.g.:
```cmake
cmake_minimum_required(VERSION 3.18)
-project(hello-world VERSION "1.0")
+project(pybind11-hello-world VERSION "1.0")
find_package(pybind11)
-# paste once ready
+
+pybind11_add_module(_cumsum MODULE src/cumsum/cumsum.cpp)
+install(TARGETS _cumsum DESTINATION .)
```
Build-system dependencies have to be specified via the project's `pyproject.toml` file:
-```
+```toml
[build-system]
requires = [
"setuptools>=42",
"wheel",
- "pybind11[global]~=2.6.0",
+ "pybind11[global]>=2.6.0",
"cmake>=3.18",
"scikit-build",
]
build-backend = "setuptools.build_meta"
```
-Finally, the Python module can be compiled and installed by using the command `pip install --user .` in the root directory of the project.
-
-With modern Python packaging, it is not necessary to manually install pybind11 and scikit-build, instead all build dependencies will be installed in an isolated build environment by `pip`.
-Please note that the '[global]' feature of the pybind11 requirement does not affect the Python installation or environment in use, it is only installed into the dedicated build environment and can thus be used safely here.
+Now the Python module can be compiled and installed by running the command `pip install --user .` in the root directory of the project. Similarly Wheel archives can be created for distribution.
-Q: Why do we need global here only for pb? Needs clarification.
+Note that with modern Python packaging tools it is not necessary to manually install pybind11 and scikit-build, instead all build dependencies will be installed into an isolated build environment by `pip`.
+The '[global]' feature of the pybind11 requirement is necessary to install the include and cmake files correctly into the dedicated build environment, it does not affect the Python installation or environment in use and can thus be used safely.
*Sebastian Kehl, Klaus Reuter*
diff --git a/README.md b/README.md
index bf1bc69..a9aea7d 100644
--- a/README.md
+++ b/README.md
@@ -1,9 +1,9 @@
-# pybind11-skbuild-numpy-example"
+# pybind11-hello-world
-This is a minimal NumPy-based example demonstrating the use of the [pybind11](https://github.com/pybind/pybind11) binding library in concert with [scikit-build](https://github.com/scikit-build/scikit-build).
+This minimal Python/NumPy-based example demonstrates the use of the [pybind11](https://github.com/pybind/pybind11) binding library in concert with [scikit-build](https://github.com/scikit-build/scikit-build).
## Installation
-`pip install --user .`
+Run `pip install --user .` to build and install locally.
## Usage
diff --git a/pyproject.toml b/pyproject.toml
index 385e05a..08b3080 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -2,9 +2,8 @@
requires = [
"setuptools>=42",
"wheel",
- "pybind11[global]~=2.6.0",
+ "pybind11[global]>=2.6.0",
"cmake>=3.18",
"scikit-build",
]
-
-build-backend = "setuptools.build_meta"
+build-backend = "setuptools.build_meta"
\ No newline at end of file
diff --git a/setup.py b/setup.py
index 446c53f..21c1ade 100644
--- a/setup.py
+++ b/setup.py
@@ -1,9 +1,9 @@
from skbuild import setup
setup(
- name="pybind11-skbuild-numpy-example",
+ name="pybind11-hello-world",
version="1.0",
- description="pybind11-skbuild-numpy cumulative sum example",
+ description="pybind11/skbuild/numpy cumulative sum example package",
author='MPCDF',
license="MIT",
packages=['cumsum'],
diff --git a/src/cumsum/cumsum.cpp b/src/cumsum/cumsum.cpp
index db99448..ff67189 100644
--- a/src/cumsum/cumsum.cpp
+++ b/src/cumsum/cumsum.cpp
@@ -1,4 +1,4 @@
-// pybind11 example module 'cumsum'
+// pybind11 example module '_cumsum'
#include <numeric>
#include <functional>
#include <pybind11/pybind11.h>
@@ -26,7 +26,7 @@ py::array_t<double> cumsum(py::array_t<double> a)
return b;
}
-// Python binary module _cumsum, expose cumsum C++ function as cumsum to Python
+// Python binary module cumsum, exposing the cumsum C++ function to Python
PYBIND11_MODULE(_cumsum, m) {
m.doc() = "pybind11 cumulative sum example"; // module docstring
m.def("cumsum", &cumsum, // third parameter is the function docstring
--
GitLab