Docs update #26
There are no files selected for viewing
File renamed without changes
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,23 @@ | ||
| .. 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: | ||
|
|
||
| ############## | ||
| SCF Background | ||
| ############## | ||
|
|
||
| Literally the book Modern Quantum Chemistry by Szabo and Ostlund | ||
|
|
||
| .. image:: ../assets/scf_architecture.png |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,86 @@ | ||
| <!-- | ||
| ~ 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 | ||
|
|
||
| ## 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 | ||
|
Member
There was a problem hiding this comment. Each electron-nuclei pair gets a term. Nuclei don't get a term unless there are electrons present (or if the code tries to give the nuclei a term when no electrons are present it shouldn't). |
||
| 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 | ||
|
Member
There was a problem hiding this comment. How does this differ from 5? |
||
| 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 | ||
|
Comment on lines
+34
to
+35
Member
There was a problem hiding this comment. Here I'm thinking something more like: We don't want the core guess to be the long-term default, so I'd avoid saying it's the default. Again, the details of what happens in the module should be described in the documentation for the module. |
||
| 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"); | ||
|
Comment on lines
+40
to
+44
Member
There was a problem hiding this comment. This is counting the number of electrons by looping over terms in the Hamiltonian. It's an implementation detail of the module and doesn't need to be here. |
||
|
|
||
| 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); | ||
|
Comment on lines
+46
to
+48
Member
There was a problem hiding this comment. This establishes the occupations of the orbitals based on the orbital energies and the number of electrons. |
||
|
|
||
| rscf_wf zero_guess(occs, cmos); | ||
| auto& update_mod = submods.at("Guess updater"); | ||
| const auto& Psi0 = update_mod.run_as<update_pt>(f, zero_guess);``` | ||
|
Comment on lines
+50
to
+52
Member
There was a problem hiding this comment. This builds the initial guess from the zero density and the corresponding Fock operator. |
||
|
|
||
| 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 | ||
|
Member
There was a problem hiding this comment. I like how you separated the loop from the driver. I'd finish out the driver section first though, by adding a step that says something like "the SCF energy is then optimized with respect to the wavefunction by calling a module of property type |
||
| the wavefunction. It takes in a Bracket via <Psi0 | H | Psi0> = H00, and Psi0. The property type it satisfies is | ||
| ```cpp | ||
| using pt = simde::Optimize<egy_pt<WfType>, WfType>; | ||
| using egy_pt = simde::eval_braket<WfType, hamiltonian, WfType>; | ||
| using wf_type = simde::type::rscf_wf; | ||
| satisfies_property_type<pt<wf_type>>; | ||
| ``` | ||
| and the return result type is the `WfType`, or in this case the `simde::type::rscf_wf`. | ||
|
Comment on lines
+60
to
+66
Member
There was a problem hiding this comment. Make sure you understand what these lines do and what the interface means. |
||
|
|
||
| 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 | ||
|
Member
There was a problem hiding this comment. Arguably, the SCF process has already started. I'd suggest "Iteratively refine the wavefunction". |
||
| 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. | ||
|
Comment on lines
+74
to
+83
Member
There was a problem hiding this comment. I'd add details about what property types are used to do these steps and what the default algorithms are currently. Would be good to add a comment to the source code where we set the defaults to say "if you change the defaults please update /path/to/this/documentation/file accordingly" |
||
|
|
||
| ### Return results | ||
| 6. From here, the energy that is of type Tensor and the optimized wavefunction is returned. | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,112 @@ | ||
| .. 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 | ||
| ============= | ||
|
|
||
| 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 <Psi0 \| H \| Psi0> = H00, | ||
| and Psi0. The property type it satisfies is | ||
| ``cpp using pt = simde::Optimize<egy_pt<WfType>, WfType>; using egy_pt = simde::eval_braket<WfType, hamiltonian, WfType>; using wf_type = simde::type::rscf_wf; satisfies_property_type<pt<wf_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. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,23 @@ | ||
| .. 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 | ||
| ########## | ||
|
|
||
| You know the book | ||
|
|
||
| or Helgaker if you're really bought in | ||
|
Comment on lines
+19
to
+21
Member
There was a problem hiding this comment. These are supposed to be bibtex references. I'd just leave this blank for now. |
||
|
|
||
| .. bibliography:: | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,21 @@ | ||
| .. 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: | ||
|
|
||
| ####################### | ||
| Developer Documentation | ||
| ####################### | ||
|
|
||
| If you can do it better I'd like to see you try. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,19 @@ | ||
| .. 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: | ||
|
|
||
| ############################## | ||
| SCF Frequently Asked Questions | ||
| ############################## |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,19 @@ | ||
| .. 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 | ||
| #################### | ||
|
|
||
| So far a pretty neat scf! |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,19 @@ | ||
| .. 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: | ||
|
|
||
| ############## | ||
| Installing SCF | ||
| ############## |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,23 @@ | ||
| .. 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: | ||
|
|
||
|
|
||
| ############# | ||
| SCF Tutorials | ||
| ############# | ||
|
|
||
| I have never seen anyone do an scf by hand so we're probably just guessing at | ||
| this point. |
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I assume this is referring to a line where we go from an
AOBasisSetto anAOSpace. There's no physical meaning behind that. That's just a type conversion.There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
IMHO, step 2 should read something like:
In my mind, you wouldn't go into further details of the "Hamiltonian" module here (that would be reserved for the module documentation of "Hamiltonian" and linked to here).