kshell-utilities

Handy utilities for processing nuclear shell model data from KSHELL. Se the KSHELL repository for installation and usage instructions for KSHELL.

Installation

Install from the PyPi repository

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

loadtxt(..., 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, obtd_B_plot, and interference_angle save their computed x/y or matrix data, and warm cache hits can render without materializing OBTD arrays. obtd_modifier(..., 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.

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, interference_angle, obtd_B_plot, obtd_modifier, or direct obtd_dict access.

OBTD methods that first select transitions, such as obtd_heatmap, interference_angle, and obtd_B_plot, 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 loadtxt(...), or load_obtd=False to prevent automatic OBTD loading for memory-constrained non-OBTD workflows.

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:

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:

pip install -e ".[test]"

Run the test suite:

python -m pytest

Run with coverage:

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.