# adamfield118/femmi architecture

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

- Interactive diagram: https://gitdiagram.com/adamfield118/femmi
- Repository: https://github.com/adamfield118/femmi

## Overview

FEMMI maps weak-lensing shear catalogues to convergence estimates: users provide FITS catalogues and survey settings, then receive convergence images, residuals, coverage, and optional noise maps. The central stages are catalogue ingestion, mesh and lensing-operator construction, regularized inverse reconstruction, and survey output. Separate capabilities include neural priors and calibration/comparison workflows. The README documents the survey interface; sampled excerpts show selected implementation details, so some internal connections are omitted where their call paths were not shown.

Main entry points: [`femmi/operators.py`](https://github.com/adamfield118/femmi/blob/main/femmi/operators.py) (Lensing operators), [`femmi/survey.py`](https://github.com/adamfield118/femmi/blob/main/femmi/survey.py) (Survey runner), [`femmi/inverse.py`](https://github.com/adamfield118/femmi/blob/main/femmi/inverse.py) (MAP reconstruction), [`femmi/mapping.py`](https://github.com/adamfield118/femmi/blob/main/femmi/mapping.py) (Catalogue mapper)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_survey["Survey workflow"]
  node_cli["Command interface<br/>[cli.py]"]
  node_survey_runner["Survey runner<br/>[survey.py]"]
  node_catalog_io["FITS ingestion<br/>[io.py]"]
  node_output["Survey products<br/>[survey_output.py]"]
end

subgraph group_solver["Reconstruction core"]
  node_mapper["Catalogue mapper<br/>[mapping.py]"]
  node_mesh["Mesh generation<br/>[mesh.py]"]
  node_elements["Finite elements<br/>[elements.py]"]
  node_basis["P3 basis<br/>[basis.py]"]
  node_assembly["Element assembly<br/>[assembly.py]"]
  node_bem["Boundary elements<br/>[bem.py]"]
  node_operators["Lensing operators<br/>[operators.py]"]
  node_observations["Observation handling<br/>[observations.py]"]
end

subgraph group_prior["Priors and inference"]
  node_inverse["MAP reconstruction<br/>[inverse.py]"]
  node_regularization["Regularization<br/>[regularization.py]"]
  node_priors["Prior models<br/>[priors.py]"]
  node_neural["Neural prior<br/>[prior.py]"]
  node_sampling["Posterior sampling<br/>[sampling.py]"]
end

subgraph group_research["Evaluation tools"]
  node_calibration["Method calibration<br/>[calibration.py]"]
  node_comparison["Paired comparisons<br/>[comparison.py]"]
  node_ks["KS catalogue methods<br/>[catalog.py]"]
end

node_user(("Survey analyst"))

node_user -->|"runs mapping"| node_cli
node_user -->|"uses Python API"| node_survey_runner
node_survey_runner -->|"reads catalogues"| node_catalog_io
node_survey_runner -->|"builds mappings"| node_mapper
node_survey_runner -->|"writes products"| node_output
node_mapper -->|"builds mesh"| node_mesh
node_mapper -->|"builds operators"| node_operators
node_operators -->|"uses geometry"| node_mesh
node_operators -->|"uses basis"| node_basis
node_operators -->|"assembles matrices"| node_assembly
node_operators -->|"couples boundary"| node_bem
node_operators -.->|"supports elements"| node_elements
node_inverse -->|"prepares data"| node_observations
node_inverse -->|"uses penalties"| node_regularization
node_inverse -->|"accepts prior"| node_priors
node_priors -->|"supports learned prior"| node_neural
node_sampling -->|"uses prior models"| node_priors
node_calibration -->|"fits KS methods"| node_ks
node_calibration -.->|"supports evaluation"| node_comparison

click node_cli "https://github.com/adamfield118/femmi/blob/main/femmi/cli.py"
click node_survey_runner "https://github.com/adamfield118/femmi/blob/main/femmi/survey.py"
click node_catalog_io "https://github.com/adamfield118/femmi/blob/main/femmi/io.py"
click node_mapper "https://github.com/adamfield118/femmi/blob/main/femmi/mapping.py"
click node_mesh "https://github.com/adamfield118/femmi/blob/main/femmi/mesh.py"
click node_elements "https://github.com/adamfield118/femmi/blob/main/femmi/elements.py"
click node_basis "https://github.com/adamfield118/femmi/blob/main/femmi/basis.py"
click node_assembly "https://github.com/adamfield118/femmi/blob/main/femmi/assembly.py"
click node_bem "https://github.com/adamfield118/femmi/blob/main/femmi/bem.py"
click node_operators "https://github.com/adamfield118/femmi/blob/main/femmi/operators.py"
click node_observations "https://github.com/adamfield118/femmi/blob/main/femmi/observations.py"
click node_inverse "https://github.com/adamfield118/femmi/blob/main/femmi/inverse.py"
click node_regularization "https://github.com/adamfield118/femmi/blob/main/femmi/regularization.py"
click node_priors "https://github.com/adamfield118/femmi/blob/main/femmi/priors.py"
click node_neural "https://github.com/adamfield118/femmi/blob/main/femmi/neural_prior/prior.py"
click node_sampling "https://github.com/adamfield118/femmi/blob/main/femmi/sampling.py"
click node_output "https://github.com/adamfield118/femmi/blob/main/femmi/survey_output.py"
click node_calibration "https://github.com/adamfield118/femmi/blob/main/femmi/calibration.py"
click node_comparison "https://github.com/adamfield118/femmi/blob/main/femmi/comparison.py"
click node_ks "https://github.com/adamfield118/femmi/blob/main/femmi/catalog.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_cli,node_survey_runner,node_catalog_io,node_output toneBlue
class node_mapper,node_mesh,node_elements,node_basis,node_assembly,node_bem,node_operators,node_observations toneAmber
class node_inverse,node_regularization,node_priors,node_neural,node_sampling toneMint
class node_calibration,node_comparison,node_ks toneRose
class node_user toneIndigo
```

## Components

### Survey workflow

- [Command interface](https://github.com/adamfield118/femmi/blob/main/femmi/cli.py): `femmi/cli.py`
- [Survey runner](https://github.com/adamfield118/femmi/blob/main/femmi/survey.py): `femmi/survey.py`
- [FITS ingestion](https://github.com/adamfield118/femmi/blob/main/femmi/io.py): `femmi/io.py`
- [Survey products](https://github.com/adamfield118/femmi/blob/main/femmi/survey_output.py): `femmi/survey_output.py`

### Reconstruction core

- [Catalogue mapper](https://github.com/adamfield118/femmi/blob/main/femmi/mapping.py): `femmi/mapping.py`
- [Mesh generation](https://github.com/adamfield118/femmi/blob/main/femmi/mesh.py): `femmi/mesh.py`
- [Finite elements](https://github.com/adamfield118/femmi/blob/main/femmi/elements.py): `femmi/elements.py`
- [P3 basis](https://github.com/adamfield118/femmi/blob/main/femmi/basis.py): `femmi/basis.py`
- [Element assembly](https://github.com/adamfield118/femmi/blob/main/femmi/assembly.py): `femmi/assembly.py`
- [Boundary elements](https://github.com/adamfield118/femmi/blob/main/femmi/bem.py): `femmi/bem.py`
- [Lensing operators](https://github.com/adamfield118/femmi/blob/main/femmi/operators.py): `femmi/operators.py`
- [Observation handling](https://github.com/adamfield118/femmi/blob/main/femmi/observations.py): `femmi/observations.py`

### Priors and inference

- [MAP reconstruction](https://github.com/adamfield118/femmi/blob/main/femmi/inverse.py): `femmi/inverse.py`
- [Regularization](https://github.com/adamfield118/femmi/blob/main/femmi/regularization.py): `femmi/regularization.py`
- [Prior models](https://github.com/adamfield118/femmi/blob/main/femmi/priors.py): `femmi/priors.py`
- [Neural prior](https://github.com/adamfield118/femmi/blob/main/femmi/neural_prior/prior.py): `femmi/neural_prior/prior.py`
- [Posterior sampling](https://github.com/adamfield118/femmi/blob/main/femmi/sampling.py): `femmi/sampling.py`

### Evaluation tools

- [Method calibration](https://github.com/adamfield118/femmi/blob/main/femmi/calibration.py): `femmi/calibration.py`
- [Paired comparisons](https://github.com/adamfield118/femmi/blob/main/femmi/comparison.py): `femmi/comparison.py`
- [KS catalogue methods](https://github.com/adamfield118/femmi/blob/main/femmi/catalog.py): `femmi/catalog.py`

### Other components

- **Survey analyst**

## Connections

- Survey analyst → Command interface: runs mapping (evidence: `README.md`)
- Survey analyst → Survey runner: uses Python API (evidence: `README.md`)
- Survey runner → FITS ingestion: reads catalogues (evidence: `femmi/survey.py`)
- Survey runner → Catalogue mapper: builds mappings (evidence: `femmi/survey.py`)
- Survey runner → Survey products: writes products (evidence: `femmi/survey.py`)
- Catalogue mapper → Mesh generation: builds mesh (evidence: `femmi/mapping.py`)
- Catalogue mapper → Lensing operators: builds operators (evidence: `femmi/mapping.py`)
- Lensing operators → Mesh generation: uses geometry (evidence: `femmi/operators.py`)
- Lensing operators → P3 basis: uses basis (evidence: `femmi/operators.py`)
- Lensing operators → Element assembly: assembles matrices (evidence: `femmi/operators.py`)
- Lensing operators → Boundary elements: couples boundary (evidence: `femmi/operators.py`)
- Lensing operators → Finite elements: supports elements
- MAP reconstruction → Observation handling: prepares data (evidence: `femmi/inverse.py`)
- MAP reconstruction → Regularization: uses penalties (evidence: `femmi/regularization.py`)
- MAP reconstruction → Prior models: accepts prior (evidence: `femmi/inverse.py`)
- Prior models → Neural prior: supports learned prior (evidence: `femmi/priors.py`)
- Posterior sampling → Prior models: uses prior models (evidence: `femmi/sampling.py`)
- Method calibration → KS catalogue methods: fits KS methods (evidence: `femmi/calibration.py`)
- Method calibration → Paired comparisons: supports evaluation (evidence: `femmi/calibration.py`)
