Google Summer of Code 2025 Project: Ab-Initio Quantum Chemistry with Rimu.jl

[lch]

Google Summer of Code 2025 Project: Ab-Initio Quantum Chemistry with Rimu.jl

This is the final report for the project Ab-Initio Quantum Chemistry with Rimu.jl in GSoC2025. This project proposes adding new features to Rimu.jl —a Julia package that implements a random integrator for many-body quantum systems—allowing it to read FCIDUMP files or directly use data from the ElemCo.jl package and construct a molecular Hamiltonian. This will provide users with the ability to obtain highly accurate data from quantum Monte Carlo simulations and exact diagonalisation for extensible models involving the electronic structure of molecules starting from readily available quantum chemistry data.

Related issue: #321

Summary

During the coding period, I implemented MolecularHamiltonian. The constructor reads the provided FCIDUMP file. A MolecularHamiltonianOperatorColumn type was implemented to represent $\hat{H} | \Psi \rangle$. Off-diagonal terms are then generated through the Base.iterate methods, utilizing the overlap integrals from the FCIDUMP file together with the Slater-Condon rules¹. This generation process is allocation-free to achieve high performance.

This project is proposed to reach following targets and most of them are now achieved and reflected in PR #327. The striked goals are planned in the Future Work.

Major Goals

• Define a MolecularHamiltonian type with suitable constructors that stores the FCIDUMP information.
• Basic functionality of AbstractHamiltonian interface.
• offdiagonals(operator_column(molecular_hamiltonian, address)) provides an iterator over all offidiagonal matrix element; the type can be used in ExactDiagonalizationProblem.
• random_offdiagonal implemented; enables FCIQMC.
• Code is fully tested, passes test_hamiltonian_interface and test_hamiltonian_structure.
• All interface functions are type stable and allocation free.
• How-to guide for MolecularHamiltonian.
• [ ] Dependency of Rimu.jl on ElemCo.jl is realised as a package extension.

Extended Goals

• [ ] Efficient heat-bath sampling.
• [ ] Selective CI filtering.

Code in Review

• Molecular Hamiltonian #327 (This is the major PR)

Code Merged

These PRs are supportive contributions that facilitate the implementation of MolecularHamiltonian.

• Fix uninitialized variable in FermiFS #347
• Fix typo in documentation for ModifiedHamiltonian #338
• Unified ModeMap Type #330

Future Work

As indicated in the Summary section, we have achieved most of the goals set for this project. The code in the branch feature/molecular-hamiltonian is now fully functional for both exact diagonalization and FCIQMC calculations. However, PR #327 still requires some improvements before it can be merged into the develop branch. One of the pending items is a major goal that was postponed due to limited time, and there are also extended goals that will require additional time to implement.

ElemCo.jl as Package Extension

ElemCo.jl is a relatively large package that requires a long time to precompile. If it becomes a dependency of Rimu.jl, importing Rimu in code would be time-consuming. During the project, we chose to depend directly on ElemCo.jl for convenience. However, this is not user-friendly for those who do not need this feature. We plan to make ElemCo.jl an optional dependency and utilize the Package Extension feature from Pkg.jl² to provide a smoother experience, finalizing PR #327. We aim to implement and test this feature in the coming weeks.

Test on Large-Scale Calculation

So far, we have verified the correctness of small-scale exact diagonalization calculations on the hydrogen (H₂) molecule. However, the situation becomes considerably more challenging for larger molecules. We have not yet tested exact diagonalization on larger systems, as such calculations require significantly greater computational resources. As the next step, we plan to perform a larger-scale exact diagonalization test on the water (H₂O) molecule to further validate the correctness of the code.

Improvements to Documentation and Tutorial

Currently, the tutorial located at scripts/Molecule-example.jl serves as a basic introduction to the usage of MolecularHamiltonian developed in this project. However, it is only a skeletal guide and lacks sufficient detail to help users get started quickly. We plan to expand and improve this tutorial, making it more comprehensive and educational, once PR #327 has been merged.

Random Off-Diagonal Terms Generation

In the proposal, we identified “Efficient heat-bath sampling” and “Selective CI filtering” as extended goals. Currently, the random_offdiagonal function implemented in PR #327 samples uniformly from all off-diagonal terms, which can be inefficient in many cases. The two extended goals will modify both the process of generating off-diagonal terms and the behavior of the random_offdiagonal function. These improvements are intended as future extensions to the project, to be pursued once PR #327 has been merged.

Code Design

Type Hierarchy

Rimu.jl provides a unified interface for different types of Hamiltonians, allowing users to implement custom Hamiltonians as long as the defined type conforms to the interface requirements³. Thus we first introduced a struct MolecularHamiltonian which implement interface AbstractHAbstractHamiltonian. The constructor utilize the ElemCo.FciDumps⁴ module to load the FCIDUMP file. And then we introduced struct MolecularHamiltonianOperatorColumn which implement interface AbstractOperatorColumn as the required type returned by operator_column.

Currently, we have implemented types as shown in the following class diagram in UML.

Sequential Generation of Off-Diagonal Terms

Exact diagonalization requires access to all off-diagonal terms. However, for molecular Hamiltonians, the Fock space is typically very large, making it impractical to store all off-diagonal terms in memory. To address this, we generate the terms on-the-fly using Julia’s iterator interface⁵.

We introduce a custom iterator type, MolecularHamiltonianOffDiagonals, on which the Base.iterate function can operate to generate both the excited states and the corresponding matrix elements. This iterator can be constructed via offdiagonals, and it encapsulates the address-related information as well as the relevant overlap integrals.

The iteration process is driven by a state object of type MolecularHamiltonianOffDiagonalsIteratorState. This object tracks how many electrons are excited in each spin channel, along with the orbitals from which electrons are annihilated and those into which they are created. It is also responsible for passing information between successive calls to Base.iterate.

The excitation type can be represented as a 2-tuple, where the first element denotes the α spin channel and the second the β spin channel. There are five effective excitation types: (0,1), (1,0), (0,2), (2,0), and (1,1). Currently, Base.iterate selects the execution path according to the excitation type and generates off-diagonal terms in the order listed above.

Originally, we planned to implement five separate sub-iterators, each corresponding to a different excitation type. These would be distinguished by parametric types⁶, allowing the outer iterator type MolecularHamiltonianOffDiagonals to delegate iteration to the appropriate sub-iterator via Julia’s multiple dispatch. This design would have been more transparent and better aligned with Julia’s idioms. However, in practice, maintaining type stability with this approach proved difficult. Our tests showed that it introduced unnecessary heap allocations and performed more slowly than the current implementation, which uses a single, type-stable execution path.

Random Generation of Off-Diagonal Terms

FCIQMC requires generating off-diagonal terms randomly in order to spawn walkers. In the current implementation, we sample these terms uniformly, meaning that each off-diagonal term has an equal probability of being chosen.

Because we already have a sequential generation of off-diagonal terms, this naturally establishes a bijection between linear indices and excited states. Since excitation information (e.g., the number of excited electrons in each spin channel) is encoded in the type MolecularHamiltonianOffDiagonalsIteratorState, a given state object can be used with Base.iterate to retrieve the corresponding matrix element.

Thus, the key problem becomes: given a linear index, which state does it correspond to? To solve this, we precompute the number of excited states in each excitation type and record them in advance. Using this information, we can first determine the excitation type from the index. Then, within the determined excitation type, we reconstruct the state information by reversing the process used during sequential generation.

As a result, we can uniformly select a random number in the range 1 : N_offdiagonal, and map it to the corresponding matrix element. This ensures that random sampling of off-diagonal terms matches the uniform distribution required by FCIQMC.

Tutorial

The tutorial for the MolecularHamiltonian type, located in scripts/Molecule-example.jl, provides examples demonstrating its use in both exact diagonalization and FCIQMC calculations.

Tests

The tests in test/molecular_hamiltonian_tests.jl include unit tests for interface, tests for internal methods and integration tests on example FCIDUMP files.

First, We run the test_hamiltonian_interface and test_hamiltonian_structure against introduced MolecularHamiltonian in Interafce Tests⁷, to ensure it statisfy the requirement to be used in Rimu.jl.

Then, we have set several tests on the key internal methods to check if it behaves as we expected.

Finally, we compared the the small scale calculations with the hydrogen (H₂) molecule against the result from standard exact diagonalization to verify the correctness of the implementation.

Acknowlegement

I would like to express my sincere appreciation to my mentors Joachim Brand(@joachimbrand), Daniel Kats(@dnkats), and Elke Pahl(@ElkePahl), for their invaluable guidance and support throughout the project. I am grateful to Matija Čufar(@mtsch) for his dedicated efforts in assisting me with debugging the code. I would also like to thank the Google and Julia communities for making this summer a truly rewarding experience.

Footnotes

1. Slater–Condon rules - Wikipedia ↩

2. 5. Creating Packages · Pkg.jl ↩

3. Custom Hamiltonians · Rimu.jl ↩

4. FCIDump files · ElemCo.jl documentation ↩

5. Interfaces · The Julia Language ↩

6. Types · The Julia Language ↩

7. Custom Hamiltonians · Rimu.jl ↩

[joachimbrand]

This is a great report, @lch . Thanks so much for your dedication to the project! I'm looking forward to seeing your PR merged in the near future and releasing the new feature to our community.