How durham-qlm/elecsus works
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/