# rlado/rsparse architecture

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

- Interactive diagram: https://gitdiagram.com/rlado/rsparse
- Repository: https://github.com/rlado/rsparse

## Overview

##### Project Type and Purpose
- **Type**: A Rust-based open-source library (crate) for sparse matrix representations and direct linear solver routines.
- **Purpose**: Provide data structures (CSC and triplet), conversions from/to dense, core sparse arithmetic (addition, multiplication, transpose), and direct solvers (LU, Cholesky, QR, forward/back substitution).

##### File Structure
- **Cargo.toml**: Crate metadata, dependencies, feature flags.
- **src/lib.rs**: Public API entrypoint, re-exports modules.
- **src/data.rs**: Core data structures (`Sprs`, `Trpl`), conversion methods.
- **src/lib.rs** (plus potential hidden modules): Solver function definitions (`lsolve`, `usolve`, `cholsol`, etc.).
- **tests/**: Integration tests, asset files (.sprs), unit tests for each solver and serialization.
- **.github/workflows/rust.yml**: CI pipeline for build, test, and lint.

##### Extract Architectural Insights from the README
- **Core Modules**:
- **Data Structures**: `Sprs` (CSC) & `Trpl` (triplet)
- **Conversion Layer**: dense ↔ sparse
- **Arithmetic Layer**: addition, multiplication, transpose
- **Solvers**: forward/back substitution and factorizations (lsolve, usolve, cholsol, lusol, qrsol)
- **External Integration**: Documentation published on docs.rs, CI via GitHub Actions, crate published on crates.io.

a. **Modules (Rectangles)**
- **Public API** (`lib.rs`)
- **Data Module** (`data.rs`): Sprs & Trpl, conversion routines
- **Arithmetic Module**: add, multiply, transpose functions
- **Solver Module**: lsolve, ltsolve, usolve, utsolve, cholsol, lusol, qrsol
- **Test Harness** (`tests/`): basic_tests, solver_tests, save_load_tests, assets
- **CI/CD**: GitHub Actions workflow
- **User Code → Public API**
- **API → Data Module** → **Arithmetic Module** → **Solver Module** → **Result**
- **Test Harness → (all modules)** to validate correctness
- **Cargo.toml → Build System**
- **GitHub Actions → Build & Test**
c. **Architectural Patterns**
- **Modular Crate**: Each functional area separated into modules
- **Separation of Concerns**: Data representation, algorithms, and tests are distinct
- **Generic Programming**: Solver routines parameterized over numeric types
d. **Technologies & Frameworks**
- **Language**: Rust
- **Build System**: Cargo
- **CI**: GitHub Actions
- **Docs**: docs.rs publishing

##### Detailed Elements to Capture
- **Data Representations**: Show transformation from a `Vec<Vec<T>>` (dense) into `Trpl` and then into `Sprs`, and vice versa.
- **Algorithmic Pipelines**:
- Forward substitution → Back substitution (lsolve & usolve)
- Factorization flows: A → LU → lusol, A → Cholesky → cholsol, A → QR → qrsol
- **Test Flow**: Tests read `.sprs` asset files → instantiate matrices → run solver functions → assert correctness
- **External Interfaces**: Cargo (build/publish) and docs.rs (documentation endpoint)

## Diagram (Mermaid)

```mermaid
graph TB
    %% External Entities
    User["User Application"]:::user

    %% rsparse Crate Boundary
    subgraph "rsparse Crate"
        direction TB
        API["Public API"]:::api

        subgraph "Data Module" 
            direction TB
            Dense["Dense (Vec<Vec<T>>)"]:::data
            Trpl["Triplet (Trpl)"]:::data
            Sprs["CSC (Sprs)"]:::data
        end

        subgraph "Arithmetic Module"
            direction TB
            Add["add()"]:::arithmetic
            Mul["multiply()"]:::arithmetic
            Trans["transpose()"]:::arithmetic
        end

        subgraph "Solver Module"
            direction TB
            LSolve["lsolve()/ltsolve()"]:::solver
            USolve["usolve()/utsolve()"]:::solver
            LU["lusol()"]:::solver
            Cholesky["cholsol()"]:::solver
            QR["qrsol()"]:::solver
        end

        subgraph "Test Harness"
            direction TB
            BasicTests["basic_tests.rs"]:::tests
            SolverTests["solver_tests.rs"]:::tests
            SaveLoad["save_load_tests.rs"]:::tests
            Utils["utils.rs"]:::tests
            Assets[".sprs assets"]:::tests
        end

        Config["Build Config\n(Cargo.toml)"]:::config
    end

    CI["GitHub Actions\n(.github/workflows/rust.yml)"]:::ci

    %% Data Flows
    User -->|"calls"| API
    API -->|"uses"| Dense
    Dense -->|"to_triplet()"| Trpl
    Trpl -->|"to_csc()"| Sprs
    Sprs -->|"add/mul/transpose"| Add
    Sprs -->|"multiply()"| Mul
    Sprs -->|"transpose()"| Trans

    %% Solver Flows
    Sprs -->|"solve"| LSolve
    Sprs -->|"solve"| USolve
    Sprs -->|"solve"| LU
    Sprs -->|"solve"| Cholesky
    Sprs -->|"solve"| QR

    %% Build & CI
    Config -->|"builds"| API
    CI -->|"runs build & test"| Config
    CI -->|"runs tests"| BasicTests
    CI -->|"runs tests"| SolverTests
    CI -->|"runs tests"| SaveLoad
    CI -->|"runs tests"| Utils

    %% Test Coverage (dashed)
    BasicTests -.-> API
    BasicTests -.-> Dense
    BasicTests -.-> Add
    SolverTests -.-> LSolve
    SolverTests -.-> Mul
    SaveLoad -.-> Sprs
    Utils -.-> Assets

    %% Click Events
    click API "https://github.com/rlado/rsparse/blob/master/src/lib.rs"
    click Dense "https://github.com/rlado/rsparse/blob/master/src/data.rs"
    click Trpl "https://github.com/rlado/rsparse/blob/master/src/data.rs"
    click Sprs "https://github.com/rlado/rsparse/blob/master/src/data.rs"
    click Add "https://github.com/rlado/rsparse/blob/master/src/lib.rs"
    click Mul "https://github.com/rlado/rsparse/blob/master/src/lib.rs"
    click Trans "https://github.com/rlado/rsparse/blob/master/src/lib.rs"
    click LSolve "https://github.com/rlado/rsparse/blob/master/src/lib.rs"
    click USolve "https://github.com/rlado/rsparse/blob/master/src/lib.rs"
    click LU "https://github.com/rlado/rsparse/blob/master/src/lib.rs"
    click Cholesky "https://github.com/rlado/rsparse/blob/master/src/lib.rs"
    click QR "https://github.com/rlado/rsparse/blob/master/src/lib.rs"
    click BasicTests "https://github.com/rlado/rsparse/blob/master/tests/basic_tests.rs"
    click SolverTests "https://github.com/rlado/rsparse/blob/master/tests/solver_tests.rs"
    click SaveLoad "https://github.com/rlado/rsparse/blob/master/tests/save_load_tests.rs"
    click Utils "https://github.com/rlado/rsparse/blob/master/tests/utils.rs"
    click Assets "https://github.com/rlado/rsparse/tree/master/tests/assets/"
    click CI "https://github.com/rlado/rsparse/blob/master/.github/workflows/rust.yml"
    click Config "https://github.com/rlado/rsparse/blob/master/Cargo.toml"

    %% Styles
    classDef data fill:#cce5ff,stroke:#004085,color:#004085;
    classDef arithmetic fill:#d4edda,stroke:#155724,color:#155724;
    classDef solver fill:#fff3cd,stroke:#856404,color:#856404;
    classDef tests fill:#e2e3e5,stroke:#6c757d,color:#6c757d;
    classDef ci fill:#f5c6cb,stroke:#721c24,color:#721c24;
    classDef config fill:#ffeeba,stroke:#856404,color:#856404;
    classDef api fill:#d1ecf1,stroke:#0c5460,color:#0c5460;
    classDef user fill:#e0f7fa,stroke:#006064,color:#006064;
```
