# bullygen/stringlensing architecture

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

- Interactive diagram: https://gitdiagram.com/bullygen/stringlensing
- Repository: https://github.com/bullygen/stringlensing

## Overview

stringlensing is a research toolkit for simulating cosmic-string gravitational lensing, fitting synthetic and real astronomical images, and evaluating recovery quality. A principal workflow generates synthetic images, fits their parameters, and summarizes fit quality; telescope sweeps vary observing conditions around that workflow. Separate branches prepare real FITS observations and analyze quasar-pair detectability and CSL-1 models. The README documents the C++/pybind11 image-modeling and fitting core. Edges are limited to relationships visible in excerpts, SOURCE INDEX references, or the README; unsampled subsystems are included without speculative wiring.

Main entry points: [`stringlensing/observation_study.py`](https://github.com/bullygen/stringlensing/blob/main/stringlensing/observation_study.py) (Paired observation study), [`stringlensing/fit_quality_pipeline.py`](https://github.com/bullygen/stringlensing/blob/main/stringlensing/fit_quality_pipeline.py) (Synthetic fit quality), [`stringlensing/revision_models.py`](https://github.com/bullygen/stringlensing/blob/main/stringlensing/revision_models.py) (Fit model methods), [`stringlensing/csl1_analysis.py`](https://github.com/bullygen/stringlensing/blob/main/stringlensing/csl1_analysis.py) (CSL-1 model comparison)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_simulation["Simulation and fitting"]
  node_quality["Synthetic fit quality"]
  node_telescope["Telescope sweeps"]
  node_simcore["Lens simulation core<br/>[stringlensing.cpp]"]
  node_utilities["Model utilities"]
  node_wrapper["Python wrapper<br/>[wrapper.py]"]
end

subgraph group_observations["Observation studies"]
  node_quasarsim["Quasar-pair simulation"]
  node_study["Paired observation study"]
  node_revisionmodels["Fit model methods<br/>[revision_models.py]"]
end

subgraph group_realdata["Real-image analysis"]
  node_photometry["FITS photometry GUI<br/>[eda_photometry.py]"]
  node_photocli["FITS preparation<br/>[photometry_cli.py]"]
  node_ps1["Pan-STARRS data fetch<br/>[fetch_ps1.py]"]
  node_realfitting["Real-image fitting<br/>[real_fit.py]"]
  node_realpsf["PSF fitting<br/>[real_psf_fit.py]"]
end

subgraph group_csl1["CSL-1 research"]
  node_cslanalysis["CSL-1 model comparison<br/>[csl1_analysis.py]"]
  node_cslrevision["CSL-1 revised fits<br/>[csl1_revision.py]"]
  node_cslpsf["CSL-1 PSF analysis<br/>[csl1_psf.py]"]
  node_cslempirical["CSL-1 empirical analysis<br/>[csl1_empirical.py]"]
end

node_researcher(("Researcher"))

node_researcher -->|"runs"| node_quality
node_researcher -->|"runs sweeps"| node_telescope
node_researcher -->|"prepares FITS"| node_photometry
node_telescope -->|"uses pipeline"| node_quality
node_quality -->|"uses"| node_utilities
node_wrapper -->|"uses"| node_utilities
node_photometry -->|"uses"| node_photocli
node_study -->|"calls"| node_quasarsim
node_study -->|"uses"| node_realfitting
node_study -->|"uses"| node_revisionmodels
node_revisionmodels -->|"imports models"| node_cslanalysis
node_cslrevision -->|"uses"| node_cslanalysis
node_cslrevision -->|"fits with"| node_revisionmodels
node_cslanalysis -->|"renders images"| node_simcore
node_quasarsim -->|"fits with"| node_realfitting

click node_quality "https://github.com/bullygen/stringlensing/blob/main/stringlensing/fit_quality_pipeline.py"
click node_telescope "https://github.com/bullygen/stringlensing/blob/main/stringlensing/telescope_simulation.py"
click node_simcore "https://github.com/bullygen/stringlensing/blob/main/stringlensing/src/stringlensing.cpp"
click node_utilities "https://github.com/bullygen/stringlensing/blob/main/stringlensing/stringlensing_utilities.py"
click node_wrapper "https://github.com/bullygen/stringlensing/blob/main/stringlensing/wrapper.py"
click node_quasarsim "https://github.com/bullygen/stringlensing/blob/main/stringlensing/quasar_simulation.py"
click node_study "https://github.com/bullygen/stringlensing/blob/main/stringlensing/observation_study.py"
click node_revisionmodels "https://github.com/bullygen/stringlensing/blob/main/stringlensing/revision_models.py"
click node_photometry "https://github.com/bullygen/stringlensing/blob/main/stringlensing/eda_photometry.py"
click node_photocli "https://github.com/bullygen/stringlensing/blob/main/stringlensing/photometry_cli.py"
click node_ps1 "https://github.com/bullygen/stringlensing/blob/main/stringlensing/fetch_ps1.py"
click node_realfitting "https://github.com/bullygen/stringlensing/blob/main/stringlensing/real_fit.py"
click node_realpsf "https://github.com/bullygen/stringlensing/blob/main/stringlensing/real_psf_fit.py"
click node_cslanalysis "https://github.com/bullygen/stringlensing/blob/main/stringlensing/csl1_analysis.py"
click node_cslrevision "https://github.com/bullygen/stringlensing/blob/main/stringlensing/csl1_revision.py"
click node_cslpsf "https://github.com/bullygen/stringlensing/blob/main/stringlensing/csl1_psf.py"
click node_cslempirical "https://github.com/bullygen/stringlensing/blob/main/stringlensing/csl1_empirical.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_quality,node_telescope,node_simcore,node_utilities,node_wrapper toneBlue
class node_quasarsim,node_study,node_revisionmodels toneAmber
class node_photometry,node_photocli,node_ps1,node_realfitting,node_realpsf toneMint
class node_cslanalysis,node_cslrevision,node_cslpsf,node_cslempirical toneRose
class node_researcher toneIndigo
```

## Components

### Simulation and fitting

- [Synthetic fit quality](https://github.com/bullygen/stringlensing/blob/main/stringlensing/fit_quality_pipeline.py): `stringlensing/fit_quality_pipeline.py`
- [Telescope sweeps](https://github.com/bullygen/stringlensing/blob/main/stringlensing/telescope_simulation.py): `stringlensing/telescope_simulation.py`
- [Lens simulation core](https://github.com/bullygen/stringlensing/blob/main/stringlensing/src/stringlensing.cpp): `stringlensing/src/stringlensing.cpp`
- [Model utilities](https://github.com/bullygen/stringlensing/blob/main/stringlensing/stringlensing_utilities.py): `stringlensing/stringlensing_utilities.py`
- [Python wrapper](https://github.com/bullygen/stringlensing/blob/main/stringlensing/wrapper.py): `stringlensing/wrapper.py`

### Observation studies

- [Quasar-pair simulation](https://github.com/bullygen/stringlensing/blob/main/stringlensing/quasar_simulation.py): `stringlensing/quasar_simulation.py`
- [Paired observation study](https://github.com/bullygen/stringlensing/blob/main/stringlensing/observation_study.py): `stringlensing/observation_study.py`
- [Fit model methods](https://github.com/bullygen/stringlensing/blob/main/stringlensing/revision_models.py): `stringlensing/revision_models.py`

### Real-image analysis

- [FITS photometry GUI](https://github.com/bullygen/stringlensing/blob/main/stringlensing/eda_photometry.py): `stringlensing/eda_photometry.py`
- [FITS preparation](https://github.com/bullygen/stringlensing/blob/main/stringlensing/photometry_cli.py): `stringlensing/photometry_cli.py`
- [Pan-STARRS data fetch](https://github.com/bullygen/stringlensing/blob/main/stringlensing/fetch_ps1.py): `stringlensing/fetch_ps1.py`
- [Real-image fitting](https://github.com/bullygen/stringlensing/blob/main/stringlensing/real_fit.py): `stringlensing/real_fit.py`
- [PSF fitting](https://github.com/bullygen/stringlensing/blob/main/stringlensing/real_psf_fit.py): `stringlensing/real_psf_fit.py`

### CSL-1 research

- [CSL-1 model comparison](https://github.com/bullygen/stringlensing/blob/main/stringlensing/csl1_analysis.py): `stringlensing/csl1_analysis.py`
- [CSL-1 revised fits](https://github.com/bullygen/stringlensing/blob/main/stringlensing/csl1_revision.py): `stringlensing/csl1_revision.py`
- [CSL-1 PSF analysis](https://github.com/bullygen/stringlensing/blob/main/stringlensing/csl1_psf.py): `stringlensing/csl1_psf.py`
- [CSL-1 empirical analysis](https://github.com/bullygen/stringlensing/blob/main/stringlensing/csl1_empirical.py): `stringlensing/csl1_empirical.py`

### Other components

- **Researcher**

## Connections

- Researcher → Synthetic fit quality: runs (evidence: `README.md`)
- Researcher → Telescope sweeps: runs sweeps (evidence: `README.md`)
- Researcher → FITS photometry GUI: prepares FITS (evidence: `README.md`)
- Telescope sweeps → Synthetic fit quality: uses pipeline (evidence: `stringlensing/telescope_simulation.py`)
- Synthetic fit quality → Model utilities: uses (evidence: `stringlensing/fit_quality_pipeline.py`)
- Python wrapper → Model utilities: uses (evidence: `stringlensing/wrapper.py`)
- FITS photometry GUI → FITS preparation: uses (evidence: `stringlensing/eda_photometry.py`)
- Paired observation study → Quasar-pair simulation: calls (evidence: `stringlensing/observation_study.py`)
- Paired observation study → Real-image fitting: uses (evidence: `stringlensing/observation_study.py`)
- Paired observation study → Fit model methods: uses (evidence: `stringlensing/observation_study.py`)
- Fit model methods → CSL-1 model comparison: imports models (evidence: `stringlensing/revision_models.py`)
- CSL-1 revised fits → CSL-1 model comparison: uses (evidence: `stringlensing/csl1_revision.py`)
- CSL-1 revised fits → Fit model methods: fits with (evidence: `stringlensing/csl1_revision.py`)
- CSL-1 model comparison → Lens simulation core: renders images (evidence: `stringlensing/csl1_analysis.py`)
- Quasar-pair simulation → Real-image fitting: fits with (evidence: `stringlensing/quasar_simulation.py`)
