GitHub

ElemCo.jl Documentation

ElemCo.jl (elemcoil) is a Julia package for computing electronic structure properties of molecules and materials. It provides a set of tools for performing quantum chemical calculations, including Hartree-Fock and post-HF methods.

Installation

You can install ElemCo.jl using the Julia package manager:

julia> using Pkg
julia> Pkg.add("ElemCo")

For a development version of ElemCo.jl, clone the ElemCo.jl-devel repository and create an alias to set the project to the ElemCo.jl directory,

alias jlm='julia --project=<path_to_ElemCo.jl>'

Start jlm in the terminal and run the following command to install the dependencies,

julia> using Pkg
julia> Pkg.instantiate()

Now the command jlm can be used to start the calculations,

jlm input.jl

It is recommended to activate the precompilation in the TensorOperations module to reduce the precompilation time of ElemCo.jl.

Usage

Input file

The input file is a Julia script that contains the calculation details. The script should start with the following lines,

using ElemCo
@print_input

The @print_input macro prints the input file to the standard output. The calculation details are specified using the macros provided by ElemCo.jl.

Macros

The following macros are available in ElemCo.jl (see the documentation for more details and macros),

  • @hf/@uhf - Performs a Hartree-Fock calculation.
  • @dfhf - Performs a density-fitted Hartree-Fock calculation.
  • @cc<method> - Performs a coupled cluster calculation.
  • @dfcc<method> - Performs a coupled cluster calculation using density-fitted integrals in the correlation treatment.
  • @ints - Generates the exact AO integral files (done automatically by @hf/@uhf).
  • @dfints/@moints - Generates a persistent MO integral set (density-fitted / from the exact AO integrals).
  • @set<option> <setting> - Sets the options(ElemCo.ECInfos.Options) for the calculation.

etc.

Default scratch directory path on Windows is the first environment variable found in the ordered list TMP, TEMP, USERPROFILE. On all other operating systems TMPDIR, TMP, TEMP, and TEMPDIR. If none of these are found, the path /tmp is used. Default scratch folder name is elemcojlscr.

Variable names fcidump, geometry and basis are reserved for the file name of FCIDUMP, geometry specification and basis sets, respectively.

Input generation and orbital visualizer

ElemCo.jl input files can be generated using jlmol, which can also be used to visualize the molecular orbitals. The browser version of jlmol can be found at app.jlmol.com.

Computing Hartree-Fock and Coupled Cluster methods

The correlated methods follow the integrals of the reference. The default first-class route uses the exact (non-density-fitted) AO integrals: @hf (or @uhf) generates the AO integral files (as @ints would) and computes the Hartree-Fock reference from them, and a subsequent @cc runs AO-direct – MP2, CCSD/DCSD and their variants, (T), the Lambda equations and properties, EOM and SVD-DC-CCSDT contract the AO integrals directly, and no full MO integral set is ever formed:

using ElemCo
@print_input
geometry="bohr
     O      0.000000000    0.000000000   -0.130186067
     H1     0.000000000    1.489124508    1.033245507
     H2     0.000000000   -1.489124508    1.033245507"

basis = "cc-pVDZ"
@hf
@cc ccsd(t)

Computing density-fitted Hartree-Fock and Coupled Cluster methods

With a density-fitted reference (@dfhf) the correlation treatment uses density-fitted integrals: the MO integrals are generated on the fly inside the @cc calculation and deleted when the driver returns. If several calculations should share one MO integral set, generate it explicitly with @dfints (it then persists and is yours to refresh); @moints is the exact-AO counterpart. After @dfhf, the exact-AO route can still be selected with @ints before @cc (or @set int df=false); conversely @set int ao_direct=false routes an exact-AO calculation through a derived MO dump. Every correlated run prints one line stating which integrals it uses. Here's an example:

using ElemCo

# Print input to the output file
@print_input
# Define the molecule
geometry="bohr
     O      0.000000000    0.000000000   -0.130186067
     H1     0.000000000    1.489124508    1.033245507
     H2     0.000000000   -1.489124508    1.033245507"


basis = Dict("ao"=>"cc-pVDZ",
             "jkfit"=>"cc-pvtz-jkfit",
             "mpfit"=>"cc-pvdz-mpfit")

# Compute DF-HF 
@dfhf
# Calculate MO integrals (optional)
@dfints
# Run CCSD(T) calculation
@cc ccsd(t)

This code defines a water molecule, computes DF-HF using the cc-pVDZ basis set, calculates integrals using density fitting (mpfit basis) and computes CCSD(T) energy.

Setting options

To set options (ElemCo.ECInfos.Options) for the DF-HF, CC, etc calculations, you can use the @set macro. Here's an example of how you can use this macro:

# Set the maximum number of iterations to 10
@set scf maxit=10

# Compute DF-HF using the new options
@dfhf

This code sets the maximum number of iterations for the SCF procedure to 10 using the @set macro, and then computes DF-HF using the new options using the @dfhf macro.

Precompilation

ElemCo.jl uses PrecompileTools.jl to reduce time-to-first-execution. By default the coupled cluster and FCI workloads are precompiled in release builds. You can select which parts of the code to precompile using the Preferences.jl mechanism by editing LocalPreferences.toml in the project directory:

[ElemCo]
precompile_workload = true   # master toggle (default: true for releases, false for development builds)
precompile_cc = true          # coupled cluster methods (DCSD, UCCSD, SVD-DCSD, MP2)
precompile_fci = true         # FCI
precompile_mcscf = false      # DF-MCSCF
precompile_complex = false    # complex-valued calculations

Alternatively, preferences can be set from the Julia REPL:

using Preferences, ElemCo
set_preferences!(ElemCo,
                 "precompile_workload" => true,
                 "precompile_cc" => true,
                 "precompile_fci" => true,
                 "precompile_mcscf" => true;
                 force=true)

To disable all precompilation (e.g. during development):

[ElemCo]
precompile_workload = false

Using AVX2 instructions on AMD "Zen" machines

MKL tends to be rather slow on AMD "Zen" machines (stand 2024). To use AVX2 instructions in MKL on AMD "Zen" machines, you can slightly modify the mkl libraries by running the ElemCo.amdmkl function, which will replace two symbolic links with compiled libraries that enforce the AVX2 instructions,

using ElemCo
ElemCo.amdmkl()

Note: this function has to be called in a separate script (separate Julia session) before running the calculations, i.e., your workflow can look like this:

> julia -e 'using ElemCo; ElemCo.amdmkl()'
> julia input.jl

One can revert the changes by running the function with the argument true,

using ElemCo
ElemCo.amdmkl(true)

Documentation

Equations for the methods implemented in ElemCo.jl.