Expand description
§aicad
MDD compilation for constraint satisfaction problems, with strategies built on top of it: belief propagation, local search, and local search guided by a trained neural network.
Everything the Python package pyaicad does is available here too, for applications that
cannot afford the interpreter. The Rust API is experimental and may change between minor
versions until its users have shaped it.
§Modules
From the bottom up, each module only depends on the ones listed before it:
modelling: variables, theProblem, and the traits that a constraint implements.constraints: the constraints, with the contract that the compiler relies on.mdd: the compiler and the compiled diagram.sampling: sampling solutions from a compiled diagram.bp: belief propagation over the diagrams of the constraints.destroy: the operators that choose which variables a local search frees.local_search: the local search engine, its architectures andlocal_search::solve.diagnostics: an optional log of structured events for offline analysis.
§Features
learning(off by default): the neural networks (neural), their training (learning) and the local searches that use them. It pulls in burn, which is heavy to build; the compiler, sampling, belief propagation and the belief-propagation local search do not need it.python(off by default): the bindings built by maturin intopyaicad, and never needed from Rust. Combined withlearningthey give the full wheel; alone, the slim one.
§Settings
A few settings are global: the number of threads of the worker pool that runs the parallel parts
of the library (set_num_threads, num_threads), a quarter of the available threads
unless set, and the seed of the randomness (set_seed).
§Example
use aicad::constraints::all_different;
use aicad::mdd::Compiler;
use aicad::mdd::heuristics::CompilationHeuristic;
use aicad::modelling::Problem;
use std::sync::Arc;
let mut problem = Problem::default();
let vars = problem.add_variables(3, vec![0, 1, 2]);
let constraint = all_different(&mut problem, vars);
let mut compiler = Compiler::new(
Arc::new(problem),
CompilationHeuristic::default(),
&[constraint],
);
compiler.refine(usize::MAX);
assert_eq!(compiler.into_mdd().count_solutions().to_string(), "6");Modules§
- bp
- Loopy belief propagation over compiled MDDs: refines the per-variable distributions of a network with what the constraints say about them.
- constraints
- Constraints, and the contract that lets the MDD compiler use them.
- destroy
- Destroy operators: heuristical way of destroying parts of a full assignment to variables.
- diagnostics
- A switchable sink for structured events, written as JSON lines for offline analysis.
- learning
- Training of the neural networks of
crate::neural. - local_
search - Local search: repeatedly destroys part of an assignment and repairs it, until the problem is solved or the budget is spent.
- mdd
- Multi-valued decision diagrams (MDDs) of constraints: compilation, relaxation and queries.
- modelling
- The description of a problem: variables with finite integer domains, and constraints over them.
- neural
- The neural networks of the crate, and what both training and local search need to use them.
- sampling
- Everything that draws or chooses from a distribution: values of a categorical distribution, random assignments, and solutions sampled from a diagram.
Functions§
- default_
num_ threads - The number of threads the pool has unless
set_num_threadsis called: a quarter of the available threads, and at least one. - num_
threads - The number of threads of the worker pool: the last value given to
set_num_threads, ordefault_num_threadsif there is none. - set_
num_ threads - Sets the number of threads of the worker pool, which runs the parallel parts of batched solving, training and dataset building. It applies from the next parallel loop on; loops already running finish with the threads they had.
- set_
seed - Seeds every source of randomness of the crate, so that a later run of a compilation, a
training or a search reproduces itself given the same seed: the process-wide generator (the
sampling of diagrams, the destroy operators, the train and validation split, the masking of
training samples) and, with the
learningfeature, the generators of the burn backends (the initial weights, the sampling of logits).