Orientation¶
A Rust crate and a Python package¶
aicad is a Rust crate, and pyaicad is the Python package built from it. The Python bindings are
thin wrappers over public Rust items: they translate arguments and errors, and hold no algorithm.
The rule behind the design is that everything that can be done from Python can be done from
Rust, so that applications that care about runtime can use the Rust API directly. A feature is
therefore implemented in Rust first and exposed to Python second.
Python code is not pluggable. Crossing between Python and Rust in an inner loop is slow, so a new constraint, destroy operator, search architecture or network is written in Rust, in this crate or in your own.
Layers¶
The modules are layered, and a module only depends on the ones before it:
utils < modelling < constraints < mdd < sampling < bp < destroy < neural < learning < local_search < pyaicad
scripts/check_layering.py enforces the order in CI. When a change needs something from a later
layer, the code usually belongs in a later layer.
Features¶
Feature |
What it adds |
|---|---|
(default) |
Modelling, constraints, MDD compiler, sampling, belief propagation, destroy operators, the local-search engine and the belief-propagation search. No heavy dependency. |
|
The burn dependency: |
|
The PyO3 bindings ( |
Code that needs burn is gated with #[cfg(feature = "learning")]. A change must build and pass its
tests with and without the feature (see Before you open a pull request). The Python package is built in two
flavours, slim (--features python) and full (--features python,learning); the Python side
reads pyaicad.HAS_LEARNING and raises FeatureUnavailableError when the slim build is asked for
something that needs learning.
Where the documentation is¶
the Python guide, the Rust guide and the Python API reference: this site;
the public Rust API: docs.rs, built with the
learningfeature;the contributor Rust documentation, private items included: built in CI with
cargo doc --document-private-items, next to this site.
Every module starts with a //! header in the same shape: a one-line summary, what it means, how it
works, design notes, and a runnable example. Follow it for new modules; cargo doc runs the
examples as tests and fails on a broken link.
Plugging code in from another crate¶
Several extension points are open on purpose, so that work can live in your own crate without being merged here. Each is demonstrated by a test that is compiled as a separate crate, and that therefore fails to build if the public API stops being enough:
a local-search architecture:
tests/custom_search.rs;a neural network, trained and used for search:
tests/custom_network.rs;a destroy operator is a trait object (
DestroyOperator) and goes into any search that takes one.
Constraints are the exception: the set is closed, because the compiler shares compiled structures through an enum of shapes (see Adding a constraint).