PiShield — A PyTorch Package for Learning with Requirements

What is PiShield?

PiShield is the first framework ever allowing for the integration of requirements directly into a neural network's topology.

The integration happens in a straightforward and efficient manner, producing deep learning models that are guaranteed to be compliant with the given requirements — no matter the input.

Requirements can be integrated at inference and/or training time, depending on the practitioners' needs.

Built on our research

PiShield brings together the methods we proposed across several papers — each one contributing to the codebase. (Hover a card to see how it contributes.)

ICLR 2025

Beyond the Convexity Assumption: Realistic Tabular Data Generation under Quantifier-Free Real Linear Constraints

M. C. Stoian, E. Giunchiglia

Allows for integrating QFLRA requirements (quantifier-free linear real arithmetic) via a Shield Layer, capturing nonconvex and even disconnected spaces.

arXiv

ICLR 2024

How Realistic Is Your Synthetic Data? Constraining Deep Generative Models for Tabular Data

M. C. Stoian, S. Dyrmishi, M. Cordy, T. Lukasiewicz, E. Giunchiglia

Introduces linear inequality requirements and the Shield Layer for tabular data generation.

arXiv

IJAR 2024

CCN+: A Neuro-Symbolic Framework for Deep Learning with Requirements

E. Giunchiglia, A. Tatomir, M. C. Stoian, T. Lukasiewicz

Allows for integrating propositional requirements via a Shield Layer.

Paper

NeSy 2023

Exploiting T-norms for Deep Learning in Autonomous Driving

M. C. Stoian, E. Giunchiglia, T. Lukasiewicz

Introduces the memory-efficient t-norm loss that encourages requirement satisfaction at training time.

arXiv

NeurIPS 2020

Coherent Hierarchical Multi-Label Classification Networks

E. Giunchiglia, T. Lukasiewicz

The original constraint layer for hierarchical multi-label classification.

arXiv

Shield Layer

One layer, three requirement types

A differentiable layer that corrects a model's outputs so they are guaranteed to satisfy the requirements. Usable at both inference and training time.

from pishield.shield_layer import build_shield_layer
layer = build_shield_layer(num_variables, "reqs.txt")
corrected = layer(predictions)

Linear

Linear inequality constraints over real variables.

y_0 - y_1 >= 0

QFLRA

Quantifier-free linear real arithmetic: disjunctions and negations of inequalities.

y1 - 2y2 > 0 or neg y3 >= 0

Propositional

Boolean constraints as Horn rules or disjunctive clauses.

y_0 or not y_1 or y_2

Memory-efficient Loss

One loss, three t-norms

A memory-efficient t-norm loss inspired by LTN (Logic Tensor Networks) that encourages requirement satisfaction at training time. Pick whichever of the three t-norms — Godel, Product, or Lukasiewicz — best fits your task.

from pishield.shield_loss import build_shield_loss
loss_fn = build_shield_loss(num_variables, "reqs.txt", tnorm_choice="godel")
penalty = loss_fn(preds)

Examples

Try all three examples in one click — no local setup required.

Shield Layer — Inference

Correct a network's predictions so they satisfy the requirements.

shield_layer_inference.ipynb →

Shield Layer — Training

Train a model with a Shield Layer and compare against an unconstrained baseline.

shield_layer_training.ipynb →

Memory-efficient Loss

Encourage requirement satisfaction at training time with a t-norm penalty.

shield_loss.ipynb →

Read the full documentation

Performance

Across three domains, models with Shield Layers outperform their standard counterparts.

Autonomous Driving

f-mAP @ IoU 0.5 [2]

Model	Baseline	Shielded
I3D	29.30	30.98
C2D	26.34	27.93
RCN	29.26	30.02
RCGRU	29.24	30.50
RCLSTM	28.93	30.42
SlowFast	29.73	31.88
Average	28.80	30.29

Tabular Data Generation

Averages over 5 models [1]

	Utility ↑	Detection ↓
Baseline (F1)	0.430	0.910
Shielded (F1)	0.458	0.900
Baseline (wF1)	0.464	0.909
Shielded (wF1)	0.487	0.896
Baseline (AUC)	0.719	0.927
Shielded (AUC)	0.734	0.921

Wins in 28/30 cases.

Functional Genomics

AU(PRC) [3]

Dataset	Baseline	PiShield
CELLCYCLE	0.220	0.232
DERISI	0.179	0.182
EISEN	0.262	0.285
EXPRE	0.246	0.270
GASCH1	0.239	0.261
GASCH2	0.221	0.235
SEQ	0.245	0.274
SPO	0.186	0.190
Average	0.225	0.241

Authorship & maintenance

Created by Mihaela Cătălina Stoian in 2024, during her DPhil at the University of Oxford.
Maintained solely by Mihaela C. Stoian since its creation and, since October 2025, as a Research Associate in the Data, Uncertainty, Constraints and Knowledge (DUCK) Lab at Imperial College London.
The Shield Layer for propositional constraints was developed by Mihaela C. Stoian and Alex Tatomir.
Based on papers co-authored with the following collaborators, without whom this package would not have been possible:
- Eleonora Giunchiglia
- Alex Tatomir
- Salijona Dyrmishi
- Maxime Cordy
- Thomas Lukasiewicz

Citing PiShield

If you use PiShield, please cite:

@inproceedings{ijcai2024p1037,
  title     = {PiShield: A PyTorch Package for Learning with Requirements},
  author    = {Stoian, Mihaela C. and Tatomir, Alex and Lukasiewicz, Thomas and Giunchiglia, Eleonora},
  booktitle = {Proceedings of the Thirty-Third International Joint Conference on
               Artificial Intelligence, {IJCAI-24}},
  publisher = {International Joint Conferences on Artificial Intelligence Organization},
  editor    = {Kate Larson},
  pages     = {8805--8809},
  year      = {2024},
  month     = {8},
  note      = {Demo Track},
  doi       = {10.24963/ijcai.2024/1037},
  url       = {https://doi.org/10.24963/ijcai.2024/1037},
}

Depending on which feature you use, please additionally cite:

Shield Layer with linear requirements — [1]
Shield Layer with QFLRA requirements — [4]
Shield Layer with propositional requirements — [2]
Memory-efficient Loss with propositional requirements — [5], in addition to LTN [6]

References

[1] M. C. Stoian, S. Dyrmishi, M. Cordy, T. Lukasiewicz, E. Giunchiglia. How Realistic Is Your Synthetic Data? Constraining Deep Generative Models for Tabular Data. ICLR, 2024.

[2] E. Giunchiglia, A. Tatomir, M. C. Stoian, T. Lukasiewicz. CCN+: A neuro-symbolic framework for deep learning with requirements. International Journal of Approximate Reasoning, 2024.

[3] E. Giunchiglia, T. Lukasiewicz. Coherent Hierarchical Multi-Label Classification Networks. NeurIPS, 2020.

[4] M. C. Stoian, E. Giunchiglia. Beyond the Convexity Assumption: Realistic Tabular Data Generation under Quantifier-Free Real Linear Constraints. ICLR, 2025.

[5] M. C. Stoian, E. Giunchiglia, T. Lukasiewicz. Exploiting T-norms for Deep Learning in Autonomous Driving. NeSy, 2023.

[6] S. Badreddine, A. d'Avila Garcez, L. Serafini, M. Spranger. Logic Tensor Networks. Artificial Intelligence, 303, 2022.