# meta-pytorch/opacus architecture

> Architecture diagram of the GitHub repository meta-pytorch/opacus, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/meta-pytorch/opacus
- Repository: https://github.com/meta-pytorch/opacus

## Overview

##### Project type and purpose
- **Type**: Open-source Python library (not a standalone service or web app).
- **Purpose**: Enable DP-SGD training in PyTorch via minimal code changes.

##### File structure
- **Top-level “opacus” package**: contains subpackages for core engine (`privacy_engine.py`), accountants (`accountants/`), gradient sampling (`grad_sample/`), DP layers (`layers/`), optimizers (`optimizers/`), schedulers (`schedulers/`), utility functions (`utils/`), and validators (`validators/`).
- **Support files**: Examples (`examples/`), Benchmarks (`benchmarks/`), Tutorials (`tutorials/`), Research experiments (`research/`), Documentation (`docs/`, `website/`).
- **Configuration & CI**: `.github/workflows/`, `setup.py`, `requirements.txt`, etc.

##### README for key insights
- Core concept: instantiate a `PrivacyEngine`, call `make_private(model, optimizer, data_loader, …)`, then proceed with standard PyTorch training.
- Major abstractions:
- **PrivacyEngine** – the façade for making components “private.”
- **Accountants** – compute and track the privacy budget.
- **Fast/ghost clipping** – memory-efficient gradient clipping.
- **Grad samplers** – hooks into per-sample gradient computation.

##### Main components
a. **API Layer**
- User script / Jupyter notebook (examples/tutorials)
- Calls into `PrivacyEngine`
b. **PrivacyEngine** (core)
- Accepts: PyTorch `Module`, `Optimizer`, `DataLoader`
- Returns: wrapped versions with DP hooks
c. **DP Hooks Pipeline**
1. **Gradient Sampling** (`grad_sample/`): intercepts backward pass to compute per-sample gradients.
2. **Clipping & Noise Scheduling** (`utils/fast_gradient_clipping_utils.py`, `schedulers/noise_scheduler.py`): clip per-sample grads, add Gaussian noise.
3. **Accountant** (`accountants/*`): update privacy ledger (RDP, GDP, PRV analyses).
4. **Optimizers** (`optimizers/*`): wrappers around SGD/Adam that integrate clipped-noisy gradients.
d. **DP Layers** (`layers/*`): DP-aware versions of RNN, multihead attention, etc., used for built-in modules.
e. **Validators** (`validators/*`): pre-flight checks/fixes on user models to ensure compatibility with DP (e.g., no unsupported ops).
f. **External Dependencies**
- PyTorch core (autograd, optim, nn)
- NumPy (benchmarks, utils)

##### Relationships & interactions
- User script → PrivacyEngine
- PrivacyEngine → hooks into Model, Optimizer, DataLoader
- Model’s backward pass → GradientSampling → Clipping → NoiseScheduler → Accountant → Optimizer.update
- Accountant → exposes privacy budget metric back to user/UI
- That DP Layers and Validators plug into Model construction phase.
- Examples/tutorials/benchmarks drive end-to-end usage.

##### Architectural patterns & design principles
- **Layered modularity**: each concern (accounting, sampling, clipping, optimization) is in its own package.
- **Plugin-style hooks**: DP functionality is injected via wrappers rather than core PyTorch modifications.
- **Extensibility**: new accountants or clipping strategies can be added by dropping modules into the respective directories.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Layer
    subgraph "API Layer (User Code)"
        direction TB
        User["User Scripts/Notebooks"]:::user
        Examples["examples/"]:::user
        Tutorials["tutorials/"]:::user
        DP_Script["compute_dp_sgd_privacy.py"]:::user
    end

    %% Core Engine
    subgraph "Core Engine"
        direction TB
        PrivacyEngine["PrivacyEngine"]:::core
    end

    %% DP Hooks Pipeline
    subgraph "DP Hooks Pipeline"
        direction TB
        subgraph "Gradient Sampling" 
            direction TB
            GradSample["grad_sample_module.py"]:::dp
            GradSampleFast["grad_sample_module_fast_gradient_clipping.py"]:::dp
        end
        subgraph "Clipping & Scheduling"
            direction TB
            ClipUtils["fast_gradient_clipping_utils.py"]:::dp
            ClipSched["grad_clip_scheduler.py"]:::dp
            NoiseSched["noise_scheduler.py"]:::dp
        end
        subgraph "Accountants"
            direction TB
            Accountant["accountant.py"]:::dp
        end
        subgraph "Optimizers"
            direction TB
            Optimizer["optimizer.py"]:::dp
        end
    end

    %% DP Layers & Validators
    subgraph "DP Extensions"
        direction TB
        DPLayers["opacus/layers/"]:::dp
        Validators["opacus/validators/"]:::dp
    end

    %% External Dependencies
    subgraph "External Dependencies"
        direction TB
        PyTorch["PyTorch Core"]:::ext
        NumPy["NumPy"]:::ext
    end

    %% Interactions
    User -->|"make_private"| PrivacyEngine
    PrivacyEngine -->|wraps| GradSample
    PrivacyEngine -->|wraps| ClipUtils
    PrivacyEngine -->|wraps| Accountant
    PrivacyEngine -->|wraps| Optimizer
    PrivacyEngine -->|validates| Validators
    PrivacyEngine -->|provides| DPLayers

    GradSample --> ClipUtils
    ClipUtils --> NoiseSched
    NoiseSched --> Accountant
    Accountant --> Optimizer
    Optimizer --> PrivacyEngine

    Accountant -->|"privacy budget"| User

    PyTorch --> PrivacyEngine
    PyTorch --> GradSample
    PyTorch --> Optimizer
    NumPy --> ClipUtils

    %% Click Events
    click Examples "https://github.com/meta-pytorch/opacus/tree/main/examples/"
    click Tutorials "https://github.com/meta-pytorch/opacus/tree/main/tutorials/"
    click DP_Script "https://github.com/meta-pytorch/opacus/blob/main/opacus/scripts/compute_dp_sgd_privacy.py"
    click PrivacyEngine "https://github.com/meta-pytorch/opacus/blob/main/opacus/privacy_engine.py"
    click GradSample "https://github.com/meta-pytorch/opacus/blob/main/opacus/grad_sample/grad_sample_module.py"
    click GradSampleFast "https://github.com/meta-pytorch/opacus/blob/main/opacus/grad_sample/grad_sample_module_fast_gradient_clipping.py"
    click ClipUtils "https://github.com/meta-pytorch/opacus/blob/main/opacus/utils/fast_gradient_clipping_utils.py"
    click ClipSched "https://github.com/meta-pytorch/opacus/blob/main/opacus/schedulers/grad_clip_scheduler.py"
    click NoiseSched "https://github.com/meta-pytorch/opacus/blob/main/opacus/schedulers/noise_scheduler.py"
    click Accountant "https://github.com/meta-pytorch/opacus/blob/main/opacus/accountants/accountant.py"
    click Optimizer "https://github.com/meta-pytorch/opacus/blob/main/opacus/optimizers/optimizer.py"
    click DPLayers "https://github.com/meta-pytorch/opacus/tree/main/opacus/layers/"
    click Validators "https://github.com/meta-pytorch/opacus/tree/main/opacus/validators/"

    %% Styles
    classDef core fill:#D0E1FF,stroke:#4C6EF5,color:#1A237E;
    classDef dp fill:#E8F5E9,stroke:#43A047,color:#1B5E20;
    classDef user fill:#FFF3E0,stroke:#FB8C00,color:#E65100;
    classDef ext fill:#ECEFF1,stroke:#607D8B,color:#263238;
```
