/ampsci

Solves the Dirac equation for single-valence atomic systems using the Hartree-Fock + correlation potential method. Calculates ionisation cross sections with high values for energy/momentum transfer

Primary LanguageC++

ampsci

Atomic Many-body Perturbation theory in the Screened Coulomb Interaction

Solves the Dirac equation for single-valence atomic systems using the Hartree-Fock + correlation potential method (Dzuba-Flambaum-Sushkov method). Fully relativistic, includes electron correlations (all-orders screening and hole-particle interaction), finite-nuclear size, Breit interaction, radiative QED effects, and RPA for matrix elements (with structure radiation/renormalisation). QED is included via the Ginges-Flambaum radiative potential method. Can solve for continuum states with high energy. Calculates ionisation cross sections with high values for energy/momentum transfer. Parallelised using openMP.

Designed to be fast, accurate, and easy to use. The "modules" system (see documentation) makes it simple to add your own routines to use the atomic wavefunctions to calculate whatever properties you may be interested in.

Documentation

There are four documentation types provided:

  1. README (this document)

    • Brief overview, including compilation instructions (given below)

  2. Input options -- how to run the code

    • doc/ampsci_input.md -- detailed info on all input options
      • Best viewed with a markdown reader or on GitHub
    • See also: doc/examples/ampsci.in -- an example/template input file
    • In doc/examples/ there are several example input files, with the expected output; use these to test if everything is working

  3. Physics documentation: ampsci.pdf -- Description of physics/methods used in the code

    • Includes many references to the works where the methods implemented here were developed.
    • Available online: benroberts999.github.io/ampsci/ampsci.pdf
    • Latex file provided in doc/tex/ampsci.tex
    • If you have latex installed, you can use Makefile to generate the pdf
      • Run '$make docs' -- this will create new pdf file: 'doc/ampsci.pdf'

  4. Code documentation -- details on classes/functions in the code

    • Available online: benroberts999.github.io/ampsci/
    • Auto-generated (Doxygen), so be wary of mistakes/typos etc.
    • You can generate this by running '$make doxy', which produces html documentation (see doc/html/index.html), and a pdf version (doc/documentation.pdf) -- but it's much easier to view this online

Compilation:

  • Copy "doc/Makefile.example" from doc/ directory to the working directory, and rename to -> "Makefile"
    • $cp ./doc/Makefile.example ./Makefile
  • All programs compiled using the Makefile (run $make)
  • The file Makefile has some basic compilation options. It's currently set up to work on most linux systems; you may need to change a few options for others (see below)
  • Tested with g++ and clang++ on linux and mac (requires c++17)
    • Works+tested with g++7 and newer
    • Works+tested with clang++6 and newer

Requires GSL (GNU scientific libraries) https://www.gnu.org/software/gsl/, and LAPACK. These must be installed for the code to run (see below).

  • Requires GSL ver 2.0+ (tested with 2.1, 2.6)

  • Quick start (ubuntu). Full dependencies list, run:

    • $sudo apt install g++ clang++ make liblapack-dev libblas-dev libgsl-dev libomp5 libomp-dev

Compilation: Linux:

  • Instructions for ubuntu; similar commands for other flavours
  • Install make: $sudo apt-get install make
  • Install GSL libraries: $sudo apt-get install libgsl-dev
  • May also need LAPACK/BLAS libraries: $sudo apt-get install libatlas-base-dev liblapack-dev libblas-dev
  • Install the compiler: $sudo apt-get install g++ and/or $sudo apt-get install clang++
  • Then compile by running $make from the ampsci directory
  • To use with openMP (for parallelisation) with clang++, you might have to also install clangs openmp libraries: $sudo apt install libomp5 (and perhaps $sudo apt install libomp-dev)

Compilation: MacOS:

  • On mac: use homebrew to install gsl: $brew install gsl
  • (homebrew is a package manager; install from https://brew.sh/)
  • Seems to work best with the homebrew version of gcc. Install as: $brew install gcc
  • Note: you may need to change the compiler from g++ to g++-9 (or similar), or update your environment variables, since calling g++ on mac actually calls clang++ by default
  • You might have to tell the compiler how to link to the GSL library; in Makefile:
    • PathForGSL=/usr/local/opt/gnu-scientific-library
  • Then compile by running $make from the ampsci directory
  • Use openMP for parellelisation when using clang++ on mac:
    • If using g++, should work as per normal
    • To use openMP with clang, seem to require the llvm version
    • $brew install llvm
    • Then, in the Makefile, set (exact paths may be different for you):
      • CXX=/usr/local/opt/llvm/bin/clang++
      • ExtraInclude=/usr/local/opt/llvm/include/
      • ExtraLink=/usr/local/opt/llvm/lib/
    • Note: For me, I have to set OPT=-O1 for this to work, otherwise takes infinite time to compile.

Compilation: Windows:

For windows, the easiest way (for me, anyway) is to use the 'windows subsystem for linux' (requires Windows10). Instructions on installation/use here: https://www.roberts999.com/posts/2018/11/wsl-coding-windows-ubuntu. Then, the compilation + use can proceed as per Linux above. In theory, should work with MSVC - but no CMAKE file provided (yet)

Common Compilation errors:

  • error: unsupported option -fopenmp
  • openmp (used for parallelisation) is not working. See above for some possible solutions.
  • Quick fix: change 'UseOpenMP=yes' to 'UseOpenMP=no' in Makefile
  • fatal error: gsl/<...>.h: No such file or directory (or similar)
  • gsl related linking/compilation error:
  • Could not find required GSL libraries. Either they are not installed, or you need to link to them
    1. Ensure GSL is installed (see above for instructions)
    1. If GSL library is not installed in /usr/local/, you have to tell the compiler where to find the GSL files. Do this by setting the PathForGSL option in Makefile. Common examples:
    • PathForGSL=/opt/gsl/2.1/gnu # For UQ's getafix cluster
    • PathForGSL=/usr/local/opt/gnu-scientific-library # For my macbook
    • Note: the exact path may differ for you, depending on where GSL was installed
  • error: too few arguments to function ‘int gsl_bspline_deriv_eval
  • This is because the code is linking to a very old version of GSL. You might need to update GSL. If you have updated GSL (to at least version 2.0) and still get the message, the code is probably linking against the wrong version of GSL; see above to point the compiler to the correct version
  • other:
  • Sometimes, the compiler will not be able to find the correct libraries (particular, e.g., on clusters). In this case, there are two options in the Makfefile: ExtraInclude and ExtraLink
    • These add paths to include the correct directories for both -I "includes" (for compilation), and -L link flags (for linking libraries) in Makefile. These can be a little tricky to get right (don't include the -I or -L)

ampsci (main program)

  • Input taken from a plain text file (or via command line).
  • Several example input files are given in: doc/examples/, along with their expected output; use these to test if everything is working.
  • You may re-name the input files (e.g., to "filename.txt"), then run as:
    • $ ./ampsci filename.txt
    • If no input filename is given, program will assume input filename is 'ampsci.in':
  • Note: input file uses c++-like format, including c++-style comments
  • See doc/ampsci_input.md for a full list of input options + descriptions
  • See ampsci.pdf for a description of the physics, and for references to the works where the methods implemented here were developed.

Other programs:

periodicTable

Command-line periodic table, with electron configurations, nuclear data, and some physical constants

  • Compiled using the Makefile (run $make, must have 'make' installed)
  • Alternatively, compile with command:
    • $g++ -std=c++17 src/Physics/AtomData.cpp src/Physics/NuclearData.cpp src/periodicTable.cpp -o periodicTable -I./src/
  • No other dependencies

Gives info regarding particular element, including Z, default A, and electron configuration. Takes input in one line from command line.

Usage: (examples)

  • $./periodicTable -- Prints periodic table
  • $./periodicTable Cs -- Info for Cs with default A
  • $./periodicTable Cs 137 -- Info for Cs-137
  • $./periodicTable Cs all -- Info for all available Cs isotopes
  • Note: numbers come from online database, and have some errors, so should be checked if needed.

Or, enter 'c' to print list of physics constants

  • $./periodicTable c -- Prints values for some handy physical constants

Note: ground-state electron configurations are "guessed", and can sometimes be incorrect.

Nuclear data mostly comes from:

  • Radius data: I. Angeli and K. P. Marinova, At. Data Nucl. Data Tables 99, 69 (2013). doi:10.1016/j.adt.2011.12.006
  • Magnetic moments: N. Stone, At. Data Nucl. Data Tables 90, 75 (2005). doi:10.1016/j.adt.2005.04.001
  • Note: data was scraped from the tables, and contains many transcription errors. Provided for convenience, but it is up to you to double check that the values are correct/up-to-date

Units:

  • r_rms: root-mean-square radius, in fm.
  • c: half-density radius (assuming Fermi nuclear distro, with t=2.3)
  • mu: magnetic moment (in nuclear magnetons)

wigner

  • Small routine to calculate 3,6,9-j symbols, and Clebsch Gordon coefficients
  • Either give input via command line directly (quote marks required)
    • e.g., ./wigner '<0.5 -0.5, 0.5 0.5| 1 0>'
    • or e.g., ./wigner '(0.5 1 0.5, -0.5 0 0.5)' etc.
  • Or, give an input file, that contains any number of symbols, all on new line
    • e.g., ./wigner -f myInputFile.in
    • nb: the '-f' flag can be dropped in the '.in' file extension is used
    • Do not use quote marks in input file. Lines marked '!' or '#' are comments
  • 3j symbols must start with '('; 6,9j with '{', and CG with '<' (this is how code knows which symbol to calculate).
  • but, each number can be separated by any symbol (space, comma etc.)

dmeXSection