C++ Neural Network Extension for Python

A small educational project demonstrating how Python can call a neural-network operation implemented in C++.

The project uses pybind11 to compile C++ code into a native Python extension. Python passes NumPy arrays to C++, the C++ function performs a dense-layer calculation, and the result is returned to Python as another NumPy array.

What This Project Demonstrates

This project shows the basic architecture used by larger machine-learning frameworks:

Python application
        ↓
Python-to-C++ binding
        ↓
Compiled C++ function
        ↓
Native CPU execution
        ↓
Result returned to Python

The implemented neural-network operation is:

output = ReLU(weights × input + bias)

Where:

• input contains the input features.
• weights contains the learned weight values.
• bias contains one bias value for each output neuron.
• ReLU replaces negative results with zero.

Terminal Output

The screenshot below shows the C++ extension being built successfully and then called from Python.

The final output is:

[0.1 0.  4.2]

Project Structure

cpp-neural-example/
├── cpp/
│   └── neural.cpp
├── docs/
│   └── terminal-output.png
├── demo.py
├── pyproject.toml
├── setup.py
└── README.md

Requirements

• Python 3.13 or another supported Python 3 version
• A C++ compiler with C++17 support
• NumPy
• pybind11
• setuptools
• wheel

On macOS, the compiler is normally provided by the Xcode Command Line Tools.

Install them with:

xcode-select --install

Installation

Clone the repository:

git clone https://github.com/GordenArcher/cpp-neural-example.git
cd cpp-neural-example

Install the required Python packages:

python3 -m pip install numpy pybind11 setuptools wheel

Compile and install the C++ extension in editable mode:

python3 -m pip install -e .

Running the Example

Run:

python3 demo.py

Expected output:

Input:
[ 2. -1.]

Weights:
[[ 0.5   1.  ]
 [-1.    0.25]
 [ 2.   -0.5 ]]

Bias:
[ 0.1  0.2 -0.3]

Output:
[0.1 0.  4.2]

How the Calculation Works

The input vector is:

[2.0, -1.0]

The weight matrix is:

[
  [ 0.5,  1.0 ],
  [-1.0,  0.25],
  [ 2.0, -0.5 ]
]

The bias vector is:

[0.1, 0.2, -0.3]

First output neuron

(0.5 × 2.0) + (1.0 × -1.0) + 0.1
= 0.1

ReLU(0.1) = 0.1

Second output neuron

(-1.0 × 2.0) + (0.25 × -1.0) + 0.2
= -2.05

ReLU(-2.05) = 0.0

Third output neuron

(2.0 × 2.0) + (-0.5 × -1.0) - 0.3
= 4.2

ReLU(4.2) = 4.2

The final result is therefore:

[0.1, 0.0, 4.2]

How Python Calls C++

Python cannot directly execute a .cpp source file. The C++ source must first be compiled into a native shared library.

The PYBIND11_MODULE macro creates the initialization entry point that Python expects:

PYBIND11_MODULE(neural_cpp, module) {
    module.def(
        "dense_relu",
        &dense_relu,
        py::arg("input"),
        py::arg("weights"),
        py::arg("bias")
    );
}

After compilation, Python can import the native module:

import neural_cpp

It can then call the C++ function like a normal Python function:

output = neural_cpp.dense_relu(
    input_values,
    weights,
    bias,
)

The execution path is:

demo.py
   ↓
import neural_cpp
   ↓
Python loads the compiled extension
   ↓
pybind11 validates and exposes the NumPy arrays
   ↓
C++ performs the dense-layer calculation
   ↓
C++ returns a NumPy array
   ↓
Python prints the result

NumPy and Native Memory

The project accepts contiguous NumPy arrays.

pybind11 reads information such as:

• Array dimensions
• Shape
• Data type
• Memory address

The C++ code then accesses the underlying array memory through native pointers.

This avoids converting every NumPy value into a separate Python object before performing the calculation.

Rebuilding After C++ Changes

After changing cpp/neural.cpp, rebuild the extension:

python3 -m pip install -e .

Then run the demonstration again:

python3 demo.py

Finding the Compiled Extension

Run:

python3 -c "import neural_cpp; print(neural_cpp.__file__)"

The generated extension will have a name similar to:

neural_cpp.cpython-313-darwin.so

The exact filename depends on the operating system, processor architecture, and Python version.

Technologies Used

• C++17
• Python
• pybind11
• NumPy
• setuptools

Possible Improvements

Future versions could add:

• Multiple dense layers
• Additional activation functions
• Softmax output
• Loss functions
• Backpropagation
• Gradient calculation
• Weight updates
• Batch processing
• OpenMP parallelization
• SIMD optimization
• CUDA support
• PyTorch tensor integration

Purpose

This project is intended for learning how native machine-learning operations can be implemented in C++ and exposed to Python.

It is not intended to replace full machine-learning frameworks such as PyTorch or TensorFlow. Instead, it demonstrates the same fundamental language-interop approach on a much smaller and easier-to-understand scale.

License

This project is available under the MIT License.