How to customize a block?

[Tarcomn]

Hi developers,

I'm interested in modeling a system similar to the shell model in nuclear physics. It comprises spinless fermions, where each orbital can be either empty or occupied. Also, the orbital has definite quantum number of angular momentum (l,m), and the total angular momentum J^2, J_z are conserved.
But I found none of the built-in blocks (Electron, Spin, tJ) fit my purpose.

So I may need to define a new block, perhaps called ShellFermion. Just like defining a custom SiteType in ITensor.

I've taken a look at the source code, specifically XDiag.jl/src/blocks/electron.jl, and I understand that the Julia struct is essentially a wrapper for an underlying C++ implementation (e.g., cxx_Electron). This suggests that properly defining a new block requires work at both the C++ and Julia levels.

Could you please provide a brief roadmap or summary of the key steps involved in this process? I'm trying to understand:

C++ Implementation: Which C++ base classes would a new block need to inherit from? What are the essential virtual methods that must be implemented (e.g., for generating the basis states, handling symmetries, etc.)?
Julia Wrapper: What are the necessary steps to expose the C++ block to Julia, following the pattern seen in electron.jl? This would presumably involve defining the struct, constructors, and methods that call the C++ backend.

Any guidance, high-level overview, or pointers to relevant parts of the source code would be extremely helpful for me.

[awietek]

Dear @Tarcomn,

thank you very much for your interest in XDiag. Your application sounds interesting and it would indeed be very nice to have a new spinless fermion class in XDiag. Overall, I do not think this requires entirely new implementations, but one needs to understand how the code is structured. I will explain this a bit more in detail now.

Two key concepts in XDiag are blocks and bases. A block is a subspace of a full Hilbert space with certain quantum numbers (e.g. particle number of momentum). Blocks are represented by Block objects, like Spinhalf of Electron. To have a new kind of Hilbert space one would have to add a new type called maybe Fermion.

Blocks are lightweigt objects which can be easily copied. Every block contains a shared pointer to a basis, which is the actual data structure that implements the computation of matrix elements. These basis objects are hidden from the user but can be chosen at runtime, if different basis codings are desired. Writing a new basis class would be the main task when creating a new kind of Hilbert space. You can see all kinds of bases in the folder https://github.com/awietek/xdiag/tree/main/xdiag/basis

For example, the basis implementation for spin 1/2 particles with spatial symmetries and Sz conservation can be found here: https://github.com/awietek/xdiag/blob/main/xdiag/basis/spinhalf/basis_symmetric_sz.cpp. These files create the basis, i.e. they store the computational basis configurations. Beyond just computing the basis, one has to implement matrix element generation of a given operator OpSum. This is typically done in the subfolder apply, e.g. here: https://github.com/awietek/xdiag/tree/main/xdiag/basis/spinhalf/apply

There is for example this file https://github.com/awietek/xdiag/blob/main/xdiag/basis/spinhalf/apply/apply_terms.hpp which is called whenever we apply an operator to a vector or create a full matrix. This file branches out into implementations for different terms.

So the key things to implement are the new basis and the apply functions. To make this all work, one needs to tell the code then at the right places about the new block. Overall, I think it should not be too difficult for an external person to add a new block, but I am definitely willing to help in the process. If you think you want to go down this road, we can definitely discuss this in more detail. I hope this high-level overview gives you a good impression.

Best,
Alex

[Tarcomn]

Thank you very much for the clear explanation and guidance.

Given my current time constraints and project priorities, I unfortunately don’t have the capacity to contribute to XDiag’s development at this stage. I’ve decided to proceed using existing software packages that natively support spinless fermions for my ongoing work. But I am sure your answer will be helpful for others with similar interests. I may also reach out in the future if my work aligns more closely with contributing.

Thanks again for your time and support.