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.
• Rational Polynomial Tanh: Uses a highly tuned Padé rational polynomial approximation and Sleef, avoiding expensive expf instruction calls for up to a 40% speedup.
• 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:

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::RBLayer: (Experimental) A Restricted Boltzmann-style PC Layer for generative models, managing bidirectional errors (bottom-up and top-down) and integrating dynamics with forward/backward time constants.
• Deep::Layer: The virtual base class defining the standard interface for all deepity layers.

Math & Utilities

• Deep::Activations: Contains SIMD-optimized implementations (AVX-512, AVX2, SSE) for standard neural activations, including relu, tanh, sigmoid (Elliot approximation), and 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, sustaining ~119 GFLOPS on modern CPUs. To get the most out of the library, keep the following in mind:

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 pybind11. The Python module (deepity) accepts standard NumPy arrays but executes the entire inference loop in native C++ memory, running significantly faster than naive vectorization.

🛠️ Building the Project

Deepity uses CMake as its build system.

1. Ensure you have CMake, a C++20 compatible compiler (Clang recommended), OpenMP, and BLAS installed.
2. Clone the repository and run the standard CMake build generation.
3. The project will automatically fetch and link sleef and pybind11.

Note: See the repository's README.md for full code examples for both C++ and Python).