Efficient, automated resonance detection using the Stabilization Method.

ReSMax is a Python tool for identifying resonance states in quantum few-body systems, such as helium-like atoms, using the Stabilization Method. This technique analyzes how energy eigenvalues evolve with a systematically varied basis set parameter, revealing metastable bound states as well as resonance states, which appear as characteristic plateaus in the eigenvalue spectrum.

ReSMax automates the full workflow: it computes the density of states (DOS) for each root, segments and fits DOS peaks using Lorentzian profiles, groups them into resonances, and extracts resonance parameters (energy and width) from the best-fitting DOS peaks — all with minimal manual input. Results can be interactively inspected and refined via plots and command-line controls, allowing for careful manual validation.

The tool is designed for reproducibility and efficient large-scale analysis of stabilization data, helping researchers extract physical resonance parameters quickly and consistently.

• Automated resonance detection from stabilization diagrams with minimal user input.
• Supports multiple input formats (.dat, .dal, .ou).
• Interactive command-line interface for manual resonance refinement.
• Fast processing: Handles large datasets in seconds.
• Outputs
  • Stabilization diagram plots,
  • Global DOS vs. energy panorama plots,
  • Summary table of detected resonances and their fitted parameters,
  • DOS peak & Lorentzian fit plots.

If you use ReSMax in your research, please cite the following article (currently in preparation):

Johanna Langner, Anjan Sadhukhan, Henryk A. Witek, and Jayanta K. Saha.
An Algorithm for Automated Extraction of Resonance Parameters from the Stabilization Method.
Manuscript in preparation, 2025.
https://github.com/giogina/ReSMax

Download citation files here:

• BibTeX
• RIS

• Installation
• Input File Formats
• Program Workflow
  • Run ReSMax
  • Stabilization Diagram and Threshold Inputs
  • DOS Peak Fitting and Resonance Detection
  • Manual Resonance Refinement
  • Output Files
• License

• Python version: 3.10+
• Supported OS: Linux, macOS, and Windows 10+.

Follow these steps to install and run ReSMax on your system.

Before running ReSMax, you need:

• Python 3.10+
• pip (Python package installer)
• venv (Python virtual environment module)
• git (to clone the repository)

Instructions vary by operating system:

    sudo apt update
    sudo apt install python3 python3-pip python3-venv git

    /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

   brew install python git

Windows users may download the Windows executable.

Otherwise, clone the ReSMax repository from GitHub and navigate into the project directory:

    git clone https://github.com/giogina/ReSMax.git

This downloads the latest version of ReSMax locally.

    cd ReSMax/
    pip install -r requirements.txt

resmax.exe -f path\to\input_file.dat

resmax.exe -f input_file.dat

   py path/to/resmax.py -f path/to/input_file.dat

   python path/to/resmax.py -f path/to/input_file.dat

    path/to/resmax.py -f path/to/input_file.dat

   chmod +x resmax.py

    resmax.py -f path/to/input_file.dat

    export PATH="$PATH:/path/to/resmax"

    source ~/.bashrc   # or ~/.bash_profile or ~/.zshrc, depending on your shell

ReSMax accepts input files containing the diagonalized eigenroot spectrum for a range of values of the basis set parameter $\gamma$. The parser supports three file formats, which are identified automatically by their file extensions:

gamma_1    E_1_root1    E_1_root2    ...    E_1_rootN
gamma_2    E_2_root1    E_2_root2    ...    E_2_rootN
...
gamma_M    E_M_root1    E_M_root2    ...    E_M_rootN

gamma_1
E_1_root1
E_1_root2
...
E_1_rootN

gamma_2
E_2_root1
E_2_root2
...
E_2_rootN

gamma_1    gamma_2    ...    gamma_M

# Energies for Root 1
E_1_root1  E_2_root1  ...    E_M_root1

# Energies for Root 2
E_1_root2  E_2_root2  ...    E_M_root2

If an unsupported extension is provided, ReSMax will raise an error and list the accepted formats.

Follow these instructions to run ReSMax and interpret its outputs. In the following, the workflow is demonstrated on the input file he_1Po_InfMass.dal, which can be found in the example/ directory of this repository.

All output files are written to a directory of the same name as the input file, in our case he_1Po_InfMass/. Therefore, it is recommended to first move the input file to a convenient location before running ReSMax.

After loading and parsing a valid input file, a stabilization diagram is displayed:

Then, ReSMax enters the first interactive stage:

Here, the ionization threshold of the investigated few-body system can be entered in two different ways: Either by inputting the nuclear charge Z of a helium-like atom, which causes the thresholds to be computed as -Z^2/n^2/2 for n ranging from 1 to 20, or by directly entering a list of thresholds. By default, the ionization thresholds for the helium atom (Z=2) are used.

The panorama plot is a scatter plot of log10(DOS) over the entire energy range for all roots, with each root colored separately:

This plot gives a clear visual representation of the resonance energies in the form of accumulative peaks, which also makes it clear which peaks are reliable (i.e., clusters of clearly separated higher DOS values), and which are not (in noisy regions below the thresholds).

Selecting the r command triggers the automatic detection of resonances, which takes about 2 seconds.

The automatic analysis of the stabilization diagram begins by listing the metastable bound states (MBS), which are detected as local energy minima below the lowest populated ionization threshold. The MBS are listed together with the value of the basis set parameter $\gamma$ at which they appear. If the minimum appears very close to either end of the $\gamma$ range, a warning is issued; these MBS can likely be improved by widening the investigated range of $\gamma$ in the underlying stabilization diagram computation. The printed MBS are also listed in the results.txt file.

The DOS curves for each root are now automatically sectioned into individual peaks, which are then fitted to Lorentzian curves, and classified into resonances. The result is shown graphically, for each ionization threshold, in form of a stabilization diagram in which the plateaus corresponding to each DOS peak are highlighted, and colored according to their respective resonance.

Each plateau is given a label of the form iRj, where i specifies the resonance number, and j the root number. On the right side of the plot, an accumulative scatter plot diplays $\log_{10}(\text{DOS})$ on the horizontal axis vs. the energy on the vertical axis. This gives additional confirmation as to how well the roots stabilize along each resonance.

In some cases, the algorithm for automatic selection of best-fitting peaks for each resonance makes a wrong choice. For example, in the plot above, the plateau selected for the resonance number 7 is clearly not a very appropriate one. In such situations, manual refinemens can be made via an interactive loop:

To address the issue observed in our example case, we can first plot a zoomed-in version of the overview stabilization diagram by entering:

plot -0.55 -0.52

which results in

Several observations can be made in this plot: Firstly, some of the plateaus are annotated in red. These are sections in which the energy descends with growing $\gamma$, making it impossible to fit the DOS to a Lorentzian peak. This can happen either if the basis set is insufficiently sized to accurately describe this resonance state, or when one encounters fluorescence-active resonance states, as is likely the case e.g. for resonance states 7 and 8 here. ReSMax generally chooses fittable DOS peaks to represent resonances, if any are available. Therefore, even though the section annotated by 7R19 can barely be counted as a plateau, it is selected for resonance 7, rather than any of the descending sections observed for roots 25-27. The DOS scatter plot on the right side confirms the presence of very closely spaced resonance states around E=-0.546 and E=-0.527, but the complete absense of any resonance at E=-0.529 (where resonance 7 is currently being placed).

This can be fixed by selecting a different plateau to represent resonance 7, such as the one formed by root 25. To select it, simply enter

7R25

This immediately triggers the creation of a new plot with the adjusted peak selection:

Note that resonance 7 is now being correctly identified. Its energy, just like the one of resonance 8, is displayed in red on the right side, to signify that a descending section is chosen as its representative.

We may now verify whether the correct section has been chosen for other resonances, say, resonance 5. This can be achieved by entering

grid 5

to obtain a grid plot of DOS vs. energy data points vs. their corresponding Lorentizan fits for all roots forming a plateau at this resonance:

In the top-left panel of this grid, all DOS points are displayed together, to show any drift in the maxima, as well as the relative heights of the DOS values. We can see here that most roots form Lorentzian-like peaks in the same position; jsut the data points from root 25 (cyan) have their maximum values in a different location and fail to form a fittable shape. This is due to the descending nature of the plateau formed by root 25. As all other plateaus correspond to well-behaving DOS peaks, which are fitted well by a Lorentzian curve, we can conclude that the correct one (root 23, green) has been selected.

Closer to each threshold, the resonance states become both more densely packed, and more difficult to describe by any given basis set. This is reflected in the stabilization diagram overview by a more noisy DOS scatter plot on the right sight, where the energy curves on the left side become wavy rather than properly stabilized:

Most of the descending sections in the upper part of this plot are spurious, and should not be registered as resonances. We can easily de-select all resonances starting from number 15 by entering

15+R

to obtain

After being satisfied with all selections for this threshold, we can proceed to the next one by typing

ok

Now, just as before, the stabilization diagram overview between the thresholds at E=-0.5 and E=-0.22222 is shown:

This area is much noisier, with more wrongly detected resonance states. From the inspection of the right-side scatter plot, it becomes quickly apparent that resonance 48 is entirely spurious; and resonances 51 and up are likely unreliable. We deactivate these resonances by

48R 51+R

and obtain

This verification process opens a large amount of images; to close all of them, the image viewer process can be terminated by entering close. (Note that this only works if the process was started by ReSMax.)

The loop over the thresholds can be terminated by typing end. This makes sense to do if the presently shown energy range already no longer contains good resonances. No resonances from higher, un-inspected thresholds will be listed in the results.

Upon completion, ReSMax generates and opens a results.txt file listing all detected MBS and resonances, grouped by thresholds:

This file lists, for each resonance $r$, the energy $E_r$, Lorentzian fit parameters (Width $\Gamma$, area $A$, offset $y_0$), as well as measures for the fit quality - as sum of squared restudies (SSR), and as relative SSR per point defined by $$\chi_{r} = \frac{\sqrt{SSR}}{N \cdot \rho_{\text{max}}^2}.$$ Additionally, the value of the basis set parameter $\gamma$ at which the chosen DOS peak's maximum occurs is given.

The resonance information is tab-separated, so that it can be copy&pasted into Excel or any other spreadsheet software.

Additionally, plots of the chosen DOS peaks for each resonance, together with their Lorentzian fits, can be generated:

By inputting p or pn, these plots are generated for all thresholds or the $n^\text{th}$ threshold, respectively. The plot .png files are stored in the directory {file_name}/resonance_plots/{threshold_energy}/. In our example, the fitted DOS peak for the lowest detected resonance can, after selecting p1, be found under he_1Po_InfMass/resonance_plots/-0.50000/[1]-0.69313909.png:

Additionally, for each plotted DOS peak, a .txt file of the same name is created, in which the energy and DOS arrays for the DOS data points as well as the fitted Lorentzian curve are given. Using this data, the plot shown above can be re-created in any data visualizer of choice.

ReSMax is released under the MIT License.
You are free to use, modify, and distribute this software with proper attribution.