Metadata-Version: 2.4
Name: columx
Version: 2.3.0
Summary: Advanced electron optics simulation platform for TEM/STEM/SEM column design
Author: ColumX Contributors
License-Expression: MIT
Project-URL: Homepage, https://github.com/allen-li1231/ColumX
Project-URL: Documentation, https://github.com/allen-li1231/ColumX#readme
Project-URL: Issues, https://github.com/allen-li1231/ColumX/issues
Keywords: electron-optics,transmission-electron-microscopy,TEM,STEM,aberration,multislice,glaser-lens,paraxial,simulation
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.24.0
Requires-Dist: scipy>=1.10.0
Provides-Extra: gui
Requires-Dist: PySide6>=6.5; extra == "gui"
Provides-Extra: api
Requires-Dist: fastapi>=0.104.0; extra == "api"
Requires-Dist: uvicorn[standard]>=0.24.0; extra == "api"
Requires-Dist: pydantic>=2.0.0; extra == "api"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Provides-Extra: all
Requires-Dist: columx[api,dev,gui]; extra == "all"
Dynamic: license-file

# ColumX

**Advanced Electron Optics Simulation Platform for TEM/STEM/SEM Column Design**

ColumX is a comprehensive Python library for electron optics simulation, covering paraxial ray tracing, aberration calculation, wave optics, multislice propagation, crystal potentials, and full TEM/STEM column modeling. It is designed for researchers and engineers working on electron microscope column design, beam physics analysis, and image simulation.

## Features

ColumX provides 20 physics modules organized into four layers:

**Ray Optics** — `paraxial`, `ray3d`, `glaser`, `aberration`, `electrostatic_paraxial`
Magnetic and electrostatic lens modeling with Glaser analytical fields, adaptive-power Seidel aberration integrals (Cs < 0.04%, Cc < 0.02% vs MEBS), 5th-order aberration framework (C5, S5, Krivanek naming), and 3D relativistic Lorentz ray tracing.

**Wave Optics** — `wave`, `multislice`, `crystal`
Contrast transfer function with spatial/temporal coherence envelopes, STEM probe formation, FFT-based multislice propagation engine, and crystal structure module with Kirkland scattering factors for 7 built-in crystal presets (Si, Ge, GaAs, SiC, MgO, Al, Au).

**Advanced Imaging** — `stem`, `cbed`, `eels`, `hrtem`, `dpc`
STEM imaging chain (probe, annular detectors BF/ADF/HAADF, Z-contrast), convergent beam electron diffraction with HOLZ lines, EELS spectrum simulation with thickness measurement, HRTEM imaging (WPOA linear and multislice nonlinear), and differential phase contrast with electric/magnetic field reconstruction.

**Column & Infrastructure** — `column`, `lens_cascade`, `multipole`, `source`, `deflection`, `coulomb`, `fem2d`, `field`, `instruments`, `constants`
Full TEM column simulator, multi-lens cascade with Conrady aberration propagation, multipole elements, electron gun models (thermionic/field emission/Schottky), scanning deflection, space charge and Boersch effect, 2D FEM field solver, and instrument presets (Titan, Themis, ARM200F, ARM300F2).

## Installation

```bash
# Core library
pip install columx

# With GUI (PySide6)
pip install "columx[gui]"

# With web API (FastAPI)
pip install "columx[api]"

# Everything
pip install "columx[all]"
```

### From Source

```bash
git clone https://github.com/allen-li1231/ColumX.git
cd ColumX
pip install -e ".[all]"
```

## Quick Start

### Glaser Lens

```python
from columx import GlaserLens

lens = GlaserLens(V=200e3, B0=0.5, a=3e-3, z0=-30e-3, zf=60e-3)
print(f"Focal length: {lens.analytical_efl()*1e3:.2f} mm")
print(f"Magnification: {lens.analytical_magnification():.3f}")
print(lens.summary())
```

### CTF and Probe

```python
from columx import ContrastTransferFunction, STEMProbe

ctf = ContrastTransferFunction(V=200e3, Cs=1.2e-3, Cc=1.2e-3, defocus=-50e-9)
print(f"Scherzer resolution: {ctf.scherzer_resolution()*1e10:.2f} A")

probe = STEMProbe(V=200e3, Cs=1e-3, alpha=10e-3)
print(f"Probe FWHM: {probe.probe_size()*1e10:.2f} A")
```

### Multislice Simulation

```python
from columx import MultisliceEngine
from columx.multislice import phase_grating_potential
import numpy as np

V = np.stack([phase_grating_potential(
    nx=128, ny=128, Lx=5e-9, Ly=5e-9,
    period=1e-9, amplitude=10.0
)] * 20)

engine = MultisliceEngine(V=200e3, nx=128, ny=128, Lx=5e-9, Ly=5e-9, dz=0.5e-9)
psi_exit = engine.run(V)
dp = engine.diffraction_pattern(psi_exit)
```

### Crystal Potential

```python
from columx import CrystalStructure, projected_potential

si = CrystalStructure.from_preset("Si")
V_proj, info = projected_potential(si, nx=256)
print(f"MIP: {info['MIP_V']:.1f} V")
```

## Web API

Start the REST API server:

```bash
python run_web.py
# → http://127.0.0.1:8000 (interactive frontend)
# → http://127.0.0.1:8000/docs (OpenAPI documentation)
```

Endpoints: `POST /api/glaser/compute`, `POST /api/wave/ctf`, `POST /api/wave/probe`, `POST /api/multislice/simulate`, `POST /api/crystal/potential`, `POST /api/stem/probe`.

## Desktop GUI

Launch the PySide6 desktop application with 20 interactive panels:

```bash
python gui/columx_gui.py
```

## Testing

```bash
cd tests
python test_all.py        # Core modules (13 modules)
python test_new_physics.py # v2.0+ modules
python test_crystal_stem.py # Crystal + STEM + CBED + EELS + HRTEM + DPC
```

269 tests covering all 20 modules.

## Architecture

```
columx/
├── columx/           # 20 physics modules (13,000+ lines)
├── api/              # FastAPI REST API layer
├── web/              # Vue3 + Plotly.js frontend
├── gui/              # PySide6 desktop GUI (20 panels)
├── tests/            # 269 tests across 8 test files
└── docs/             # Architecture documentation
```

## Validation

ColumX has been systematically validated against MEBS (Munro's Electron Beam Software):

- **Paraxial**: M and theta accuracy 0.006%
- **Aberrations**: Cs < 0.04%, Cc < 0.02% (200 kV, objective lens)
- **5th order**: C5 verified against Krivanek analytical values
- **MEBS compatibility**: `match_mebs=True` mode replicates MEBS mixed relativistic convention

## References

1. Glaser, W. *Grundlagen der Elektronenoptik* (Springer, 1952)
2. Hawkes, P.W. & Kasper, E. *Principles of Electron Optics* (Academic Press, 1989)
3. Reimer, L. *Transmission Electron Microscopy* 5th ed. (Springer, 2013)
4. Krivanek, O.L. et al. *Ultramicroscopy* 110 (2010) 571-585
5. Kirkland, E.J. *Advanced Computing in Electron Microscopy* 2nd ed. (Springer, 2010)

## License

MIT License. See [LICENSE](LICENSE).
