# hana225-hub/prime-anc architecture

> Architecture diagram of the GitHub repository hana225-hub/prime-anc, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hana225-hub/prime-anc
- Repository: https://github.com/hana225-hub/prime-anc

## Overview

PRIME-ANC is a research implementation for active-noise-control filter design: it turns calibrated primary/secondary paths into causal FIR filters, optionally refines them, and scores frozen filters against evaluation paths and audio. The README also documents training-objective development, calibration, WMMSE and adaptive reference methods. Relationships below follow excerpts, SOURCE INDEX references, or README statements; unsampled internals are represented only where documented.

Main entry points: [`prime_anc/synthesis.py`](https://github.com/hana225-hub/prime-anc/blob/main/prime_anc/synthesis.py) (Path-to-FIR synthesis), [`scripts/replay_adaptive_table.py`](https://github.com/hana225-hub/prime-anc/blob/main/scripts/replay_adaptive_table.py) (Adaptive replay), [`scripts/synthesize.py`](https://github.com/hana225-hub/prime-anc/blob/main/scripts/synthesize.py) (Synthesis command), [`prime_anc/refinement/fast_gn.py`](https://github.com/hana225-hub/prime-anc/blob/main/prime_anc/refinement/fast_gn.py) (Gauss–Newton solver)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_synthesis["Filter synthesis"]
  node_synthesize_cli["Synthesis command<br/>[synthesize.py]"]
  node_synth["Path-to-FIR synthesis<br/>[synthesis.py]"]
  node_features["Path features<br/>[features.py]"]
  node_model["Generator and realization<br/>[models.py]"]
  node_calibration["Path calibration<br/>[calibration.py]"]
end

subgraph group_refinement["Filter refinement"]
  node_gn["Gauss–Newton solver<br/>[fast_gn.py]"]
  node_pcg["Fused GPU PCG<br/>[fused_pcg.py]"]
end

subgraph group_evaluation["Scoring and references"]
  node_eval_cli["Evaluation command<br/>[evaluate.py]"]
  node_replay["Frozen-FIR scorer<br/>[evaluation.py]"]
  node_wmmse["Direct WMMSE<br/>[wmmse.py]"]
  node_adaptive["Adaptive references<br/>[adaptive.py]"]
  node_adaptive_cli["Adaptive replay"]
end

subgraph group_method["Method development"]
  node_training["Training objective<br/>[training.py]"]
  node_ablations["Output controls<br/>[ablations.py]"]
end

node_user(("Engineer"))

node_user -->|"runs"| node_synthesize_cli
node_synthesize_cli -->|"calls"| node_synth
node_synth -->|"builds features"| node_features
node_synth -->|"loads and realizes"| node_model
node_user -.->|"calibrates paths"| node_calibration
node_user -.->|"refines FIR"| node_gn
node_gn -->|"dispatches fused solve"| node_pcg
node_user -->|"runs scoring"| node_eval_cli
node_eval_cli -->|"calls"| node_replay
node_user -.->|"designs comparison FIR"| node_wmmse
node_user -->|"replays references"| node_adaptive_cli
node_adaptive_cli -->|"scores FIR banks"| node_replay
node_adaptive_cli -.->|"replays methods"| node_adaptive
node_user -.->|"develops objective"| node_training
node_user -.->|"compares controls"| node_ablations

click node_synthesize_cli "https://github.com/hana225-hub/prime-anc/blob/main/scripts/synthesize.py"
click node_synth "https://github.com/hana225-hub/prime-anc/blob/main/prime_anc/synthesis.py"
click node_features "https://github.com/hana225-hub/prime-anc/blob/main/prime_anc/features.py"
click node_model "https://github.com/hana225-hub/prime-anc/blob/main/prime_anc/models.py"
click node_calibration "https://github.com/hana225-hub/prime-anc/blob/main/prime_anc/calibration.py"
click node_gn "https://github.com/hana225-hub/prime-anc/blob/main/prime_anc/refinement/fast_gn.py"
click node_pcg "https://github.com/hana225-hub/prime-anc/blob/main/prime_anc/refinement/fused_pcg.py"
click node_eval_cli "https://github.com/hana225-hub/prime-anc/blob/main/scripts/evaluate.py"
click node_replay "https://github.com/hana225-hub/prime-anc/blob/main/prime_anc/evaluation.py"
click node_wmmse "https://github.com/hana225-hub/prime-anc/blob/main/prime_anc/baselines/wmmse.py"
click node_adaptive "https://github.com/hana225-hub/prime-anc/blob/main/prime_anc/baselines/adaptive.py"
click node_adaptive_cli "https://github.com/hana225-hub/prime-anc/blob/main/scripts/replay_adaptive_table.py"
click node_training "https://github.com/hana225-hub/prime-anc/blob/main/prime_anc/training.py"
click node_ablations "https://github.com/hana225-hub/prime-anc/blob/main/prime_anc/ablations.py"

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_synthesize_cli,node_synth,node_features,node_model,node_calibration toneBlue
class node_gn,node_pcg toneAmber
class node_eval_cli,node_replay,node_wmmse,node_adaptive,node_adaptive_cli toneMint
class node_training,node_ablations toneRose
class node_user toneIndigo
```

## Components

### Filter synthesis

- [Synthesis command](https://github.com/hana225-hub/prime-anc/blob/main/scripts/synthesize.py): `scripts/synthesize.py`
- [Path-to-FIR synthesis](https://github.com/hana225-hub/prime-anc/blob/main/prime_anc/synthesis.py): `prime_anc/synthesis.py`
- [Path features](https://github.com/hana225-hub/prime-anc/blob/main/prime_anc/features.py): `prime_anc/features.py`
- [Generator and realization](https://github.com/hana225-hub/prime-anc/blob/main/prime_anc/models.py): `prime_anc/models.py`
- [Path calibration](https://github.com/hana225-hub/prime-anc/blob/main/prime_anc/calibration.py): `prime_anc/calibration.py`

### Filter refinement

- [Gauss–Newton solver](https://github.com/hana225-hub/prime-anc/blob/main/prime_anc/refinement/fast_gn.py): `prime_anc/refinement/fast_gn.py`
- [Fused GPU PCG](https://github.com/hana225-hub/prime-anc/blob/main/prime_anc/refinement/fused_pcg.py): `prime_anc/refinement/fused_pcg.py`

### Scoring and references

- [Evaluation command](https://github.com/hana225-hub/prime-anc/blob/main/scripts/evaluate.py): `scripts/evaluate.py`
- [Frozen-FIR scorer](https://github.com/hana225-hub/prime-anc/blob/main/prime_anc/evaluation.py): `prime_anc/evaluation.py`
- [Direct WMMSE](https://github.com/hana225-hub/prime-anc/blob/main/prime_anc/baselines/wmmse.py): `prime_anc/baselines/wmmse.py`
- [Adaptive references](https://github.com/hana225-hub/prime-anc/blob/main/prime_anc/baselines/adaptive.py): `prime_anc/baselines/adaptive.py`
- [Adaptive replay](https://github.com/hana225-hub/prime-anc/blob/main/scripts/replay_adaptive_table.py): `scripts/replay_adaptive_table.py`

### Method development

- [Training objective](https://github.com/hana225-hub/prime-anc/blob/main/prime_anc/training.py): `prime_anc/training.py`
- [Output controls](https://github.com/hana225-hub/prime-anc/blob/main/prime_anc/ablations.py): `prime_anc/ablations.py`

### Other components

- **Engineer**

## Connections

- Engineer → Synthesis command: runs (evidence: `README.md`)
- Synthesis command → Path-to-FIR synthesis: calls (evidence: `scripts/synthesize.py`)
- Path-to-FIR synthesis → Path features: builds features (evidence: `prime_anc/synthesis.py`)
- Path-to-FIR synthesis → Generator and realization: loads and realizes (evidence: `prime_anc/synthesis.py`)
- Engineer → Path calibration: calibrates paths (evidence: `README.md`)
- Engineer → Gauss–Newton solver: refines FIR (evidence: `README.md`)
- Gauss–Newton solver → Fused GPU PCG: dispatches fused solve (evidence: `prime_anc/refinement/fast_gn.py`)
- Engineer → Evaluation command: runs scoring (evidence: `README.md`)
- Evaluation command → Frozen-FIR scorer: calls (evidence: `scripts/evaluate.py`)
- Engineer → Direct WMMSE: designs comparison FIR (evidence: `README.md`)
- Engineer → Adaptive replay: replays references (evidence: `README.md`)
- Adaptive replay → Frozen-FIR scorer: scores FIR banks (evidence: `scripts/replay_adaptive_table.py`)
- Adaptive replay → Adaptive references: replays methods (evidence: `README.md`)
- Engineer → Training objective: develops objective (evidence: `README.md`)
- Engineer → Output controls: compares controls (evidence: `README.md`)