Metadata-Version: 2.4
Name: kshell-utilities
Version: 3.0.0.3
Summary: Handy utilities for handling nuclear shell model calculations from KSHELL
Author: Johannes Heines
Author-email: Jon Kristian Dahl <jonkd@uio.no>
License-Expression: MIT
Project-URL: Homepage, https://github.com/GaffaSnobb/kshell-utilities
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: MacOS
Classifier: Operating System :: Unix
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: matplotlib
Requires-Dist: numba
Requires-Dist: numpy
Requires-Dist: scipy
Requires-Dist: seaborn
Requires-Dist: tqdm
Requires-Dist: vum
Provides-Extra: test
Requires-Dist: build; extra == "test"
Requires-Dist: mypy; extra == "test"
Requires-Dist: pytest; extra == "test"
Requires-Dist: pytest-cov; extra == "test"
Requires-Dist: ruff; extra == "test"
Requires-Dist: twine; extra == "test"
Dynamic: license-file

# kshell-utilities
Handy utilities for processing nuclear shell model data from `KSHELL`. Se the [KSHELL repository](https://github.com/GaffaSnobb/kshell) for installation and usage instructions for `KSHELL`.

## Installation
Install from the PyPi repository
``` bash
pip install kshell-utilities
```
Or, for the very latest version, clone this repository to your downloads directory. cd to the root directory of this repository and run
```
pip install .
```

## Usage
Please see the *How to use the output from KSHELL* section of the Wiki in the `KSHELL` repository for an introduction on how to use `kshell-utilities`: https://github.com/GaffaSnobb/kshell/wiki/How-to-use-the-output-from-KSHELL

## Runtime cache
`load_kshell_output(..., load_and_save_to_file=...)` controls the NumPy cache used for faster re-runs:

- `False`: recalculate from source files and do not write cache files.
- `True`: load a current valid cache when available; otherwise recalculate and save a new cache.
- `"overwrite"`: recalculate from source files and replace cache files.

Cache files are written under `tmp/` by default. Set `KSHELL_UTILITIES_CACHE_DIR` to use another directory. Cache entries include schema/package metadata and source-file fingerprints; stale, unversioned, corrupt, or object-array caches are ignored and regenerated instead of being loaded.

Derived OBTD arrays are cached for repeated plotting workflows. `obtd_heatmap`, `plot_obtd_contribution_vs_b_decay`, and `m1_ls_interference_angle` save their computed x/y or matrix data, and warm cache hits can render without materializing OBTD arrays. `modified_m1_gsf_from_obtd(..., make_heatmap=False)` also checks its modified-transition cache before loading OBTD data.

For workflows that need the cached heatmap arrays but not the figure rendering, use `obtd_heatmap(..., plot=False, return_data=True)`. For faster rendered heatmaps where per-cell labels are not needed, use `annot=False`.

Use `list_cache_entries()`, `cache_size()`, and `clear_cache()` to inspect and clear cache files. A loaded `ReadKshellOutput` instance also exposes `cache_entries()`, `cache_size()`, `clear_cache()`, and `clear_derived_cache()` scoped to that output.

## OBTD loading
Directory loads use `load_obtd="lazy"` by default. Levels and transition data are loaded immediately, while one-body transition density files are loaded only if OBTD data is requested, for example through `obtd_heatmap`, `m1_ls_interference_angle`, `plot_obtd_contribution_vs_b_decay`, `modified_m1_gsf_from_obtd`, or direct `obtd_dict` access.

OBTD methods that first select transitions, such as `obtd_heatmap`, `m1_ls_interference_angle`, and `plot_obtd_contribution_vs_b_decay`, load only the OBTD master arrays needed for those selected transitions. Direct `obtd_dict` access still loads the full OBTD dictionary for compatibility.

Use `load_obtd=True` to load OBTDs during `load_kshell_output(...)`, or `load_obtd=False` to prevent automatic OBTD loading for memory-constrained non-OBTD workflows.

## Deprecated aliases
Older names such as `loadtxt`, `B_distribution`, `level_density_heatmap`, `brink_axel_j`, `primary_matrix`, `mixing_ratio`, `obtd_B_plot`, `obtd_modifier`, `interference_angle`, `com`, `check_data`, `level_table`, `nld_savetxt`, `help`, and `parameters` are still available as compatibility aliases, but they emit `DeprecationWarning`. Prefer the clearer names in new code.

## Profiling
`tools/profile_pipeline.py` runs representative pipeline timings. Add `--memory` to report current and peak traced allocations with `tracemalloc`, including cases for lazy directory loads, GSF-only workflows with OBTDs present, narrow OBTD heatmaps, full `obtd_dict` materialization, and warm derived OBTD caches.

Example:

```bash
python tools/profile_pipeline.py --iterations 1 --memory --case gsf_only_directory_with_obtd --case obtd_heatmap_narrow_warm_cache
```

## Plot display
Plotting helpers should avoid implicit interactive display where possible. Newer plotting APIs use `show=False` by default and return matplotlib figure/axes objects so callers can decide whether to display, save, or close figures.

## Testing
The test suite is being built against the latest stable Python 3.14 series.

Install the package with test dependencies:
``` bash
pip install -e ".[test]"
```

Run the test suite:
``` bash
python -m pytest
```

Run with coverage:
``` bash
python -m pytest --cov
```

See `TESTING.md` for the current baseline and known xfailed regressions.

## Credits
KSHELL is created by Noritaka Shimizu https://arxiv.org/abs/1310.5431. Code in this repository is built upon tools created by Jørgen Eriksson Midtbø: https://github.com/jorgenem/kshell_public.
