kshell-utilities 3.0.0.3

Handy utilities for handling nuclear shell model calculations from KSHELL

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

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:

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.