Rbm/README.md

Rbm

A C++11 library and set of executables implementing Restricted Boltzmann Machines (RBMs), stacked into deep belief networks (DeepStack) or recurrent structures (RnnStack) for character-level text generation ("poet"). Three build targets share the same core sources: a JUCE-based desktop GUI, a project test suite, and a text-generation CLI.

See CLAUDE.md for the full architecture writeup (core RBM/Layer/Stack hierarchy, entry points, project file format) and docs/RNN_ARCHITECTURE.md for how the RNN text-generation stack works specifically.

Dependencies

System-installed, not vendored:

• Armadillo (libarmadillo) — all matrix/vector math.
• JsonCpp (libjsoncpp) — project files (*.prj) serialize to/from JSON.
• JUCE (vendored under juce/, only needed for the GUI target) plus its Linux deps: freetype, X11, Xinerama, Xext, GL, pthread, dl, rt.

Build

The build system is a hand-written Makefile (no CMake). Select the target with PRJ and the build flavor with CONFIG:

make PRJ=POET CONFIG=release   # builds build/release/poet.elf (default: PRJ=POET, CONFIG=release)
make PRJ=TEST CONFIG=debug     # builds build/debug/test.elf
make PRJ=GUI                   # builds build/release/rbm.elf, also builds the JUCE static lib first
make clean                     # removes build/${CONFIG} (respects CONFIG, defaults to release)
make install                   # copies build/release/rbm.elf to ${HOME}/bin

Running make with no arguments builds POET in release. Object/dependency files land in build/${CONFIG}/; .d files are auto-included, so incremental rebuilds correctly pick up header changes.

All three targets (POET/TEST/GUI) × both configs (release/debug) have been verified to build cleanly from a fresh make clean.

Running each target

# Text generation ("poet") -- loads prj/poet_2v_5s/ by default
./build/release/poet.elf c                      # create a fresh project
./build/release/poet.elf r                       # reset (randomize) weights
./build/release/poet.elf t some_text.txt         # train on a text file
./build/release/poet.elf f "seed text" 0.7       # generate text from a seed, optional sampling temperature
                                                  # (temperature <= 0 or omitted = deterministic greedy decode)

# Project test suite -- checks every project listed in main.cpp's `projects` vector
./build/release/test.elf

# Desktop GUI -- must be run from the repo root (resolves prj/<name>/ paths relative to cwd)
./build/release/rbm.elf

GPU acceleration (optional)

run_gpu.sh runs any built binary with NVBLAS (configured via nvblas.conf), which transparently intercepts Armadillo's large matrix-multiply BLAS calls (v_to_h, h_to_v, CD gradients) and offloads them to an NVIDIA GPU via cuBLAS, falling back to the system's CPU BLAS otherwise. This is a runtime LD_PRELOAD shim — no source changes, and it's opt-in only (nothing changes if you just run the binary directly):

./run_gpu.sh ./build/release/poet.elf t some_text.txt
./run_gpu.sh ./build/release/rbm.elf

Requires an NVIDIA GPU and the CUDA runtime's libnvblas.so. Verified on this machine (RTX 4070 Ti): output is byte-identical to a plain CPU run, and GPU utilization/memory visibly rise during training. Practical speedup depends on matrix size — most projects in prj/ are fairly small (hundreds of rows, ~100-200 cols), so the benefit is real but modest compared to larger workloads like mnist/many.

Project files

Named projects (e.g. mnist, poet_2v_5s, context99 — see prj/) each live under prj/<name>/ as a <name>.prj JSON file plus per-layer weight/bias .dat files and a <name>.training.dat batch matrix. These are experiment data and generated artifacts, not something to hand-edit — see CLAUDE.md for the exact file layout and how paths get resolved.