# tiberlab/uptight architecture

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

- Interactive diagram: https://gitdiagram.com/tiberlab/uptight
- Repository: https://github.com/tiberlab/uptight

## Overview

##### Main Components
- Input & Configuration Files: These are not only the external data files (such as basis data, k-points, test.conf) found in directories like TEST and bulk but also the build/configuration scripts (configure.ac, Makefile, autoconf-related files). Show how these feed into the simulation routines.
- API Layer: The “src/api” directory contains headers, exception definitions, and test programs that expose the underlying functionality of the simulation code. Represent this component as the interface that mediates between user inputs (or external applications such as TiberCAD) and the internal engines.
- Core Computational Libraries:
- lib_uptight: Contains numerical routines, matrix and vector operations, solvers (e.g., Lanczos, Davidson methods), sparse matrix handling, and more.
- davidson: Dedicated routines for eigenvalue solvers using the Davidson method.
- palloc: Modules, likely for memory management/allocation routines and precision handling.
- External Libraries & Dependencies: Show integration with the ARPACK libraries (lib_arpack) and note the CUDA portions in lib_uptight, which hint at GPU acceleration.
- Test & Benchmark Suites: The “src/tests” and “TEST” directories populate a comprehensive suite of test cases that validate the simulation across various materials (e.g., GaAs, GaN, AlAs, etc.). This is critical for verifying computation correctness and expected behavior.
- Domain-specific Data & Bulk Parameter Files: The “bulk” directory holds numerous parameter files for various semiconductor materials—indicating that simulation configuration depends heavily on material-specific input.

##### Relationships and Interactions
- Data Flow: Illustrate how input configuration files and material parameters are fed into the API layer. The API then passes these inputs to the core computational libraries, which perform numerical tasks (like eigenvalue solving, matrix operations, etc.) and output simulation results.
- External Service Integration: Include an element that represents the interfacing with TiberCAD. Although Uptight is a standalone simulation engine, its usage is frequently via an external multiscale simulation platform, so a connection from the API to “external simulation frameworks” is worth representing.
- Testing Loops: Show a feedback loop from test harnesses (in src/tests and TEST directories) returning validation results back to the simulation code, which ensures the numerical solvers compute as expected.

##### Architectural Patterns and Design Principles
- Layered Architecture: Represent the system in layers—from low-level libraries that handle numerical computations, through an API layer that abstracts those details, up to external interfaces (like TiberCAD or input scripts).

- This to the “API Layer”, which stands as the gateway for invoking simulation routines.
- From the API, branch out to the “Computational Core”, segregating the numerical solvers (Davidson, Lanczos) and support libraries (lib_uptight, palloc).

## Diagram (Mermaid)

```mermaid
graph TD
    subgraph "Input & Initialization"
        A1["Input Files (bulk)"]:::input
        A2["Test Configuration Files (TEST)"]:::test
        A3["Build & Configuration Scripts"]:::build
    end

    B["API Module (src/api)"]:::api

    subgraph "Computational Core"
        C1["lib_uptight (Numerical Routines & CUDA)"]:::core
        C2["davidson (Eigenvalue Solvers)"]:::core
        C3["palloc (Memory & Precision Management)"]:::core
    end

    D["External Dependencies (ARPACK)"]:::external

    E["Test & Benchmark Suites (src/tests & TEST)"]:::test

    F["External Simulator (TiberCAD)"]:::external

    subgraph "Simulation Output/Logs"
        O["Results & Logs"]:::output
    end

    A1 -->|"feeds"| B
    A2 -->|"feeds"| B
    A3 -->|"initializes"| B

    B -->|"calls"| C1
    B -->|"calls"| C2
    B -->|"calls"| C3

    B -->|"integrates"| D
    B -->|"interfaces"| F

    C1 -->|"produces"| O
    C2 -->|"produces"| O
    C3 -->|"produces"| O

    E -->|"validates"| B

    click A1 "https://github.com/tiberlab/uptight/tree/main/bulk/"
    click A2 "https://github.com/tiberlab/uptight/tree/main/TEST/"
    click A3 "https://github.com/tiberlab/uptight/blob/main/src/configure.ac"
    click B "https://github.com/tiberlab/uptight/tree/main/src/api/"
    click C1 "https://github.com/tiberlab/uptight/tree/main/src/lib_uptight/"
    click C2 "https://github.com/tiberlab/uptight/tree/main/src/davidson/"
    click C3 "https://github.com/tiberlab/uptight/tree/main/src/palloc/"
    click D "https://github.com/tiberlab/uptight/tree/main/lib_arpack/"
    click E "https://github.com/tiberlab/uptight/tree/main/src/tests/"

classDef input fill:#ffebcd,stroke:#333,stroke-width:2px;
classDef test fill:#ffcccc,stroke:#333,stroke-width:2px;
classDef build fill:#e6e6fa,stroke:#333,stroke-width:2px;
classDef api fill:#add8e6,stroke:#333,stroke-width:2px;
classDef core fill:#98fb98,stroke:#333,stroke-width:2px;
classDef external fill:#d3d3d3,stroke:#333,stroke-width:2px;
classDef output fill:#f0e68c,stroke:#333,stroke-width:2px;
```
