[binary_autoencoder] - add BB-RBM autoencoder test and tests README

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

src/tests/README.md

@@ -0,0 +1,58 @@
+# Tests
+
+Run any test from the `src/tests/` directory:
+
+```bash
+cd src/tests
+python test_<name>.py
+```
+
+---
+
+## Self-contained tests
+
+These generate their own data and run without external files.
+
+| File | RBM type | What it tests |
+|---|---|---|
+| `test_binary_autoencoder.py` | BB-RBM | Auto-encoder on synthetic bars-and-stripes binary images (8×8). Trains, reconstructs, and plots original vs. reconstruction. |
+| `test_model.py` | BB-RBM (4 layers) | Deep auto-encoder on random binary data (1024-dim). Prints per-pattern reconstruction error. |
+| `test_xor.py` | BB-RBM | Auto-encoder on XOR-like 3-bit patterns using the older `Layer` API. |
+| `test_linear.py` | GB-RBM or GG-RBM | GB/GG-RBM on random continuous data (3000-dim). Toggle `do_gaussian_hidden` at the top of the file. |
+| `test_sub_image.py` | — | Unit test for `SubImage` (patch extraction). No RBM involved. |
+| `test_conv2d.py` | — | Unit test for `conv2d`. No RBM involved. |
+
+---
+
+## Tests requiring external data
+
+These load data from `/home/jens/work/repos/Rbm/` (Armadillo `.dat` files).
+
+| File | RBM type | What it tests |
+|---|---|---|
+| `test_norbs.py` | GB-RBM or GG-RBM | Single-layer auto-encoder on NORB small (96×96 images). Toggle `DO_HIDDEN_GAUSSIAN` at the top of the file. |
+| `test_deep_norbs.py` | GB-RBM + BB-RBM | Two-layer deep auto-encoder: loads pre-trained GB-RBM weights, trains a BB-RBM on top. |
+| `test_learn_norbs_labels.py` | GB-RBM + BB-RBM | Multimodal model combining NORB image features with one-hot label embeddings in a joint hidden layer. |
+| `test_rbm.py` | Any (from `.prj` file) | Full pipeline via `StackFactory`. Takes a project name as CLI argument (`python test_rbm.py <name>`). Uses OpenCV for interactive reconstruction display. |
+
+---
+
+## Tests requiring saved state
+
+These expect a trained model to already exist in `results/`.
+
+| File | Prerequisite |
+|---|---|
+| `test_label.py` | Requires a saved `Label` fitter. Trains a binary label encoder (vocabulary of 100 integers → 5×5 binary codes) and visualises encoded labels. Set `do_train = True` on first run. |
+| `test_learn_encoded_labels.py` | Requires a saved one-hot label fitter. Trains a BB-RBM on one-hot encoded integer labels and plots hidden representation, reconstruction, and original. Set `do_train = True` on first run. |
+
+---
+
+## RBM type reference
+
+| Type | Visible | Hidden | `EntityParams` |
+|---|---|---|---|
+| BB-RBM | Binary | Binary | `EntityParams()` |
+| GB-RBM | Gaussian | Binary | `EntityParams(do_gaussian_visible=True)` |
+| BG-RBM | Binary | Gaussian | `EntityParams(do_gaussian_hidden=True)` |
+| GG-RBM | Gaussian | Gaussian | `EntityParams(do_gaussian_visible=True, do_gaussian_hidden=True)` |

src/tests/test_binary_autoencoder.py

@@ -0,0 +1,75 @@
+import random
+import matplotlib.pyplot as plt
+
+from rbm.model import Model
+from rbm.entity import Entity, EntityParams, TrainingParams
+from rbm.matrix import Mat, np
+
+N = 8
+N_VIS = N * N
+N_HID = 32
+N_CASES = 400
+
+
+class TestModel(Model):
+	def __init__(self, name: str, work_dir: str = '.'):
+		super().__init__(name, work_dir)
+		self.unit1 = Entity(
+			(N_VIS, N_HID),
+			EntityParams(),
+			TrainingParams(learning_rate=0.1, momentum=0.9, num_epochs=5000, do_rao_blackwell=True)
+		)
+
+	def forward(self, x: Mat) -> Mat:
+		return self.unit1.forward(x)
+
+	def reconstruct(self, x: Mat) -> Mat:
+		return self.unit1.reconstruct(x)
+
+
+def make_bars_and_stripes(n_cases: int, n: int = N) -> Mat:
+	data = np.zeros((n_cases, n * n), dtype=np.float64)
+	for i in range(n_cases):
+		img = np.zeros((n * n,), dtype=np.float64)
+		if random.random() > 0.5:
+			row = random.randint(0, n - 1)
+			img[row * n:(row + 1) * n] = 1.0
+		else:
+			col = random.randint(0, n - 1)
+			img[col::n] = 1.0
+		data[i] = img
+	return data
+
+
+if __name__ == "__main__":
+	prj_name = "binary_autoencoder"
+	work_dir = "results"
+
+	model = TestModel(prj_name, work_dir)
+	model.init(0.01)
+
+	train_batch = make_bars_and_stripes(N_CASES)
+	model.train(train_batch)
+	model.save()
+
+	test_batch = make_bars_and_stripes(10)
+	n_show = len(test_batch)
+
+	fig, axes = plt.subplots(2, n_show, figsize=(n_show * 1.5, 3))
+	axes[0, 0].set_ylabel("Original")
+	axes[1, 0].set_ylabel("Recon")
+
+	total_error = 0.0
+	for i, inp in enumerate(test_batch):
+		h = model.forward(inp)
+		recon = model.reconstruct(h)
+		total_error += float(np.mean(np.abs(inp - recon)))
+
+		axes[0, i].imshow(np.asnumpy(np.reshape(inp, (N, N))), cmap='gray', vmin=0, vmax=1)
+		axes[0, i].axis('off')
+		axes[1, i].imshow(np.asnumpy(np.reshape(recon, (N, N))), cmap='gray', vmin=0, vmax=1)
+		axes[1, i].axis('off')
+
+	print(f"Mean reconstruction error: {total_error / n_show:.4f}")
+	plt.tight_layout()
+	plt.show()