# sidd0529/cosmos_lens architecture

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

- Interactive diagram: https://gitdiagram.com/sidd0529/cosmos_lens
- Repository: https://github.com/sidd0529/cosmos_lens

## Overview

##### Project type and purpose
- This is a scientific data‐processing pipeline (not a web or full‐stack app) that generates convergence and lensing maps from the COSMOS2015 galaxy catalog.
- It combines Python for orchestration, Cython as a bridge, and C for the high‐performance core routines.

##### File structure
Top‐level files and directories:
- setup.py            – build script (cythonize + compile C)
- cosmos_cy.pyx       – Cython wrapper module
- potential.c / .h    – C implementation of the Poisson solver
- galaxy_bias.py      – Python routine for calculating galaxy bias
- gauss_smooth.py     – Python routine for Gaussian smoothing
- hole_fill.py        – Python routine to fill masked regions
- cosmos_runme.py     – main Python driver orchestrating the pipeline
- README.md, LICENSE, .gitignore

##### README for additional insights
- Input: COSMOS2015_FITS data (download externally).
- Build: “python setup.py build_ext --inplace” compiles C/Cython.
- Run: “python cosmos_runme.py” invokes end‐to‐end map generation.
- Outputs: convergence map, potential map (image files).

##### Main components
a. Input Data
- COSMOS2015 FITS catalog files
b. Build System
- setup.py → invokes Cython + C compiler → produces extension module “cosmos_cy.so” (or .pyd)
c. Orchestration Layer (Python)
- cosmos_runme.py – top‐level script
- galaxy_bias.py, gauss_smooth.py, hole_fill.py – pre‐ and post‐processing Python modules
d. Compute Core (C via Cython)
- cosmos_cy.pyx → wraps potential.c functions and exposes them as Python‐callable APIs
- potential.c / .h – high-performance numerical routines
e. External Libraries
- NumPy (arrays, FFTs, etc.)
- Cython (build and wrapping)
- astropy.io or fits I/O libraries (if used for FITS read/write)
f. Outputs
- Convergence map (image)
- Potential map (image)

##### Relationships and interactions
1. User invokes cosmos_runme.py
2. Python code loads FITS data → NumPy arrays
3. Preprocessing steps in Python modules (gauss_smooth, hole_fill, galaxy_bias)
4. cosmos_runme calls Cython‐wrapped functions in cosmos_cy
5. Inside cosmos_cy: data marshaled to C arrays → potential.c solver runs → results returned
6. Python receives results → further processing/normalization → write output images

##### Architectural patterns and principles
- Layered architecture:
– Top: Python orchestration & I/O
– Middle: Cython interface (glue)
– Bottom: Native C compute engine
- Separation of concerns:
– Python handles I/O, control flow, plotting;
– C handles CPU‐intensive numerical kernels
- Build pipeline: Cython compilation orchestrated by setup.py

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Input Data
    subgraph "Input Data"
        FITSInput["COSMOS2015 FITS Catalog"]:::data
    end

    %% Build Process
    subgraph "Build Process"
        Setup["setup.py"]:::python
        Cythonize["cythonize cosmos_cy.pyx"]:::cython
        CompileC["compile potential.c"]:::c
        Extension["cosmos_cy.so"]:::cython
        Setup -->|"build_ext"| Cythonize
        Cythonize --> CompileC
        CompileC --> Extension
    end

    %% Python Orchestration
    subgraph "Python Orchestration"
        Run["cosmos_runme.py"]:::python
        Bias["galaxy_bias.py"]:::python
        Smooth["gauss_smooth.py"]:::python
        Hole["hole_fill.py"]:::python
        Run -->|"invokes"| Bias
        Run -->|"invokes"| Smooth
        Run -->|"invokes"| Hole
    end

    %% Cython Glue
    subgraph "Cython Glue"
        CWrap["cosmos_cy.pyx"]:::cython
    end

    %% Native C Compute
    subgraph "Native C Compute"
        CImplC["potential.c"]:::c
        CImplH["potential.h"]:::c
    end

    %% Outputs
    subgraph "Outputs"
        ConvMap["Convergence Map (Image)"]:::data
        PotMap["Potential Map (Image)"]:::data
    end

    %% Documentation
    subgraph "Documentation & Metadata"
        RD["README.md"]:::data
        LIC["LICENSE"]:::data
    end

    %% Data Flow
    FITSInput -->|"FITS (via astropy/io)"| Run
    Run -->|"NumPy arrays"| Bias
    Run -->|"NumPy arrays"| Smooth
    Run -->|"NumPy arrays"| Hole
    Run -->|"calls APIs"| CWrap
    CWrap -->|"marshals to C arrays"| CImplC
    CImplC -->|"uses header"| CImplH
    CImplC -->|"results (C arrays)"| CWrap
    CWrap -->|"returns NumPy arrays"| Run
    Run -->|"writes outputs"| ConvMap
    Run -->|"writes outputs"| PotMap

    %% Click Events
    click Setup "https://github.com/sidd0529/cosmos_lens/blob/master/setup.py"
    click CWrap "https://github.com/sidd0529/cosmos_lens/blob/master/cosmos_cy.pyx"
    click CImplC "https://github.com/sidd0529/cosmos_lens/blob/master/potential.c"
    click CImplH "https://github.com/sidd0529/cosmos_lens/blob/master/potential.h"
    click Run "https://github.com/sidd0529/cosmos_lens/blob/master/cosmos_runme.py"
    click Bias "https://github.com/sidd0529/cosmos_lens/blob/master/galaxy_bias.py"
    click Smooth "https://github.com/sidd0529/cosmos_lens/blob/master/gauss_smooth.py"
    click Hole "https://github.com/sidd0529/cosmos_lens/blob/master/hole_fill.py"
    click RD "https://github.com/sidd0529/cosmos_lens/blob/master/README.md"
    click LIC "https://github.com/sidd0529/cosmos_lens/tree/master/LICENSE"

    %% Styles
    classDef python fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef cython fill:#90EE90,stroke:#333,stroke-width:1px
    classDef c fill:#FFA500,stroke:#333,stroke-width:1px
    classDef data fill:#D3D3D3,stroke:#333,stroke-width:1px
```
