# martiniani-lab/sweetsourcod architecture

> Architecture diagram of the GitHub repository martiniani-lab/sweetsourcod, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/martiniani-lab/sweetsourcod
- Repository: https://github.com/martiniani-lab/sweetsourcod

## Overview

SweetSourCod is a source-coding library for estimating sequence entropy and complexity through compression and parsing. Users supply sequences to its Python-facing algorithm modules and obtain measures or compressed representations. Its documented capabilities include LZ77/LZ78 and cross-parsing, block entropy and BWT-based estimation, general-purpose compressors and run-length encoding, and Hilbert/Gosper space-filling curves. The sampled C++ code shows LZ77 and BWT relying on suffix-array routines; unsampled Python extension internals limit detail on how all documented algorithms are exposed.

Main entry points: [`source/sweetsourcod/lempel_ziv.hpp`](https://github.com/martiniani-lab/sweetsourcod/blob/master/source/sweetsourcod/lempel_ziv.hpp) (LZ algorithms), [`source/kkp.cpp`](https://github.com/martiniani-lab/sweetsourcod/blob/master/source/kkp.cpp) (KKP parsing), [`source/divsufsort.c`](https://github.com/martiniani-lab/sweetsourcod/blob/master/source/divsufsort.c) (Suffix sorting), [`source/sweetsourcod/block_sorting.hpp`](https://github.com/martiniani-lab/sweetsourcod/blob/master/source/sweetsourcod/block_sorting.hpp) (BWT core)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_parsing["Parsing and complexity"]
  node_lz["Lempel-Ziv<br/>[lempel_ziv.pyx]"]
  node_lzcore["LZ algorithms<br/>[lempel_ziv.hpp]"]
  node_kkp["KKP parsing<br/>[kkp.cpp]"]
  node_kkpapi["KKP interfaces<br/>[kkp.h]"]
  node_streamer["SA streamer<br/>[SA_streamer.h]"]
  node_suffix["Suffix sorting<br/>[divsufsort.c]"]
  node_suffixapi["Suffix API<br/>[divsufsort.h]"]
end

subgraph group_entropy["Entropy estimators"]
  node_blockentropy["Block entropy<br/>[block_entropy.pyx]"]
  node_blockcore["Block entropy core<br/>[block_entropy.hpp]"]
  node_blocksort["BWT estimator<br/>[block_sorting.pyx]"]
  node_sortcore["BWT core<br/>[block_sorting.hpp]"]
end

subgraph group_compression["Compression utilities"]
  node_compress["Compression and RLE<br/>[zipper_compress.py]"]
  node_utils["Sequence utilities<br/>[utils.py]"]
end

subgraph group_curves["Space-filling curves"]
  node_hilbert["Hilbert curve<br/>[hilbert.pyx]"]
  node_gosper["Gosper curve<br/>[gosper.pyx]"]
end

node_user(("Python user"))

node_user -->|"uses"| node_lz
node_user -->|"uses"| node_blockentropy
node_user -->|"uses"| node_blocksort
node_user -->|"uses"| node_compress
node_user -->|"uses"| node_hilbert
node_user -->|"uses"| node_gosper
node_lzcore -->|"calls"| node_kkp
node_lzcore -->|"builds suffix array"| node_suffix
node_kkp -->|"reads array file"| node_streamer
node_kkp -->|"implements"| node_kkpapi
node_suffix -->|"implements"| node_suffixapi
node_blockcore -->|"uses conversions"| node_lzcore
node_sortcore -->|"computes transform"| node_suffix
node_sortcore -->|"uses conversions"| node_lzcore
node_compress -->|"uses byte helpers"| node_utils

click node_lz "https://github.com/martiniani-lab/sweetsourcod/blob/master/sweetsourcod/lempel_ziv.pyx"
click node_lzcore "https://github.com/martiniani-lab/sweetsourcod/blob/master/source/sweetsourcod/lempel_ziv.hpp"
click node_kkp "https://github.com/martiniani-lab/sweetsourcod/blob/master/source/kkp.cpp"
click node_kkpapi "https://github.com/martiniani-lab/sweetsourcod/blob/master/source/kkp/kkp.h"
click node_streamer "https://github.com/martiniani-lab/sweetsourcod/blob/master/source/kkp/SA_streamer.h"
click node_suffix "https://github.com/martiniani-lab/sweetsourcod/blob/master/source/divsufsort.c"
click node_suffixapi "https://github.com/martiniani-lab/sweetsourcod/blob/master/source/kkp/divsufsort.h"
click node_blockentropy "https://github.com/martiniani-lab/sweetsourcod/blob/master/sweetsourcod/block_entropy.pyx"
click node_blockcore "https://github.com/martiniani-lab/sweetsourcod/blob/master/source/sweetsourcod/block_entropy.hpp"
click node_blocksort "https://github.com/martiniani-lab/sweetsourcod/blob/master/sweetsourcod/block_sorting.pyx"
click node_sortcore "https://github.com/martiniani-lab/sweetsourcod/blob/master/source/sweetsourcod/block_sorting.hpp"
click node_compress "https://github.com/martiniani-lab/sweetsourcod/blob/master/sweetsourcod/zipper_compress.py"
click node_utils "https://github.com/martiniani-lab/sweetsourcod/blob/master/sweetsourcod/utils.py"
click node_hilbert "https://github.com/martiniani-lab/sweetsourcod/blob/master/sweetsourcod/hilbert.pyx"
click node_gosper "https://github.com/martiniani-lab/sweetsourcod/blob/master/sweetsourcod/gosper.pyx"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_lz,node_lzcore,node_kkp,node_kkpapi,node_streamer,node_suffix,node_suffixapi,node_user toneBlue
class node_blockentropy,node_blockcore,node_blocksort,node_sortcore toneAmber
class node_compress,node_utils toneMint
class node_hilbert,node_gosper toneRose
```

## Components

### Parsing and complexity

- [Lempel-Ziv](https://github.com/martiniani-lab/sweetsourcod/blob/master/sweetsourcod/lempel_ziv.pyx): `sweetsourcod/lempel_ziv.pyx`
- [LZ algorithms](https://github.com/martiniani-lab/sweetsourcod/blob/master/source/sweetsourcod/lempel_ziv.hpp): `source/sweetsourcod/lempel_ziv.hpp`
- [KKP parsing](https://github.com/martiniani-lab/sweetsourcod/blob/master/source/kkp.cpp): `source/kkp.cpp`
- [KKP interfaces](https://github.com/martiniani-lab/sweetsourcod/blob/master/source/kkp/kkp.h): `source/kkp/kkp.h`
- [SA streamer](https://github.com/martiniani-lab/sweetsourcod/blob/master/source/kkp/SA_streamer.h): `source/kkp/SA_streamer.h`
- [Suffix sorting](https://github.com/martiniani-lab/sweetsourcod/blob/master/source/divsufsort.c): `source/divsufsort.c`
- [Suffix API](https://github.com/martiniani-lab/sweetsourcod/blob/master/source/kkp/divsufsort.h): `source/kkp/divsufsort.h`

### Entropy estimators

- [Block entropy](https://github.com/martiniani-lab/sweetsourcod/blob/master/sweetsourcod/block_entropy.pyx): `sweetsourcod/block_entropy.pyx`
- [Block entropy core](https://github.com/martiniani-lab/sweetsourcod/blob/master/source/sweetsourcod/block_entropy.hpp): `source/sweetsourcod/block_entropy.hpp`
- [BWT estimator](https://github.com/martiniani-lab/sweetsourcod/blob/master/sweetsourcod/block_sorting.pyx): `sweetsourcod/block_sorting.pyx`
- [BWT core](https://github.com/martiniani-lab/sweetsourcod/blob/master/source/sweetsourcod/block_sorting.hpp): `source/sweetsourcod/block_sorting.hpp`

### Compression utilities

- [Compression and RLE](https://github.com/martiniani-lab/sweetsourcod/blob/master/sweetsourcod/zipper_compress.py): `sweetsourcod/zipper_compress.py`
- [Sequence utilities](https://github.com/martiniani-lab/sweetsourcod/blob/master/sweetsourcod/utils.py): `sweetsourcod/utils.py`

### Space-filling curves

- [Hilbert curve](https://github.com/martiniani-lab/sweetsourcod/blob/master/sweetsourcod/hilbert.pyx): `sweetsourcod/hilbert.pyx`
- [Gosper curve](https://github.com/martiniani-lab/sweetsourcod/blob/master/sweetsourcod/gosper.pyx): `sweetsourcod/gosper.pyx`

### Other components

- **Python user**

## Connections

- Python user → Lempel-Ziv: uses (evidence: `README.md`)
- Python user → Block entropy: uses (evidence: `README.md`)
- Python user → BWT estimator: uses (evidence: `README.md`)
- Python user → Compression and RLE: uses (evidence: `README.md`)
- Python user → Hilbert curve: uses (evidence: `README.md`)
- Python user → Gosper curve: uses (evidence: `README.md`)
- LZ algorithms → KKP parsing: calls (evidence: `source/sweetsourcod/lempel_ziv.hpp`)
- LZ algorithms → Suffix sorting: builds suffix array (evidence: `source/sweetsourcod/lempel_ziv.hpp`)
- KKP parsing → SA streamer: reads array file (evidence: `source/kkp.cpp`)
- KKP parsing → KKP interfaces: implements (evidence: `source/kkp.cpp`)
- Suffix sorting → Suffix API: implements (evidence: `source/divsufsort.c`)
- Block entropy core → LZ algorithms: uses conversions (evidence: `source/sweetsourcod/block_entropy.hpp`)
- BWT core → Suffix sorting: computes transform (evidence: `source/sweetsourcod/block_sorting.hpp`)
- BWT core → LZ algorithms: uses conversions (evidence: `source/sweetsourcod/block_sorting.hpp`)
- Compression and RLE → Sequence utilities: uses byte helpers (evidence: `sweetsourcod/zipper_compress.py`)