GSoC 2025: Toolkit for Molecular Hamiltonians

[RichRick1]

Description

Enhance the Model Hamiltonian package by implementing utilities for molecular Hamiltonians manipulation, transformation, and interfacing with quantum chemistry packages.

:books: Package Description and Impact

The Model Hamiltonian package aims to provide a comprehensive toolkit for working with molecular Hamiltonians in quantum chemistry calculations. The package will introduce utilities for Hamiltonian transformations, basis set conversions, and integration with popular quantum chemistry software. This will enable researchers to efficiently manipulate and analyze electronic structure calculations while maintaining the flexibility to work with different theoretical frameworks.

:construction_worker: What will you do?

Your main focus will be on developing utilities for molecular Hamiltonian manipulations. This includes implementing symmetrization procedures, spin-adaptation routines, basis set transformations, and interfaces with external quantum chemistry packages. The project will emphasize creating robust, well-tested APIs that seamlessly integrate with existing quantum chemistry workflows.

:checkered_flag: Expected Outcomes

1. Implement Hamiltonian symmetrization utilities to ensure correct properties of Hamiltonians in MO basis
2. Develop spin-adaptation routines for generating proper spin eigenfunctions
3. Create tools for basis set transformations (MO to AO conversion)
4. Implement mapping utilities onto geminal basis representations
5. Add support for FCIDump file format reading and writing
6. Develop interface with PySCF for seamless integration with quantum chemistry calculations
7. Write comprehensive tests and documentation for all new functionality

Required skills	Python, OOP, Linear Algebra
Preferred skills	Experience with quantum chemistry software (PySCF, Psi4), familiarity with electronic structure theory, knowledge of group theory
Project size	350 hours, Large
Difficulty	Medium to Hard 🥵

:raising_hand: Mentors

Valerii Chuiko	valerachuiko_at_gmail_dot_com	@RichRick1
Paul Ayers	ayers_at_mcmaster_dot_ca	@PaulWAyers

[mallaanirudh]

Interest in Enhancing the Model Hamiltonian Package

Hi everyone,

I'm interested in working on the Model Hamiltonian Package project for GSoC. The idea of developing utilities for molecular Hamiltonian transformations, spin-adaptation, and basis set conversions aligns well with my experience in Python, OOP, and linear algebra . I’ve also been working on a project on quantum molecular simulations , so I’m excited to explore this topic further.

Before I get started, I’d love to clarify a few things:

1. Hamiltonian Symmetrization – Are there specific symmetry constraints or group theory principles that need to be considered?
2. Basis Set Transformations – Should we support multiple quantum chemistry software formats (e.g., PySCF, Psi4, OpenMolcas), or is the focus primarily on PySCF?
3. FCIDump Integration – Is the plan to only read/write FCIDump files, or should we also provide utilities to manipulate and visualize them?

Looking forward to contributing and learning from the community! Any guidance on where to start (relevant papers, existing code structure) would be greatly appreciated.

Best,
[Anirudh Malla]

[RichRick1]

Hello Anirudh, Hello Matthew,

Thanks a lot for sharing your interest in Model Hamiltonian package. I really admire your passion and dedication :)

As for the questions:

1. We mostly looking for the correct antisymmetrization of the hamiltonian, assuming you build it from the electron repulsion integrals and one-electron integrals.
2. We mostly focus on pyscf and psi4, but it’s always good to include OpenMolcas.
3. We just need to read/write fcidump files. No need for visualization.

Considering youl background here are some sources you may find useful:

https://www.if.ufrgs.br/~magusmao/FIP10601/text10.pdf https://en.wikipedia.org/wiki/Second_quantization https://www.cs.vu.nl/~eliens/download/giamarchi-x.pdf

To gain a broader understanding of the project, you can look at the first issue on the repo. It should help you familiarize yourself with the package and demonstrate your knowledge of Model Hamiltonians. You can definitely give it a try. We consider whether a candidate actively contributed to the project during the application process.

I don’t expected participants to know Quantum Chemistry in depth, the main thing is to be comfortable with creation/annihilation operators and commutation relationships. However, understanding of one- and two- electron integrals would be beneficial.Please, let me know if you have further questions.

Best, Rick

On Mar 8, 2025, at 8:24 AM, mallaanirudh @.***> wrote:

Interest in Enhancing the Model Hamiltonian Package Hi everyone, I'm interested in working on the Model Hamiltonian Package project for GSoC. The idea of developing utilities for molecular Hamiltonian transformations, spin-adaptation, and basis set conversions aligns well with my experience in Python, OOP, and linear algebra . I’ve also been working on a project that combines NLP and quantum molecular simulations , so I’m excited to explore this topic further. Before I get started, I’d love to clarify a few things: • Hamiltonian Symmetrization – Are there specific symmetry constraints or group theory principles that need to be considered? • Basis Set Transformations – Should we support multiple quantum chemistry software formats (e.g., PySCF, Psi4, OpenMolcas), or is the focus primarily on PySCF? • FCIDump Integration – Is the plan to only read/write FCIDump files, or should we also provide utilities to manipulate and visualize them? Looking forward to contributing and learning from the community! Any guidance on where to start (relevant papers, existing code structure) would be greatly appreciated. Best, [Anirudh Malla] — Reply to this email directly, view it on GitHub, or unsubscribe. You are receiving this because you were mentioned.Message ID: @.> mallaanirudh left a comment (theochem/ModelHamiltonian#148) Interest in Enhancing the Model Hamiltonian Package Hi everyone, I'm interested in working on the Model Hamiltonian Package project for GSoC. The idea of developing utilities for molecular Hamiltonian transformations, spin-adaptation, and basis set conversions aligns well with my experience in Python, OOP, and linear algebra . I’ve also been working on a project that combines NLP and quantum molecular simulations , so I’m excited to explore this topic further. Before I get started, I’d love to clarify a few things: • Hamiltonian Symmetrization – Are there specific symmetry constraints or group theory principles that need to be considered? • Basis Set Transformations – Should we support multiple quantum chemistry software formats (e.g., PySCF, Psi4, OpenMolcas), or is the focus primarily on PySCF? • FCIDump Integration – Is the plan to only read/write FCIDump files, or should we also provide utilities to manipulate and visualize them? Looking forward to contributing and learning from the community! Any guidance on where to start (relevant papers, existing code structure) would be greatly appreciated. Best, [Anirudh Malla] — Reply to this email directly, view it on GitHub, or unsubscribe. You are receiving this because you were mentioned.Message ID: @.>

[deba-cyber]

Interested to work on Model Hamiltonian project Hello everyone,

I'm interested to work on this project. I'm a PhD in theoretical chemistry where I've numerically solved time-independent and time-dependent Scrodinger equation(wave packet dynamics) . I'm proficient in Python, OOP, C++ and Parallel computing. My github link is : github.com/deba-cyber

One specific question I have right now : Will there be any work to correlate symmetries of the model Hamiltonians and standard electronic structure Hamiltonians with specific point group symmetry for a molecule in mind.

I'd love to hear from you about how to proceed and details regarding application.

Thanks, Sincerely, Debabrata

[PaulWAyers]

@deba-cyber we haven't thought about implementing symmetries yet. In general, point-group symmetry is not enforced in the QC-Devs ecosystem, mostly because we are lazy, though my excuse is that John Pople once said that any molecule that was big enough to be interesting didn't have symmetery (this was before fullerenes and the like).

[mallaanirudh]

Question: Should we include optional parameters for symmetry enforcement in Hamiltonian symmetrization?

Hi everyone,

While implementing Hamiltonian antisymmetrization in utils.py, I also incorporated additional symmetry constraints to ensure correctness in the molecular orbital (MO) basis. These symmetries are optional, meaning users can enable them as needed. However, the core antisymmetrization of the Hamiltonian is always enforced correctly.

Symmetries Implemented:

• ✅ Antisymmetrization – Ensures correct exchange symmetry for electron repulsion integrals. (Always applied)
• ✅ Hermitian symmetry – Ensures ( H^\dagger = H ), preserving physical properties. (Optional)
• ✅ Time-reversal symmetry (TRS) – Ensures invariance under complex conjugation. (Optional)
• ✅ Point-group symmetry – Enforces spatial symmetry constraints based on the molecular system. (Optional)
• ✅ Permutation symmetry – Ensures ( (pq|rs) = (qp|sr) = (rs|pq) = (sr|qp) ). (Optional)

Would it be useful to expose these as user-selectable options in the symmetrization functions? This could provide flexibility based on different Hamiltonian construction approaches.

Looking forward to your thoughts!
Thank you for your time Best, Anirudh Malla

[PaulWAyers]

What do you think @RichRick1 ?

[RichRick1]

Hello @mallaanirudh! That looks good to me. You can leave the additional symmetries as user-specified option. It might be a good idea to implement those as separate functions and then call them inside one function when user calls the antisymmetrization.

[mallaanirudh]

Issue Summary: SparseEfficiencyWarning in generate_two_body_integral()

Error Description

While running test_Heisenberg.py, all tests pass successfully, but we still get the following warning:

SparseEfficiencyWarning: Changing the sparsity structure of a csr_matrix is expensive. lil and dok are more efficient. self._set_intXint(row, col, x.flat[0])

Efforts Made to Fix the Warning Converted csr_matrix to lil_matrix before modifications in generate_two_body_integral(). Ensured v is lil_matrix before passing it to expand_sym() and to_spatial() to avoid modifying csr_matrix directly. Added debug prints to track when csr_matrix is being modified. Verified that all test cases pass successfully, meaning the core logic works, but the warning persists.

Request for Guidance Despite these fixes, the warning still appears during test execution.

Could there be another part of the code modifying a csr_matrix directly? Is there an alternative way to handle sparse matrices more efficiently in this scenario? Any suggestions on resolving this warning would be greatly appreciated! 🙌

Screenshot of the error is attached below.

[mallaanirudh]

hello @RichRick1 @PaulWAyers Is FCI Energy Validation Required? While implementing antisymmetrization of two-electron integrals, I added a test to check if FCI energy remains unchanged after applying the transformation. However, I wanted to confirm if validating FCI energy is necessary for this implementation. Should we explicitly check for FCI invariance, or is ensuring the correct symmetry properties sufficient?

Looking forward to your input!

[PaulWAyers]

FCI validation is a good test, and feasible for very small systems. It is just one test, though; others are possible. In general, we are "testing maximalists" believing that more tests is always preferable. We can always add a slow test flag so that not all tests are run all the time.

[astrolemonmarafk]

Hi! I'm Mar ☆*: .｡. o(≧▽≦)o .｡.:*☆, a mathematics undergrad from Mexico passionate about quantum theory and particle physics.

is there a good issue or test I could start with to get familiar with the package?

I’m really interested in contributing to this project!

[PaulWAyers]

Hi @astrolemonmarafk , we are mostly suggesting that people get their feet wet with the project by writing a tutorial; that helps us (better documentation for users!) and lets you learn more about the code base. @RichRick1 may have some other ideas.

[sanskritisinghgautam]

Hello everyone, I am excited about the opportunity to contribute to this project and enhance the Model Hamiltonian package. My experience in quantum chemistry, coupled with my software development expertise, makes me a strong candidate for this role. I look forward to collaborating with the team to implement robust, well-documented, and user-friendly tools for molecular Hamiltonian manipulation and integration with quantum chemistry workflows Best Sanskriti Singh Gautam

[achalcipher]

Hey @RichRick1 ,

I hope you're doing well! My name is Achal, and I’m excited about the opportunity to contribute to QC-Devs as part of GSoC 2025. After reviewing the project’s goals and deliverables, I’m eager to bring my skills and enthusiasm to the team.

My Vision for the Project

The objectives of enhancing the Model Hamiltonian package—such as symmetrization, spin adaptation routines, basis set transformations, and PySCF integration—strongly align with my interests and expertise. I’m particularly excited about contributing to robust testing and documentation to ensure the package’s reliability and accessibility.

Questions & Collaboration

To ensure a smooth workflow, I’d love to discuss:

1. Preferred design strategies for integrating with PySCF and optimizing data flow.

2. Benchmarks or example cases that could guide implementation.

3. Key milestones and deliverables to prioritize early in the timeline.

I look forward to learning from the team and engaging in meaningful discussions about these ideas. Please let me know if there are additional resources or guidelines I should explore to deepen my understanding.

Thank you for this opportunity—I’m eager to contribute and collaborate with you all!

Best regards, Achal

[RichRick1]

Thanks to everyone who applied to this project! We got a lot of strong applications this year :) I'm gonna close this issue for now