# iqtree/iqtree3 architecture

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

- Interactive diagram: https://gitdiagram.com/iqtree/iqtree3
- Repository: https://github.com/iqtree/iqtree3

## Overview

IQ-TREE is maximum-likelihood phylogenomic software. Its principal workflow takes an alignment and analysis options, prepares sequence data and evolutionary models, searches and evaluates phylogenetic trees, then writes reports and Newick trees. The README also identifies model selection, branch and topology tests, partitioning, and AliSim as product capabilities. The source excerpts are partial, so links for some documented capabilities are shown from the CLI only where the index supports them; unsampled implementation details are not inferred.

Main entry points: [`main/main.cpp`](https://github.com/iqtree/iqtree3/blob/master/main/main.cpp) (CLI orchestration), [`tree/phylotree.cpp`](https://github.com/iqtree/iqtree3/blob/master/tree/phylotree.cpp) (Tree likelihood search), [`model/modelmixture.cpp`](https://github.com/iqtree/iqtree3/blob/master/model/modelmixture.cpp) (Substitution models), [`alignment/alignment.cpp`](https://github.com/iqtree/iqtree3/blob/master/alignment/alignment.cpp) (Alignment data)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_input["Input and setup"]
  node_cli["CLI orchestration<br/>[main.cpp]"]
  node_alignment["Alignment data<br/>[alignment.cpp]"]
  node_nexus["Nexus parsing"]
end

subgraph group_models["Evolutionary models"]
  node_model["Substitution models<br/>[modelmixture.cpp]"]
  node_partitions["Partition models<br/>[partitionmodel.cpp]"]
  node_rates["Rate variation<br/>[rategamma.cpp]"]
end

subgraph group_inference["Tree inference"]
  node_tree["Tree likelihood search<br/>[phylotree.cpp]"]
  node_treebase["Tree structures<br/>[mtree.cpp]"]
end

subgraph group_analysis["Analysis features"]
  node_bootstrap["Branch support<br/>[phyloanalysis.cpp]"]
  node_modelselect["Model selection<br/>[phylotesting.cpp]"]
  node_tests["Tree tests<br/>[treetesting.cpp]"]
  node_simulator["Alignment simulation<br/>[alisimulator.cpp]"]
  node_terrace["Terrace analysis<br/>[terrace.cpp]"]
end

subgraph group_runtime["Runtime support"]
  node_report["Analysis outputs<br/>[main.cpp]"]
  node_checkpoint["Checkpointing<br/>[checkpoint.cpp]"]
  node_parallel["Distributed execution<br/>[MPIHelper.cpp]"]
  node_progress["Progress and timing<br/>[progress.cpp]"]
end

node_user(("Researcher"))

node_user -->|"provides inputs"| node_cli
node_cli -->|"loads alignment"| node_alignment
node_alignment -->|"parses Nexus"| node_nexus
node_cli -->|"runs inference"| node_tree
node_tree -->|"evaluates likelihood"| node_model
node_tree -.->|"uses tree structures"| node_treebase
node_model -->|"supports partitions"| node_partitions
node_model -->|"supports rate variation"| node_rates
node_cli -->|"selects models"| node_modelselect
node_cli -->|"assesses support"| node_bootstrap
node_cli -->|"tests topologies"| node_tests
node_cli -->|"runs AliSim"| node_simulator
node_cli -->|"runs terrace analysis"| node_terrace
node_cli -.->|"saves state"| node_checkpoint
node_cli -->|"uses distributed execution"| node_parallel
node_cli -->|"reports progress"| node_progress
node_cli -->|"writes results"| node_report
node_tree -.->|"produces tree result"| node_report

click node_cli "https://github.com/iqtree/iqtree3/blob/master/main/main.cpp"
click node_alignment "https://github.com/iqtree/iqtree3/blob/master/alignment/alignment.cpp"
click node_nexus "https://github.com/iqtree/iqtree3/blob/master/ncl/nxscharactersblock.cpp"
click node_model "https://github.com/iqtree/iqtree3/blob/master/model/modelmixture.cpp"
click node_partitions "https://github.com/iqtree/iqtree3/blob/master/model/partitionmodel.cpp"
click node_rates "https://github.com/iqtree/iqtree3/blob/master/model/rategamma.cpp"
click node_tree "https://github.com/iqtree/iqtree3/blob/master/tree/phylotree.cpp"
click node_treebase "https://github.com/iqtree/iqtree3/blob/master/tree/mtree.cpp"
click node_bootstrap "https://github.com/iqtree/iqtree3/blob/master/main/phyloanalysis.cpp"
click node_modelselect "https://github.com/iqtree/iqtree3/blob/master/main/phylotesting.cpp"
click node_tests "https://github.com/iqtree/iqtree3/blob/master/main/treetesting.cpp"
click node_simulator "https://github.com/iqtree/iqtree3/blob/master/simulator/alisimulator.cpp"
click node_terrace "https://github.com/iqtree/iqtree3/blob/master/terrace/terrace.cpp"
click node_report "https://github.com/iqtree/iqtree3/blob/master/main/main.cpp"
click node_checkpoint "https://github.com/iqtree/iqtree3/blob/master/utils/checkpoint.cpp"
click node_parallel "https://github.com/iqtree/iqtree3/blob/master/utils/MPIHelper.cpp"
click node_progress "https://github.com/iqtree/iqtree3/blob/master/utils/progress.cpp"

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_cli,node_alignment,node_nexus toneBlue
class node_model,node_partitions,node_rates toneAmber
class node_tree,node_treebase toneMint
class node_bootstrap,node_modelselect,node_tests,node_simulator,node_terrace toneRose
class node_report,node_checkpoint,node_parallel,node_progress,node_user toneIndigo
```

## Components

### Input and setup

- [CLI orchestration](https://github.com/iqtree/iqtree3/blob/master/main/main.cpp): `main/main.cpp`
- [Alignment data](https://github.com/iqtree/iqtree3/blob/master/alignment/alignment.cpp): `alignment/alignment.cpp`
- [Nexus parsing](https://github.com/iqtree/iqtree3/blob/master/ncl/nxscharactersblock.cpp): `ncl/nxscharactersblock.cpp`

### Evolutionary models

- [Substitution models](https://github.com/iqtree/iqtree3/blob/master/model/modelmixture.cpp): `model/modelmixture.cpp`
- [Partition models](https://github.com/iqtree/iqtree3/blob/master/model/partitionmodel.cpp): `model/partitionmodel.cpp`
- [Rate variation](https://github.com/iqtree/iqtree3/blob/master/model/rategamma.cpp): `model/rategamma.cpp`

### Tree inference

- [Tree likelihood search](https://github.com/iqtree/iqtree3/blob/master/tree/phylotree.cpp): `tree/phylotree.cpp`
- [Tree structures](https://github.com/iqtree/iqtree3/blob/master/tree/mtree.cpp): `tree/mtree.cpp`

### Analysis features

- [Branch support](https://github.com/iqtree/iqtree3/blob/master/main/phyloanalysis.cpp): `main/phyloanalysis.cpp`
- [Model selection](https://github.com/iqtree/iqtree3/blob/master/main/phylotesting.cpp): `main/phylotesting.cpp`
- [Tree tests](https://github.com/iqtree/iqtree3/blob/master/main/treetesting.cpp): `main/treetesting.cpp`
- [Alignment simulation](https://github.com/iqtree/iqtree3/blob/master/simulator/alisimulator.cpp): `simulator/alisimulator.cpp`
- [Terrace analysis](https://github.com/iqtree/iqtree3/blob/master/terrace/terrace.cpp): `terrace/terrace.cpp`

### Runtime support

- [Analysis outputs](https://github.com/iqtree/iqtree3/blob/master/main/main.cpp): `main/main.cpp`
- [Checkpointing](https://github.com/iqtree/iqtree3/blob/master/utils/checkpoint.cpp): `utils/checkpoint.cpp`
- [Distributed execution](https://github.com/iqtree/iqtree3/blob/master/utils/MPIHelper.cpp): `utils/MPIHelper.cpp`
- [Progress and timing](https://github.com/iqtree/iqtree3/blob/master/utils/progress.cpp): `utils/progress.cpp`

### Other components

- **Researcher**

## Connections

- Researcher → CLI orchestration: provides inputs (evidence: `README.md`)
- CLI orchestration → Alignment data: loads alignment (evidence: `main/main.cpp`)
- Alignment data → Nexus parsing: parses Nexus (evidence: `alignment/alignment.cpp`)
- CLI orchestration → Tree likelihood search: runs inference (evidence: `main/main.cpp`)
- Tree likelihood search → Substitution models: evaluates likelihood (evidence: `tree/phylotree.cpp`)
- Tree likelihood search → Tree structures: uses tree structures
- Substitution models → Partition models: supports partitions (evidence: `README.md`)
- Substitution models → Rate variation: supports rate variation (evidence: `README.md`)
- CLI orchestration → Model selection: selects models (evidence: `README.md`)
- CLI orchestration → Branch support: assesses support (evidence: `README.md`)
- CLI orchestration → Tree tests: tests topologies (evidence: `README.md`)
- CLI orchestration → Alignment simulation: runs AliSim (evidence: `main/main.cpp`)
- CLI orchestration → Terrace analysis: runs terrace analysis (evidence: `main/main.cpp`)
- CLI orchestration → Checkpointing: saves state
- CLI orchestration → Distributed execution: uses distributed execution (evidence: `README.md`)
- CLI orchestration → Progress and timing: reports progress (evidence: `main/main.cpp`)
- CLI orchestration → Analysis outputs: writes results (evidence: `README.md`)
- Tree likelihood search → Analysis outputs: produces tree result
