# iolivag/symmetry-reduction-combinatorial-optimization architecture

> Architecture diagram of the GitHub repository iolivag/symmetry-reduction-combinatorial-optimization, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-02-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/iolivag/symmetry-reduction-combinatorial-optimization
- Repository: https://github.com/iolivag/symmetry-reduction-combinatorial-optimization

## Overview

##### Main Components
- **Jupyter Notebook UI** (Browser)
- **IJulia / Julia Kernel**
- **JuMP Modeling API** (Julia package)
- **HiGHS Solver** (via HiGHS.jl)
- **Symmetry Analysis Engine** (custom code in notebooks for graph automorphisms and orbit detection)
- **Problem Modules / Notebooks**
- shortest_path.ipynb
- graph_coloring.ipynb (planned)
- max_cut.ipynb (planned)
- traveling_salesman.ipynb (planned)
- **Results & Visualization** (plots, tables inside notebooks)
- **References Repository** (bibliography.bib)
- **External Dependencies** (Julia runtime, Jupyter server)

##### Relationships & Data Flow
- User types code in **Jupyter UI** → dispatch to **Julia Kernel**.
- Kernel loads a specific **Notebook Module** →
a. Calls **JuMP** to build ILP/MIP model for that CO problem.
b. Invokes **Symmetry Analysis Engine** to detect automorphisms and orbits.
c. Applies symmetry‐breaking constraints to the JuMP model.
d. Passes the augmented model through **HiGHS Solver** (via HiGHS.jl).
e. Receives solutions back into JuMP → kernel → notebook.
- Notebook renders results via **Results & Visualization** components.
- **References Repository** is consulted for bibliographic citations (static resource).

##### Architectural Patterns
- **Pipeline Pattern**: Model → Symmetry‐Detect → Constraint‐Augment → Solve → Post‐Process.
- **Modular Notebook Design**: each CO problem is a plug‐and‐play pipeline instance.
- **Extensibility**: new notebooks/problems follow exactly the same chain of steps.

##### Relevant Technologies & Roles
- **Jupyter / IJulia**: Interactive front end & execution environment.
- **Julia 1.9+**: Programming language runtime.
- **JuMP**: Algebraic modeling DSL for mathematical programs.
- **HiGHS**: High‐performance LP/MIP solver.
- **Graph Automorphism Routines**: symmetry detection submodule in notebooks.

##### Essential Details to Capture
- The **IJulia bridge** between Jupyter and Julia.
- The **separate symmetry‐reduction step** distinct from pure modeling and solving.
- The **parallel modular notebooks** as instances of the same workflow.
- The **flow of results** back into notebooks for visualization and analysis.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Layers and Components
    subgraph "UI Layer"
        direction TB
        JNB["Jupyter Notebook UI"]:::ui
    end

    subgraph "Execution Layer"
        direction TB
        IJulia["IJulia Bridge"]:::execution
        Kernel["Julia Kernel"]:::execution
        JuMP["JuMP Modeling API"]:::execution
        Symmetry["Symmetry Analysis Engine"]:::execution
        Results["Results & Visualization"]:::execution
    end

    subgraph "Solver Layer"
        direction TB
        HiGHS["HiGHS Solver (via HiGHS.jl)"]:::solver
    end

    subgraph "Problem Notebooks"
        direction TB
        SP["shortest_path.ipynb"]:::document
        GC["graph_coloring.ipynb"]:::document
        MC["max_cut.ipynb"]:::document
        TS["traveling_salesman.ipynb"]:::document
    end

    subgraph "Data Layer"
        direction TB
        Bib["bibliography.bib"]:::data
        README["README.md"]:::data
        LICENSEF["LICENSE"]:::data
    end

    %% Flow
    JNB -->|"executes code"| IJulia
    IJulia -->|"forwards to"| Kernel
    Kernel -->|"builds model"| JuMP
    JuMP -->|"calls symmetry detect"| Symmetry
    Symmetry -->|"augments constraints"| JuMP
    JuMP -->|"solves model"| HiGHS
    HiGHS -->|"returns solution"| JuMP
    JuMP -->|"sends results to"| Kernel
    Kernel -->|"renders outputs"| Results
    Results -->|"displays in"| JNB

    %% Modular Notebooks Plug-in
    JNB -->|"opens"| SP
    JNB -->|"opens"| GC
    JNB -->|"opens"| MC
    JNB -->|"opens"| TS
    SP -->|embedded code| Kernel
    GC -->|embedded code| Kernel
    MC -->|embedded code| Kernel
    TS -->|embedded code| Kernel

    %% References
    Results -->|"cites"| Bib

    %% Static Docs
    JNB -->|"project docs"| README
    JNB -->|"license info"| LICENSEF

    %% Click Events
    click SP "https://github.com/iolivag/symmetry-reduction-combinatorial-optimization/blob/main/CO_problems_notebooks/shortest_path.ipynb"
    click GC "https://github.com/iolivag/symmetry-reduction-combinatorial-optimization/blob/main/CO_problems_notebooks/graph_coloring.ipynb"
    click MC "https://github.com/iolivag/symmetry-reduction-combinatorial-optimization/blob/main/CO_problems_notebooks/max_cut.ipynb"
    click TS "https://github.com/iolivag/symmetry-reduction-combinatorial-optimization/blob/main/CO_problems_notebooks/traveling_salesman.ipynb"
    click Bib "https://github.com/iolivag/symmetry-reduction-combinatorial-optimization/blob/main/references/bibliography.bib"
    click README "https://github.com/iolivag/symmetry-reduction-combinatorial-optimization/blob/main/README.md"
    click LICENSEF "https://github.com/iolivag/symmetry-reduction-combinatorial-optimization/tree/main/LICENSE"

    %% Styles
    classDef ui fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef execution fill:#90EE90,stroke:#000,stroke-width:1px
    classDef solver fill:#FFA500,stroke:#000,stroke-width:1px
    classDef data fill:#D3D3D3,stroke:#000,stroke-width:1px
    classDef document fill:#FFFFFF,stroke:#000,stroke-width:1px,stroke-dasharray: 3 3
```
