Metadata-Version: 2.4
Name: slater-orbital
Version: 0.3
Summary: Slater-type orbital slice visualizer with effective nuclear charge
Project-URL: Homepage, https://github.com/zhuangl/slater-orbital
Project-URL: Repository, https://github.com/zhuangl/slater-orbital
Project-URL: Issues, https://github.com/zhuangl/slater-orbital/issues
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: numpy>=1.24
Requires-Dist: scipy>=1.10
Requires-Dist: matplotlib>=3.7
Provides-Extra: dev
Requires-Dist: pytest>=7.4; extra == "dev"

# slater-orbital

`slater-orbital` is a Python package with CLI and Tkinter GUI for visualizing
2D orbital slices. It keeps the plotting experience close to the
`H-orbital` program while replacing the right panel with multi-electron
Slater-type orbital (STO) models based on effective nuclear charge.

Project version: `0.3`

## Scientific basis

The program provides **three effective-charge models**, based on **four key
papers**:

1. `slater_rules`: classical Slater shielding model.
2. `clementi1963`: SCF STO exponents from Clementi-Raimondi (1963), extended by
   Clementi-Raimondi-Reinhardt (1967); internal conversion uses `Zeff = n * xi`.
3. `guerra2017`: tabulated relativistic Dirac-Fock effective charges.

Wavefunction form:

\[
\psi(r,\theta,\phi)=R_{\mathrm{STO}}(r; n,\zeta)\,Y_l^m(\theta,\phi),
\quad \zeta=\frac{Z_{\mathrm{eff}}}{n}
\]

## Model coverage in GUI

- `slater_rules`: `Z = 2..36`
- `clementi1963`: `Z = 2..86`
- `guerra2017`: `Z = 2..118`

When `clementi1963` is used for ions (`charge != 0`), the code applies an ion
correction using the Slater-model `delta Zeff`.

## Features

- CLI rendering modes: `density`, `real`, `imag`, `radial_distribution`
- Slice controls: `--plane`, `--value`, `--range`, `--points`
- Effective-charge controls: `--element`, `--electrons`, `--model`, `--zeta`
- Radial comparison mode: `--compare-electrons 1,2,8,...`
- GUI side-by-side comparison:
  - left panel fixed to analytic hydrogen
  - right panel selectable element/charge/model
  - auto-refresh on parameter changes

## Installation

```bash
python -m pip install -e .
```

Development install:

```bash
python -m pip install -e '.[dev]'
```

## Quick start

CLI:

```bash
# O atom (neutral), 2p(m=0) real-part slice
slater-orbital 2 1 0 --element 8 --electrons 8 --mode real --plane z --value 0

# Compare radial profile during filling
slater-orbital 2 0 0 --element 8 --mode radial_distribution --compare-electrons 1,2,4,6,8

# Use Guerra model
slater-orbital 2 1 0 --element 8 --electrons 8 --model guerra2017 --mode real
```

GUI:

```bash
slater-orbital-ui
```

## Test

```bash
python -m pytest
```

## Code layout

- `slater_orbital/analytic.py`: STO and hydrogen analytic wavefunctions
- `slater_orbital/slater.py`: Zeff model dispatcher and Clementi ion correction
- `slater_orbital/clementi_data.py`: Clementi 1963/1967 exponent tables
- `slater_orbital/guerra_data.py`: Guerra 2017 Zeff tables
- `slater_orbital/cli.py`: command-line plotting entrypoint
- `slater_orbital/gui.py`: side-by-side GUI application
- `slater_orbital/plotting.py`: Matplotlib rendering helpers
- `slater_orbital/slicing.py`: plane grid and spherical transform helpers
- `slater_orbital/modes.py`: complex field mode mapping
- `slater_orbital/auto_settings.py`: automatic extent/plane selection
- `slater_orbital/electron_config.py`: aufbau occupation helpers
- `slater_orbital/quantum_numbers.py`: quantum number parsing and validation
- `slater-orbital`, `slater-orbital-ui`: launcher scripts

Detailed file-level notes: `docs/FILES.md`

## GitHub and PyPI release checklist (v0.3)

```bash
# 1) clean env and install build tools
python -m pip install --upgrade build twine

# 2) run tests
python -m pytest

# 3) build distributions
python -m build

# 4) verify package metadata
python -m twine check dist/*

# 5) upload to PyPI (or TestPyPI first)
python -m twine upload dist/*
```

For GitHub release:

1. Create tag `v0.3`
2. Push tag and release notes
3. Attach source/wheel artifacts from `dist/` if desired

## References

1. Slater, J. C. (1930). *Atomic Shielding Constants*. Phys. Rev. 36, 57-64.
2. Clementi, E.; Raimondi, D. L. (1963). *Atomic Screening Constants from SCF
   Functions*. J. Chem. Phys. 38, 2686-2689.
3. Clementi, E.; Raimondi, D. L.; Reinhardt, W. P. (1967). *Atomic Screening
   Constants from SCF Functions. II*. J. Chem. Phys. 47, 1300-1307.
4. Guerra, M.; Gaudreau, P.; et al. (2017). *Relativistic atomic screening
   constants from Dirac-Fock calculations*. At. Data Nucl. Data Tables 117-118.
