Training a network

Note

This chapter needs the full build of pyaicad (see Installation).

The neural searches repair with the predictions of a network. A network is trained on a set of problems, one problem per example, and the trained network lives in a checkpoint directory, so a network trained once can be used by any later program.

Each network has its own restrictions

This chapter shows the workflow. What a given network accepts (how its problems may differ, how many variables or values it handles, what it needs from a model) depends on the network, and is documented with it in the Rust documentation of the aicad crate, for the ConsFormer network in the neural::consformer module. The examples below use graph colourings of the same size because that is what the ConsFormer network accepts. fit and the searches check what they can and raise an error that names the problem.

Hide code cell source

import random
import tempfile
import pyaicad as ac
from pyaicad import learning

def coloring(rng, nodes, colours, degree):
    hidden = [rng.randrange(colours) for _ in range(nodes)]
    model = ac.Model()
    colour = model.int_vars(nodes, domain=range(colours))
    pairs = [(i, j) for i in range(nodes) for j in range(i + 1, nodes) if hidden[i] != hidden[j]]
    probability = min(1.0, degree * nodes / 2 / len(pairs))
    for i, j in pairs:
        if rng.random() < probability:
            model.add(ac.not_equal(colour[i], colour[j]))
    return model

Data

Dataset.split divides the problems you train on into a training and a validation set. The validation problems pick the best network during training. (fit also takes a plain list and splits it 80/20 itself.)

There is no test set in a Dataset on purpose. The problems you evaluate on are yours to keep apart: generate them separately and never pass them to fit, so that the network has certainly not seen them.

rng = random.Random(0)
training_problems = [coloring(rng, nodes=20, colours=3, degree=3.5) for _ in range(108)]
test_problems = [coloring(rng, nodes=20, colours=3, degree=3.5) for _ in range(12)]

data = learning.Dataset.split(training_problems, 0.1, seed=0)
print(len(data.train), "training,", len(data.validation), "validation,", len(test_problems), "test")
97 training, 11 validation, 12 test

Recipes

A recipe is a named way of training: the loss, the architecture and the optimiser. Settings of a recipe are changed by name.

print(sorted(learning.RECIPES))
['consformer', 'consformer-mdd']

consformer-mdd scores the network with the exact probability that its predictions satisfy each constraint, computed on the diagram of the constraint. Before the count, the diagrams are labelled by bp_rounds rounds of belief propagation (0 by default: the predictions are scored as they are), the same ones NeuralPriorBPSearch runs: with bp_rounds > 0 each constraint scores the network’s predictions tilted by what the other constraints say about each variable, so the loss is not blind to them. The rounds are not differentiated through: the gradient is taken with respect to the predictions, the messages being constants.

The predictions are the softmax of the network’s logits after Gumbel noise, as in ConsFormer. gumbel_scale multiplies that noise: 1 (the default) is the Gumbel-softmax relaxation, 0 trains on the plain softmax, with no noise, which makes the loss, and the validation loss that keeps the best network, deterministic. It applies to the whole loss, belief propagation included.

checkpoint_dir = tempfile.mkdtemp()
checkpoint = learning.fit(
    data,
    "consformer-mdd",
    checkpoint_dir=checkpoint_dir,
    seed=0,
    epochs=4,
    validation_interval=2,
    embedding_size=16,
    hidden_size=16,
    expand_size=32,
    num_heads=2,
)
print("network saved in", checkpoint.path)
network saved in /tmp/tmpgugj16p1

fit keeps the best network in the checkpoint directory. The network here is tiny and trained for a few epochs, so it will not beat belief propagation alone on problems this easy; the example shows the workflow.

Searching with the network

The checkpoint is a parameter of the neural searches, which otherwise take the same options as the belief-propagation one. NeuralPriorSearch repairs with the network directly; NeuralPriorBPSearch refines its predictions with belief propagation on the constraint diagrams before choosing.

limits = ac.Limits(time=10, iterations=100)
searches = {
    "belief propagation": ac.BeliefPropagationSearch(destroy="worst", destroy_fraction=0.2),
    "neural prior": ac.NeuralPriorSearch(checkpoint, destroy="worst", destroy_fraction=0.2),
    "neural prior + BP": ac.NeuralPriorBPSearch(checkpoint, destroy="worst", destroy_fraction=0.2),
}
for name, search in searches.items():
    results = ac.local_search(test_problems, search, limits, seed=0)
    print(f"{name:>20}: solved {sum(r.found for r in results)} of {len(results)} test problems")
  belief propagation: solved 12 of 12 test problems
        neural prior: solved 0 of 12 test problems
   neural prior + BP: solved 11 of 12 test problems

Using a checkpoint later

learning.load reads a checkpoint back. A network is tied to the problems it was trained on, in a way that depends on the network (see the note at the top of the chapter): problems that fit it are solved with it directly. batch_size=1 solves them one after the other, each with its own limits, as a deployment would; by default all the problems are stepped together on the device.

checkpoint = learning.load(checkpoint_dir)
print("a network over", checkpoint.domain_size, "values")

new_problems = [coloring(random.Random(123 + k), nodes=20, colours=3, degree=3.5) for k in range(3)]
search = ac.NeuralPriorBPSearch(checkpoint, destroy="worst", destroy_fraction=0.2, batch_size=1)
for model, result in zip(new_problems, ac.local_search(new_problems, search, limits, seed=0)):
    print(result.status.value, "after", result.iterations, "iterations")
    if result.found:
        assert model.check(result.assignment)
a network over 3 values
feasible after 13 iterations
feasible after 15 iterations
feasible after 40 iterations

Note

Compilation and local search are reproducible given their seed. Training is seeded too, but bit-for-bit reproducibility of a training run is not guaranteed.