Skip to content

Density Fitting HamiltonianContainer#335

Open
rainli323 wants to merge 77 commits intomainfrom
feature/RL/DensityFittingHamiltonian
Open

Density Fitting HamiltonianContainer#335
rainli323 wants to merge 77 commits intomainfrom
feature/RL/DensityFittingHamiltonian

Conversation

@rainli323
Copy link
Copy Markdown
Contributor

@rainli323 rainli323 commented Jan 22, 2026

Density fitted hamiltonian is provided for post SCF calculations.

  • Data Side: A new type of Hamiltonian Container DensityFittedHamiltonianContainer is created for density fitted Hamiltonian in the MO space. The three center integrals are stored in memory, and unless get_two_body_integrals() are called, the 4 center integrals are never calculated or stored. If a user wants to obtain the three-center integrals, Hamiltonian.get_container().get_three_center_integrals() must be called, otherwise Hamiltonian.get_container().get_two_body_integrals() and Hamiltonian.get_two_body_integrals() will give the constructed 4 center integrals. The 3 center integrals are stored in a matrix of size n_aux * n_geminal, where n_geminal is n_orb * n_orb, and n_aux is the number of auxiliary basis functions.
  • Algorithm side: A new class microsoft::DensityFittedHamiltonianConstructor is created as a derived class of algorithm::HamiltonanConstructor. It can be created by HamiltonianConstructorFactory, then upon run() creates Hamiltonian corresponding to DensityFittedHamiltonianContainer. The run() function requires orbital and auxiliary basis set as parameters. The run() function does not break the API for other Hamiltonian Constructors.
  • Test: ctest for various Hamiltonian Containers (data) are done with TEST_P, which runs the same tests for each container. The integrated test for constructing the DF Hamiltonian is DFMP2, where normal MP2 used integrals reconstructed from DF Hamiltonian to obtain correlation energy, and the result is compared with Psi4.

rainli323 and others added 28 commits December 16, 2025 21:56
@github-actions
Copy link
Copy Markdown

github-actions bot commented Jan 22, 2026

📊 Coverage Summary

Component Coverage
C++ Library 78%
Python Package 87%
Pybind11 Bindings 89%

Detailed Coverage Reports

C++ Coverage Details
------------------------------------------------------------------------------
                           GCC Code Coverage Report
Directory: cpp
------------------------------------------------------------------------------
File                                       Lines    Exec  Cover   Missing
------------------------------------------------------------------------------
include/qdk/chemistry/algorithms/active_space.hpp
                                               5       5   100%
include/qdk/chemistry/algorithms/algorithm.hpp
                                              60      55    91%   187,209,211-212,270
include/qdk/chemistry/algorithms/dynamical_correlation_calculator.hpp
                                               7       6    85%   115
include/qdk/chemistry/algorithms/hamiltonian.hpp
                                               7       7   100%
include/qdk/chemistry/algorithms/localization.hpp
                                               5       5   100%
include/qdk/chemistry/algorithms/mc.hpp       18      18   100%
include/qdk/chemistry/algorithms/mcscf.hpp
                                               6       6   100%
include/qdk/chemistry/algorithms/pmc.hpp       9       8    88%   186
include/qdk/chemistry/algorithms/scf.hpp      13      12    92%   23
include/qdk/chemistry/algorithms/stability.hpp
                                               5       4    80%   131
include/qdk/chemistry/data/ansatz.hpp          3       3   100%
include/qdk/chemistry/data/basis_set.hpp      35      30    85%   108-109,112,114,319
include/qdk/chemistry/data/configuration.hpp
                                              32      30    93%   71,119
include/qdk/chemistry/data/configuration_set.hpp
                                               3       2    66%   35
include/qdk/chemistry/data/data_class.hpp
                                               4       4   100%
include/qdk/chemistry/data/element_data.hpp
                                              18      18   100%
include/qdk/chemistry/data/hamiltonian.hpp
                                              12      12   100%
include/qdk/chemistry/data/hamiltonian_containers/canonical_four_center.hpp
                                               1       1   100%
include/qdk/chemistry/data/hamiltonian_containers/cholesky.hpp
                                               1       1   100%
include/qdk/chemistry/data/hamiltonian_containers/density_fitted.hpp
                                               1       1   100%
include/qdk/chemistry/data/hamiltonian_containers/sparse.hpp
                                               1       1   100%
include/qdk/chemistry/data/lattice_graph.hpp
                                               3       1    33%   324-325
include/qdk/chemistry/data/orbitals.hpp        6       6   100%
include/qdk/chemistry/data/pauli_operator.hpp
                                              88      83    94%   1203,1227,1262,1274,1288
include/qdk/chemistry/data/settings.hpp       90      68    75%   180-181,311,353,488,857,864,866,881-882,886-888,892-893,895-897,899-900,989,993
include/qdk/chemistry/data/stability_result.hpp
                                              38      38   100%
include/qdk/chemistry/data/structure.hpp       8       8   100%
include/qdk/chemistry/data/wavefunction.hpp
                                              25      19    76%   496,502,510-512,673
include/qdk/chemistry/data/wavefunction_containers/cas.hpp
                                               1       1   100%
include/qdk/chemistry/data/wavefunction_containers/cc.hpp
                                               1       1   100%
include/qdk/chemistry/data/wavefunction_containers/mp2.hpp
                                               1       1   100%
include/qdk/chemistry/data/wavefunction_containers/sci.hpp
                                               1       1   100%
include/qdk/chemistry/data/wavefunction_containers/sd.hpp
                                               1       1   100%
include/qdk/chemistry/utils/hash.hpp           4       4   100%
include/qdk/chemistry/utils/logger.hpp        41      35    85%   223-224,226,233-234,236
include/qdk/chemistry/utils/model_hamiltonians.hpp
                                             128     122    95%   59-60,89-90,143,147
include/qdk/chemistry/utils/string_utils.hpp
                                              11      10    90%   41
src/qdk/chemistry/algorithms/active_space.cpp
                                             232     142    61%   35-36,40-41,45-46,116-118,143-145,147,151-154,156-159,162-163,165-168,173-174,176-179,182-184,187-189,191,194-196,218,220,224,226-229,231-232,236-239,241,243,246-249,251,253,255-256,277-278,307,310,342,347-348,350-353,355-357,359-360,363,367,369-371,413,415,417
src/qdk/chemistry/algorithms/dynamical_correlation_calculator.cpp
                                               8       8   100%
src/qdk/chemistry/algorithms/hamiltonian.cpp
                                              20      19    95%   43
src/qdk/chemistry/algorithms/localization.cpp
                                              15      15   100%
src/qdk/chemistry/algorithms/mc.cpp           11      11   100%
src/qdk/chemistry/algorithms/microsoft/active_space/autocas_active_space.cpp
                                              80      78    97%   103,133
src/qdk/chemistry/algorithms/microsoft/active_space/autocas_active_space.hpp
                                              16      16   100%
src/qdk/chemistry/algorithms/microsoft/active_space/entropy_active_space.cpp
                                              45      45   100%
src/qdk/chemistry/algorithms/microsoft/active_space/entropy_active_space.hpp
                                              10      10   100%
src/qdk/chemistry/algorithms/microsoft/active_space/occupation_active_space.cpp
                                              60      54    90%   46,48,81,83,101-102
src/qdk/chemistry/algorithms/microsoft/active_space/occupation_active_space.hpp
                                               6       6   100%
src/qdk/chemistry/algorithms/microsoft/active_space/valence_active_space.cpp
                                              75      63    84%   34,36,68-69,76-77,104-105,120-121,124-125
src/qdk/chemistry/algorithms/microsoft/active_space/valence_active_space.hpp
                                               9       9   100%
src/qdk/chemistry/algorithms/microsoft/cholesky_hamiltonian.cpp
                                             394     365    92%   99,103,421,438,440,457,460-461,475,483,485-487,638,640,652,657,671,678,743,748-749,751-752,858,864-865,868-869
src/qdk/chemistry/algorithms/microsoft/cholesky_hamiltonian.hpp
                                              13      13   100%
src/qdk/chemistry/algorithms/microsoft/density_fitted_hamiltonian.cpp
                                             239     152    63%   75,77,88-89,102-103,125,128-129,143,151,153-155,189-190,200-201,263,265,276,289,317-318,353,362-364,371-373,380-383,386-388,390,392-393,398-400,402,404-405,410,412-419,421-424,427-432,435-436,438-440,442-443,446,449-450,452-457,461-462,464-466
src/qdk/chemistry/algorithms/microsoft/density_fitted_hamiltonian.hpp
                                               8       8   100%
src/qdk/chemistry/algorithms/microsoft/hamiltonian.cpp
                                             227     215    94%   40,42,59-60,119-120,247,249,260,272,334,442
src/qdk/chemistry/algorithms/microsoft/hamiltonian.hpp
                                              10      10   100%
src/qdk/chemistry/algorithms/microsoft/hamiltonian_util.cpp
                                              78      62    79%   47-48,54-56,63-64,98,101-102,121,131,134-135,164-165
src/qdk/chemistry/algorithms/microsoft/localization/iterative_localizer_base.cpp
                                               5       5   100%
src/qdk/chemistry/algorithms/microsoft/localization/iterative_localizer_base.hpp
                                               8       8   100%
src/qdk/chemistry/algorithms/microsoft/localization/mp2_natural_orbitals.cpp
                                              79      74    93%   44,81,83,104,106
src/qdk/chemistry/algorithms/microsoft/localization/mp2_natural_orbitals.hpp
                                               3       3   100%
src/qdk/chemistry/algorithms/microsoft/localization/pipek_mezey.cpp
                                             169     160    94%   26,34,41,43,47,49,246,329,332
src/qdk/chemistry/algorithms/microsoft/localization/pipek_mezey.hpp
                                               6       6   100%
src/qdk/chemistry/algorithms/microsoft/localization/vvhv.cpp
                                             646     575    89%   336,338-339,452-453,476,534,695,739,741,746,762-765,768,778-781,784,819-821,827-831,859-862,865,887,889-891,968-972,1018-1022,1040-1043,1047-1050,1052-1054,1057,1131,1194-1196,1267,1286,1289,1293,1295,1300-1301
src/qdk/chemistry/algorithms/microsoft/localization/vvhv.hpp
                                               6       6   100%
src/qdk/chemistry/algorithms/microsoft/macis_asci.cpp
                                              69      66    95%   51,167,169
src/qdk/chemistry/algorithms/microsoft/macis_asci.hpp
                                              61      61   100%
src/qdk/chemistry/algorithms/microsoft/macis_base.cpp
                                              74      58    78%   29-31,41,46,98-99,102,106-107,110-112,119-121
src/qdk/chemistry/algorithms/microsoft/macis_base.hpp
                                              93      71    76%   66,68,70,72,74,76,187-189,191,194,196,199-201,203-205,207-209,211
src/qdk/chemistry/algorithms/microsoft/macis_cas.cpp
                                              45      42    93%   47,109,111
src/qdk/chemistry/algorithms/microsoft/macis_cas.hpp
                                               3       3   100%
src/qdk/chemistry/algorithms/microsoft/macis_pmc.cpp
                                              82      80    97%   114,153
src/qdk/chemistry/algorithms/microsoft/macis_pmc.hpp
                                              16      16   100%
src/qdk/chemistry/algorithms/microsoft/mp2.cpp
                                             204     186    91%   33,78,82-83,93-94,97,101-102,149-150,153-154,164-165,168,172-173
src/qdk/chemistry/algorithms/microsoft/mp2.hpp
                                               2       2   100%
src/qdk/chemistry/algorithms/microsoft/scf.cpp
                                             269     252    93%   101-102,132-133,141,143,197,244,313,345,350,352,378-380,399,470
src/qdk/chemistry/algorithms/microsoft/scf.hpp
                                              19      19   100%
src/qdk/chemistry/algorithms/microsoft/scf/include/qdk/chemistry/scf/core/basis_set.h
                                               9       8    88%   134
src/qdk/chemistry/algorithms/microsoft/scf/include/qdk/chemistry/scf/core/enums.h
                                              16       0     0%   38-39,48-49,54-59,70-75
src/qdk/chemistry/algorithms/microsoft/scf/include/qdk/chemistry/scf/core/eri.h
                                              15      12    80%   46-47,49
src/qdk/chemistry/algorithms/microsoft/scf/include/qdk/chemistry/scf/core/exc.h
                                               3       3   100%
src/qdk/chemistry/algorithms/microsoft/scf/include/qdk/chemistry/scf/core/moeri.h
                                               3       3   100%
src/qdk/chemistry/algorithms/microsoft/scf/include/qdk/chemistry/scf/core/molecule.h
                                               1       1   100%
src/qdk/chemistry/algorithms/microsoft/scf/include/qdk/chemistry/scf/eri/eri_multiplexer.h
                                               6       3    50%   126-127,135
src/qdk/chemistry/algorithms/microsoft/scf/include/qdk/chemistry/scf/util/cache.h
                                              27      26    96%   44
src/qdk/chemistry/algorithms/microsoft/scf/include/qdk/chemistry/scf/util/class_registry.h
                                              13      13   100%
src/qdk/chemistry/algorithms/microsoft/scf/include/qdk/chemistry/scf/util/gauxc_registry.h
                                               6       5    83%   39
src/qdk/chemistry/algorithms/microsoft/scf/include/qdk/chemistry/scf/util/gauxc_util.h
                                              21      21   100%
src/qdk/chemistry/algorithms/microsoft/scf/include/qdk/chemistry/scf/util/int1e.h
                                               2       2   100%
src/qdk/chemistry/algorithms/microsoft/scf/include/qdk/chemistry/scf/util/singleton.h
                                              13      13   100%
src/qdk/chemistry/algorithms/microsoft/scf/src/core/basis_set.cpp
                                             361     279    77%   33-34,92-93,97-98,146,150-154,157-161,172,183-184,188,190-191,197-198,201-206,210,212-215,217,219,223,225-226,228-229,231,248,257,265-266,313-314,335,337,342-343,345-346,348,401,406-407,415,436,458,460-461,463-465,478,480,482-485,487,490,493-494,542,544,548-549
src/qdk/chemistry/algorithms/microsoft/scf/src/core/scf.cpp
                                               7       7   100%
src/qdk/chemistry/algorithms/microsoft/scf/src/eri/eri.cpp
                                              36      29    80%   58-60,65-66,89-90
src/qdk/chemistry/algorithms/microsoft/scf/src/eri/eri_df_base.cpp
                                              34      32    94%   29-30
src/qdk/chemistry/algorithms/microsoft/scf/src/eri/eri_df_base.h
                                               2       2   100%
src/qdk/chemistry/algorithms/microsoft/scf/src/eri/eri_multiplexer.cpp
                                              61      37    60%   16-17,26-29,40,46-49,52-55,79,81,83-85,87-88,91,93
src/qdk/chemistry/algorithms/microsoft/scf/src/eri/INCORE/incore.cpp
                                              42      29    69%   40,42,44,66,68,70-72,74-75,77-79
src/qdk/chemistry/algorithms/microsoft/scf/src/eri/INCORE/incore_impl.cpp
                                              96      88    91%   44,136,138,235,237,239,287,289
src/qdk/chemistry/algorithms/microsoft/scf/src/eri/INCORE/incore_impl_df.cpp
                                             102      60    58%   86-87,89,203,205,207-214,216-221,224,227-233,236,253,256,263-264,286,291,305-306,309,320-321,323-324,326
src/qdk/chemistry/algorithms/microsoft/scf/src/eri/LIBINT2_DIRECT/libint2_direct.cpp
                                             182     169    92%   268,606,608,610,908,910-913,916,918-920
src/qdk/chemistry/algorithms/microsoft/scf/src/eri/moeri.cpp
                                              36      34    94%   32-33
src/qdk/chemistry/algorithms/microsoft/scf/src/eri/schwarz.cpp
                                              33      13    39%   80-81,83-88,90-93,95-98,101-102,104,106
src/qdk/chemistry/algorithms/microsoft/scf/src/eri/SNK/snk.cpp
                                              66       0     0%   36,58-60,62-65,67,69-70,72,98,100,102-104,107-110,114-116,119-121,124-127,146,148,150,167-168,170,187,191,193-194,200-201,203,205-207,209,212,214,216-218,221,223,225-227,230,232,234-235,239-240,242-243
src/qdk/chemistry/algorithms/microsoft/scf/src/exc/exc.cpp
                                              16      14    87%   42-43
src/qdk/chemistry/algorithms/microsoft/scf/src/exc/GauXC/gauxc.cpp
                                              34      25    73%   42,46-47,50-52,54,56,67
src/qdk/chemistry/algorithms/microsoft/scf/src/exc/GauXC/gauxc_impl.cpp
                                             229     163    71%   79,119,160-161,249-258,260,262-270,352-353,360-364,366,368-377,380-381,383-384,387-389,396,398-399,405-409,411,413-417,419-420,426
src/qdk/chemistry/algorithms/microsoft/scf/src/scf/cpscf.cpp
                                             234     232    99%   232,237
src/qdk/chemistry/algorithms/microsoft/scf/src/scf/guess.cpp
                                              63      63   100%
src/qdk/chemistry/algorithms/microsoft/scf/src/scf/ks_impl.cpp
                                              81      63    77%   73,75-82,140,155-158,160-161,171-172
src/qdk/chemistry/algorithms/microsoft/scf/src/scf/scf_impl.cpp
                                             547     414    75%   73,101,116,122,168-169,185-186,329-330,339-342,467,471,551,588,607-609,676,715-716,720-721,730-735,745,749-752,754-761,774-778,780-783,785-786,793-794,796-801,803-808,810,818-821,831-832,843-845,859-864,867-870,873,876,878,977-979,982,984,988-989,991-995,997-1000,1002-1003,1007,1009,1011-1019,1022-1025,1028-1030,1032,1034,1053,1055
src/qdk/chemistry/algorithms/microsoft/scf/src/scf/scf_impl.h
                                              21      16    76%   98-100,113,161
src/qdk/chemistry/algorithms/microsoft/scf/src/scf/scf_solver.cpp
                                              82      54    65%   35,37,51,55-59,66,68,90,92-93,101-103,111-113,126-128,131-133,141-143
src/qdk/chemistry/algorithms/microsoft/scf/src/scf/soad.cpp
                                              15       0     0%   189,192-204,208
src/qdk/chemistry/algorithms/microsoft/scf/src/scf_algorithm/asahf.cpp
                                             286     275    96%   49,51,68-69,101,271,464-465,506,530-531
src/qdk/chemistry/algorithms/microsoft/scf/src/scf_algorithm/diis.cpp
                                             278     259    93%   147,149,158-159,228,234,241,246,268-269,286,486-489,511,520,528,536
src/qdk/chemistry/algorithms/microsoft/scf/src/scf_algorithm/diis_gdm.cpp
                                              36      36   100%
src/qdk/chemistry/algorithms/microsoft/scf/src/scf_algorithm/gdm.cpp
                                             401     366    91%   226,249,272,443-446,449-452,478-482,487,518-522,664,667-673,805,809,899,903,905
src/qdk/chemistry/algorithms/microsoft/scf/src/scf_algorithm/line_search.h
                                              63      62    98%   60
src/qdk/chemistry/algorithms/microsoft/scf/src/scf_algorithm/scf_algorithm.cpp
                                             143     130    90%   63,71-73,75,85-88,175-176,205,264
src/qdk/chemistry/algorithms/microsoft/scf/src/util/gauxc_util.cpp
                                              85      20    23%   26-31,34-43,48-49,52-59,63-66,68,70,72-74,81-88,92-99,106-111,115-118,122-123,134-135
src/qdk/chemistry/algorithms/microsoft/scf/src/util/int1e.cpp
                                             336     226    67%   206-209,211,243,288,290-296,298-303,305-311,314-315,326,328-329,569,592,622,699,702-703,705,713,755,757-758,762-771,780,782-783,787-796,805,807-808,812-824,826-829,838,941-942,946-954,956-962,964-967,976
src/qdk/chemistry/algorithms/microsoft/scf/src/util/libint2_util.cpp
                                             181      91    50%   39,42-45,47,49-51,53-54,58-60,64-66,72,74,76-79,81-82,85-91,94-95,97-102,104-107,109-119,125-126,477,483-490,492-495,497,499,503-504,506,560,562,566-569,571-573,576,580-582,584,627
src/qdk/chemistry/algorithms/microsoft/scf/src/util/matrix_exp.cpp
                                              53      53   100%
src/qdk/chemistry/algorithms/microsoft/scf/src/util/mpi_vars.h
                                               2       2   100%
src/qdk/chemistry/algorithms/microsoft/scf/src/util/opt/gmresxx/arnoldi/arnoldi.h
                                              12      12   100%
src/qdk/chemistry/algorithms/microsoft/scf/src/util/opt/gmresxx/arnoldi/arnoldi_gmres.h
                                             202     168    83%   53-55,176,183,185-188,190-194,196,198,202,205,209,212,217-218,221,223,290,293-294,298,481-482,493,522-523,589
src/qdk/chemistry/algorithms/microsoft/scf/src/util/opt/gmresxx/linalg.h
                                              40      40   100%
src/qdk/chemistry/algorithms/microsoft/scf/src/util/timer.h
                                              29      29   100%
src/qdk/chemistry/algorithms/microsoft/stability.cpp
                                             317     294    92%   191-192,321-323,411,413,430,433-442,446,448,452,454,493
src/qdk/chemistry/algorithms/microsoft/stability.hpp
                                              13      13   100%
src/qdk/chemistry/algorithms/microsoft/utils.cpp
                                             248     171    69%   45-46,52,54,111-112,123-124,126-127,133,135,138-139,141,143-147,150-151,182,184,186,190-191,195,198-205,207-209,211,214-218,220-225,227-229,231,234-235,237,240-245,251,253-255,258-262,387-388,427,429
src/qdk/chemistry/algorithms/pmc.cpp           8       8   100%
src/qdk/chemistry/algorithms/scf.cpp           7       7   100%
src/qdk/chemistry/algorithms/stability.cpp
                                               6       6   100%
src/qdk/chemistry/data/ansatz.cpp            553     380    68%   26,36,39,46-48,50-51,53,55-56,58-60,62,69,84,99,104-105,107-108,115,120,122,148,150,207,209,280,295,297,302-303,336-340,345,347,357,359,362,364,374,376,379,381,394,396,401,403-404,410,412,417,419-420,434,436,441,443-444,449,451,456,458-459,461-462,464,468-469,471-472,474-475,477-478,480-484,486-487,489,492,495-500,502-503,506-508,510,513,515-516,549,559,569,579,601,608,612,626,630-631,641,651-652,659,668,684-687,690-691,694-696,698-699,701-703,719,727,744-747,782-783,792-793,804,812-813,824,835-836,843,852,869-872,875-876,879-881,883-884,886-888,894-895,906-907,931-934
src/qdk/chemistry/data/basis_set.cpp        1438    1250    86%   31,38,70,91-92,221,225,259-260,276-277,326-327,341,361,387,402,433,460,493,506-507,513-514,529-530,545-546,565,568-569,615,618-620,648,651-653,719,761,785,814,845,881,914,936,966,1006,1023,1032,1050,1067,1079,1090,1180-1181,1235,1249,1262,1276,1291,1298,1308,1310,1317,1331-1332,1465,1522-1523,1537-1539,1541-1542,1548-1551,1560-1561,1727,1791-1792,1805-1806,1906,1914,1926,1962-1966,1968-1970,1973-1977,2010,2024-2028,2031-2040,2042-2045,2047-2051,2053-2055,2058-2061,2065-2066,2068,2070-2074,2077-2078,2082-2086,2090-2092,2098-2101,2103-2105,2108,2110,2112,2132-2133,2142-2143,2151-2153,2160-2161,2181-2182,2184,2201-2203,2268-2269,2271-2276,2282,2390
src/qdk/chemistry/data/configuration.cpp     279     171    61%   67,167,170,172-173,176-177,179-180,183-184,186,190,194-195,204,210,236-238,266-268,271-272,274-283,285,287,289-292,294-295,297,299-300,302-304,307-308,310-311,313,315-316,318-325,327,329,331-334,336-337,341-342,344-348,351-352,354-355,358-359,361-368,370-371,373-381,421-422,432,434
src/qdk/chemistry/data/configuration_set.cpp
                                             328     209    63%   33-34,85-87,90-92,234,247,272-277,287-288,331-333,350-354,356,376-377,400-402,421,425,427,429,431-434,436-437,439,441-442,444-447,450-451,453-455,458-463,465-466,468-478,480,482,484-487,489-490,494-495,497-501,503,506-508,510-514,517-524,526-527,529-540
src/qdk/chemistry/data/filename_utils.hpp
                                              44      26    59%   30-33,35-36,51-53,72-75,77-78,93-95
src/qdk/chemistry/data/hamiltonian.cpp       553     413    74%   43,48-49,70,75-76,84,101,106,115-117,134,142,196-197,215-219,234-238,243,245,251,253,260,262-265,271,273-276,302-315,317,320-321,324-327,329-332,335-338,340-343,347-350,352-355,358-362,364-367,369-372,374-377,380-381,387,404,413-414,433,436-437,451,463,466,471,474,575,588,600,613,626,639,646,665,683,690,697,704-706,712,723-724,744-745,761-762,770-771,796-800
src/qdk/chemistry/data/hamiltonian_containers/canonical_four_center.cpp
                                             420     360    85%   38-39,67-68,98,110,128-129,156,163,169-171,204-205,213,276,309,349,353,361,373,385,391-392,423,432,437-438,443-444,462,470,477-484,487-494,514-516,597-598,607-608,634,656,721-722
src/qdk/chemistry/data/hamiltonian_containers/cholesky.cpp
                                             243     201    82%   98,102,110,122,134,140-141,172,181,186-187,192-193,211,219,235-242,245-252,272-274,302-303,312-313,339,361,432-433
src/qdk/chemistry/data/hamiltonian_containers/density_fitted.cpp
                                             443     384    86%   40-41,66-67,96,158,169,196-197,214,221,227-229,266-267,327,362,402,406,414,426,442-443,464,473,478,480,484-485,502,510,517-524,527-534,553-555,634-635,644-645,671,693,754-755
src/qdk/chemistry/data/hamiltonian_containers/sparse.cpp
                                             393     338    86%   89,103,153-155,212,232-235,260-263,364-366,398,435-441,443,471-479,481,484,487-488,494-497,506-507,512,568-569,573-574,577-578,598,607,622
src/qdk/chemistry/data/hdf5_error_handling.hpp
                                              10       3    30%   20-21,23,25-26,28-29
src/qdk/chemistry/data/hdf5_serialization.cpp
                                             240     119    49%   13,15-22,24,26-32,34,36-44,46,48-56,65-67,69-71,73-74,77-79,82-85,95,98,106-109,111-113,115-116,119-121,124-127,138,141,143-150,153-160,238-240,249-251,253-255,258-260,277-280,282-286,288-289,308-310,312-316,318-319
src/qdk/chemistry/data/json_serialization.cpp
                                             177      86    48%   29,38,45-47,57,64-68,70-71,83,90-92,94-98,100,102-103,105,114,120-121,128-129,131,133-134,136-139,141,143-146,148-149,152-153,155,163-164,173,178-179,188-189,196,201,210,212,214,216-217,219-222,225-229,231-236,246-249,252-256,260-264
src/qdk/chemistry/data/lattice_graph.cpp     408     191    46%   33-36,47-50,68,70-71,73-76,78,80-81,83-86,135,161,164,167,209,212,215,267,270,273,318,321,324,394-395,397-404,406,408,410-413,415-416,418,420-421,424-428,432-437,439-440,442-444,446-448,450,452-453,455-456,459-461,464-467,470-472,474-482,486-493,495-496,498-505,507,509,511-514,516-517,521-522,524-528,530-533,535-536,538-539,541-542,544-545,548-549,551-560,562,564-569,571-572,574-579,581-582,584-592,594-596,599-601,603-605,607-610,612-613,615,617-628,630,633-638
src/qdk/chemistry/data/orbitals.cpp         1177     913    77%   106-107,128,144-145,151-152,156-157,178,180,220-221,237,251,292,307,321,363,373,377,400,403,405-406,409-413,416-417,421-424,426-427,429,431,433-434,437-440,443,447,449,453,455,457-458,461-467,470-471,474-475,477-478,480,482,484-485,488-492,495,498,500,563-567,570-571,573-574,576-577,580-581,584,586,589-590,592-593,595-596,599-601,604,606,609-610,612-613,615-616,619-620,623,625,665,668,691,759,770,776,781,808,818,862-866,904,917,929,942,962,980,989,1065-1068,1083-1084,1109-1113,1121-1122,1157,1181-1182,1191-1192,1198-1199,1205-1206,1208-1209,1212-1213,1215-1216,1229,1231-1232,1236-1237,1243,1285-1286,1314,1320,1364-1368,1396-1397,1399-1403,1406,1409,1411,1414,1416,1419,1421-1423,1425-1427,1430-1432,1434-1436,1438-1441,1460-1462,1465-1467,1470-1472,1534-1535,1564-1566,1581-1583,1617-1618,1630-1631,1789-1793,1806-1807,1810,1813-1814,1817-1819,1821,1860,1897,1912-1914,1963-1964,1999-2000,2006-2007,2013-2014,2016-2017,2020-2021,2023-2024,2031,2047-2048
src/qdk/chemistry/data/pauli_operator.cpp
                                             756     683    90%   60,63,87-88,190,202-203,224,397,407,421-423,517,555-557,559-561,577-579,581-583,606,609,721,806,818,820-821,855,860-862,877,882-884,912,938-942,944,946,951,956,996,1014-1016,1029,1036-1037,1039-1044,1062,1073-1076,1202,1222,1300,1343
src/qdk/chemistry/data/settings.cpp         1106     556    50%   23,27,55-64,66-81,88-93,96-99,101-105,107-111,113,115-118,120-125,127-131,133-143,147-156,169,173,210,222-225,227-229,232-236,238-239,241-243,245-246,248-249,292-293,296,311,342-343,346-348,350-355,357,359-364,367,387-391,394-395,398,400,406,408,410,414,416,420,464-465,467,469,471-472,474-477,481-482,484-486,489-490,494-496,499-501,505,507,510-515,520-524,526-536,538-541,543-547,549-552,556,560-563,567-571,575-578,581-585,587-588,590,592-595,597-599,601-602,604-606,608,610-612,614-618,621-625,627,629-631,633-635,637-641,644-648,650,652-654,657-659,661,664-666,669-670,673-680,682-683,685-686,689-690,692-698,701-707,711,714-715,718-719,722-723,726-727,730-734,736,738,740-741,743-746,748-749,751-752,754-757,759-760,762,764-767,770,772-775,779-784,788-789,791,793-796,800,803-804,817,823,826,833,836,844,848,865,869-870,887-890,899,902,974-975,987,989,1137,1139-1142,1145,1147-1148,1154-1155,1158-1163,1165,1169,1171,1176,1180-1182,1188,1192,1195-1196,1201,1203-1205,1209,1254,1261,1279,1330-1332,1362,1368-1371,1393-1394,1429-1430,1432,1461-1463,1482-1487,1513-1515,1517,1519-1520,1523-1525,1527-1529,1535,1556-1563,1566-1569,1625,1653,1668-1670,1674-1684,1686-1691,1693-1695,1697-1703,1705-1707,1709,1711,1713-1717,1719-1723,1725-1727,1729-1730,1732-1739,1741-1750,1752-1754,1756-1758,1774
src/qdk/chemistry/data/stability_result.cpp
                                             317     292    92%   25,32,42,176,213,218,271,281,299,315,344,346,350,356,379,419,421,425,451,458,503-507
src/qdk/chemistry/data/structure.cpp         761     703    92%   86,101,115-116,127,140,159,176-177,204,245-246,295,479,492,512,530,649,665,802,816,964-966,974-975,985,995-996,1018-1019,1027,1055-1057,1063,1076,1122-1123,1126,1132-1135,1138-1147,1151-1153,1156
src/qdk/chemistry/data/wavefunction.cpp     1315    1133    86%   45,65,171,174,182-184,265-266,282,303-306,308-311,314,332-337,340,382,413,450,463,483,488,504-505,526,543,546,569,572,575-584,615-621,623-625,727-736,833-837,932-934,979,993,1006,1008,1013,1015,1037-1038,1097,1099-1100,1114,1116,1119-1120,1141-1144,1146,1181,1183-1184,1209,1226,1352,1451-1454,1482,1489,1495,1502,1518,1524-1526,1532,1543,1573-1574,1589-1590,1597-1598,1618,1623-1624,1630,1641,1677,1787-1788,1798-1799,1826,1852-1853,1883-1884,1956,1958,1961-1962,1970-1972,1990-1992,1994-1995,2001-2004,2007-2017,2019-2020,2022-2025,2028-2031,2033-2035,2037-2038,2040-2041
src/qdk/chemistry/data/wavefunction_containers/cas.cpp
                                             252     199    79%   76-77,79-82,84-85,87-88,90,92-93,95-96,98-99,101,116,161-162,166,168,172,174,178-179,191-193,199,201-204,207-210,227-228,231-232,337-339,359,377-378,387,398,421-422
src/qdk/chemistry/data/wavefunction_containers/cc.cpp
                                             878     525    59%   48,52,57,59,62,66,71-72,74-77,79,87-88,122-127,153-160,169-175,203-204,206-220,222-224,226-228,231,233-234,250,258-259,261,267,277,287,299,319,324,326-328,331-334,337,339-340,343,345-349,351-352,354-355,358-359,381-383,385-387,389-391,393-395,397-399,425,432,463-466,528-529,595-596,599,601,603,606-607,609-610,612,615,617-620,622-624,627-628,630,633,637,639-640,643,687,696-697,699,705-706,708-709,716,728,737-738,747-748,754,790,800,810,820,830,841,940-950,952-956,969-979,981,983-985,1058-1069,1071-1083,1085-1091,1093-1100,1115-1126,1128-1140,1142-1148,1150-1156,1171-1181,1183-1195,1197-1200,1202,1204-1207,1223-1232,1234-1246,1248-1251,1253-1257,1322-1324,1326-1327,1330,1332-1333,1335,1337-1338,1342-1344
src/qdk/chemistry/data/wavefunction_containers/mp2.cpp
                                             626     433    69%   32,36,40-41,45-47,60-62,78,85,110,139,150-151,177-178,226-227,241,311,316,318-320,323-325,328-331,334-339,341-347,349-351,372,435-436,466-467,475,488-490,492,496-498,500,533,542-543,545,551-552,554-555,562,574,583-584,604,621-622,625-626,629,631-637,639-642,644,646,648,650-656,658-661,663,665,667,669-675,677-680,682,686-695,701-710,716-725,732-734,736-737,741,743-744,746-748,752-755,757,923,929,931,962-963,966-967,971,973,1004,1021,1055,1079,1081,1086,1090-1100
src/qdk/chemistry/data/wavefunction_containers/sci.cpp
                                             213     176    82%   78-79,81-84,86-87,89-90,92,94-95,97-98,100-101,103,117,151,153,155-156,166-167,170-171,260-262,282,300-301,310,321,344-345
src/qdk/chemistry/data/wavefunction_containers/sd.cpp
                                             399     336    84%   17,42-46,54,56-60,111,113,118,120,136-137,140,143-144,156,158,161-162,200,202,205-206,275,277,280-282,309,311,314,316,369,371,467,497-498,501,511-512,515,562,571,577,591,599-602,646-647,664-665,683-684,694-695
src/qdk/chemistry/utils/logger.cpp           120     115    95%   201-203,237,281
src/qdk/chemistry/utils/orbital_rotation.cpp
                                              93      56    60%   60-62,140-142,145,149-150,152,154-155,176,178,180,182,185-186,188,192-193,196-197,200,202-203,205,208-211,214,218-219,221,223-224
src/qdk/chemistry/utils/valence_space.cpp
                                              43      37    86%   60-63,79,83
------------------------------------------------------------------------------
TOTAL                                      22954   18111    78%
------------------------------------------------------------------------------
Python Coverage Details
src/qdk_chemistry/data/time_evolution/base.py                                                       40     12    70%
src/qdk_chemistry/data/time_evolution/containers/__init__.py                                         0      0   100%
src/qdk_chemistry/data/time_evolution/containers/base.py                                            26      0   100%
src/qdk_chemistry/data/time_evolution/containers/pauli_product_formula.py                           93      4    96%
src/qdk_chemistry/data/time_evolution/controlled_time_evolution.py                                  46      8    83%
src/qdk_chemistry/definitions.py                                                                     8      0   100%
src/qdk_chemistry/plugins/__init__.py                                                                0      0   100%
src/qdk_chemistry/plugins/openfermion/__init__.py                                                   19      0   100%
src/qdk_chemistry/plugins/openfermion/conversion.py                                                 78     22    72%
src/qdk_chemistry/plugins/openfermion/qubit_mapper.py                                               63      1    98%
src/qdk_chemistry/plugins/pyscf/__init__.py                                                         18      0   100%
src/qdk_chemistry/plugins/pyscf/active_space_avas.py                                                77      7    91%
src/qdk_chemistry/plugins/pyscf/conversion.py                                                      264     16    94%
src/qdk_chemistry/plugins/pyscf/coupled_cluster.py                                                 101     27    73%
src/qdk_chemistry/plugins/pyscf/localization.py                                                     72      8    89%
src/qdk_chemistry/plugins/pyscf/mcscf.py                                                           123     15    88%
src/qdk_chemistry/plugins/pyscf/scf_solver.py                                                      102      5    95%
src/qdk_chemistry/plugins/pyscf/stability.py                                                       154      2    99%
src/qdk_chemistry/plugins/qiskit/__init__.py                                                        43      0   100%
src/qdk_chemistry/plugins/qiskit/_interop/__init__.py                                                0      0   100%
src/qdk_chemistry/plugins/qiskit/_interop/circuit.py                                               130      0   100%
src/qdk_chemistry/plugins/qiskit/_interop/noise_model.py                                            15      1    93%
src/qdk_chemistry/plugins/qiskit/_interop/qir.py                                                    83     23    72%
src/qdk_chemistry/plugins/qiskit/_interop/transpiler.py                                            139      6    96%
src/qdk_chemistry/plugins/qiskit/circuit_executor.py                                                38      0   100%
src/qdk_chemistry/plugins/qiskit/conversion.py                                                      31      0   100%
src/qdk_chemistry/plugins/qiskit/qubit_mapper.py                                                    36      1    97%
src/qdk_chemistry/plugins/qiskit/regular_isometry.py                                                40      0   100%
src/qdk_chemistry/plugins/qiskit/standard_phase_estimation.py                                       69      4    94%
src/qdk_chemistry/utils/__init__.py                                                                  4      0   100%
src/qdk_chemistry/utils/cubegen.py                                                                  54     54     0%
src/qdk_chemistry/utils/enum.py                                                                     23      3    87%
src/qdk_chemistry/utils/model_hamiltonians.py                                                       43      1    98%
src/qdk_chemistry/utils/pauli_commutation.py                                                        97      3    97%
src/qdk_chemistry/utils/pauli_matrix.py                                                             74      0   100%
src/qdk_chemistry/utils/phase.py                                                                    39      1    97%
src/qdk_chemistry/utils/qsharp/__init__.py                                                          17      0   100%
src/qdk_chemistry/utils/telemetry.py                                                               142     87    39%
src/qdk_chemistry/utils/telemetry_events.py                                                         59     48    19%
src/qdk_chemistry/utils/wavefunction.py                                                             57     57     0%
--------------------------------------------------------------------------------------------------------------------
TOTAL                                                                                             5378    708    87%
Coverage HTML written to dir ../coverage-reports/python_coverage_html
Coverage XML written to file ../coverage-reports/python_coverage.xml
=========================== short test summary info ============================
SKIPPED [2] tests/test_docs_examples.py:186: Skipping slow test. Set QDK_CHEMISTRY_RUN_SLOW_TESTS=1 to enable.
SKIPPED [1] tests/test_sample_workflow.py:219: Skipping slow test. Set QDK_CHEMISTRY_RUN_SLOW_TESTS=1 to enable.
SKIPPED [1] tests/test_sample_workflow.py:236: Skipping slow test. Set QDK_CHEMISTRY_RUN_SLOW_TESTS=1 to enable.
SKIPPED [1] tests/test_sample_workflow_rdkit.py:30: Skipping: RDKit not installed
=========== 1448 passed, 5 skipped, 3 warnings in 1208.18s (0:20:08) ===========
Pybind11 Coverage Details
------------------------------------------------------------------------------
                           GCC Code Coverage Report
Directory: .
------------------------------------------------------------------------------
File                                       Lines     Exec  Cover   Missing
------------------------------------------------------------------------------
src/pybind11/algorithms/active_space.cpp      37       37   100%
src/pybind11/algorithms/davidson_solver.cpp
                                              35       34    97%   28
src/pybind11/algorithms/dynamical_correlation_calculator.cpp
                                              30       30   100%
src/pybind11/algorithms/factory_bindings.hpp
                                             198      189    95%   218,218,218,218,218,218,218,218,218
src/pybind11/algorithms/hamiltonian.cpp       60       55    91%   53,61,63,69,72
src/pybind11/algorithms/localizer.cpp         37       37   100%
src/pybind11/algorithms/mc.cpp                36       36   100%
src/pybind11/algorithms/mcscf.cpp             33       33   100%
src/pybind11/algorithms/pmc.cpp               35       34    97%   178
src/pybind11/algorithms/scf.cpp               34       34   100%
src/pybind11/algorithms/stability.cpp         33       33   100%
src/pybind11/algorithms/syev_solver.cpp       19       18    94%   43
src/pybind11/constants.cpp                    89       89   100%
src/pybind11/data/ansatz.cpp                  69       69   100%
src/pybind11/data/basis_set.cpp              204      204   100%
src/pybind11/data/configuration.cpp           30       29    96%   200
src/pybind11/data/configuration_set.cpp       84       84   100%
src/pybind11/data/data_class.cpp             109       27    24%   19-20,23-24,27,29,32,34-37,39-44,46,48-49,52,54,57-59,64,67,71-72,75,78-79,81-82,90,92,94-96,98,101,104-105,107,110,113-115,117-120,124,126,128-129,131,133,135-137,139,141,143-145,150-151,153,156-157,159,162-163,165,168-169,171,174,176,178,249
src/pybind11/data/element_data.cpp           123      123   100%
src/pybind11/data/hamiltonian.cpp            269      258    95%   63,66,68,409,428,601,621,814,835,1018,1039
src/pybind11/data/lattice_graph.cpp          101       73    72%   20,23,25,27,29-30,33,36-37,39,41-42,45,48-49,51,53-54,423-425,429,448,459,562,564,566,568
src/pybind11/data/orbitals.cpp               138      137    99%   940
src/pybind11/data/path_utils.hpp              19       11    57%   37,39,42-47
src/pybind11/data/pauli_operator.cpp         274      254    92%   146,257,322,398,403,409,415,427,467,473,505,511,517,529,604,636,641,655,659,667
src/pybind11/data/property_binding_helpers.hpp
                                             320      320   100%
src/pybind11/data/serialization.cpp            5        5   100%
src/pybind11/data/settings.cpp               712      478    67%   40-41,57-58,108-109,115-116,121-122,127,129,134,136,162-166,175-177,180-183,188-192,196-198,208-211,215-219,228-231,235-240,244-247,257-260,264-268,271-275,279-289,291-309,311-325,327-329,333,336-338,375-378,391,441,443-444,480,551,1211,1219,1225,1228,1345,1379,1457,1520,1545,1570,1596,1660,1748-1749,1751-1755,1789-1793,1795-1800,1851,1905,1931-1932,1934,1937-1940,1966,2008-2009,2011-2012,2043-2044,2046,2049-2052,2079-2081,2102-2104,2106-2107,2126-2132,2152-2154,2156-2157,2179-2183,2185-2190,2221-2222,2240-2246,2268-2269,2287-2293,2423
src/pybind11/data/stability_result.cpp       112      112   100%
src/pybind11/data/structure.cpp              199      184    92%   69,72,75-78,82-84,87,90-91,969,977,999
src/pybind11/data/wavefunction.cpp           365      347    95%   39,98,100,264-265,268,272,278,473-477,479,1016,1018,1064,1067
src/pybind11/module.cpp                       43       43   100%
src/pybind11/qdk_scf_config.cpp               12       12   100%
src/pybind11/utils/logger.cpp                191      177    92%   27,54,68-69,92,97-99,105-106,262-263,476,480
src/pybind11/utils/model_hamiltonians.cpp
                                              62       59    95%   270-272
src/pybind11/utils/orbital_rotation.cpp        7        7   100%
src/pybind11/utils/valence_space.cpp           5        5   100%
------------------------------------------------------------------------------
TOTAL                                       4129     3677    89%
------------------------------------------------------------------------------

Copilot AI review requested due to automatic review settings March 17, 2026 22:27
Copy link
Copy Markdown
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Adds a density-fitted (RI/DF) Hamiltonian representation and constructor to reduce memory usage by storing 3-center integrals and constructing 4-center ERIs on-demand, with accompanying bindings, docs, and tests.

Changes:

  • Introduces DensityFittedHamiltonianContainer with lazy 4-center ERI construction + JSON/HDF5/FCIDUMP support.
  • Adds microsoft::DensityFittedHamiltonianConstructor and extends the HamiltonianConstructor API to accept an optional auxiliary basis.
  • Updates Python bindings, documentation, and test suites to cover the new container type and constructor behavior.

Reviewed changes

Copilot reviewed 27 out of 28 changed files in this pull request and generated 13 comments.

Show a summary per file
File Description
python/tests/test_helpers.py Extends test Hamiltonian factory helper to create density-fitted containers.
python/tests/test_hamiltonian.py Parameterizes Hamiltonian tests over canonical vs density-fitted containers and adds DF-specific checks.
python/src/qdk_chemistry/data/init.py Exposes DensityFittedHamiltonianContainer in the Python data package.
python/src/pybind11/data/hamiltonian.cpp Adds pybind bindings + docstrings for DensityFittedHamiltonianContainer.
python/src/pybind11/algorithms/hamiltonian.cpp Updates HamiltonianConstructor trampoline for new _run_impl signature and binds DF constructor type.
docs/source/user/comprehensive/data/hamiltonian.rst Documents container types and density-fitted storage/usage.
docs/source/user/comprehensive/algorithms/hamiltonian_constructor.rst Documents DF Hamiltonian constructor and auxiliary-basis requirement.
docs/source/glossary.rst Adds DF/RI glossary entries.
cpp/src/qdk/chemistry/data/hamiltonian_containers/density_fitted.cpp Implements density-fitted container with lazy 4-center caching and serialization.
cpp/src/qdk/chemistry/data/hamiltonian_containers/canonical_four_center.cpp Removes FCIDUMP implementation now centralized in the base container.
cpp/src/qdk/chemistry/data/hamiltonian.cpp Adds DF container deserialization support, centralizes FCIDUMP writing, and adds extra validation.
cpp/src/qdk/chemistry/data/CMakeLists.txt Registers new DF container source in the data build.
cpp/src/qdk/chemistry/algorithms/microsoft/mp2.cpp Fixes MP2 energy computation to use active-space orbital energies.
cpp/src/qdk/chemistry/algorithms/microsoft/hamiltonian_util.hpp Introduces shared helpers for active-index validation and 3-center transformations/J/K builds.
cpp/src/qdk/chemistry/algorithms/microsoft/hamiltonian_util.cpp Implements the shared 3-center transformation and J/K utilities.
cpp/src/qdk/chemistry/algorithms/microsoft/hamiltonian.hpp Updates 4-center constructor signature to accept optional aux basis (rejected for 4-center).
cpp/src/qdk/chemistry/algorithms/microsoft/hamiltonian.cpp Rejects aux basis for 4-center constructor via the new API.
cpp/src/qdk/chemistry/algorithms/microsoft/density_fitted_hamiltonian.hpp Adds the DF Hamiltonian constructor type + settings.
cpp/src/qdk/chemistry/algorithms/microsoft/density_fitted_hamiltonian.cpp Implements DF Hamiltonian construction using an auxiliary basis and 3-center DF integrals.
cpp/src/qdk/chemistry/algorithms/microsoft/cholesky_hamiltonian.hpp Updates signature for optional aux basis and reuses shared 3-center utilities.
cpp/src/qdk/chemistry/algorithms/microsoft/cholesky_hamiltonian.cpp Refactors Cholesky path to shared utilities and rejects aux basis.
cpp/src/qdk/chemistry/algorithms/microsoft/CMakeLists.txt Adds DF constructor + util sources to the Microsoft algorithms build.
cpp/src/qdk/chemistry/algorithms/hamiltonian.cpp Registers the DF Hamiltonian constructor with the factory.
cpp/include/qdk/chemistry/data/hamiltonian_containers/density_fitted.hpp Declares the DF container interface and caching members.
cpp/include/qdk/chemistry/data/hamiltonian_containers/canonical_four_center.hpp Removes FCIDUMP override and updates container doc wording.
cpp/include/qdk/chemistry/data/hamiltonian.hpp Makes to_fcidump_file non-pure virtual to share implementation across containers.
cpp/include/qdk/chemistry/algorithms/hamiltonian.hpp Extends the HamiltonianConstructor algorithm signature with OptionalAuxBasis.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot AI review requested due to automatic review settings March 18, 2026 05:28
Copy link
Copy Markdown
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

This PR adds density-fitted (RI/DF) Hamiltonian support to QDK/Chemistry by introducing a new Hamiltonian container that stores 3-center integrals and a corresponding Hamiltonian constructor that requires an auxiliary basis, plus updates to bindings, docs, and tests.

Changes:

  • Added DensityFittedHamiltonianContainer with lazy on-demand 4-center integral materialization and JSON/HDF5/FCIDUMP support.
  • Added microsoft::DensityFittedHamiltonianConstructor and extended the Hamiltonian-constructor API to optionally accept an auxiliary basis.
  • Updated Python bindings/tests/docs to expose and validate the new container/constructor, including an O2 DF-MP2 integration test.

Reviewed changes

Copilot reviewed 29 out of 30 changed files in this pull request and generated 12 comments.

Show a summary per file
File Description
python/tests/test_helpers.py Extends test Hamiltonian factory to create canonical vs density-fitted containers.
python/tests/test_hamiltonian.py Parameterizes Hamiltonian tests across container types; adds DF-specific and factory integration tests.
python/src/qdk_chemistry/data/init.py Re-exports DensityFittedHamiltonianContainer in the Python data package.
python/src/qdk_chemistry/algorithms/hamiltonian_constructor.py Re-exports QdkDensityFittedHamiltonianConstructor.
python/src/qdk_chemistry/algorithms/init.py Exposes QdkDensityFittedHamiltonianConstructor at package level.
python/src/pybind11/data/hamiltonian.cpp Binds DensityFittedHamiltonianContainer and updates container docstrings/examples.
python/src/pybind11/algorithms/hamiltonian.cpp Adds run(orbitals, aux_basis) overload and binds QdkDensityFittedHamiltonianConstructor.
docs/source/user/comprehensive/data/hamiltonian.rst Documents container types and DF usage.
docs/source/user/comprehensive/algorithms/hamiltonian_constructor.rst Documents the DF constructor and its factory name/usage.
docs/source/glossary.rst Adds DF/RI glossary entries.
cpp/src/qdk/chemistry/data/hamiltonian_containers/density_fitted.cpp Implements DF container, lazy 4-center cache, and serialization.
cpp/src/qdk/chemistry/data/hamiltonian_containers/canonical_four_center.cpp Removes FCIDUMP implementation now moved to base container.
cpp/src/qdk/chemistry/data/hamiltonian.cpp Adds DF container deserialization and moves FCIDUMP writing to base container; strengthens validation.
cpp/src/qdk/chemistry/data/CMakeLists.txt Adds DF container source to build.
cpp/src/qdk/chemistry/algorithms/microsoft/mp2.cpp Uses active-space orbital energies for MP2 computations.
cpp/src/qdk/chemistry/algorithms/microsoft/hamiltonian_util.hpp/.cpp Introduces shared helper utilities (active-space validation; 3-center transforms; J/K builds).
cpp/src/qdk/chemistry/algorithms/microsoft/hamiltonian.hpp/.cpp Updates constructor signature to accept optional aux basis and rejects aux basis for non-DF constructor.
cpp/src/qdk/chemistry/algorithms/microsoft/density_fitted_hamiltonian.hpp/.cpp Adds DF Hamiltonian constructor implementation.
cpp/src/qdk/chemistry/algorithms/microsoft/cholesky_hamiltonian.hpp/.cpp Updates signature to accept optional aux basis and rejects aux basis for Cholesky constructor; refactors helpers.
cpp/src/qdk/chemistry/algorithms/microsoft/CMakeLists.txt Adds DF constructor + shared util sources to build.
cpp/src/qdk/chemistry/algorithms/hamiltonian.cpp Registers DF Hamiltonian constructor factory instance.
cpp/include/qdk/chemistry/data/hamiltonian_containers/density_fitted.hpp Adds DF container public C++ API.
cpp/include/qdk/chemistry/data/hamiltonian_containers/canonical_four_center.hpp Updates canonical container docs and removes FCIDUMP override.
cpp/include/qdk/chemistry/data/hamiltonian.hpp Makes to_fcidump_file non-pure virtual (base implementation).
cpp/include/qdk/chemistry/algorithms/hamiltonian.hpp Extends constructor API to accept OptionalAuxBasis and adds run(orbitals) convenience overload.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot AI review requested due to automatic review settings March 19, 2026 03:41
Copy link
Copy Markdown
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

This PR adds first-class density-fitting (RI/DF) support for Hamiltonian construction and storage across the C++ core, Python bindings, docs, and tests, enabling three-center integral storage with lazy four-center materialization for post-SCF workflows (e.g., DF-MP2).

Changes:

  • Introduces DensityFittedHamiltonianContainer (C++ + pybind) with three-center integral storage, lazy four-center cache, and JSON/HDF5/FCIDUMP support.
  • Adds microsoft::DensityFittedHamiltonianConstructor and extends HamiltonianConstructor.run() to support an optional auxiliary basis parameter (while keeping a 1-arg convenience overload).
  • Expands/parameterizes Python tests and documentation to cover the new container type and density-fitted construction.

Reviewed changes

Copilot reviewed 29 out of 30 changed files in this pull request and generated 8 comments.

Show a summary per file
File Description
python/tests/test_helpers.py Extends test helper to construct Hamiltonians with either canonical or density-fitted containers.
python/tests/test_hamiltonian.py Parameterizes Hamiltonian tests across container types and adds DF constructor integration test.
python/src/qdk_chemistry/data/init.py Re-exports DensityFittedHamiltonianContainer in the public Python data API.
python/src/qdk_chemistry/algorithms/hamiltonian_constructor.py Re-exports the new density-fitted constructor binding.
python/src/qdk_chemistry/algorithms/init.py Exposes QdkDensityFittedHamiltonianConstructor in the algorithms package surface.
python/src/pybind11/data/hamiltonian.cpp Binds DensityFittedHamiltonianContainer to Python and updates integral-notation docs.
python/src/pybind11/algorithms/hamiltonian.cpp Adds run(orbitals, aux_basis) overload and binds QdkDensityFittedHamiltonianConstructor.
docs/source/user/comprehensive/data/hamiltonian.rst Documents Hamiltonian container types, including density-fitted container usage.
docs/source/user/comprehensive/algorithms/hamiltonian_constructor.rst Documents the DF Hamiltonian constructor factory implementation and aux-basis requirement.
docs/source/glossary.rst Adds glossary entries for DF and RI.
cpp/src/qdk/chemistry/data/hamiltonian_containers/density_fitted.cpp Implements DF container logic, lazy four-center construction, and JSON/HDF5 serialization.
cpp/src/qdk/chemistry/data/hamiltonian_containers/canonical_four_center.cpp Removes FCIDUMP writing implementation (moved to base container implementation).
cpp/src/qdk/chemistry/data/hamiltonian.cpp Routes container deserialization for DF and moves FCIDUMP writing into HamiltonianContainer.
cpp/src/qdk/chemistry/data/CMakeLists.txt Adds DF container source to the data target.
cpp/src/qdk/chemistry/algorithms/microsoft/mp2.cpp Fixes MP2 to use active-space orbital energies (consistent with active-space Hamiltonians).
cpp/src/qdk/chemistry/algorithms/microsoft/hamiltonian_util.hpp Introduces shared helpers for active-index validation and three-center transformations/J/K builds.
cpp/src/qdk/chemistry/algorithms/microsoft/hamiltonian_util.cpp Implements shared helper functions used by Cholesky and DF paths.
cpp/src/qdk/chemistry/algorithms/microsoft/hamiltonian.hpp Updates four-center Hamiltonian constructor to the new _run_impl(orbitals, aux_basis) signature.
cpp/src/qdk/chemistry/algorithms/microsoft/hamiltonian.cpp Enforces aux-basis is not accepted by the four-center constructor.
cpp/src/qdk/chemistry/algorithms/microsoft/density_fitted_hamiltonian.hpp Declares the DF Hamiltonian constructor and its settings.
cpp/src/qdk/chemistry/algorithms/microsoft/density_fitted_hamiltonian.cpp Implements DF Hamiltonian construction using an auxiliary basis and three-center machinery.
cpp/src/qdk/chemistry/algorithms/microsoft/cholesky_hamiltonian.hpp Updates Cholesky constructor signature and reuses shared three-center utilities.
cpp/src/qdk/chemistry/algorithms/microsoft/cholesky_hamiltonian.cpp Refactors Cholesky constructor to shared utilities and rejects aux-basis.
cpp/src/qdk/chemistry/algorithms/microsoft/CMakeLists.txt Adds DF constructor + shared utility sources to the microsoft algorithms target.
cpp/src/qdk/chemistry/algorithms/hamiltonian.cpp Registers the DF constructor in the factory.
cpp/include/qdk/chemistry/data/hamiltonian_containers/density_fitted.hpp Adds the public DF container header/API.
cpp/include/qdk/chemistry/data/hamiltonian_containers/canonical_four_center.hpp Removes per-container FCIDUMP API and updates doc comments.
cpp/include/qdk/chemistry/data/hamiltonian.hpp Makes HamiltonianContainer::to_fcidump_file a concrete base implementation.
cpp/include/qdk/chemistry/algorithms/hamiltonian.hpp Extends constructor API to accept optional auxiliary basis (variant of BasisSet ptr or name).

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot AI review requested due to automatic review settings March 19, 2026 21:01
Copy link
Copy Markdown
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

This PR introduces a new density-fitted Hamiltonian representation and constructor path, enabling memory-efficient storage of MO-space ERIs via three-center integrals with lazy on-demand reconstruction of four-center integrals. It also extends the Hamiltonian-constructor API to accept an optional auxiliary basis and wires the new implementation through C++/Python bindings, documentation, and tests.

Changes:

  • Added DensityFittedHamiltonianContainer (C++ + pybind) with three-center integral storage and lazy four-center cache generation.
  • Added qdk_density_fitted_hamiltonian constructor implementation and extended HamiltonianConstructor::run / _run_impl to accept an optional auxiliary basis.
  • Updated Python exports, docs, and tests (parameterized container tests + DF MP2 integration test).

Reviewed changes

Copilot reviewed 28 out of 29 changed files in this pull request and generated 3 comments.

Show a summary per file
File Description
python/tests/test_helpers.py Extends test Hamiltonian factory to create canonical vs density-fitted containers.
python/tests/test_hamiltonian.py Parameterizes Hamiltonian tests across container types and adds DF constructor integration test.
python/src/qdk_chemistry/data/init.py Exposes DensityFittedHamiltonianContainer in the public Python data API.
python/src/qdk_chemistry/algorithms/hamiltonian_constructor.py Re-exports QdkDensityFittedHamiltonianConstructor from core bindings.
python/src/qdk_chemistry/algorithms/init.py Adds DF constructor to algorithm package exports.
python/src/pybind11/data/hamiltonian.cpp Binds DensityFittedHamiltonianContainer and updates docstrings/indexing notes.
python/src/pybind11/algorithms/hamiltonian.cpp Updates HamiltonianConstructor.run binding to accept optional aux basis and binds QdkDensityFittedHamiltonianConstructor.
docs/source/user/comprehensive/data/hamiltonian.rst Documents container types and density-fitted container usage.
docs/source/user/comprehensive/algorithms/hamiltonian_constructor.rst Documents the new qdk_density_fitted_hamiltonian implementation and aux-basis requirement.
docs/source/glossary.rst Adds DF/RI glossary entries.
cpp/src/qdk/chemistry/data/hamiltonian_containers/density_fitted.cpp Implements the new DF container with lazy four-center cache + JSON/HDF5 I/O.
cpp/src/qdk/chemistry/data/hamiltonian_containers/canonical_four_center.cpp Removes FCIDUMP logic (moved to base container).
cpp/src/qdk/chemistry/data/hamiltonian.cpp Adds DF container dispatch + moves FCIDUMP writer to HamiltonianContainer.
cpp/src/qdk/chemistry/data/CMakeLists.txt Adds DF container source to build.
cpp/src/qdk/chemistry/algorithms/microsoft/hamiltonian_util.hpp Adds shared helpers for active-index validation and three-center transformations/J/K builds.
cpp/src/qdk/chemistry/algorithms/microsoft/hamiltonian_util.cpp Implements the new shared Hamiltonian utilities.
cpp/src/qdk/chemistry/algorithms/microsoft/hamiltonian.hpp Updates four-center constructor signature to accept optional aux basis (and reject it at runtime).
cpp/src/qdk/chemistry/algorithms/microsoft/hamiltonian.cpp Implements aux-basis rejection for the four-center constructor.
cpp/src/qdk/chemistry/algorithms/microsoft/density_fitted_hamiltonian.hpp Declares DF constructor implementation and settings.
cpp/src/qdk/chemistry/algorithms/microsoft/density_fitted_hamiltonian.cpp Implements DF Hamiltonian construction using an auxiliary basis and three-center integrals.
cpp/src/qdk/chemistry/algorithms/microsoft/cholesky_hamiltonian.hpp Updates Cholesky constructor signature and reuses shared utilities.
cpp/src/qdk/chemistry/algorithms/microsoft/cholesky_hamiltonian.cpp Updates Cholesky constructor to accept (and reject) aux basis and reuse shared utilities.
cpp/src/qdk/chemistry/algorithms/microsoft/CMakeLists.txt Adds DF constructor + shared utility sources to build.
cpp/src/qdk/chemistry/algorithms/hamiltonian.cpp Registers qdk_density_fitted_hamiltonian in the factory.
cpp/include/qdk/chemistry/data/hamiltonian_containers/density_fitted.hpp Declares the DF container public C++ API.
cpp/include/qdk/chemistry/data/hamiltonian_containers/canonical_four_center.hpp Removes FCIDUMP override and updates docs/comments.
cpp/include/qdk/chemistry/data/hamiltonian.hpp Makes HamiltonianContainer::to_fcidump_file non-pure virtual (base implementation).
cpp/include/qdk/chemistry/algorithms/hamiltonian.hpp Adds OptionalAuxBasis and updates HamiltonianConstructor API to accept it.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

@wavefunction91 wavefunction91 removed this from the Release 1.1 milestone Mar 25, 2026
@@ -0,0 +1,198 @@
// Copyright (c) Microsoft Corporation. All rights reserved.
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The content of this file can be moved into the hamiltonian.cpp and .hpp

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@wavefunction91 This is the comment

/**
* @class CanonicalFourCenterHamiltonianContainer
* @brief Contains a molecular Hamiltonian using canonical four center
* integrals, implemented as a subclass of HamiltonianContainer.
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What was the reason for changing the class docstring here?

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Because a previous reviewer does not think the implementation detail is relevant to users.


namespace qdk::chemistry::algorithms {

/**
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Each algorithm provides one run function. This here will break that pattern.
Since this is specific to DF, is the basis set argument really required and can not be a setting?


protected:
std::shared_ptr<data::Hamiltonian> _run_impl(
std::shared_ptr<data::Orbitals> orbitals) const override;
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

See comment about basis set argument

std::shared_ptr<Orbitals> orbitals) const override {
PYBIND11_OVERRIDE_PURE(std::shared_ptr<Hamiltonian>, HamiltonianConstructor,
_run_impl, orbitals);
std::shared_ptr<Orbitals> orbitals,
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

See comment about basis set argument

py::arg("filename"), py::arg("nalpha"), py::arg("nbeta"));

// ============================================================================
// DensityFittedHamiltonianContainer - Density-fitted integral storage
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why is this different than the cholesky hamiltonian? Could this container work for both methods?

Copy link
Copy Markdown
Contributor Author

@rainli323 rainli323 Apr 1, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

They would need to be merged in the next PR, not this one.

Copilot AI review requested due to automatic review settings April 2, 2026 04:34
Copy link
Copy Markdown
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 28 out of 29 changed files in this pull request and generated 3 comments.


💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Comment on lines +18 to +22
* @brief Type alias for basis set specification or initial guess
*
* Can be one of:
* - A shared pointer to BasisSet for custom basis
* - A string for standard basis set name (e.g., "sto-3g")
Copy link

Copilot AI Apr 2, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The Doxygen comment for OptionalAuxBasis says "basis set specification or initial guess", but this type is specifically for auxiliary basis selection for density fitting. Updating the description (and example string) would avoid confusing API users about what this parameter is for.

Suggested change
* @brief Type alias for basis set specification or initial guess
*
* Can be one of:
* - A shared pointer to BasisSet for custom basis
* - A string for standard basis set name (e.g., "sto-3g")
* @brief Type alias for auxiliary basis set specification used in density fitting
*
* Can be one of:
* - A shared pointer to BasisSet for a custom auxiliary basis
* - A string for a standard auxiliary basis set name (e.g., "def2-svp/jkfit")

Copilot uses AI. Check for mistakes.
Comment on lines +246 to +252
size_t norb_alpha = _one_body_integrals.first->rows();
unsigned orb_pair_size = norb_alpha * norb_alpha;

// Check alpha-alpha integrals - rows should equal orb_pair_size
if (static_cast<unsigned>(_three_center_integrals.first->rows()) !=
orb_pair_size) {
throw std::invalid_argument(
Copy link

Copilot AI Apr 2, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

orb_pair_size is computed as unsigned from size_t norb_alpha. For larger active spaces this can overflow/narrow and make the dimension check incorrect. Prefer using size_t throughout (and compare against rows()/cols() as Eigen::Index/size_t) to keep validation correct for large systems.

Copilot uses AI. Check for mistakes.
// Check beta-beta integrals (if different from alpha-alpha)
if (_three_center_integrals.second != _three_center_integrals.first) {
if (static_cast<unsigned>(_three_center_integrals.second->rows()) !=
orb_pair_size or
Copy link

Copilot AI Apr 2, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This condition uses the alternative token or instead of ||. The rest of the C++ codebase appears to use ||, so switching to || would improve consistency/readability.

Suggested change
orb_pair_size or
orb_pair_size ||

Copilot uses AI. Check for mistakes.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants