# tristandelcourt/tipe architecture

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

- Interactive diagram: https://gitdiagram.com/tristandelcourt/tipe
- Repository: https://github.com/tristandelcourt/tipe

## Overview

##### Project Type and Purpose
- Project Type: A command-line, C-based factorization toolkit.
- Purpose: Expose multiple prime-factor algorithms (Dixon, Quadratic Sieve, Multipolynomial Quadratic Sieve, Parallel MPQS) via a single executable called `factor`.
- Users interact via CLI flags; the program delegates to one of four algorithms and prints or saves results.

##### File Structure
Top-level:
- `_python_deprecated`, `_random_deprecated`: historical implementations (can be shown as “legacy” or omitted).
- `c/`: primary source code.
- `tests/`: test inputs, outputs, and test drivers (both C and Python).
Inside `c/`:
- `main.c` + `Makefile`: build and entry point.
- Algo modules: `dixon/`, `qsieve/`, `mpqs/` (with `parallel_mpqs.c`).
- Shared utilities: `factorbase.{c,h}`, `list_matrix_utils.{c,h}`, `parse_input.{c,h}`, `system.{c,h}`, `vector.{c,h}`, plus MPQS-specific `polynomial.{c,h}`.

##### README for Insights
- Confirms CLI flags (`--number`, `--type`, `--bound`, etc.)
- Explains each algorithm’s folder holds the core smooth-relation logic.
- Build via `Makefile` → produces `factor` executable.

##### Main Components & Interactions
a. Components:
1. User / CLI Interface
2. Argument Parser (`parse_input`)
3. Main Controller (`main.c`)
4. Algorithm Modules (plug-ins):
– Dixon (`c/dixon/dixon.c`)
– QSieve (`c/qsieve/qsieve.c`)
– MPQS (`c/mpqs/mpqs.c`)
– Parallel MPQS (`c/mpqs/parallel_mpqs.c`)
5. Shared Libraries:
– Factor Base (`factorbase.*`)
– Matrix Utilities (`list_matrix_utils.*`)
– Polynomial Utils (for MPQS)
– System Helpers (`system.*`)
– Vector Data Structures (`vector.*`)
6. Output Layer (stdout or file)
7. Test Harness (`tests/tests.c`, `tests/tests.py`)

b. Interactions & Data Flow:
- User runs `factor --type qsieve -n 12345 …`
↓
- CLI Interface → `parse_input` populates a config struct
↓
- `main.c` reads config → switches on algorithm type
↓
- Invokes selected Algorithm Module → calls Shared Libraries for:
– Building prime factor base
– Sieving or relation collection
– Linear algebra (matrix utils)
↓
- Algorithm returns factorization result
↓
- Main Controller sends output to stdout or writes to file
↓
- Tests invoke the same CLI or call modules directly, compare against expected JSON/text results.

c. Architectural Patterns & Principles:
- Modular plugin-style for each algorithm.
- Core-side separation: CLI/Controller vs. Algorithm vs. Shared Utilities.
- Reuse of generic data structures (vectors, matrices).
- Parallelism hidden behind the MPQS plugin (note thread-creation or OpenMP).

d. Key Technologies:
- Language: C
- Build: GNU Make
- Parallelism: POSIX threads or OpenMP (in `parallel_mpqs.c`)
- Tests: C unit-style (`tests.c`) and Python runner (`tests.py`)
- Documentation: LaTeX/Beamer

##### Don’t Overthink—Be Exhaustive
- Every logical component (do not merge Dixon and QSieve into “Algorithms” without noting them separately).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Source Code Layer
    subgraph "Source Code (c/)"
        direction TB
        subgraph "Core"
            direction TB
            CLI["User / CLI Interface"]:::core
            Parser["Argument Parser\n(parse_input.c/h)"]:::core
            Controller["Main Controller\n(main.c, Makefile)"]:::core
            Output["Output Layer\n(stdout or file)"]:::core
        end
        subgraph "Algorithm Modules"
            direction TB
            Dixon["Dixon\n(dixon.c/h)"]:::algo
            QSieve["QSieve\n(qsieve.c/h)"]:::algo
            MPQS["MPQS\n(mpqs.c/h)"]:::algo
            ParMPQS["Parallel MPQS\n(parallel_mpqs.c/h)"]:::algo
        end
        subgraph "Shared Utilities"
            direction TB
            CommonMPQS["Common MPQS\n(common_mpqs.c/h)"]:::util
            Poly["Polynomial Utils\n(polynomial.c/h)"]:::util
            FactorBase["Factor Base\n(factorbase.c/h)"]:::util
            Matrix["Matrix Utils\n(list_matrix_utils.c/h)"]:::util
            System["System Helpers\n(system.c/h)"]:::util
            Vector["Vector DS\n(vector.c/h)"]:::util
            Tonelli["Tonelli–Shanks\n(tonellishanks.c/h)"]:::util
        end
    end

    %% Testing Layer
    subgraph "Testing (tests/)"
        direction TB
        Ctests["C Unit Tests\n(tests/tests.c)"]:::test
        Pytests["Python Runner\n(tests/tests.py)"]:::test
        TestData["Test Data\n(someprimes.txt, optimization_results.json)"]:::test
    end

    %% Documentation Layer
    subgraph "Documentation (beamer/)"
        direction TB
        Beamer["Beamer Slides\n(main.tex, diagrams/*)"]:::doc
    end

    %% Connections
    CLI -->|provides flags| Parser
    Parser -->|parses config| Controller
    Controller -->|selects| Dixon
    Controller -->|selects| QSieve
    Controller -->|selects| MPQS
    Controller -->|selects| ParMPQS
    Dixon -->|uses| FactorBase
    Dixon -->|uses| Matrix
    QSieve -->|uses| FactorBase
    QSieve -->|uses| Matrix
    MPQS -->|uses| FactorBase
    MPQS -->|uses| Matrix
    MPQS -->|uses| CommonMPQS
    MPQS -->|uses| Poly
    ParMPQS -->|uses| FactorBase
    ParMPQS -->|uses| Matrix
    ParMPQS -->|uses| CommonMPQS
    ParMPQS -->|uses| Poly
    Controller -->|outputs result| Output

    Ctests -->|runs CLI| Controller
    Pytests -->|runs CLI| Controller
    Ctests -->|verifies via| TestData
    Pytests -->|verifies via| TestData

    %% Click Events
    click CLI "https://github.com/tristandelcourt/tipe/blob/main/c/main.c"
    click Parser "https://github.com/tristandelcourt/tipe/blob/main/c/parse_input.c"
    click Controller "https://github.com/tristandelcourt/tipe/blob/main/c/main.c"
    click Controller "https://github.com/tristandelcourt/tipe/tree/main/c/Makefile"
    click Dixon "https://github.com/tristandelcourt/tipe/blob/main/c/dixon/dixon.c"
    click Dixon "https://github.com/tristandelcourt/tipe/blob/main/c/dixon/dixon.h"
    click QSieve "https://github.com/tristandelcourt/tipe/blob/main/c/qsieve/qsieve.c"
    click QSieve "https://github.com/tristandelcourt/tipe/blob/main/c/qsieve/qsieve.h"
    click MPQS "https://github.com/tristandelcourt/tipe/blob/main/c/mpqs/mpqs.c"
    click MPQS "https://github.com/tristandelcourt/tipe/blob/main/c/mpqs/mpqs.h"
    click ParMPQS "https://github.com/tristandelcourt/tipe/blob/main/c/mpqs/parallel_mpqs.c"
    click ParMPQS "https://github.com/tristandelcourt/tipe/blob/main/c/mpqs/parallel_mpqs.h"
    click CommonMPQS "https://github.com/tristandelcourt/tipe/blob/main/c/mpqs/common_mpqs.c"
    click CommonMPQS "https://github.com/tristandelcourt/tipe/blob/main/c/mpqs/common_mpqs.h"
    click Poly "https://github.com/tristandelcourt/tipe/blob/main/c/mpqs/polynomial.c"
    click Poly "https://github.com/tristandelcourt/tipe/blob/main/c/mpqs/polynomial.h"
    click FactorBase "https://github.com/tristandelcourt/tipe/blob/main/c/factorbase.c"
    click FactorBase "https://github.com/tristandelcourt/tipe/blob/main/c/factorbase.h"
    click Matrix "https://github.com/tristandelcourt/tipe/blob/main/c/list_matrix_utils.c"
    click Matrix "https://github.com/tristandelcourt/tipe/blob/main/c/list_matrix_utils.h"
    click System "https://github.com/tristandelcourt/tipe/blob/main/c/system.c"
    click System "https://github.com/tristandelcourt/tipe/blob/main/c/system.h"
    click Vector "https://github.com/tristandelcourt/tipe/blob/main/c/vector.c"
    click Vector "https://github.com/tristandelcourt/tipe/blob/main/c/vector.h"
    click Tonelli "https://github.com/tristandelcourt/tipe/blob/main/c/tonellishanks.c"
    click Tonelli "https://github.com/tristandelcourt/tipe/blob/main/c/tonellishanks.h"
    click Ctests "https://github.com/tristandelcourt/tipe/blob/main/tests/tests.c"
    click Pytests "https://github.com/tristandelcourt/tipe/blob/main/tests/tests.py"
    click TestData "https://github.com/tristandelcourt/tipe/blob/main/tests/someprimes.txt"
    click TestData "https://github.com/tristandelcourt/tipe/blob/main/tests/optimization_results.json"
    click Beamer "https://github.com/tristandelcourt/tipe/blob/main/beamer/main.tex"

    %% Styles
    classDef core fill:#ADD8E6,stroke:#000,color:#000;
    classDef algo fill:#90EE90,stroke:#000,color:#000;
    classDef util fill:#FFFFE0,stroke:#000,color:#000;
    classDef test fill:#D3D3D3,stroke:#000,color:#000;
    classDef doc fill:#D3D3D3,stroke:#000,color:#000;
```
