|
ampsci
c++ program for high-precision atomic structure calculations of single-valence systems
|
brief Basic tutorial for using ampsci, including examples.
This assumes you already have ampsci compiled.
Open up a terminal and navigate to the directory where ampsci was compiled.
First, just run the executable:
No calculation was performed, however, some instructions should be printed to the screen. These should serve as a reminder if you forget any of the commands we will look at below. You can also run:
which will print the same.
Now, try the following, which should print the current version info (including the git commit hash, if you're using git). You can use this to check which exact version of the code you are running. This is also automatically printed when you run any calculation.
To actually perform an atomic calculation, we need to tell ampsci what we want to calculate.
Typically, this is done using an input file where we specify all the options. For very simple calculations, however, we can do this directly from the command line using the form:
(where <Core> and <Valence> are both optional). For example, the following should all produce the same result. They will calculate Hartree-Fock for Cs, including all the electrons in the "core" (so-called \(V^N\) approximation).
[] is a noble gas, but in ampsci you can put any atom (the core configuration for non-noble-gas atoms is guessed based on simple filling rules, and is sometimes not correct, so always check the output!).The next few cases will calculate Hartree-Fock for Cs, using the \(V^{N-1}\) approximation, including valence states up to \(n=7\) for \(s\) and \(p\) states, and \(n=5\) for \(d\) states:
For anything more complicated, we must use an input file.
Input is a plain text file that consists of sets of 'Blocks' and 'Options'.
Firstly, we can use the code to tell us which input options are available using the -a (or --ampsci) command-line option:
This will print the list of available top-level "Input Blocks". The output will look something like this:
This will be in the correct format for the input file, so we can start making our input file by copy+pasting these. We don't need all the options, so let's start with just the basics: Atom{}, Grid{}, and HartreeFock{}. In each of these blocks, we can specify certain options; most have default values, and can be thus left blank. We can also ask the code to tell us which options are available for each block, for example:
The output will list all options for the Atom{} block:
This is also in the correct format for the input file, so we can copy+paste into our input file.
// is a comment and will be ignored by the program.} at the end of each input block, and the semi-colon ; after each option!We can list more than one block name for this. For example, try:
which will give something like:
We will use the above to create our first simple We will call this text file example.in, but any filename is OK (the .in file extension is just by convention; you may use .txt or anything else). We may then set up the input file like:
From the Atom{} block, we have chosen to run calculations for Cs-133. Since we did not set any parameters in the Nucleus{} block, the code will run using the default nuclear parameters (which are looked up based on the isotope).
In the Grid{} block, we specify the discrete radial grid to have 3000 grid points dispersed between the range [1.0e-6, 150.0] atomic units (atomic unit of length is the Bohr radius: \(1\,{\rm au}=1\,a_0 = \tfrac{4\pi\epsilon_0\hbar^2}{m_e e^2}\approx 5.3\times10^{-11}\,{\rm m}\)). Since we did not specify a grid type the default (log-linear) will be used (see ampsci.pdf).
Finally, in the HartreeFock{} block, we specify that we wish to solve Hartree-Fock equations for Cs with a Xe-like core, and consider valence states up to \(n=5\) for \(s,p\)-states, and \(n=5\) for \(d\)-states. Since a Xenon-like core has 1 fewer electrons than neutral Cs, this is a \(V^{N-1}\) calculation. Note that the format for the core configuration copies that used by NIST in their periodic table. A nice copy can be downloaded from here.
You may also use the built-in periodic table to see the possible ground-state electron configuration:
Caution: this "guesses" the configuration based on simple filling rules, so may not be the true ground-state configuration.
If we run the code with the above input file:
we will get something like the following output:
For calculations that matter, the entire output should be saved. The best way to do this is to forward the output directly to a text file when running the code. The input options and the ampsci version details are also printed, so that the program output contains all required info to exactly reproduce it. A nice way to do this is by piping the output through the unix tee program: e.g.,
-a) to file "example.out".It's important to understand the meaning of the program output. The first part of the output just prints the version information for ampsci. This is important for reproducing old results, which may depend on the ampsci version.
Then, the entire set of input options is printed. This is useful, since it tells you explicitly which calculations were run, and is very useful for catching mistakes and reproducing old calculations. Importantly, the format is exactly what is required on input, so to re-run the calculation, this can simply be copy+pasted into a new input file.
s+ = \(s_{1/2}\), p- = \(p_{1/2}\), p+ = \(p_{3/2}\), d- = \(d_{3/2}\), and so on0 (i.e., floating point underflowed) in 38 iterationsstate: which core statek: value of \(\kappa\) (Dirac quantum number) for stateRinf: Radius of the 'practical infinity', i.e., point on the radial grid where that orbital can be safely said to be zero. It's crucial to check all of these values lie well below rmax (set in Grid{}). If these are close to rmax, rmax should be increased.its: Number of iterations it took to solve the single-particle Dirac equation upon the final Hartree-Fock iterationeps: Extent to which the single-particle energy converged when solving the Dirac equation upon the last Hartree-Fock iteration. These numbers should be extremely small; if any are larger, it means there is possibly a serious numerical error. Normally, these will always be fine, so long as Hartree-Fock convergedEn (au) and En (/cm) are the single-particle (binding) energies in atomic units and \({\rm cm}^{-1}\), respectively. Atomic unit for energy is the Hartree: \(E_h = 2 Ry = \frac{\hbar^2}{m_e a_0^2} \approx 27.2\,{\rm eV}\).E_c is the total Hartree-Fock energy of the core, in atomic unitsTo do more complicated calculations, including constructing complete set of basis orbitals, and including core-valence correlations, see:
The general usage of the code is to first use the main blocks to construct the atomic wavefunction and basis states, then to add as many 'Module::' blocks as required. Each module is a separate routine that will take the calculated wavefunction and compute any desired property (e.g., matrix elements). The code is designed such that anyone can write a new Module (See doc/writing_modules.md)
Above, we ran ampsci, which calculated the atomic wavefunctions and printed their energies to screen. If we want to actually do anything with the wavefunctions, we have to run one or more modules. We do this by adding a module block to the input file, which has the form Module::ModuleName{}
Here, we will just consider a simple example. For further detail:
We can see a list of all available modules with the -m command-line option
Many are listed. Here we will consider the simple/common example of matrixElements module, which (unsurprisingly) calculates matrix elements.
To see the available options for this block, list the block name after -m on the command-line:
which prints:
The first option, operator is which operator we want to calculate matrix elements of. You can see a list of operators with the -o command-line option:
The second option, which is a sub-input-block, options is the set of options for the given operator. Most operators have no extra options, so this can be left blank. Some (e.g., hyperfine operator hfs have many available options). Like above, you can see the available options by further passing the operator name after -o. For example:
Here we will consider the simpler E1 operator. To our above example.in file, we can add the following block (note we may add as many Module:: blocks as we like, they will all be run one-by-one in order):
The omega = 0.0; option means we have solved RPA equations for each transition at zero frequency. It is also possible to automatically solve RPA for each transition frequency by setting: omega = each;. See ampsci.pdf for description of RPA.
The output format will depend on the specific module. In this case, we are shown the extent to which the RPA (/TDHF) equations converged, and then the valued of the reduced matrix elements are printed (at the Hartree-Fock, first-order core-polarisation, and all-orders RPA levels)
1.9.1