Deepity is a Predictive Coding (PC) library engineered from the ground up for zero-overhead, ultra-low-variance inference and learning. It is aggressively CPU-optimized to extract maximum throughput from modern hardware, with a CUDA backend currently in development.

This page is the entry point into the API reference. For build instructions, benchmarks, and contribution guidelines, see the GitHub README.

Overview

Deepity implements Predictive Coding Networks (PCNs) as an alternative to standard backpropagation-based training. The library is written in C++20, uses custom AVX2/AVX-512 SIMD kernels for activation functions, and packs layer buffers into a single contiguous memory arena for cache locality. A nanobind-based Python extension (pydeepity) exposes the same native engine to Python with negligible overhead.

Quick Start

C++

The DiscriminativePCNetwork class manages layer hierarchies, bidirectionality, and dynamic thread scaling based on batch size automatically:

#include <deepity/networks/DiscriminativePCNetwork.h>
#include <deepity/utils/Activations.h>
#include <vector>
#include <random>
#include <iostream>
 
int main() {
// Initialize a network with a batch size of 4 (e.g., for XOR)
Deep::DiscriminativePCNetwork net(4);
 
    // ... configure layers, load data (see examples/xor.py for a full
    // worked example, and DiscriminativePCNetwork's own docs below for
    // the layer-configuration API) ...
 
    // Train using the clean TrainStep API (150 relaxation steps per epoch)
    for (int epoch = 0; epoch < 1500; ++epoch) {
        float energy = net.TrainStep(X, Y, 150);
    }
 
    // Run inference using the Predict API
    std::vector<float> predictions = net.Predict(X, 150);
 
    for (float pred : predictions) {
        std::cout << "Prediction: " << pred << "\n";
    }
 
    return 0;
 
}

Python

The same engine is available from Python via the compiled pydeepity extension module. Runnable examples live in examples/, including examples/xor.py (minimal training loop) and examples/train_mnist_deep.py (end-to-end MNIST training).

Core Architecture

Networks

Top-level network abstractions, each managing a layer stack and the predictive-coding relaxation loop:

Deep::SimplePCNetwork — no precision weighting
Deep::DiscriminativePCNetwork — the original, precision-weighted PCN
Deep::ConvPCNetwork / Deep::SimpleConvPCNetwork — convolutional, im2col-based
Deep::GaussSeidelPCNetwork — sequential (Gauss-Seidel) layer sweeps instead of simultaneous updates
Deep::DirectKPPCNetwork — Direct Kolen-Pollack feedback alignment (DFA) in place of symmetric weight transport
Deep::FullPCNetwork — DirectKPPCNetwork's DFA structure plus opt-in muPC scaling and residual connections, every extra OFF by default so it reproduces DirectKPPCNetwork exactly

Layers

All layers derive from a common Layer base:

Supporting Components

Deep::MemoryArena / Deep::DeviceMemoryArena — contiguous buffer allocation for layer state
Deep::AdamUpdate / Deep::AdamWUpdate — weight-update optimizer
Deep::StreamAlignedBatcher — batch alignment for SIMD kernels
Deep::Im2Col — convolution lowering
Deep::ModelIO — model save/load
Deep::ProfileAccumulator / Timer — internal profiling utilities
Activation functions (Elliot Sigmoid approximation, vectorized ReLU) — see Activations.h

Performance

On a 12th Gen Intel Core i7-12700H, Deepity sustains roughly 123 GFLOPS during predictive-coding inference and learning when compiled with Clang (LLVM), via custom SIMD micro-kernels, 64-byte-aligned buffers, and a contiguous memory arena. Full benchmark methodology and GCC-vs-Clang comparisons are in the README.

Roadmap

SIMD micro-kernels (AVX2/AVX-512 Padé approximations)

Contiguous flat-memory buffers

PCNetwork abstraction (Layer hierarchy & bidirectional inference)

Python bindings (nanobind + NumPy support)

API reference documentation (Doxygen)

Multithreading and Precision Metrics

Memory Arena Contiguity

File IO Support (Deep::ModelIO)
CUDA accelerated engine (GPU GEMM operations for massive scales) — in active development on the dev/CUDA branch

Java port

Elsewhere

GitHub README — install, build (build.py), and benchmark details
CONTRIBUTING.md