Add two-dimensional Fermi-Hubbard model

[bartandrews]

Fixes #126

[bartandrews]

Note that as part of this addition, I have added the "initialize tunneling keys" block to fermi_hubbard_1d. This fixes the edge case where N=2 and periodic boundary conditions are set. In this case, dictionary entries will appear twice, once corresponding to the internal hopping and once corresponding to the periodic boundaries. Previously, these dictionary entries were overwritten, however now they are added, as intended. The same care needs to be taken in fermi_hubbard_2d when Nx=2 or Ny=2. Other terms in the Hamiltonian are not affected.

[kevinsung]

Note that as part of this addition, I have added the "initialize tunneling keys" block to fermi_hubbard_1d. This fixes the edge case where N=2 and periodic boundary conditions are set. In this case, dictionary entries will appear twice, once corresponding to the internal hopping and once corresponding to the periodic boundaries. Previously, these dictionary entries were overwritten, however now they are added, as intended.

If I understand correctly, you're saying that this PR fixes a bug in fermi_hubbard_1d? If so, can you please split that off into a separate PR which also adds a test case that triggers the bug (and which that PR should fix)?

[bartandrews]

Yes, that's right. I have now split that off into pull request #142, and I have reverted any changes to fermi_hubbard_1d for this PR

[bartandrews]

In the fermi_hubbard_1d case, I tested the ground-state energies for a N=4 chain because I found empirically this was the upper limit before the tests become noticeably slow, compared to your other tests. However, I have since noticed the above-mentioned edge case when N=2 with periodic boundaries, and so I have fixed this issue and added tests for that case too.

In the fermi_hubbard_2d case, the same is true. I test the ground-state energies of a 2x2 system because I find empirically that this is the upper limit before the tests become cumbersome. However, since N_x=2 and N_y=2, this is an edge case for PBCs. I find that it is too slow to test the ground-state energies for the smallest non-edge-case system (3x3). Instead, I test the terms of the edge-case (2x2) and non-edge-case (3x3) systems explicitly, and I check the ground-state energies for the edge-case (2x2) system only.

If you don't mind having tests that are slow (e.g. 60-120 seconds each), then I could add ground-state energy tests for the 3x3 system also. However, since I check the terms explicitly anyway, it may not be necessary.

[bartandrews]

I have noticed that OpenFermion has a fermi_hubbard function, which is essentially the fermi_hubbard_2d function in this PR. Should we "merge" our fermi_hubbard_1d and fermi_hubbard_2d functions/tests into a single fermi_hubbard function, as in OpenFermion?

[kevinsung]

I have noticed that OpenFermion has a fermi_hubbard function, which is essentially the fermi_hubbard_2d function in this PR. Should we "merge" our fermi_hubbard_1d and fermi_hubbard_2d functions/tests into a single fermi_hubbard function, as in OpenFermion?

Is the 2D model the most general model that people might possibly be interested in? Do people ever study the 3D model or other graphs? If so then I'd like to reserve fermi_hubbard for a potential future function that can handle more general graphs.

[bartandrews]

Is the 2D model the most general model that people might possibly be interested in? Do people ever study the 3D model or other graphs? If so then I'd like to reserve fermi_hubbard for a potential future function that can handle more general graphs.

That's true, we will probably want other 2D lattices in the future (e.g. triangular, honeycomb, kagome) and potentially also the 3D Hubbard model (although this is less common). I agree that we can reserve fermi_hubbard for this most general case.

[kevinsung]

Thanks Bart!