v2.0.0

ENFORCE 2.0.0 is a modular redesign of the package. The projection method and its results are unchanged; the API is new.

Breaking changes. Code written for 1.x needs to be ported. Start from the README quick start and the tutorial notebooks in notebooks/tutorials/.

Highlights

• Any PyTorch backbone. ENFORCEConstrainedModel wraps any nn.Module; the test suite trains Transformer and GNN backbones through the same Trainer / Evaluator.
• Modular package. enforce.core (Scaler, Constraint, Constraints), enforce.layers (the ENFORCE projection layer), enforce.losses, enforce.models, enforce.engines (Trainer, Evaluator) and enforce.data, each with its own config.
• Vectorised constraint blocks. Constraint(fn, size, jac) holds many equations in one block, with an optional analytical Jacobian. Equalities go in c=, inequalities in g=; inequalities can be vectorised too.
• Faster Jacobians. With many constraints written one per equation, or with inequalities, the Jacobian is about 12-19x faster than in 1.0.4. Vectorised constraints and analytical Jacobians are as fast as before.
• Simpler behaviour. Supervised or self-supervised mode follows from the loss, adaptive activation is handled inside the layer, prediction works under torch.no_grad(), and Scaler follows the device of its inputs, so models run on GPU without extra steps.

Reproducibility

The paper benchmarks reproduce 1.0.4: loss curves and test predictions are bitwise identical for function fitting, sin_ineq, pooling, extraction column and nonconvex linear; nonconvex nonlinear differs by about 1e-8 (rounding).

Installation

Install the PyTorch build for your hardware first, then:

pip install enforce-nn
pip install "enforce-nn[examples]"   # matplotlib and pandas for the notebooks and benchmark scripts

Also in this release

• Clearer validation errors (constraint shapes, max_it, empty constraint sets).
• Documentation: contributing guide, code of conduct, issue and pull request templates, CITATION.cff ("Cite this repository"), and AGENTS.md for coding agents.
• CI: the README quick start runs as a test, and the built wheel is installed and tested in a clean environment.

Known limitations

Trainer and Evaluator batch by slicing one input tensor: backbones need a batch-first tensor input and flat outputs. DataLoaders, dict inputs and variable-size graph batches are planned.

Contributors

Giacomo Lastrucci, Daniel Schicksnus.

Resolved issues: #20, #24, #26, #27, #28.

Full changelog: v1.0.4...v2.0.0