Python-C++ Interface

The PyC module provides Python bindings for AnalysisG’s C++ components using Cython.

For complete API reference, see the Doxygen-generated HTML documentation in doxygen-docs/html/.

Interface Components

C Utilities

Low-level C utility bindings.

Location: src/AnalysisG/pyc/cutils/

Interface Layer

Main Python-C++ interface layer.

Location: src/AnalysisG/pyc/interface/

Features: * Core class wrappers * Method bindings * Property accessors * Python-friendly APIs * Automatic memory management * Exception handling

Operators

Operator implementations for Python.

Location: src/AnalysisG/pyc/operators/

Implements: * Mathematical operators * Comparison operators * Container operators * Special methods

Physics Module

Physics calculation bindings.

Location: src/AnalysisG/pyc/physics/

Common functions: * Transverse momentum (pT) * Pseudorapidity (η) * Azimuthal angle (φ) * ΔR distance * Invariant mass

Transform

Data transformation utilities.

Location: src/AnalysisG/pyc/transform/

Features: * Coordinate transformations * Reference frame changes * Normalization operations * Feature scaling

Graph Interface

Graph operations for Python.

Location: src/AnalysisG/pyc/graph/

Features: * Graph construction from Python * Node/edge manipulation * Graph property access * PyTorch Geometric format conversion

Neutrino Solver Interface

Python interface to neutrino reconstruction.

Location: src/AnalysisG/pyc/nusol/

Submodules: * tensor/ - Tensor operations * cuda/ - CUDA acceleration interface

Usage Examples

Basic Usage

from AnalysisG import Event, Particle, Graph

# Create event
event = Event()
event.load_from_file("data.root")

# Access particles
for particle in event.particles:
    print(f"pT: {particle.pt}, eta: {particle.eta}")

# Build graph
graph = Graph()
graph.build(event)

Advanced Usage

from AnalysisG import NeutrinoSolver, PhysicsUtils

# Neutrino reconstruction
solver = NeutrinoSolver()
solutions = solver.solve(leptons, jets, met)

# Physics calculations
dr = PhysicsUtils.delta_r(particle1, particle2)
mass = PhysicsUtils.invariant_mass([p1, p2, p3])

Design Philosophy

The PyC interface follows:

Pythonic: Natural Python syntax
Performance: Minimal overhead
Safety: Type checking and error handling
Memory: Automatic management
Compatibility: Works with NumPy, PyTorch

Cython Implementation

Uses Cython for binding:

.pxd files: C++ declarations
.pyx files: Implementation
Automatic class wrapping
Direct memory access

Benefits:

Near-zero overhead
Native Python integration
Automatic reference counting
Exception translation

Adding New Bindings

To add bindings for a C++ class:

Declare in .pxd file:

cdef extern from "myclass.h":
    cdef cppclass MyClass:
        void method()
        int property

Wrap in .pyx file:

cdef class PyMyClass:
    cdef MyClass* c_instance

    def method(self):
        self.c_instance.method()

    @property
    def property(self):
        return self.c_instance.property