# toenshoff/anycsp architecture

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

- Interactive diagram: https://gitdiagram.com/toenshoff/anycsp
- Repository: https://github.com/toenshoff/anycsp

## Overview

##### Project Type and Purpose
- This is a research-oriented machine learning pipeline for solving various constraint satisfaction problems (3SAT, MaxCut, MaxSAT, Graph Coloring (COL), and RB).
- It provides an end-to-end workflow: configuration → data generation/ingestion → model training → evaluation.

##### High-Level Architecture Components
a. Orchestration Layer
- Shell scripts (`scripts/train_*.sh`, `scripts/eval_*.sh`) invoke the training and evaluation pipelines.
- Entrypoints: `train.py` for training, `evaluate.py` (and specialized variants like `evaluate_maxcut.py`) for evaluation.
b. Configuration Store
- JSON files under `configs/<PROBLEM>/<PROBLEM>_default.json`. Each defines hyperparameters, dataset paths, training settings.
c. Data Layer
- `src/data/` module:
- `dataset.py`, `generators.py`, `tuple_generator.py`: sample or load problem instances.
- `xparser.py`: parse external data formats.
- `intension.py`: handle constraint expressions.
d. CSP Abstraction Layer
- `src/csp/` module:
- `csp_data.py`: wraps CSP instances into a common format.
- `constraints.py`: defines constraint types and interfaces.
e. Model Layer
- `src/model/` module:
- `model.py`: assembles neural network model based on configuration.
- `layers.py`: custom GNN or other layers.
- `loss.py`: problem-specific loss functions.
f. Utility Layer
- `src/utils/` module:
- `config_utils.py`: loads and validates JSON configs.
- `data_utils.py`: common preprocessing helpers.
- `rb_utils.py`: specialized utilities for “RB” problem.
g. External Dependencies
- PyTorch (+ GPU support), Python 3.10 environment managed by Conda.
- Pre-downloaded datasets (unzipped into project root) from provided Google Drive link.

##### Relationships and Data Flow
1. User runs a shell script (e.g., `bash scripts/train_maxcut.sh`).
2. Script calls `train.py --config configs/MAXCUT/MAXCUT_default.json`.
3. `train.py` uses `config_utils` to read JSON → instantiates data generator from `src/data` → `csp_data` to convert to graph or tensor inputs.
4. Inputs feed into the model assembled by `src/model/model.py`, which uses layers in `src/model/layers.py`.
5. Training loop applies loss from `src/model/loss.py`, updates parameters via PyTorch.
6. Checkpoints and logs are written to disk.
7. For evaluation, a similar flow via `evaluate.py` (or problem-specific variant), producing metrics.

##### Architectural Patterns and Design Principles
- Modular layering: separation of concerns between configuration, data ingestion, domain logic (CSP), model definition, and utilities.
- Config-driven runtime: JSON files define behavior, enabling easy experiment swapping.
- Reusable components: data generators and CSP abstractions usable across all problem types.
- CLI entrypoints for reproducibility (shell scripts + Python scripts).

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Orchestration"
        ScriptsTrain["Training Scripts (scripts/)"]:::script
        ScriptsEval["Evaluation Scripts (scripts/)"]:::script
    end
    subgraph "Entrypoints"
        TrainPy["train.py"]:::script
        EvalPy["evaluate.py"]:::script
        EvalCOL["evaluate_col.py"]:::script
        EvalMaxCut["evaluate_maxcut.py"]:::script
    end
    ScriptsTrain --> TrainPy
    ScriptsEval --> EvalPy
    ScriptsEval --> EvalCOL
    ScriptsEval --> EvalMaxCut

    subgraph "Configuration Store"
        Configs["configs/"]:::config
    end

    Configs --> TrainPy
    Configs --> EvalPy
    Configs --> EvalCOL
    Configs --> EvalMaxCut

    subgraph "Utility Layer"
        ConfigUtils["config_utils.py"]:::blue
        DataUtils["data_utils.py"]:::blue
        RBUtils["rb_utils.py"]:::blue
    end
    TrainPy --> ConfigUtils
    EvalPy --> ConfigUtils

    subgraph "Data Layer"
        DL1["dataset.py"]:::blue
        DL2["generators.py"]:::blue
        DL3["tuple_generator.py"]:::blue
        DL4["xparser.py"]:::blue
        DL5["intension.py"]:::blue
        subgraph "CSP Abstraction"
            CSP1["csp_data.py"]:::blue
            CSP2["constraints.py"]:::blue
        end
    end

    subgraph "Model Layer"
        ModelMain["model.py"]:::blue
        ModelLayers["layers.py"]:::blue
        ModelLoss["loss.py"]:::blue
    end

    TrainPy -->|"runs with JSON→dict"| ConfigUtils
    EvalPy -->|"runs with JSON→dict"| ConfigUtils
    ConfigUtils -->|"provides config"| DL1
    ConfigUtils -->|"provides config"| ModelMain

    DL1 --> DL2
    DL2 --> DL3
    DL3 --> DL4
    DL4 --> DL5
    DL5 --> CSP1
    CSP1 --> CSP2
    CSP2 --> ModelMain
    DL5 --> DataUtils

    ModelMain --> ModelLayers
    ModelLayers --> ModelLoss

    ModelLoss --> Checkpoints["Checkpoints & Logs"]:::script
    EvalCOL --> ConfigUtils
    EvalMaxCut --> ConfigUtils
    EvalPy --> DL1
    EvalCOL --> DL1
    EvalMaxCut --> DL1
    ModelLoss --> Metrics["Evaluation Metrics"]:::script
    Metrics --> Configs

    Cloud["PyTorch / GPU / Data Files"]:::external
    Cloud --> DL1
    Cloud --> ModelMain

    click ScriptsTrain "https://github.com/toenshoff/anycsp/tree/main/scripts/"
    click TrainPy "https://github.com/toenshoff/anycsp/blob/main/train.py"
    click EvalPy "https://github.com/toenshoff/anycsp/blob/main/evaluate.py"
    click EvalCOL "https://github.com/toenshoff/anycsp/blob/main/evaluate_col.py"
    click EvalMaxCut "https://github.com/toenshoff/anycsp/blob/main/evaluate_maxcut.py"
    click Configs "https://github.com/toenshoff/anycsp/tree/main/configs/"
    click DL1 "https://github.com/toenshoff/anycsp/blob/main/src/data/dataset.py"
    click DL2 "https://github.com/toenshoff/anycsp/blob/main/src/data/generators.py"
    click DL3 "https://github.com/toenshoff/anycsp/blob/main/src/data/tuple_generator.py"
    click DL4 "https://github.com/toenshoff/anycsp/blob/main/src/data/xparser.py"
    click DL5 "https://github.com/toenshoff/anycsp/blob/main/src/data/intension.py"
    click CSP1 "https://github.com/toenshoff/anycsp/blob/main/src/csp/csp_data.py"
    click CSP2 "https://github.com/toenshoff/anycsp/blob/main/src/csp/constraints.py"
    click ModelMain "https://github.com/toenshoff/anycsp/blob/main/src/model/model.py"
    click ModelLayers "https://github.com/toenshoff/anycsp/blob/main/src/model/layers.py"
    click ModelLoss "https://github.com/toenshoff/anycsp/blob/main/src/model/loss.py"
    click ConfigUtils "https://github.com/toenshoff/anycsp/blob/main/src/utils/config_utils.py"
    click DataUtils "https://github.com/toenshoff/anycsp/blob/main/src/utils/data_utils.py"
    click RBUtils "https://github.com/toenshoff/anycsp/blob/main/src/utils/rb_utils.py"

    classDef script fill:#c2f0c2,stroke:#333,stroke-width:1px,shape:parallelogram
    classDef blue fill:#daf1ff,stroke:#333,stroke-width:1px,shape:rect
    classDef config fill:#fff2cc,stroke:#333,stroke-width:1px,shape:cylinder
    classDef external fill:#e0e0e0,stroke:#333,stroke-width:1px,shape:cloud
```
