- Generated on Wed Mar 11 2026 08:43:17 for ampsci by
1.9.8
|
ampsci
High-precision calculations for one- and two-valence atomic systems
|
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 -i (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 nist.gov/pml/periodic-table-elements.
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 units 1.9.8