PyC is a library built upon PyTorch to easily implement interpretable and causally transparent deep learning models. The library provides primitives for interpretable layers, probabilistic models, causal models, and APIs for running experiments at scale.

The name of the library stands for both:

PyTorch Concepts: as concepts are essential building blocks for interpretable deep learning.
P(y|C): as the main purpose of the library is to support sound probabilistic modeling of the conditional distribution of targets y given concepts C.

Get Started¶

Installation

Learn how to install PyC and set up your environment.

Installation

Using PyC

Explore tutorials and examples to get started with PyC.

User Guide

Contributing

Contribute to PyC and help improve the library.

Contributing Guide

Explore Based on Your Background¶

PyC is designed to accommodate users with different backgrounds and expertise levels. Pick the best entry point based on your experience:

Pure torch user?

Start from the Low-Level API to build models from basic interpretable layers.

Interpretable Layers and Interventions

Probabilistic modeling user?

Start from the Mid-Level API to build custom probabilistic models.

Interpretable Probabilistic Models

Causal modeling user?

Start from the Mid-Level API to build Structural Equation Models for causal inference.

Structural Equation Models

Just want to use state-of-the-art models out-of-the-box?

Start from the High-Level API to use pre-defined models with one line of code.

Out-of-the-box Models

Benchmarking or no experience with programming?

Use Conceptarium, a no-code framework built on top of PyC for running large-scale experiments on concept-based models.

Conceptarium

API Reference¶

Main Modules¶

The main modules of the library are organized into three levels of abstraction: Low-Level API, Mid-Level API, and High-Level API. These modules allow users with different levels of abstraction to build interpretable models.

Low-Level API

Build architectures from basic interpretable layers in a plain PyTorch-like interface.

Low-level API

Mid-Level API

Build custom interpretable and causally transparent probabilistic models.

Warning

This API is still under development and interfaces might change in future releases.

Mid-level API

High-Level API

Use out-of-the-box state-of-the-art PyTorch Lightning models with one line of code.

High-level API

Shared Modules¶

The library also includes shared modules that provide additional functionalities such as loss functions, metrics, and utilities.

Loss Functions

Various loss functions for concept-based models.

Loss Functions

Metrics

Evaluation metrics for concept-based models.

Metrics

Functional

Functional utilities for concept-based models.

Functional API

Conceptarium¶

Conceptarium is a no-code framework for running large-scale experiments on concept-based models. The interface is based on YAML configuration files, making it easy to set up and run experiments without writing code. This framework is intended for benchmarking or researchers in other fields who want to use concept-based models without programming knowledge.

Conceptarium

Conceptarium is a no-code framework for running large-scale experiments on concept-based models. Built on top of PyC, with PyTorch Lightning, Hydra and WandB.

Conceptarium

Extra Modules¶

Extra modules provide additional APIs for data handling and probability distributions. These modules have additional dependencies and can be installed separately.

Data API

Access datasets, dataloaders, preprocessing, and data utilities.

Data

Distributions API

Work with probability distributions for probabilistic modeling.

Distributions

Contributing¶

We welcome contributions from the community to help improve PyC! Follow the instructions in the Contributing Guide to get started.

Thanks to all contributors! 🧡

External Contributors¶

Sonia Laguna, ETH Zurich (CH).
Moritz Vandenhirtz, ETH Zurich (CH).

Cite this library¶

If you found this library useful for your research article, blog post, or product, we would be grateful if you would cite it using the following bibtex entry:

@software{pycteam2025concept,
    author = {Barbiero, Pietro and De Felice, Giovanni and Espinosa Zarlenga, Mateo and Ciravegna, Gabriele and Dominici, Gabriele and De Santis, Francesco and Casanova, Arianna and Debot, David and Giannini, Francesco and Diligenti, Michelangelo and Marra, Giuseppe},
    license = {Apache 2.0},
    month = {3},
    title = {{PyTorch Concepts}},
    url = {https://github.com/pyc-team/pytorch_concepts},
    year = {2025}
}