kshell-utilities

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

Installation

Install from PyPI:

pip install kshell-utilities

Or, for the latest development version, clone this repository and run from the repository root:

pip install .

Usage

Please see the How to use the output from KSHELL section of the Wiki in the KSHELL repository for a broader introduction: https://github.com/GaffaSnobb/kshell/wiki/How-to-use-the-output-from-KSHELL

Archive KSHELL Runs

After installation, the archive-kshell-run command can slim completed KSHELL energy logs and pack run outputs into compressed tar.zst archives:

archive-kshell-run --pack-directory /path/to/run --archive-prefix my_run --delete-after-verify

Archive outputs are split into level logs, transition logs, OBTD groups, and input/job metadata. By default, archive verification checks the member list. Use --verify content to additionally compare archive contents with tar -df.

Minimal example:

import kshell_utilities as ksutil

kshell = ksutil.load_kshell_output(
    "path/to/summary_or_kshell_directory",
    load_and_save_to_file=True,
)

bins, gsf, n_transitions, included_transitions = kshell.gsf(
    bin_width=0.2,
    Ex_min=0,
    Ex_max=10,
    multipolarity="M1",
    plot=False,
)

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.

entries = ksutil.list_cache_entries(derived_only=True)
total_mb = ksutil.cache_size(derived_only=True)/(1024**2)
would_remove = ksutil.clear_cache(derived_only=True, dry_run=True)

kshell.clear_derived_cache(dry_run=True)
kshell.clear_derived_cache(kinds="obtd_heatmap")

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.

kshell = ksutil.load_kshell_output("kshell_run/", load_obtd="lazy")
assert not kshell.obtd_loaded

heatmap_data = kshell.obtd_heatmap(
    E_gamma_min=0,
    E_gamma_max=10,
    multipolarity="M1",
    gsf_bin_width=0.2,
    gsf_Ex_min=0,
    gsf_Ex_max=10,
    plot=False,
    return_data=True,
)

M1 operator changes

Use change_m1_operator when changing magnetic-operator coefficients without excluding or modifying OBTD matrix elements:

bins, gsf, n_transitions, included = kshell.change_m1_operator(
    gl_p=1.0,
    gl_n=0.0,
    gs_p=5.5857,
    gs_n=-3.8261,
    quenching_factor=0.75,
    gsf_bin_width=0.2,
    gsf_Ex_min=0,
    gsf_Ex_max=10,
)

Use modified_m1_gsf_from_obtd when the workflow intentionally excludes or modifies OBTD contributions before recalculating M1 strength.

Renamed plotting and analysis APIs

Prefer the clearer names introduced in 3.0.0.3:

• load_kshell_output instead of loadtxt
• b_value_distribution instead of B_distribution
• level_density_j_heatmap instead of level_density_heatmap
• plot_brink_axel_by_j instead of brink_axel_j
• primary_b_matrix instead of primary_matrix
• e2_m1_mixing_ratio instead of mixing_ratio
• plot_obtd_contribution_vs_b_decay instead of obtd_B_plot
• modified_m1_gsf_from_obtd instead of obtd_modifier
• m1_ls_interference_angle instead of interference_angle
• center_of_mass_plot instead of com

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 targets the latest stable Python 3.14 series while keeping the declared package compatibility floor at Python 3.11.

Install the package with test dependencies:

pip install -e ".[test]"

Run the test suite:

python -m pytest -q

Run with coverage:

python -m pytest --cov=kshell_utilities --cov-report=term-missing -q

See TESTING.md for the current baseline and release verification commands.

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.