# hellas-ai/open-hypergraphs architecture

> Architecture diagram of the GitHub repository hellas-ai/open-hypergraphs, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hellas-ai/open-hypergraphs
- Repository: https://github.com/hellas-ai/open-hypergraphs

## Overview

##### File structure
- Top-level: Cargo.toml, src/, examples/, tests/.
- src/ contains self-contained modules:
– array: parallel array back-end
– category: abstract category interfaces and spiders
– finite_function: category of finite functions
– functor: functor traits and optic transformations
– hypergraph & open_hypergraph: core hypergraph and open-hypergraph structures
– indexed_coproduct, semifinite, lax: general constructions used by core types
– eval.rs, operations.rs, layer.rs: evaluation engine and layering logic
- examples/ shows user-facing entry points; tests/ verify each module.
- No external services or databases—pure library code.

##### README for additional insights
- Features: tensor & composition, functors (including reverse differentiation), data-parallel layering.
- Examples illustrate how end users define and evaluate circuits.

##### Main components and their relationships
a. User API (examples/**)
b. Core types
– open_hypergraph module (user‐facing graph type)
– hypergraph module (underlying graph structure)
– category module (abstract categorical interface)
– functor module (transforms between categories)
c. Supporting algebraic constructions
– finite_function, indexed_coproduct, lax, semifinite
d. Execution engine
– layer.rs (data-parallel layering)
– array module (vector/array operations for parallelism)
e. Operations (combinators) in operations.rs

##### Architectural patterns and principles
- Modular layering: each algebraic concept in its own module.
- Separation of interface (traits in category, functor) vs. implementation (finite_function, hypergraph).
- Plug-in extensibility: new categories or functors can be added by implementing traits.
- Data-parallel core: array/vec back-end used by evaluation and layering.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Layer
    subgraph "User Layer"
        direction TB
        User1(["Adder Example"]):::user
        User2(["Poly Circuit Example"]):::user
    end

    %% API Modules
    subgraph "API Layer" 
        direction TB
        OHG(["Open Hypergraph"]):::api
        HG(["Hypergraph"]):::api
        Cat(["Category"]):::api
        Fun(["Functor"]):::api
    end

    %% Execution Engine & Back-end
    subgraph "Engine & Back-end"
        direction TB
        Eval(["Evaluation Engine"]):::engine
        Layer(["Layering Engine"]):::engine
        Array(["Array Back-end"]):::engine
    end

    %% Algebraic Primitives
    subgraph "Primitives"
        direction TB
        FF(["Finite Function"]):::primitive
        IC(["Indexed Coproduct"]):::primitive
        Lax(["Lax Constructions"]):::primitive
        Semi(["Semifinite Constructions"]):::primitive
        Ops(["Operations Combinators"]):::primitive
    end

    %% Dependencies
    User1 -->|defines diagram| OHG
    User2 -->|defines diagram| OHG

    OHG -->|uses| HG
    OHG -->|implements| Cat
    OHG -->|transforms| Fun

    HG -->|depends on| Cat
    Fun -->|implements| Cat

    HG -->|builds on| FF
    HG -->|builds on| IC
    HG -->|builds on| Lax
    HG -->|builds on| Semi

    Fun -->|uses| Lax
    Fun -->|uses| Semi

    OHG -->|combinators| Ops
    HG -->|combinators| Ops
    Cat -->|combinators| Ops
    Fun -->|combinators| Ops

    OHG -->|evaluates via| Eval
    OHG -->|layers via| Layer
    HG -->|evaluates via| Eval
    HG -->|layers via| Layer

    Eval -->|parallel ops| Array
    Layer -->|parallel ops| Array

    %% Click Events
    click User1 "https://github.com/hellas-ai/open-hypergraphs/blob/master/examples/adder.rs"
    click User2 "https://github.com/hellas-ai/open-hypergraphs/blob/master/examples/polycirc.rs"
    click OHG "https://github.com/hellas-ai/open-hypergraphs/blob/master/src/open_hypergraph/mod.rs"
    click OHG "https://github.com/hellas-ai/open-hypergraphs/blob/master/src/open_hypergraph/arrow.rs"
    click HG "https://github.com/hellas-ai/open-hypergraphs/blob/master/src/hypergraph/mod.rs"
    click HG "https://github.com/hellas-ai/open-hypergraphs/blob/master/src/hypergraph/arrow.rs"
    click HG "https://github.com/hellas-ai/open-hypergraphs/blob/master/src/hypergraph/object.rs"
    click Cat "https://github.com/hellas-ai/open-hypergraphs/blob/master/src/category/mod.rs"
    click Cat "https://github.com/hellas-ai/open-hypergraphs/blob/master/src/category/traits.rs"
    click Cat "https://github.com/hellas-ai/open-hypergraphs/blob/master/src/category/spider.rs"
    click Fun "https://github.com/hellas-ai/open-hypergraphs/blob/master/src/functor/mod.rs"
    click Fun "https://github.com/hellas-ai/open-hypergraphs/blob/master/src/functor/optic.rs"
    click Fun "https://github.com/hellas-ai/open-hypergraphs/blob/master/src/functor/spider.rs"
    click FF "https://github.com/hellas-ai/open-hypergraphs/blob/master/src/finite_function/mod.rs"
    click FF "https://github.com/hellas-ai/open-hypergraphs/blob/master/src/finite_function/arrow.rs"
    click IC "https://github.com/hellas-ai/open-hypergraphs/blob/master/src/indexed_coproduct/mod.rs"
    click IC "https://github.com/hellas-ai/open-hypergraphs/blob/master/src/indexed_coproduct/arrow.rs"
    click IC "https://github.com/hellas-ai/open-hypergraphs/blob/master/src/indexed_coproduct/iterator.rs"
    click IC "https://github.com/hellas-ai/open-hypergraphs/blob/master/src/indexed_coproduct/semifinite_iterator.rs"
    click Lax "https://github.com/hellas-ai/open-hypergraphs/blob/master/src/lax/mod.rs"
    click Lax "https://github.com/hellas-ai/open-hypergraphs/blob/master/src/lax/category.rs"
    click Lax "https://github.com/hellas-ai/open-hypergraphs/blob/master/src/lax/hypergraph.rs"
    click Lax "https://github.com/hellas-ai/open-hypergraphs/blob/master/src/lax/open_hypergraph.rs"
    click Lax "https://github.com/hellas-ai/open-hypergraphs/blob/master/src/lax/var/var.rs"
    click Lax "https://github.com/hellas-ai/open-hypergraphs/blob/master/src/lax/var/operators.rs"
    click Semi "https://github.com/hellas-ai/open-hypergraphs/blob/master/src/semifinite/mod.rs"
    click Semi "https://github.com/hellas-ai/open-hypergraphs/blob/master/src/semifinite/arrow.rs"
    click Semi "https://github.com/hellas-ai/open-hypergraphs/blob/master/src/semifinite/types.rs"
    click Eval "https://github.com/hellas-ai/open-hypergraphs/blob/master/src/eval.rs"
    click Layer "https://github.com/hellas-ai/open-hypergraphs/blob/master/src/layer.rs"
    click Array "https://github.com/hellas-ai/open-hypergraphs/blob/master/src/array/mod.rs"
    click Array "https://github.com/hellas-ai/open-hypergraphs/blob/master/src/array/traits.rs"
    click Array "https://github.com/hellas-ai/open-hypergraphs/blob/master/src/array/vec/mod.rs"
    click Array "https://github.com/hellas-ai/open-hypergraphs/blob/master/src/array/vec/vec_array.rs"
    click Array "https://github.com/hellas-ai/open-hypergraphs/blob/master/src/array/vec/connected_components.rs"
    click Ops "https://github.com/hellas-ai/open-hypergraphs/blob/master/src/operations.rs"

    %% Styles
    classDef user fill:#f9f,stroke:#333,stroke-width:1px;
    classDef api fill:#bbf,stroke:#333,stroke-width:1px;
    classDef engine fill:#bfb,stroke:#333,stroke-width:1px;
    classDef primitive fill:#fbf,stroke:#333,stroke-width:1px;
```
