Docs update #26
Docs update #26
Conversation
ryanmrichard
left a comment
ryanmrichard
left a comment
There was a problem hiding this comment.
This looks like you're on the right track.
| ## SCF Driver | ||
|
|
||
| 1. Obtain the AO parameters as well as the chemical system (inputs) | ||
| 2. Assign the AO parameters as atomic orbitals |
There was a problem hiding this comment.
I assume this is referring to a line where we go from an AOBasisSet to an AOSpace. There's no physical meaning behind that. That's just a type conversion.
There was a problem hiding this comment.
IMHO, step 2 should read something like:
Mathematically, the inputs to the SCF procedure are a trial wavefunction and a Hamiltonian. Here, the input `ChemicalSystem` is converted to a Hamiltonian by calling a module of property type `WhateverPT`. By default, this is done subject to the Born-Openheimer approximation (i.e., the resulting Hamiltonian will contain the pair-wise interactions of all the particles, but only the kinetic energy of the electrons).
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).
| 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 |
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).
| 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 |
| 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 |
There was a problem hiding this comment.
How does this differ from 5?
| 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"); |
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.
|
|
||
| ### SCF Loop | ||
|
|
||
| 5. The work horse of the module, the submod "Optimizer", uses `scf_loop.cpp` and the module `Loop` to optimize |
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 Optimize<Types,Go,Here>.
| ```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`. |
There was a problem hiding this comment.
Make sure you understand what these lines do and what the interface means.
| 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 |
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. |
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"
| You know the book | ||
|
|
||
| or Helgaker if you're really bought in |
There was a problem hiding this comment.
These are supposed to be bibtex references. I'd just leave this blank for now.
Is this pull request associated with an issue(s)?
Working to improve the documentation of the NWChemEx SCF
Description
This will (hopefully) result in documentation of the NWChemEx SCF that explains the underlying procedure of the SCF Driver.
TODOs