# durham-qlm/elecsus architecture

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

- Interactive diagram: https://gitdiagram.com/durham-qlm/elecsus
- Repository: https://github.com/durham-qlm/elecsus

## Overview

##### Project type and purpose
- ElecSus is an open-source scientific computation tool written in Python.
- Its primary purpose is to calculate the electric susceptibility and simulate weak-probe laser spectra for thermal alkali vapour cells, with fitting routines to extract experimental parameters.
- It includes both a programmatic API (elecsus_methods), a GUI (wxPython-based), Jupyter notebooks, and command-line installers for end users.

##### File structure
- Top level
- setup.py, MANIFEST.in – installation and packaging
- README.md, LICENSE.txt – documentation and licensing
- runGUI.py – entry point to launch GUI
- dist/ – pre-built Windows binaries
- Notebooks/ – Jupyter notebook examples
- elecsus/ package
- elecsus_gui.py – GUI startup and view layer
- elecsus_methods.py – facade methods: calculate(), fit_data()
- docs/ – GUI user guide PDF
- libs/ – core computational modules (physics libraries, numerical methods, fitting routines)
- images/ – static assets for GUI or documentation
- tests/ – unit and integration tests for core and fitting routines
- ElecSus.egg-info/ – packaging metadata

##### Key insights from README
- Core architecture separation: GUI layer, methods façade, core computational engine, notebooks.
- Major external dependencies: numpy, scipy, matplotlib, lmfit, wxPython.
- Entry points:
- GUI via elecsus_gui.start() or runGUI.py
- Notebook via Jupyter opening Notebooks/Basic Calculations.ipynb
- API via elecsus_methods.calculate() and fit_data()

a. Main components
- User Interfaces
– Jupyter Notebooks
– GUI application (wxPython)
– Command-line installer / script runner (runGUI.py, setup.py)
- Application Facade
– elecsus_methods.py exposing calculate() and fit_data()
- Core Computation Engine
– libs/ modules: physics (AtomConstants, EigenSystem, spectra), numerical routines (MLFittingRoutine, RRFittingRoutine, SAFittingRoutine), data processing, rotation and Jones matrices
- Data Store & Resources
– Static assets (images, docs/ElecSus GUI User Guide.pdf)
– Configuration & constants in libs/
- Testing & QA
– tests/ directory with fitting_tests.py, spectroscopy_tests.py, etc.
- Packaging & Distribution
– setup.py, MANIFEST.in, dist/ for binaries

b. Relationships and data flow
1. User action (GUI click, notebook cell, or API call)
2. UI layer invokes the facade methods in elecsus_methods.py
3. Facade passes input parameters to core computation modules in libs/
4. Core modules compute susceptibility, spectra, fits using numpy/scipy/lmfit
5. Results returned to facade
6. UI layer renders plots (matplotlib), displays results, or notebook visualizations
7. Tests invoke facade and core modules to validate correctness

c. Architectural patterns and design principles
- Layered Architecture: UI → Facade → Core Engine → Data/Resources
- Modular design: each physical calculation and fitting routine is isolated in its own library module
- Separation of concerns: GUI and notebooks do not contain physics code; they rely on well-defined interfaces in elecsus_methods
- Test-driven validation: dedicated tests for each fitting routine and spectroscopy calculation

d. Relevant technologies and frameworks
- Python 3.9 and below
- Numerical: numpy, scipy
- Plotting: matplotlib
- Fitting: lmfit
- UI: wxPython
- Packaging: setuptools (setup.py), PyPI metadata, Windows installer in dist/

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interfaces
    subgraph "User Interfaces"
        RUN["runGUI.py"]:::ui
        GUI_APP["elecsus_gui.py"]:::ui
        NB["Basic Calculations.ipynb"]:::ui
    end

    %% Application Facade
    subgraph "Application Facade"
        API["elecsus_methods.py"]:::api
    end

    %% Core Computation Engine
    subgraph "Core Computation Engine"
        subgraph "Physical Constants & Foundations"
            FC["FundamentalConstants.py"]:::core
            AC["AtomConstants.py"]:::core
            AM["ang_mom.py"]:::core
            AMP["ang_mom_p.py"]:::core
        end
        subgraph "Linear Algebra & Eigen Systems"
            BC["BasisChanger.py"]:::core
            ES["EigenSystem.py"]:::core
        end
        subgraph "Spectra Calculations"
            SP["spectra.py"]:::core
            SE["spectra_energies.py"]:::core
            SI["spectra_idealatom.py"]:::core
        end
        subgraph "Dielectric & Density Equations"
            SD["solve_dielectric.py"]:::core
            ND["numberDensityEqs.py"]:::core
        end
        subgraph "Rotation & Jones Matrices"
            RM["RotationMatrices.py"]:::core
            JM["JonesMatrices.py"]:::core
        end
        subgraph "Fitting Routines"
            ML["MLFittingRoutine.py"]:::core
            RR["RRFittingRoutine.py"]:::core
            SA["SAFittingRoutine.py"]:::core
        end
        subgraph "Data Processing & Visualization"
            DP["data_proc.py"]:::core
            PA["polarisation_animation_mpl.py"]:::core
            DC["durhamcolours.py"]:::core
            PR["preamble.py"]:::core
        end
    end

    %% Static Resources & Documentation
    subgraph "Static Resources & Documentation"
        DOC["ElecSus GUI User Guide.pdf"]:::res
        IMG["images/"]:::res
    end

    %% Testing & QA
    subgraph "Testing & QA"
        FT["fitting_tests.py"]:::test
        ST["spectroscopy_tests.py"]:::test
        FF["fit_fieldgradient.py"]:::test
        RT["rotondaro_tests.py"]:::test
    end

    %% Packaging & Distribution
    subgraph "Packaging & Distribution"
        SETUP["setup.py"]:::pack
        MANI["MANIFEST.in"]:::pack
        EGG["ElecSus.egg-info/"]:::pack
        DIST["ElecSus-3.0.8.win-amd64.exe"]:::pack
    end

    %% Connections
    RUN -->|starts| GUI_APP
    GUI_APP -->|calls| API
    NB -->|imports| API

    API -->|calls| FC
    API -->|calls| AC
    API -->|calls| AM
    API -->|calls| AMP
    API -->|calls| BC
    API -->|calls| ES
    API -->|calls| SP
    API -->|calls| SE
    API -->|calls| SI
    API -->|calls| SD
    API -->|calls| ND
    API -->|calls| RM
    API -->|calls| JM
    API -->|calls| ML
    API -->|calls| RR
    API -->|calls| SA
    API -->|calls| DP
    API -->|calls| PA
    API -->|calls| DC
    API -->|calls| PR

    API -->|returns results| GUI_APP
    API -->|returns results| NB

    FT -->|tests| API
    FT -->|tests| ML
    ST -->|tests| SP
    FF -->|tests| ND
    RT -->|tests| RM

    SETUP -->|packages| API
    SETUP -->|packages| FC

    %% Click Events
    click GUI_APP "https://github.com/durham-qlm/elecsus/blob/main/elecsus/elecsus_gui.py"
    click RUN "https://github.com/durham-qlm/elecsus/blob/main/runGUI.py"
    click NB "https://github.com/durham-qlm/elecsus/blob/main/Notebooks/Basic Calculations.ipynb"
    click API "https://github.com/durham-qlm/elecsus/blob/main/elecsus/elecsus_methods.py"
    click FC "https://github.com/durham-qlm/elecsus/blob/main/elecsus/libs/FundamentalConstants.py"
    click AC "https://github.com/durham-qlm/elecsus/blob/main/elecsus/libs/AtomConstants.py"
    click AM "https://github.com/durham-qlm/elecsus/blob/main/elecsus/libs/ang_mom.py"
    click AMP "https://github.com/durham-qlm/elecsus/blob/main/elecsus/libs/ang_mom_p.py"
    click BC "https://github.com/durham-qlm/elecsus/blob/main/elecsus/libs/BasisChanger.py"
    click ES "https://github.com/durham-qlm/elecsus/blob/main/elecsus/libs/EigenSystem.py"
    click SP "https://github.com/durham-qlm/elecsus/blob/main/elecsus/libs/spectra.py"
    click SE "https://github.com/durham-qlm/elecsus/blob/main/elecsus/libs/spectra_energies.py"
    click SI "https://github.com/durham-qlm/elecsus/blob/main/elecsus/libs/spectra_idealatom.py"
    click SD "https://github.com/durham-qlm/elecsus/blob/main/elecsus/libs/solve_dielectric.py"
    click ND "https://github.com/durham-qlm/elecsus/blob/main/elecsus/libs/numberDensityEqs.py"
    click RM "https://github.com/durham-qlm/elecsus/blob/main/elecsus/libs/RotationMatrices.py"
    click JM "https://github.com/durham-qlm/elecsus/blob/main/elecsus/libs/JonesMatrices.py"
    click ML "https://github.com/durham-qlm/elecsus/blob/main/elecsus/libs/MLFittingRoutine.py"
    click RR "https://github.com/durham-qlm/elecsus/blob/main/elecsus/libs/RRFittingRoutine.py"
    click SA "https://github.com/durham-qlm/elecsus/blob/main/elecsus/libs/SAFittingRoutine.py"
    click DP "https://github.com/durham-qlm/elecsus/blob/main/elecsus/libs/data_proc.py"
    click PA "https://github.com/durham-qlm/elecsus/blob/main/elecsus/libs/polarisation_animation_mpl.py"
    click DC "https://github.com/durham-qlm/elecsus/blob/main/elecsus/libs/durhamcolours.py"
    click PR "https://github.com/durham-qlm/elecsus/blob/main/elecsus/libs/preamble.py"
    click DOC "https://github.com/durham-qlm/elecsus/blob/main/elecsus/docs/ElecSus GUI User Guide.pdf"
    click IMG "https://github.com/durham-qlm/elecsus/tree/main/elecsus/images/"
    click FT "https://github.com/durham-qlm/elecsus/blob/main/elecsus/tests/fitting_tests.py"
    click ST "https://github.com/durham-qlm/elecsus/blob/main/elecsus/tests/spectroscopy_tests.py"
    click FF "https://github.com/durham-qlm/elecsus/blob/main/elecsus/tests/fit_fieldgradient.py"
    click RT "https://github.com/durham-qlm/elecsus/blob/main/elecsus/tests/rotondaro_tests.py"
    click SETUP "https://github.com/durham-qlm/elecsus/blob/main/setup.py"
    click MANI "https://github.com/durham-qlm/elecsus/blob/main/MANIFEST.in"
    click EGG "https://github.com/durham-qlm/elecsus/tree/main/ElecSus.egg-info/"
    click DIST "https://github.com/durham-qlm/elecsus/blob/main/dist/ElecSus-3.0.8.win-amd64.exe"

    %% Styles
    classDef ui fill:#cce5ff,stroke:#005cbf,color:#004085;
    classDef api fill:#ffe5b4,stroke:#ff8c00,color:#7f5f00;
    classDef core fill:#d4edda,stroke:#28a745,color:#155724;
    classDef res fill:#e2e3e5,stroke:#6c757d,color:#383d41;
    classDef test fill:#f8d7da,stroke:#dc3545,color:#721c24;
    classDef pack fill:#fff3cd,stroke:#ffc107,color:#856404;
```
