# lh3/minimap2 architecture

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

- Interactive diagram: https://gitdiagram.com/lh3/minimap2
- Repository: https://github.com/lh3/minimap2

## Overview

1. This repository is the source tree for Minimap2, a C-based sequence aligner and mapper. The core product is both a command-line tool (`minimap2`) and a reusable alignment library exposed through `minimap.h`.

2. The highest-level runtime flow is: read reference sequences or a prebuilt index, build/load a minimizer index, stream query sequences, find seed matches, chain them into candidate mappings, optionally perform base-level alignment, and emit PAF or SAM output. The README’s algorithm steps map directly onto the codebase’s main stages.

3. The code is split into a small set of core alignment subsystems:
   - indexing and seeding (`index.c`, `seed.c`, `sketch.c`, `splitidx.c`)
   - chaining and mapping (`chain` logic spread across `lchain.c`, `map.c`, `main.c`)
   - base-level alignment and scoring (`align.c`, `ksw2*`, `esterr.c`, `sdust.c`)
   - output formatting and record handling (`format.c`, `hit.c`, `bseq.c`)
   - option parsing and execution control (`options.c`, `main.c`)

4. `main.c` is the CLI orchestrator. It owns the top-level control loop, parses options, loads reference/index data, dispatches query processing, and coordinates which subsystems run depending on presets such as `map-ont`, `splice`, `sr`, `ava-pb`, or `asm5`.

5. `minimap.h` is the public API boundary for library use. External C callers can build/load an index and run alignments without going through the CLI. `mmpriv.h` contains internal/private structures and functions that are not intended to be stable.

6. Sequence I/O is handled by a dedicated layer centered on `bseq.c`/`bseq.h` and the bundled sequence readers (`kseq.h`, `krmq.h`). This layer isolates FASTA/FASTQ parsing, gzip-aware input handling, and batched query streaming from the alignment logic.

7. The low-level performance core relies on a collection of reusable utility headers and SIMD-aware code:
   - memory and allocation (`kalloc.c`, `kalloc.h`)
   - dynamic arrays/heaps/sorting/hash utilities (`kvec.h`, `kdq.h`, `khash.h`, `ksort.h`)
   - threading (`kthread.c`, `kthread.h`)
   - pairwise sequence alignment kernels (`ksw2.h`, `ksw2_dispatch.c`, `ksw2_*_sse.c`)
   - ARM compatibility via `sse2neon/` and optional SIMDe support via `Makefile.simde`
   This is where most architecture-specific performance behavior lives.

8. The alignment pipeline includes repeat/low-complexity filtering and error-aware heuristics before final extension. Files such as `sdust.c`/`sdust.h`, `esterr.c`, `misc.c`, `jump.c`, and `align.c` support the accuracy-focused parts of the mapper, especially for noisy long reads and spliced RNA alignment.

9. The repository supports multiple mapping modes, but they all share the same pipeline with different presets and scoring rules. The distinct use cases in the README are not separate products; they are configuration profiles layered over the same seeding/chaining/alignment engine.

10. Output is intentionally dual-format: approximate or detailed mappings can be emitted as PAF, SAM, or index files. The `-a`, `-c`, and `-d` modes correspond to different boundaries in the pipeline: final alignment output, CIGAR-rich alignment output, and serialized reference index output.

11. Python support is a separate binding layer rather than a second implementation. The `python/` directory contains the Cython-based `mappy` extension (`mappy.pyx`, `cmappy.*`, `minimap2.py`) that wraps a subset of the C API for embedding Minimap2 in Python applications and packaging it on PyPI/BioConda.

12. Utility and post-processing tooling lives outside the core aligner. `misc/paftools.js` and `misc/pafcluster.js` operate on PAF output for downstream conversion, evaluation, liftover, and variant/summary workflows. This is an auxiliary analysis layer, not part of the alignment engine.

13. Testing and validation are lightweight but data-backed. The `test/` directory contains small reference/query fixtures and expected alignments, while `tex/` holds evaluation material and benchmark-related documentation. The GitHub Actions workflow (`.github/workflows/ci.yaml`) drives automated build and regression checks.

14. Packaging and distribution are first-class concerns. `setup.py`, `pyproject.toml`, `MANIFEST.in`, and the release/docs references in the README show that the repo targets both native builds from source and packaged Python distribution, while the `Makefile` family is the primary native build entry point.

15. In diagram terms, the key boundaries are: input parsing, reference indexing, query seeding/chaining, base-level alignment, output formatting, and optional wrappers/tooling. The main internal dependency direction is from high-level orchestration in `main.c` down into reusable alignment kernels and utility libraries, with Python/JS tooling consuming the same core outputs rather than bypassing them.

Main entry points: [`main.c`](https://github.com/lh3/minimap2/blob/master/main.c) (CLI), [`align.c`](https://github.com/lh3/minimap2/blob/master/align.c) (Alignment), [`index.c`](https://github.com/lh3/minimap2/blob/master/index.c) (Indexing), [`format.c`](https://github.com/lh3/minimap2/blob/master/format.c) (Output)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Core aligner"]
  node_main["CLI<br/>orchestrator<br/>[main.c]"]
  node_options["Options<br/>arg parsing<br/>[options.c]"]
  node_index[("Indexing<br/>reference index<br/>[index.c]")]
  node_seed{{"Seeding<br/>minimizers<br/>[seed.c]"}}
  node_splitidx[("Split index<br/>index partitioning<br/>[splitidx.c]")]
  node_chain{{"Chaining<br/>candidate mapping<br/>[lchain.c]"}}
  node_map["Mapping<br/>[map.c]"]
  node_align{{"Alignment<br/>base-level extension<br/>[align.c]"}}
  node_format["Output<br/>record formatting<br/>[format.c]"]
  node_hit["Hits<br/>mapping records<br/>[hit.c]"]
  node_sdust{{"Dust filter<br/>low-complexity filter<br/>[sdust.c]"}}
  node_esterr["Error model<br/>heuristics<br/>[esterr.c]"]
  node_misc["Aux heuristics<br/>heuristic helpers<br/>[misc.c]"]
  node_minimap_h["Public API<br/>[minimap.h]"]
  node_mmpriv["Private API<br/>internal ABI<br/>[mmpriv.h]"]
end

subgraph group_runtime["Runtime support"]
  node_bseq["Sequence I/O<br/>batch reader<br/>[bseq.c]"]
  node_ksw2{{"DP kernels<br/>SIMD aligner<br/>[ksw2_dispatch.c]"}}
  node_kthread["Threads<br/>parallel runtime<br/>[kthread.c]"]
  node_kalloc["Allocator<br/>memory pool<br/>[kalloc.c]"]
  node_utils["Core utils<br/>containers and sort<br/>[kvec.h]"]
end

subgraph group_bindings["Bindings"]
  node_python["Python binding<br/>mappy wrapper<br/>[mappy.pyx]"]
end

subgraph group_tooling["Tooling"]
  node_paftools["PAF tools<br/>post-processing<br/>[paftools.js]"]
  node_pafcluster["PAF cluster<br/>post-processing<br/>[pafcluster.js]"]
  node_build["Build files<br/>native+python packaging"]
end

subgraph group_validation["Validation"]
  node_ci["CI<br/>automation<br/>[ci.yaml]"]
  node_tests["Fixtures<br/>test data<br/>[x3s-ref.fa]"]
  node_bench["Benchmarks<br/>evaluation<br/>[minimap2.tex]"]
end

node_main -->|"parse"| node_options
node_main -->|"load/build"| node_index
node_main -->|"stream queries"| node_bseq
node_main -->|"dispatch"| node_map
node_map -->|"seed"| node_seed
node_seed -->|"chain"| node_chain
node_chain -->|"extend"| node_align
node_align -->|"emit"| node_format
node_index -->|"index data"| node_seed
node_splitidx -->|"layout"| node_index
node_bseq -->|"records"| node_hit
node_map -->|"track"| node_hit
node_sdust -->|"filter"| node_align
node_esterr -->|"score"| node_align
node_misc -->|"helpers"| node_align
node_ksw2 -->|"kernel"| node_align
node_kthread -->|"parallelize"| node_main
node_kalloc -->|"alloc"| node_index
node_utils -->|"containers"| node_index
node_utils -->|"containers"| node_chain
node_minimap_h -->|"wrap"| node_python
node_minimap_h -->|"shared engine"| node_main
node_mmpriv -->|"internal state"| node_main
node_paftools -->|"consume"| node_format
node_pafcluster -->|"consume"| node_format
node_build -->|"package"| node_python
node_ci -->|"validate"| node_build
node_tests -->|"regress"| node_main
node_bench -->|"evaluate"| node_format

click node_main "https://github.com/lh3/minimap2/blob/master/main.c"
click node_options "https://github.com/lh3/minimap2/blob/master/options.c"
click node_index "https://github.com/lh3/minimap2/blob/master/index.c"
click node_seed "https://github.com/lh3/minimap2/blob/master/seed.c"
click node_splitidx "https://github.com/lh3/minimap2/blob/master/splitidx.c"
click node_chain "https://github.com/lh3/minimap2/blob/master/lchain.c"
click node_map "https://github.com/lh3/minimap2/blob/master/map.c"
click node_align "https://github.com/lh3/minimap2/blob/master/align.c"
click node_format "https://github.com/lh3/minimap2/blob/master/format.c"
click node_hit "https://github.com/lh3/minimap2/blob/master/hit.c"
click node_bseq "https://github.com/lh3/minimap2/blob/master/bseq.c"
click node_ksw2 "https://github.com/lh3/minimap2/blob/master/ksw2_dispatch.c"
click node_kthread "https://github.com/lh3/minimap2/blob/master/kthread.c"
click node_kalloc "https://github.com/lh3/minimap2/blob/master/kalloc.c"
click node_utils "https://github.com/lh3/minimap2/blob/master/kvec.h"
click node_sdust "https://github.com/lh3/minimap2/blob/master/sdust.c"
click node_esterr "https://github.com/lh3/minimap2/blob/master/esterr.c"
click node_misc "https://github.com/lh3/minimap2/blob/master/misc.c"
click node_minimap_h "https://github.com/lh3/minimap2/blob/master/minimap.h"
click node_mmpriv "https://github.com/lh3/minimap2/blob/master/mmpriv.h"
click node_python "https://github.com/lh3/minimap2/blob/master/python/mappy.pyx"
click node_paftools "https://github.com/lh3/minimap2/blob/master/misc/paftools.js"
click node_pafcluster "https://github.com/lh3/minimap2/blob/master/misc/pafcluster.js"
click node_build "https://github.com/lh3/minimap2/tree/master/Makefile"
click node_ci "https://github.com/lh3/minimap2/blob/master/.github/workflows/ci.yaml"
click node_tests "https://github.com/lh3/minimap2/blob/master/test/x3s-ref.fa"
click node_bench "https://github.com/lh3/minimap2/blob/master/tex/minimap2.tex"

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_main,node_options,node_index,node_seed,node_splitidx,node_chain,node_map,node_align,node_format,node_hit,node_sdust,node_esterr,node_misc,node_minimap_h,node_mmpriv toneBlue
class node_bseq,node_ksw2,node_kthread,node_kalloc,node_utils toneAmber
class node_python toneMint
class node_paftools,node_pafcluster,node_build toneRose
class node_ci,node_tests,node_bench toneIndigo
```

## Components

### Core aligner

Main indexing, mapping, alignment, and CLI orchestration pipeline.

- [CLI](https://github.com/lh3/minimap2/blob/master/main.c): orchestrator · Top-level command-line control flow and preset-driven execution. · `main.c`
- [Options](https://github.com/lh3/minimap2/blob/master/options.c): arg parsing · Command-line option parsing and preset configuration. · `options.c`
- [Indexing](https://github.com/lh3/minimap2/blob/master/index.c): reference index · Builds and loads minimizer indexes from reference sequences. · `index.c`
- [Seeding](https://github.com/lh3/minimap2/blob/master/seed.c): minimizers · Seed generation and lookup logic for query/reference matches. · `seed.c`
- [Split index](https://github.com/lh3/minimap2/blob/master/splitidx.c): index partitioning · Handles split/reference index layouts and serialized index boundaries. · `splitidx.c`
- [Chaining](https://github.com/lh3/minimap2/blob/master/lchain.c): candidate mapping · Clusters seed hits into candidate mapping chains. · `lchain.c`
- [Mapping](https://github.com/lh3/minimap2/blob/master/map.c): mapping control · Coordinates mapping decisions and chaining-to-alignment flow. · `map.c`
- [Alignment](https://github.com/lh3/minimap2/blob/master/align.c): base-level extension · Base-level alignment, scoring, and extension heuristics. · `align.c`
- [Output](https://github.com/lh3/minimap2/blob/master/format.c): record formatting · Formats alignments into PAF, SAM, and index outputs. · `format.c`
- [Hits](https://github.com/lh3/minimap2/blob/master/hit.c): mapping records · Core hit and alignment record structures used across the pipeline. · `hit.c`
- [Dust filter](https://github.com/lh3/minimap2/blob/master/sdust.c): low-complexity filter · Low-complexity masking and repeat filtering heuristics. · `sdust.c`
- [Error model](https://github.com/lh3/minimap2/blob/master/esterr.c): heuristics · Error-rate estimation and alignment heuristics. · `esterr.c`
- [Aux heuristics](https://github.com/lh3/minimap2/blob/master/misc.c): heuristic helpers · Miscellaneous alignment helpers and jump/trace utilities. · `misc.c`
- [Public API](https://github.com/lh3/minimap2/blob/master/minimap.h): C API · Stable library boundary for embedding the aligner in C code. · `minimap.h`
- [Private API](https://github.com/lh3/minimap2/blob/master/mmpriv.h): internal ABI · Internal structures and non-stable implementation details. · `mmpriv.h`

### Runtime support

Sequence I/O, threading, memory, and SIMD utility layers used by the core.

- [Sequence I/O](https://github.com/lh3/minimap2/blob/master/bseq.c): batch reader · FASTA/FASTQ parsing and batched query streaming. · `bseq.c`
- [DP kernels](https://github.com/lh3/minimap2/blob/master/ksw2_dispatch.c): SIMD aligner · Pairwise alignment kernels and SIMD dispatch layer. · `ksw2_dispatch.c`
- [Threads](https://github.com/lh3/minimap2/blob/master/kthread.c): parallel runtime · Threading primitives and work scheduling support. · `kthread.c`
- [Allocator](https://github.com/lh3/minimap2/blob/master/kalloc.c): memory pool · Memory allocation helpers used by performance-critical code. · `kalloc.c`
- [Core utils](https://github.com/lh3/minimap2/blob/master/kvec.h): containers and sort · Reusable vector, queue, hash, and sort utilities. · `kvec.h`

### Bindings

Python packaging and Cython wrapper around the C API.

- [Python binding](https://github.com/lh3/minimap2/blob/master/python/mappy.pyx): mappy wrapper · Cython-based Python extension and packaging glue. · `python/mappy.pyx`

### Tooling

Auxiliary analysis scripts and distribution/build entry points.

- [PAF tools](https://github.com/lh3/minimap2/blob/master/misc/paftools.js): post-processing · JavaScript utilities for downstream PAF analysis and conversion. · `misc/paftools.js`
- [PAF cluster](https://github.com/lh3/minimap2/blob/master/misc/pafcluster.js): post-processing · Clustering and summary tool for PAF-based workflows. · `misc/pafcluster.js`
- [Build files](https://github.com/lh3/minimap2/tree/master/Makefile): native+python packaging · Makefile and packaging entry points for native and Python distribution. · `Makefile`

### Validation

Fixtures, benchmarks, and CI checks.

- [CI](https://github.com/lh3/minimap2/blob/master/.github/workflows/ci.yaml): automation · Automated build and regression checks. · `.github/workflows/ci.yaml`
- [Fixtures](https://github.com/lh3/minimap2/blob/master/test/x3s-ref.fa): test data · Small reference, query, and expected alignment fixtures. · `test/x3s-ref.fa`
- [Benchmarks](https://github.com/lh3/minimap2/blob/master/tex/minimap2.tex): evaluation · Evaluation and benchmarking materials for mapping accuracy. · `tex/minimap2.tex`

## Connections

- CLI → Options: parse · CLI reads options and presets before execution.
- CLI → Indexing: load/build · Main orchestrator builds or loads the reference index.
- CLI → Sequence I/O: stream queries · Main orchestrator consumes batched sequence input.
- CLI → Mapping: dispatch · Top-level control passes work into the mapping pipeline.
- Mapping → Seeding: seed · Mapping starts by finding minimizer hits.
- Seeding → Chaining: chain · Seed matches are chained into candidate mappings.
- Chaining → Alignment: extend · Candidate chains are optionally extended into base-level alignments.
- Alignment → Output: emit · Final alignments are prepared for output formatting.
- Indexing → Seeding: index data · Index structures feed seeding and lookup.
- Split index → Indexing: layout · Split-index support shapes how reference data is organized.
- Sequence I/O → Hits: records · Sequence batching produces query records used throughout mapping.
- Mapping → Hits: track · Mapping updates and reuses hit/alignment records.
- Dust filter → Alignment: filter · Low-complexity masking influences extension and scoring.
- Error model → Alignment: score · Error-aware heuristics tune alignment decisions.
- Aux heuristics → Alignment: helpers · Auxiliary heuristics support extension and traceback behavior.
- DP kernels → Alignment: kernel · SIMD pairwise alignment kernels implement the DP core.
- Threads → CLI: parallelize · Threading support enables concurrent mapping work.
- Allocator → Indexing: alloc · Allocator support underpins memory-heavy index structures.
- Core utils → Indexing: containers · Generic containers and hashing support indexing and chaining data structures.
- Core utils → Chaining: containers · Chaining uses shared vector, queue, hash, and sort utilities.
- Public API → Python binding: wrap · Python extension wraps the public C API.
- Public API → CLI: shared engine · CLI and library share the same core alignment engine.
- Private API → CLI: internal state · Private structures are used internally by the orchestrator and subsystems.
- PAF tools → Output: consume · PAF tooling operates on mapper output.
- PAF cluster → Output: consume · Clustering tool consumes PAF output.
- Build files → Python binding: package · Build and packaging files support the Python binding.
- CI → Build files: validate · CI runs build and regression checks.
- Fixtures → CLI: regress · Fixtures exercise the mapper end-to-end.
- Benchmarks → Output: evaluate · Benchmark material compares mapper output and accuracy.
