Metadata-Version: 2.5
Name: grasp-atomic-kit
Version: 3.4.1
Summary: Stable data I/O, processing, and plotting for GRASP calculations
Project-URL: Homepage, https://github.com/YenochQin/graspkit
Project-URL: Source, https://github.com/YenochQin/graspkit
Project-URL: Issues, https://github.com/YenochQin/graspkit/issues
Author-email: "Yi (Yenoch) Qin" <yenochqin@hotmail.com>
License-Expression: GPL-3.0-only
License-File: LICENSE
Keywords: GRASP,atomic physics,data processing,plotting
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.14
Requires-Dist: cycler>=0.12.1
Requires-Dist: matplotlib>=3.10.8
Requires-Dist: numpy>=2.4.2
Requires-Dist: polars>=1.38.1
Requires-Dist: rich>=14.3.3
Requires-Dist: rtoml>=0.13.0
Provides-Extra: all
Requires-Dist: basedpyright>=1.34.0; extra == 'all'
Requires-Dist: build>=1.4.0; extra == 'all'
Requires-Dist: ipykernel>=7.2.0; extra == 'all'
Requires-Dist: ipython>=9.10.0; extra == 'all'
Requires-Dist: jupyter>=1.1.1; extra == 'all'
Requires-Dist: jupyterlab>=4.5.4; extra == 'all'
Requires-Dist: notebook>=7.5.3; extra == 'all'
Requires-Dist: pytest>=9.0.2; extra == 'all'
Requires-Dist: ruff>=0.15.1; extra == 'all'
Requires-Dist: twine>=6.2.0; extra == 'all'
Provides-Extra: dev
Requires-Dist: basedpyright>=1.34.0; extra == 'dev'
Requires-Dist: build>=1.4.0; extra == 'dev'
Requires-Dist: ipykernel>=7.2.0; extra == 'dev'
Requires-Dist: ipython>=9.10.0; extra == 'dev'
Requires-Dist: jupyter>=1.1.1; extra == 'dev'
Requires-Dist: jupyterlab>=4.5.4; extra == 'dev'
Requires-Dist: notebook>=7.5.3; extra == 'dev'
Requires-Dist: pytest>=9.0.2; extra == 'dev'
Requires-Dist: ruff>=0.15.1; extra == 'dev'
Requires-Dist: twine>=6.2.0; extra == 'dev'
Description-Content-Type: text/markdown

# graspkit

English | [简体中文](README_zh.md)

`graspkit` is the stable foundation for reading, processing, and plotting
GRASP atomic-structure calculation results. Machine-learning workflow code is
owned by the sibling `graspkit-tools` repository.

## Package structure

- `graspkit.data_IO`: typed GRASP text/binary loaders and stable CSF writers.
- `graspkit.grasp_data_extractor`: ASF, level, composition, transition, and
  mixing-coefficient post-processing.
- `graspkit.CSFs_processor`: CSF parsing, descriptors, and deterministic
  selection helpers.
- `graspkit.utils`: shared GRASP data models, environment detection, and
  quantum-number helpers.
- `graspkit_plot`: plotting and publication-style helpers.

The package deliberately does not contain ML models, training configuration,
or iterative pipeline state. Those live under
`graspkit-tools/ml_CSFs_selection_scripts/ml_csf_choosing/`.

## Installation

The distribution name is `grasp-atomic-kit`; the Python imports remain
`graspkit` and `graspkit_plot`. Python 3.14 or newer is required.
From a source checkout:

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

When developing in the full workspace, use the environment owned by
`graspkit-tools`; it installs this repository as an editable dependency.

## Imports

```python
from graspkit.data_IO import EnergyFileLoader, MixCoefLoader
from graspkit.grasp_data_extractor import format_energy_configurations
from graspkit.CSFs_processor import select_csf_indices_by_ci_squared_cutoff
from graspkit_plot import configure_matplotlib_for_publication
```

## Windows terminal encoding

On Windows terminals that use a legacy code page, Rich output from loaders
such as `MixCoefLoader` may raise `UnicodeEncodeError` when printing scientific
labels such as `cm⁻¹`. Run Python in UTF-8 mode:

```powershell
python -X utf8 your_script.py
```

For a one-line loader check:

```powershell
python -X utf8 -c "from graspkit.data_IO import MixCoefLoader; MixCoefLoader(r'path\to\file.m').load()"
```

This option changes terminal text encoding only; it does not change how GRASP
files are parsed.

## Development

In the full workspace, activate the shared environment first:

```bash
source ../graspkit-tools/.venv/bin/activate
pytest tests/
ruff check .
basedpyright src/
python -m build
```

See [INSTALL.md](INSTALL.md) for installation details.

## Release preparation

See [the release guide](docs/releasing.md) for local wheel/source builds and
artifact validation. Once published on PyPI, the installation command is
`python -m pip install grasp-atomic-kit`.

## License

GNU GPL version 3 (`GPL-3.0-only`). See [LICENSE](LICENSE).
