# CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
## Build & Development Commands
```bash
cargo build # Build the library
cargo test # Run all tests
cargo test --test tree-tests <test_name> # Run a single integration test
cargo clippy --all-targets --all-features # Lint (CI runs this)
cargo bench --no-run # Build benchmarks (divan framework)
cargo bench # Run benchmarks
cargo run --example <name> # Run an example (e.g., phylogenetic-diversity)
```
**Feature flags:**
- Default: `non_crypto_hash`, `simple_rooted_tree`
- Optional: `parallel` (enables rayon-based parallel computation)
- `cargo test --features parallel` to test with parallelism enabled
## Architecture
**phylo** is a phylogenetic analysis library. The core design is trait-based: narrow traits compose to provide tree functionality, and the library ships a concrete implementation (`SimpleRootedTree`) plus type aliases (`PhyloTree`, `PhyloNode`).
### Node layer (`src/node/`)
`Node<T, W, Z>` is generic over taxa type (`T: NodeTaxa`), edge weight (`W: EdgeWeight`), and node annotation (`Z: NodeWeight`). Traits build incrementally:
- `RootedTreeNode` — core: id, parent, children
- `RootedMetaNode` — taxa annotations
- `RootedWeightedNode` — edge weights
- `RootedZetaNode` — numeric node annotations (used by distance metrics)
### Tree layer (`src/tree/`)
`SimpleRootedTree<T, W, Z>` uses arena allocation (`Vec<Option<Node<T,W,Z>>>`) with `NodeID` (usize) indexing. Key submodules:
- `simple_rtree.rs` — `RootedTree`, `RootedMetaTree`, `RootedWeightedTree` traits and the `SimpleRootedTree` struct
- `ops.rs` — tree mutations: SPR, NNI, reroot, subtree extraction, contraction
- `distances.rs` — RF, weighted RF, cluster affinity, cophenetic distance, distance matrices
- `io.rs` — Newick and Nexus parsing/serialization
- `simulation.rs` — random tree generation (Yule, uniform)
### Iteration layer (`src/iter/node_iter.rs`)
Traversal traits implemented on any `RootedTree`: `DFS`, `BFS`, `PreOrder`, `Ancestors`, `EulerWalk`, `Clusters`. The `EulerWalk` trait supports O(1) LCA queries via `precompute_constant_time_lca()` using `BinaryRmq`.
### Prelude
`use phylo::prelude::*;` imports all public traits and types. This is the standard entry point.
### Feature-gated hashing
When `non_crypto_hash` is enabled (default), `FxHashMap`/`FxHashSet` replace `std::collections::HashMap`/`HashSet` throughout. Code that uses hash maps should follow this pattern:
```rust
#[cfg(feature = "non_crypto_hash")]
use fxhash::{FxHashMap as HashMap, FxHashSet as HashSet};
#[cfg(not(feature = "non_crypto_hash"))]
use std::collections::{HashMap, HashSet};
```
### Tests
Integration tests live in `tests/tree-tests.rs` and `tests/node-tests.rs`. Benchmarks use the `divan` framework in `benches/main.rs`.