Skip to content
Skills Library
Programming · Building & coding

cpp-bindings

/cpp-bindings

Use when writing Python bindings for C++ HEP code with nanobind or pybind11: exposing a C++ class or function to Python, binding STL containers (vector, map), handling numpy/awkward array interop, choosing between nanobind and pybind11, or setting up a CMake build that produces a Python extension module.

Repository
marketplace ↗
Licence
MIT
Last repository change
16.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
2
Deprecation

No signals detected. Repository changed on 16.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Use when writing Python bindings for C++ HEP code with nanobind or pybind11: exposing a C++ class or function to Python, binding STL containers (vector, map), handling numpy/awkward array interop, choosing between nanobind and pybind11, or setting up a CMake build that produces a Python extension module.

Original author description

Use when writing Python bindings for C++ HEP code with nanobind or pybind11: exposing a C++ class or function to Python, binding STL containers (vector, map), handling numpy/awkward array interop, choosing between nanobind and pybind11, or setting up a CMake build that produces a Python extension module.

How it works

  1. Overview
  2. When to Use
  3. Key Concepts
  4. Canonical Patterns
  5. Gotchas
  6. Interop
  7. Docs
Original SKILL.md headings · 191 lines, 735 words
SKILL.md preview
---
name: cpp-bindings
description: >-
  Use when writing Python bindings for C++ HEP code with nanobind or pybind11:
  exposing a C++ class or function to Python, binding STL containers (vector,
  map), handling numpy/awkward array interop, choosing between nanobind and
  pybind11, or setting up a CMake build that produces a Python extension module.
---

# C++ Python Bindings (nanobind / pybind11)

## Overview

nanobind and pybind11 are C++ header-only libraries for creating Python
extension modules from C++ code. pybind11 is the established standard; nanobind
is a leaner, faster successor from the same author (Wenzel Jakob), offering
smaller binary size and faster compile times. (Current nanobind requires Python
3.9+; older releases supported 3.8.) In HEP, bindings are used to expose
ROOT-based code, custom reconstruction algorithms, or legacy C++ analysis code
to Python without rewriting.

## When to Use

- Exposing a C++ class or function to Python without rewriting it
- Binding STL containers (`std::vector`, `std::map`) or Eigen arrays to numpy
- Wrapping ROOT-based reconstruction algorithms or legacy C++ analysis code
- Choosing between nanobind (faster compile, leaner) and pybind11 (broader
  ecosystem) for a new project
- Setting up a CMake build that produces an importable Python extension module

## Key Concepts

| Feature       | nanobind                         | pybind11             |
| ------------- | -------------------------------- | -------------------- |
| Compile time  | Faster (30–50%)                  | Slower               |
| Binary size   | Smaller                          | Larger               |
| STL casters   | Opt-in per-type header           | Bulk `stl.h` header  |
| ABI isolation | Versioned ABI + domain isolation | No version isolation |
| Maturity      | Newer (2022+)                    | Very mature (2015+)  |
| Documentation | Growing                          | Comprehensive        |

**Recommendation**: Use **nanobind** for new projects. Use **pybind11** when
integrating with existing pybind11-based code or when you need the larger
ecosystem of pybind11 extensions.

## Canonical Patterns

### CMake setup (nanobind)

```cmake
cmake_minimum_required(VERSION 3.15)
project(myhep)

find_package(Python 3.9 COMPONENTS Interpreter Development.Module REQUIRED)
find_package(nanobind CONFIG REQUIRED)

nanobind_add_module(myhep_ext myhep.cpp)
target_link_libraries(myhep_ext PRIVATE MyHEPLib)
```

### CMake setup (pybind11)

```cmake
find_package(pybind11 CONFIG REQUIRED)
pybind11_add_module(myhep_ext myhep.cpp)
target_link_libraries(myhep_ext PRIVATE MyHEPLib)
```

### Bind a simple function (nanobind)

```cpp
// myhep.cpp
#include <nanobind/nanobind.h>

namespace nb = nanobind;

double invariant_mass(double px, double py, double pz, double e) {
    double m2 = e*e - px*px - py*py - pz*pz;
    return m2 > 0.0 ? std::sqrt(m2) : 0.0;
}

NB_MODULE(myhep_ext, m) {
    m.def("invariant_mass", &invariant_mass,
          nb::arg("px"), nb::arg("py"), nb::arg("pz"), nb::arg("e"),
          "Compute invariant mass from four-momentum (GeV).");
}
```

```python
import myhep_ext
m = myhep_ext.invariant_mass(0.0, 0.0, 0.0, 125.0)  # → 125.0 GeV
```

### Bind a class (nanobind)

```cpp
#include <nanobind/nanobind.h>
#include <nanobind/stl/string.h>

namespace nb = nanobind;

class Jet {
public:
    Jet(double pt, double eta, double phi) : pt_(pt), eta_(eta), phi_(phi) {}
    double pt() const { return pt_; }
    double eta() const { return eta_; }
    std::string repr() const {
        return "Jet(pt=" + std::to_string(pt_) + ")";
    }
private:
    double pt_, eta_, phi_;
};

NB_MODULE(myhep_ext, m) {
    nb::class_<Jet>(m, "Jet")
        .def(nb::init<double, double, double>(),
             nb::arg("pt"), nb::arg("eta"), nb::arg("phi"))
        .def("pt",  &Jet::pt)
        .def("eta", &Jet::eta)
        .def("__repr__", &Jet::repr);
}
```

### numpy array interop (nanobind)

```cpp
#include <nanobind/nanobind.h>
#include <nanobind/ndarray.h>

namespace nb = nanobind;
using Array1D = nb::ndarray<double, nb::shape<-1>, nb::c_contig>;

nb::ndarray<double, nb::ndim<1>, nb::c_contig>
compute_pt(Array1D px, Array1D py) {
    size_t n = px.shape(0);
    auto result = new double[n];
    for (size_t i = 0; i < n; ++i)
        result[i] = std::sqrt(px(i)*px(i) + py(i)*py(i));
    nb::capsule owner(result, [](void *p) noexcept { delete[] (double*)p; });
    return nb::ndarray<double, nb::ndim<1>, nb::c_contig>(result, {n}, owner);
}

NB_MODULE(myhep_ext, m) {
    m.def("compute_pt", &compute_pt);
}
```

### STL containers (pybind11)

```cpp
#include <pybind11/pybind11.h>
#include <pybind11/stl.h>   // auto-converts std::vector ↔ list

namespace py = pybind11;

std::vector<double> jet_pts(std::vector<double> px, std::vector<double> py) {
    std::vector<double> result;
    for (size_t i = 0; i < px.size(); ++i)
        result.push_back(std::sqrt(px[i]*px[i] + py[i]*py[i]));
    return result;
}

PYBIND11_MODULE(myhep_ext, m) {
    m.def("jet_pts", &jet_pts);
}
```

## Gotchas

- **GIL (Global Interpreter Lock)**: For CPU-bound C++ functions that don't
  touch Python objects, release the GIL with `nb::gil_scoped_release` to allow
  parallel Python threads.
- **Lifetime management**: Python's garbage collector doesn't know about C++
  object lifetimes. Use `nb::keep_alive` or `py::keep_alive` policies for
  objects that hold references.
- **STL opaque types in nanobind**: nanobind does NOT auto-convert `std::vector`
  to Python lists by default (unlike pybind11). Include
  `<nanobind/stl/vector.h>` to enable conversion.
- **ROOT dictionary conflicts**: When linking against ROOT, ROOT's
  auto-generated dictionaries may conflict with pybind11/nanobind. Use a
  separate shared library to isolate ROOT from the Python extension.
- **ABI mismatch**: The Python extension must be compiled against the same
  Python version and ABI as the interpreter. Use `scikit-build-core` or
  `meson-python` to manage this.

## Interop

- **numpy**: `<nanobind/ndarray.h>` (nanobind) or `<pybind11/numpy.h>`
  (pybind11) for zero-copy array passing.
- **awkward**: awkward's `ak.from_buffers` / `ak.to_buffers` can wrap C++
  arrays; combine with nanobind ndarray for zero-copy workflows.
- **CMake + scikit-build-core**: The recommended build backend for Python
  extensions that use CMake.

## Docs

nanobind: https://nanobind.readthedocs.io/ pybind11:
https://pybind11.readthedocs.io/

Versions

The database has no other skills named cpp-bindings.

Database snapshot: 13.11.2026 · package version fab10c32c472 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 95cpp-style
    Applies C++ coding conventions when writing, reviewing, or refactoring code. Covers .h, .hpp, and .cpp files, Doxygen documentation, naming, formatting, error handling, includes, file ordering, template patterns, embedded (Arduino/PlatformIO) conventions, and Python C++…
  • 90agent-cpp-expert
    Specialist subagent: C and C++ development, modern C++ (C++17/20/23), CMake, systems programming, and memory management specialist. Use when writing C/C++ code, debugging memory issues, or building systems-level software. Trigger phrases: C++, C language, CMake, modern C++,…
  • 91cmake-build-system
    CMake build-system design. Use for Literate AI workflow tasks.
  • 100gdextension
    Use when building native extensions for Godot — godot-cpp (C++) or gdext (Rust), binding classes, building, and GDScript/C# interop
  • 100cpp-expert
    Expert-level C++ development with modern C++20/23, STL, memory management, and performance. Use when the user mentions C++, C++20, C++23, the STL, templates, or performance, or when the task involves Modern C++ Features, Memory Management, Ranges and Views, or Coroutines.
  • 100gdextension
    Use when building native extensions for Godot — godot-cpp (C++) or gdext (Rust), binding classes, building, and GDScript/C# interop

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.