Home

Welcome to the Deepity wiki!

Welcome to the official documentation for Deepity, a Predictive Coding (PC) library engineered from the ground up for zero-overhead, ultra-low variance inference and learning. Deepity is aggressively CPU-optimized to extract maximum throughput from modern hardware, maintaining this performance footprint in both native C++ and Python.

Use this wiki to navigate the library's core concepts, architecture, and API.

📖 Overview

Deepity implements Predictive Coding models, allowing networks to iteratively settle into equilibrium over "artificial time" by minimizing prediction errors. Unlike rigid, one-shot forward passes in standard backpropagation, Deepity layers dynamically adjust their latent states based on bottom-up data and top-down expectations.

Core Architectural Features

• Custom SIMD Micro-Kernels: Deepity bypasses standard C++ library bottlenecks by implementing highly optimized activation functions using raw AVX2 and AVX-512 intrinsics.
• SLEEF-backed transcendentals: Activations route through Sleef's vectorized tanh/exp kernels — themselves Padé rational polynomial approximations under the hood — instead of scalar expf/tanhf libm calls, with per-ISA AVX-512/AVX2/SSE paths and a scalar tail. See Performance & Compilation Guide for measured speedups by activation and size.
• Contiguous Arena Allocator: All layer buffers in a network are packed into a single contiguous memory block to maximize L1/L2 cache locality and eliminate pointer-chasing overhead.
• Strict Memory Alignment: Enforces strict 64-byte memory boundaries (std::align_val_t{64}) for all internal sequential sub-buffers to prevent hardware exceptions during wide SIMD register loads.

🧭 API Reference

Explore the core C++ classes and modules that power Deepity (all under the Deep:: namespace):

Networks & Layers

• Deep::DiscriminativePCNetwork: The network-level abstraction managing an array of predictive coding layers. Handles auto-batch size detection and full-network state/weight updates.
• Deep::DiscriminativePCLayer: The standard single-layer implementation of a PC model, managing beliefs ($z$), errors ($e$), and weight matrices ($W$).
• Deep::SimplePCLayer / Deep::FullPCLayer: The two most commonly used layer variants — SimplePCLayer is classic settling; FullPCLayer adds optional research extras (DKP, µPC scaling, residual connections, iPC, ePC, momentum settling) switchable one at a time. See the main repo's README for the full comparison table.
• Deep::Layer: The virtual base class defining the standard interface for all Deepity layers.

Math & Utilities

• Deep::Activations: SIMD-optimized implementations (AVX-512, AVX2, SSE) for standard neural activations — ReLU, GELU, TanH, the standard logistic Sigmoid, and the faster Elliot Sigmoid approximation (S(x) = (1/2)((x / (1 + |x|)) + 1)) — plus their derivatives.
• Deep::Optimize: Hardware-specific utility functions, such as GetL2CacheBytes() and AutoBatchSize(), designed to dynamically optimize execution based on the host CPU's L2 cache.

⚡ Performance & Compilation Guide

Deepity is built for speed. On the benchmarked MNIST training loop (SimplePCN, matched against the JAX-based jpc and ngc-learn predictive-coding libraries), Deepity sustains ~675 GFLOPS/s end-to-end, and ~690 GFLOPS/s on the raw kernel throughput benchmark alone — see the main repo's Performance & Benchmarks section for the full methodology, FLOP accounting, and per-activation SIMD-vs-naive speedup tables (TanH, Sigmoid, GELU, ReLU).

Compiler Recommendation: Clang (LLVM)

We heavily recommend compiling Deepity with Clang (LLVM). Recent benchmarking shows Clang provides measurable speedups over GCC, nearly halving execution time for layer weight updates and winning heavily in the primary training loop.

Batching & Scaling

Batching provides massive scaling. Through hardware profiling, a batch size of 256 proved to be the sweet spot for maximizing CPU utilization before cache eviction penalties take over. You can also use the AutoBatchSize utility to let the framework calculate the optimal batch size for your specific CPU.

Python Interface

Deepity ships with lightweight Python bindings via nanobind. Install with pip install pydeepity, then import deepity (the distribution name on PyPI and the importable module name differ). It accepts standard NumPy arrays but executes the entire inference loop in native C++ memory, running significantly faster than naive vectorization.

pip install pydeepity

🛠️ Building the Project

Deepity uses CMake as its build system.

1. Ensure you have CMake 3.21+, a C++20-compatible compiler (Clang recommended), OpenMP, and BLAS (OpenBLAS or Intel MKL) installed.
2. Clone the repository and run python build.py Release OpenBLAS --fast from the repo root — this configures CMake, builds, and runs the test suite in one command.
3. The project automatically fetches and links its native dependencies (SLEEF, oneDNN, Google Benchmark, and nanobind for the Python bindings) via CMake's FetchContent.

Note: See the repository's README.md for full code examples for both C++ and Python, and CONTRIBUTING.md for the complete prerequisite list and known-working manual CMake invocations.