CERES: Complex-Energy Reduced-basis Emulator for continuum States

This repository contains the source code and notebooks for the papers:

• A non-Hermitian quantum mechanics approach for extracting and emulating continuum physics based on bound-state-like calculations (Phys. Rev. Lett., to be published, arXiv:2408.03309)
• ...: detailed description (Phys. Rev. C, to be published, arXiv:2411.06712)

CERES is a Python-based framework for developing and testing emulators for the continuum states of finite quantum systems (e.g., atomic nuclei, atoms). It is based on the Reduced Basis Method (also known as Eigenvector Continuation).

The core novelty of this work is the use of the complex-energy plane as part of the emulation space. This allows for the analytical continuation of continuum physics observables (such as scattering amplitudes and response functions) from numerically simpler bound-state-like calculations. Moreover, it enables, in principle, rapid emulation of the analytical continuation in the space of other real-valued input parameters.

Directory Structure

• src/: Contains all the core Python source code (.py) and the Fortran module (.f). This includes the direct solvers, the emulator classes, potential definitions, and etc. This directory is treated as an installable package.
• Two_Body/: Contains the Jupyter notebooks (.ipynb) used to generate the figures and results for the two-body system calculations presented in the papers.
• Three_Body/: This directory is a placeholder for the notebooks related to the three-body system. These will be added in a future update.

Project Status & Reproducibility

This repository is actively being developed to support the results presented in the companion papers.

• Two-Body System: The code and Jupyter notebooks for all two-body calculations are complete and available in the Two_Body/ directory.
• Three-Body System: The core src code for the three-body calculations and the Jupyter notebooks required to reproduce the specific results from the publications are currently being refactored and will be made public in a future update. In the meantime, researchers interested in reproducing the three-body results can contact the author directly.

Installation and Setup

To get started with this project, clone the repository and set up the Conda environment.

1. Clone the Repository

git clone https://github.com/buqeye/CERES.git
cd CERES

2. Create and Activate the Conda Environment

This project's dependencies are managed in the environment.yml file. This single command will create a new Conda environment named ceres-env with all the necessary Python packages and the Fortran compiler.

conda env create -f environment.yml
conda activate ceres-env

3. Compile the Fortran Code

The Fortran R-matrix module needs to be compiled into a Python-callable library.

From the CERES root directory, run:

cd src
python -m numpy.f2py -c -m rmatrix_f2py rmatrix_f2py.f -llapack
cd ..

This will create a compiled module (rmatrix_f2py.so or similar) inside the src directory.

4. Install the Project in Editable Mode

This final, crucial step makes your src directory importable as a package from anywhere within the project (e.g., from your notebooks), so that your from src imports ... work correctly.

From the CERES root directory, run:

pip install -e .

You are now ready to run the notebooks.

Usage

After completing the installation, launch Jupyter Lab to run the experiments:

jupyter lab

Navigate to the Two_Body/ directory to access the completed notebooks.

It is recommended to follow the following exploration order: Scattering_by_Fixing_V_Emulating_in_Erel_E.ipynb -> Spectrum_by_Fixing_V_Erel_Emulating_in_E.ipynb -> SpectrumAndScattering_by_Emulating_in_Erel_E_V.ipynb. The first studies emulation in $(E_{rel}, E)$, the second in $(E)$, and the 3rd in $(E_{rel}, E, \mathrm{parameters\ of}V)$.

Acknowledgements

• The R-matrix calculation code, src/rmatrix_f2py.f, is based on R-matrix package documented at Computer Physics Communications 200 (2016) 199–219, by P. Descouvemont. The original package itself can be downloaded from http://cpc.cs.qub.ac.uk/summaries/AEYP_v1_0.html. For details on the method, please refer to the original publication. Moreover, the package have been modified here so that we can apply f2py to wrap the F90 code rmatrix_f2py.f (the instructions are provided above).
• AI on Google Search (powered by the Gemini family of models) was used to help with adding and improving the code comments.

Citation

If you use this code in your research, please cite the following publications.

Letter: arXiv:2408.03309

@article{Zhang:2024ril,
author = "Zhang, Xilin",
title = "{A non-Hermitian quantum mechanics approach for extracting and emulating continuum physics based on bound-state-like calculations}",
eprint = "2408.03309",
archivePrefix = "arXiv",
primaryClass = "nucl-th",
month = "8",
year = "2024"
}

Companion Paper: arXiv:2411.06712

@article{Zhang:2024gac,
author = "Zhang, Xilin",
title = "{A non-Hermitian quantum mechanics approach for extracting and emulating continuum physics based on bound-state-like calculations: detailed descriptions}",
eprint = "2411.06712",
archivePrefix = "arXiv",
primaryClass = "nucl-th",
month = "11",
year = "2024"
}

Contact

Xilin Zhang ([email protected])

Facility for Rare Isotope Beams

Michigan State University

East Lansing, MI 48824, USA