Mujou¶

Asynchronous Distributed Deep Learning Library for Continuous Learning

Mujou is a deep learning framework that keeps inferring and learning at the same time. You write nodes in PyTorch code and run a network that connects them.

Early development

Mujou is in an early stage of development. The API may change without notice.

🌱 A network that keeps learning¶

Conventional machine learning trains a model, then freezes its weights for inference. A Mujou network takes input and produces output for as long as it runs, and keeps learning at the same time.

There is no mode to switch between training and inference, and there are no epochs.

The name comes from 無常 (mujō, impermanence: nothing stays the same), as in the Buddhist phrase 諸行無常. Mujou is a framework for machines that keep learning from a stream and keep changing. It targets uses that learn while they act, such as real-time processing and robotics.

The program below is such a network: a chain of PC-ALM nodes, three of them learning, that learns a regression from a stream of batches. Each batch is predicted before the nodes learn from it, while the nodes keep running.

SHOWN = 0.032  # seconds of the run's timer each batch is shown
# tau.h sets how fast the credit settles (and the period of the nodes, h / 2),
# and the weights learn once per batch, by SGD at the rate
# SHOWN / optimizer.tau = 0.3.
tau = pc.TimeConstants(h=4e-3, lam=2e-3, r=4e-3)
optimizer = pc.optim.SGD(tau=SHOWN / 0.3)
torch.manual_seed(0)  # the initial weights, before the run
net = pc.Chain(
    nn.Sequential(nn.Linear(2, 64), nn.Tanh()),
    nn.Sequential(nn.Linear(64, 64), nn.Tanh()),
    nn.Linear(64, 1),
    x=TensorSpec((B, 2)),
    y=TensorSpec((B, 1)),
    batch=B,
    loss=pc.loss.MSELoss(B),  # the loss of each sample, (B,)
    tau=tau,
    optimizer=optimizer,
    learn_interval=0.75 * SHOWN,  # learn once, 3/4 of the way through each batch
)

torch.set_num_threads(1)
g = torch.Generator().manual_seed(1)
every = torch.ones(B, dtype=torch.bool)  # every sample has a target, and is new
losses: list[float] = []
with mujou.run(net) as run:
    for i in range(300):
        x = 2 * torch.rand(B, 2, generator=g) - 1
        y = torch.sin(2 * x[:, :1]) * torch.cos(x[:, 1:])
        sample = pc.msg.Sample(x=x, y=y, mask=every, reset=every)
        p = pc.show(run, net, sample, seconds=SHOWN)
        losses.append(nn.functional.mse_loss(p["y_hat"], y).item())  # before learning
        if i == 0 or (i + 1) % 50 == 0:
            recent = losses[-50:]
            mean = sum(recent) / len(recent)
            print(
                f"batch {i + 1:3d}: loss {mean:.4f} (the mean of the last {len(recent)})"
            )
    # The state of a node, by its path: input, layer0, layer1, output.
    lam = run.state_dict()["nodes"]["layer0"]["state"]["lam"]
print(f"the mean |lam| of layer0 (its credit) at the end: {lam.abs().mean():.2e}")

✨ Features¶

🔄 Inference and learning at once: no training mode, no inference mode, no epochs
🧩 Nodes in PyTorch: write each node in ordinary PyTorch code, run synchronously inside the node
⚡ Asynchronous nodes: each node updates on its own schedule and never waits for another
⏱️ Continuous time: nodes update in proportion to dt, the time that really passed
🧠 Any update rule: backpropagation inside a node, PC-ALM across nodes, or a rule of your own
💾 State without stopping: take the state of a running network and resume from it later
🧪 Deterministic tests: a virtual timer and manual updates for testing nodes

⚙️ How it runs¶

flowchart LR
    H["Host (your program)"] -->|"writes inputs"| A["Node A"]
    A -->|"latest value"| B["Node B"]
    B -->|"reads outputs"| H

Each node repeats its update on its own schedule and never waits for another node; it reads the latest value its neighbor sent.

The host (the program that runs the network) writes inputs to the running network and reads its outputs.

🧭 Where to go next¶

New to Mujou? Install it, read How Mujou Works, then follow the Tutorial from the first page. The Topics go deeper into each part, the Examples list every program, and the API Reference has every public name.

📦 Installation

Build Mujou from source and check that it works.

Installation
🧠 How Mujou Works

Nodes, ports, networks, runs, time, state, testing and learning, and the rules a node keeps.

How Mujou Works
🚀 Tutorial

Run a network, write and test a node, learn in a node and with PC-ALM, save and resume.

Tutorial
🗺️ Topics

Ports, groups, host I/O, time, threads and devices, errors, update rules, PC-ALM.

Topics
💡 Examples

Every example program, by what you want to do.

Examples
📚 API Reference

Every public class and function, generated from the docstrings.

API Reference