From a0e0c06700ee2311e0259a98b136c2f7e0a466f8 Mon Sep 17 00:00:00 2001 From: Jacob Heflin Date: Thu, 12 Jun 2025 10:50:46 -0500 Subject: [PATCH 1/3] readying the docs --- docs/source/{ => assets}/scf_architecture.png | Bin docs/source/background/index.rst | 9 ++ docs/source/background/scf_notes.md | 70 +++++++++++++ docs/source/background/scf_notes.rst | 98 ++++++++++++++++++ docs/source/bibliography/index.rst | 9 ++ docs/source/developer/index.rst | 7 ++ docs/source/faqs.rst | 5 + docs/source/features.rst | 5 + docs/source/index.rst | 17 ++- docs/source/install.rst | 5 + docs/source/tutorials/index.rst | 9 ++ 11 files changed, 231 insertions(+), 3 deletions(-) rename docs/source/{ => assets}/scf_architecture.png (100%) create mode 100644 docs/source/background/index.rst create mode 100644 docs/source/background/scf_notes.md create mode 100644 docs/source/background/scf_notes.rst create mode 100644 docs/source/bibliography/index.rst create mode 100644 docs/source/developer/index.rst create mode 100644 docs/source/faqs.rst create mode 100644 docs/source/features.rst create mode 100644 docs/source/install.rst create mode 100644 docs/source/tutorials/index.rst diff --git a/docs/source/scf_architecture.png b/docs/source/assets/scf_architecture.png similarity index 100% rename from docs/source/scf_architecture.png rename to docs/source/assets/scf_architecture.png diff --git a/docs/source/background/index.rst b/docs/source/background/index.rst new file mode 100644 index 0000000..14290c7 --- /dev/null +++ b/docs/source/background/index.rst @@ -0,0 +1,9 @@ +.. _scf_background: + +############## +SCF Background +############## + +Literally the book Modern Quantum Chemistry by Szabo and Ostlund + +.. image:: ../assets/scf_architecture.png diff --git a/docs/source/background/scf_notes.md b/docs/source/background/scf_notes.md new file mode 100644 index 0000000..9e61aa0 --- /dev/null +++ b/docs/source/background/scf_notes.md @@ -0,0 +1,70 @@ +# SCF Procedure + +## SCF Driver + +1. Obtain the AO parameters as well as the chemical system (inputs) +2. Assign the AO parameters as atomic orbitals +3. Create the Hamitonian from the Chemical System (Submod "Hamiltonian" used, currently only the BO Approximation from NUX) + 1. For the BO Approximation Hamiltonian: + 1. From the Chemical System, the Electrons and Nuclei are used to form the Hamiltonian + 2. Each electron gets a 1 electron kinetic energy term + 3. Each nuclei gets an Electron-Nuclei potential energy term + 4. If more than 1 electron, an Electron-Electron potential energy repulson term is added + 5. If more than 1 nuclei, a Nuclei-Nuclei potential energy repulsion term is added + 6. In order, the Electron kinetic energy, Electron-nucleus attraction energy, and Electron-electron repulsion energy are + formed to create the Electronic Hamiltonian + 7. The Nuclear-nuclear repulsion energy is also created + 8. The BO Approximation returns the constructed Hamiltonian, H. +4. With the guess submod, (of type InitialGuess), the inputs are the Hamiltonian and the AOs, and the return value is the + initial wavefunction + 1. The main module used is the "Core guess" module, which first builds the fock operator with 0 density + 2. I am not sure on what happens during lines 78-92: + ```cpp + simde::type::cmos cmos(tensor{}, aos, tensor{}); + NElectronCounter visitor; + H.visit(visitor); + auto n_electrons = visitor.n_electrons; + if(n_electrons % 2 != 0) + throw std::runtime_error("Assumed even number of electrons"); + + typename rscf_wf::orbital_index_set_type occs; + using value_type = typename rscf_wf::orbital_index_set_type::value_type; + for(value_type i = 0; i < n_electrons / 2; ++i) occs.insert(i); + + rscf_wf zero_guess(occs, cmos); + auto& update_mod = submods.at("Guess updater"); + const auto& Psi0 = update_mod.run_as(f, zero_guess);``` + + 3. From there, Psi0 is returned + +### SCF Loop + +5. The work horse of the module, the submod "Optimizer", uses `scf_loop.cpp` and the module `Loop` to optimize + the wavefunction. It takes in a Bracket via = H00, and Psi0. The property type it satisfies is + ```cpp + using pt = simde::Optimize, WfType>; + using egy_pt = simde::eval_braket; + using wf_type = simde::type::rscf_wf; + satisfies_property_type>; + ``` + and the return result type is the `WfType`, or in this case the `simde::type::rscf_wf`. + + 1. Step one is to get the nuclear-nuclear repulsion via lines 125-141 + 1. This is a little messy, so I'll skip the explanation. + 2. Compute the overlap matrix, S + 1. This runs the S_mod, which is the "Overlap" module provided by the "Integrals" plugin, creating the overlap matrix. + 3. Build the density matrix + 4. Start the scf process + 1. The fock matrix is build, starting with the one-electron fock builder, then the Fock builder, which who knows what is going on there. + 2. The new wavefunction is build from the new fock matrix and the old wavefunction + 3. the new density is built from the new wavefunction + 4. The new electronic hamiltonian is built from the H_core and the new Fock matrix + 5. the H_00 BraKet is built, and then used to calculate the new electronic energy + 6. We then check for convergence: + 1. We calculate delta_e for the change in energy, the delta_p for the change in density, and then the + gradient norm (FPS - SPF). + 2. check to see if they have hit convergence + 7. energy total is then calculated by adding the electronic energy to the nuclear energy calculated earlier. + +### Return results +6. From here, the energy that is of type Tensor and the optimized wavefunction is returned. diff --git a/docs/source/background/scf_notes.rst b/docs/source/background/scf_notes.rst new file mode 100644 index 0000000..6f1d5cf --- /dev/null +++ b/docs/source/background/scf_notes.rst @@ -0,0 +1,98 @@ +SCF Procedure +============= + +SCF Driver +---------- + +1. Obtain the AO parameters as well as the chemical system (inputs) +2. Assign the AO parameters as atomic orbitals +3. Create the Hamitonian from the Chemical System (Submod “Hamiltonian” + used, currently only the BO Approximation from NUX) + + 1. For the BO Approximation Hamiltonian: + + 1. From the Chemical System, the Electrons and Nuclei are used to + form the Hamiltonian + 2. Each electron gets a 1 electron kinetic energy term + 3. Each nuclei gets an Electron-Nuclei potential energy term + 4. If more than 1 electron, an Electron-Electron potential energy + repulson term is added + 5. If more than 1 nuclei, a Nuclei-Nuclei potential energy + repulsion term is added + 6. In order, the Electron kinetic energy, Electron-nucleus + attraction energy, and Electron-electron repulsion energy are + formed to create the Electronic Hamiltonian + 7. The Nuclear-nuclear repulsion energy is also created + 8. The BO Approximation returns the constructed Hamiltonian, H. + +4. With the guess submod, (of type InitialGuess), the inputs are the + Hamiltonian and the AOs, and the return value is the initial + wavefunction + + 1. The main module used is the “Core guess” module, which first + builds the fock operator with 0 density + + 2. I am not sure on what happens during lines 78-92: \```cpp + simde::type::cmos cmos(tensor{}, aos, tensor{}); NElectronCounter + visitor; H.visit(visitor); auto n_electrons = visitor.n_electrons; + if(n_electrons % 2 != 0) throw std::runtime_error(“Assumed even + number of electrons”); + + typename rscf_wf::orbital_index_set_type occs; using value_type = + typename rscf_wf::orbital_index_set_type::value_type; + for(value_type i = 0; i < n_electrons / 2; ++i) occs.insert(i); + + rscf_wf zero_guess(occs, cmos); auto& update_mod = + submods.at(“Guess updater”); const auto& Psi0 = + update_mod.run_as(f, zero_guess);``\` + + 3. From there, Psi0 is returned + +SCF Loop +~~~~~~~~ + +5. The work horse of the module, the submod “Optimizer”, uses + ``scf_loop.cpp`` and the module ``Loop`` to optimize the + wavefunction. It takes in a Bracket via = H00, + and Psi0. The property type it satisfies is + ``cpp using pt = simde::Optimize, WfType>; using egy_pt = simde::eval_braket; using wf_type = simde::type::rscf_wf; satisfies_property_type>;`` + and the return result type is the ``WfType``, or in this case the + ``simde::type::rscf_wf``. + + 1. Step one is to get the nuclear-nuclear repulsion via lines 125-141 + + 1. This is a little messy, so I’ll skip the explanation. + + 2. Compute the overlap matrix, S + + 1. This runs the S_mod, which is the “Overlap” module provided by + the “Integrals” plugin, creating the overlap matrix. + + 3. Build the density matrix + 4. Start the scf process + + 1. The fock matrix is build, starting with the one-electron fock + builder, then the Fock builder, which who knows what is going + on there. + 2. The new wavefunction is build from the new fock matrix and the + old wavefunction + 3. the new density is built from the new wavefunction + 4. The new electronic hamiltonian is built from the H_core and the + new Fock matrix + 5. the H_00 BraKet is built, and then used to calculate the new + electronic energy + 6. We then check for convergence: + + 1. We calculate delta_e for the change in energy, the delta_p + for the change in density, and then the gradient norm (FPS - + SPF). + 2. check to see if they have hit convergence + + 7. energy total is then calculated by adding the electronic energy + to the nuclear energy calculated earlier. + +Return results +~~~~~~~~~~~~~~ + +6. From here, the energy that is of type Tensor and the optimized + wavefunction is returned. diff --git a/docs/source/bibliography/index.rst b/docs/source/bibliography/index.rst new file mode 100644 index 0000000..78a16ba --- /dev/null +++ b/docs/source/bibliography/index.rst @@ -0,0 +1,9 @@ +########## +References +########## + +You know the book + +or Helgaker if you're really bought in + +.. bibliography:: diff --git a/docs/source/developer/index.rst b/docs/source/developer/index.rst new file mode 100644 index 0000000..e4eaac4 --- /dev/null +++ b/docs/source/developer/index.rst @@ -0,0 +1,7 @@ +.. _scf_developer: + +####################### +Developer Documentation +####################### + +If you can do it better I'd like to see you try. diff --git a/docs/source/faqs.rst b/docs/source/faqs.rst new file mode 100644 index 0000000..5392bd9 --- /dev/null +++ b/docs/source/faqs.rst @@ -0,0 +1,5 @@ +.. _scf_faqs: + +############################## +SCF Frequently Asked Questions +############################## diff --git a/docs/source/features.rst b/docs/source/features.rst new file mode 100644 index 0000000..bb22ab1 --- /dev/null +++ b/docs/source/features.rst @@ -0,0 +1,5 @@ +#################### +List of SCF Features +#################### + +So far a pretty neat scf! diff --git a/docs/source/index.rst b/docs/source/index.rst index fd545e0..e71e185 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -12,13 +12,24 @@ .. See the License for the specific language governing permissions and .. limitations under the License. -######### +### SCF -######### +### .. toctree:: :maxdepth: 2 - :caption: APIs: module_api/index + background/index.rst + features + install + tutorials/index + developer/index + faqs + bibliography/index.rst + +.. toctree:: + :maxdepth: 2 + :caption: APIs: + C++ API diff --git a/docs/source/install.rst b/docs/source/install.rst new file mode 100644 index 0000000..db4fb10 --- /dev/null +++ b/docs/source/install.rst @@ -0,0 +1,5 @@ +.. _installing_scf: + +############## +Installing SCF +############## diff --git a/docs/source/tutorials/index.rst b/docs/source/tutorials/index.rst new file mode 100644 index 0000000..e6f5b63 --- /dev/null +++ b/docs/source/tutorials/index.rst @@ -0,0 +1,9 @@ +.. _scf_tutorials: + + +############# +SCF Tutorials +############# + +I have never seen anyone do an scf by hand so we're probably just guessing at +this point. From 24000acf4a48e91903fab3607f5d10cf5b8fb5c9 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Tue, 17 Jun 2025 16:45:35 +0000 Subject: [PATCH 2/3] Committing clang-format changes --- docs/source/background/index.rst | 14 ++++++++++++++ docs/source/background/scf_notes.md | 16 ++++++++++++++++ docs/source/background/scf_notes.rst | 14 ++++++++++++++ docs/source/bibliography/index.rst | 14 ++++++++++++++ docs/source/developer/index.rst | 14 ++++++++++++++ docs/source/faqs.rst | 14 ++++++++++++++ docs/source/features.rst | 14 ++++++++++++++ docs/source/install.rst | 14 ++++++++++++++ docs/source/tutorials/index.rst | 14 ++++++++++++++ 9 files changed, 128 insertions(+) diff --git a/docs/source/background/index.rst b/docs/source/background/index.rst index 14290c7..753ddbd 100644 --- a/docs/source/background/index.rst +++ b/docs/source/background/index.rst @@ -1,3 +1,17 @@ +.. Copyright 2025 NWChemEx-Project +.. +.. Licensed under the Apache License, Version 2.0 (the "License"); +.. you may not use this file except in compliance with the License. +.. You may obtain a copy of the License at +.. +.. http://www.apache.org/licenses/LICENSE-2.0 +.. +.. Unless required by applicable law or agreed to in writing, software +.. distributed under the License is distributed on an "AS IS" BASIS, +.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +.. See the License for the specific language governing permissions and +.. limitations under the License. + .. _scf_background: ############## diff --git a/docs/source/background/scf_notes.md b/docs/source/background/scf_notes.md index 9e61aa0..c122a08 100644 --- a/docs/source/background/scf_notes.md +++ b/docs/source/background/scf_notes.md @@ -1,3 +1,19 @@ + + # SCF Procedure ## SCF Driver diff --git a/docs/source/background/scf_notes.rst b/docs/source/background/scf_notes.rst index 6f1d5cf..ba158be 100644 --- a/docs/source/background/scf_notes.rst +++ b/docs/source/background/scf_notes.rst @@ -1,3 +1,17 @@ +.. Copyright 2025 NWChemEx-Project +.. +.. Licensed under the Apache License, Version 2.0 (the "License"); +.. you may not use this file except in compliance with the License. +.. You may obtain a copy of the License at +.. +.. http://www.apache.org/licenses/LICENSE-2.0 +.. +.. Unless required by applicable law or agreed to in writing, software +.. distributed under the License is distributed on an "AS IS" BASIS, +.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +.. See the License for the specific language governing permissions and +.. limitations under the License. + SCF Procedure ============= diff --git a/docs/source/bibliography/index.rst b/docs/source/bibliography/index.rst index 78a16ba..912ced4 100644 --- a/docs/source/bibliography/index.rst +++ b/docs/source/bibliography/index.rst @@ -1,3 +1,17 @@ +.. Copyright 2025 NWChemEx-Project +.. +.. Licensed under the Apache License, Version 2.0 (the "License"); +.. you may not use this file except in compliance with the License. +.. You may obtain a copy of the License at +.. +.. http://www.apache.org/licenses/LICENSE-2.0 +.. +.. Unless required by applicable law or agreed to in writing, software +.. distributed under the License is distributed on an "AS IS" BASIS, +.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +.. See the License for the specific language governing permissions and +.. limitations under the License. + ########## References ########## diff --git a/docs/source/developer/index.rst b/docs/source/developer/index.rst index e4eaac4..43f12f9 100644 --- a/docs/source/developer/index.rst +++ b/docs/source/developer/index.rst @@ -1,3 +1,17 @@ +.. Copyright 2025 NWChemEx-Project +.. +.. Licensed under the Apache License, Version 2.0 (the "License"); +.. you may not use this file except in compliance with the License. +.. You may obtain a copy of the License at +.. +.. http://www.apache.org/licenses/LICENSE-2.0 +.. +.. Unless required by applicable law or agreed to in writing, software +.. distributed under the License is distributed on an "AS IS" BASIS, +.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +.. See the License for the specific language governing permissions and +.. limitations under the License. + .. _scf_developer: ####################### diff --git a/docs/source/faqs.rst b/docs/source/faqs.rst index 5392bd9..2ab40f8 100644 --- a/docs/source/faqs.rst +++ b/docs/source/faqs.rst @@ -1,3 +1,17 @@ +.. Copyright 2025 NWChemEx-Project +.. +.. Licensed under the Apache License, Version 2.0 (the "License"); +.. you may not use this file except in compliance with the License. +.. You may obtain a copy of the License at +.. +.. http://www.apache.org/licenses/LICENSE-2.0 +.. +.. Unless required by applicable law or agreed to in writing, software +.. distributed under the License is distributed on an "AS IS" BASIS, +.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +.. See the License for the specific language governing permissions and +.. limitations under the License. + .. _scf_faqs: ############################## diff --git a/docs/source/features.rst b/docs/source/features.rst index bb22ab1..4a6a9cd 100644 --- a/docs/source/features.rst +++ b/docs/source/features.rst @@ -1,3 +1,17 @@ +.. Copyright 2025 NWChemEx-Project +.. +.. Licensed under the Apache License, Version 2.0 (the "License"); +.. you may not use this file except in compliance with the License. +.. You may obtain a copy of the License at +.. +.. http://www.apache.org/licenses/LICENSE-2.0 +.. +.. Unless required by applicable law or agreed to in writing, software +.. distributed under the License is distributed on an "AS IS" BASIS, +.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +.. See the License for the specific language governing permissions and +.. limitations under the License. + #################### List of SCF Features #################### diff --git a/docs/source/install.rst b/docs/source/install.rst index db4fb10..5d37ff9 100644 --- a/docs/source/install.rst +++ b/docs/source/install.rst @@ -1,3 +1,17 @@ +.. Copyright 2025 NWChemEx-Project +.. +.. Licensed under the Apache License, Version 2.0 (the "License"); +.. you may not use this file except in compliance with the License. +.. You may obtain a copy of the License at +.. +.. http://www.apache.org/licenses/LICENSE-2.0 +.. +.. Unless required by applicable law or agreed to in writing, software +.. distributed under the License is distributed on an "AS IS" BASIS, +.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +.. See the License for the specific language governing permissions and +.. limitations under the License. + .. _installing_scf: ############## diff --git a/docs/source/tutorials/index.rst b/docs/source/tutorials/index.rst index e6f5b63..1e0dd51 100644 --- a/docs/source/tutorials/index.rst +++ b/docs/source/tutorials/index.rst @@ -1,3 +1,17 @@ +.. Copyright 2025 NWChemEx-Project +.. +.. Licensed under the Apache License, Version 2.0 (the "License"); +.. you may not use this file except in compliance with the License. +.. You may obtain a copy of the License at +.. +.. http://www.apache.org/licenses/LICENSE-2.0 +.. +.. Unless required by applicable law or agreed to in writing, software +.. distributed under the License is distributed on an "AS IS" BASIS, +.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +.. See the License for the specific language governing permissions and +.. limitations under the License. + .. _scf_tutorials: From ece07431296f3ff88b73703d2f6d53adb2777372 Mon Sep 17 00:00:00 2001 From: Jacob Heflin Date: Thu, 19 Jun 2025 15:44:36 -0500 Subject: [PATCH 3/3] adjusting toctree --- docs/source/background/index.rst | 5 +++++ docs/source/bibliography/index.rst | 2 +- 2 files changed, 6 insertions(+), 1 deletion(-) diff --git a/docs/source/background/index.rst b/docs/source/background/index.rst index 753ddbd..468d5de 100644 --- a/docs/source/background/index.rst +++ b/docs/source/background/index.rst @@ -21,3 +21,8 @@ SCF Background Literally the book Modern Quantum Chemistry by Szabo and Ostlund .. image:: ../assets/scf_architecture.png + +.. toctree:: + :maxdepth: 2 + + scf_notes.rst diff --git a/docs/source/bibliography/index.rst b/docs/source/bibliography/index.rst index 912ced4..935aab7 100644 --- a/docs/source/bibliography/index.rst +++ b/docs/source/bibliography/index.rst @@ -20,4 +20,4 @@ You know the book or Helgaker if you're really bought in -.. bibliography:: +.. .. bibliography::