Installation¶

DMFTwDFT3 is configured for Python 3.11 environments.

The installation has five parts,

Clone the repository.
Create a Python environment.
Choose and edit the root Makefile.in build configuration.
Run setup.py, which builds the internal and external components and installs them into bin. This step also sets up the required environmental variables.
Set up the external executables for Wannier90 and the DFT code(s) you intend to use.

Cloning the Repository¶

DMFTwDFT is built from source, so start by cloning the repository and working from within it. All subsequent commands assume the repository root as the working directory.

git clone https://github.com/dmftwdft/DMFTwDFT3.git
cd DMFTwDFT3

If you have SSH keys configured with GitHub, you can clone over SSH instead,

git clone git@github.com:dmftwdft/DMFTwDFT3.git

Python Environment¶

Recommended environment files are provided in the repository root,

Linux: environment.yml
macOS: environment.macos.yml

For example, on Linux,

mamba env create -f environment.yml
mamba activate dmft

Build Configuration¶

Copy a template from config to the repository root as Makefile.in, then edit paths and compiler choices for your machine and run the setup.

cp config/Makefile.in.gnu Makefile.in
python setup.py

Available templates,

config/Makefile.in.gnu: GNU compilers on Linux systems.
config/Makefile.in.intel: Intel oneAPI compilers on Linux systems.
config/Makefile.in.mac: macOS Apple Silicon/Homebrew OpenMPI build.

The root Makefile.in is the user-managed build configuration that governs the compilation of DMFTwDFT and its dependencies. setup.py regenerates internal build files such as sources/make.inc and the staged eDMFT Makefile.in from the root file. Do not edit generated build files unless you are debugging a build.

The compiled-library dependencies include,

GSL
LAPACK
BLAS
FFTW
MPI

Linux GNU¶

For a GNU compiler stack, start from,

cp config/Makefile.in.gnu Makefile.in

Check that Makefile.in points to the correct BLAS, LAPACK, GSL, FFTW, and MPI locations on your system. The template assumes common Linux-style library paths; adjust LALIB, GSLLIB, compiler commands, and additional flags as needed.

The GNU template assumes that liblapack.a, libblas.a, and GSL libraries are installed in /usr/local/lib. If your system uses different paths, modify LALIB and GSLLIB in Makefile.in. Use FFLAGSEXTRA for additional compiler flags required by your compiler or platform.

Linux Intel OneAPI¶

For Intel oneAPI compilers on a cluster, start from,

cp config/Makefile.in.intel Makefile.in

Most of the necessary libraries for the Intel setup will come from the Intel MKL library. Ensure that $MKLROOT is set correctly in your environment.

macOS Apple Silicon¶

For Apple Silicon, start from,

mamba env create -f environment.macos.yml
mamba activate dmft
cp config/Makefile.in.mac Makefile.in
python setup.py

Use one MPI implementation end-to-end. The macOS template is intended for Homebrew OpenMPI, so use Homebrew mpirun, Homebrew MPI compiler wrappers, and binaries/extensions linked to Homebrew OpenMPI.

Keep every compiled component on the same architecture and MPI stack. On Apple Silicon, use Homebrew OpenMPI consistently for mpirun, mpi4py, DMFTwDFT, CTQMC, Wannier90, and DFT interfaces.

Do not mix Homebrew OpenMPI with conda MPICH-linked components. In particular, make sure these components use the same MPI ABI,

mpi4py
dmft.x
dmft_dos.x
dmft_ksum_band
dmft_ksum_partial_band
ctqmc
Wannier90 executables
DFT executables launched under MPI

On Apple Silicon, also keep every compiled component native arm64. Do not mix x86_64 Wannier90, SIESTA, or CTQMC binaries with an arm64 Python environment and libraries.

Setup Output¶

If compilation succeeds, the following executables and libraries are copied to bin,

dmft.x: performs the DMFT k-point sum and computes G_loc.out and Delta.inp.
dmft_dos.x: performs DOS calculation.
dmft_ksum_band: performs band-structure calculation.
dmft_ksum_partial_band: performs projected band-structure calculation.
fort_kpt_tools.so: Fortran-based k-point utility module.
ctqmc: CTQMC impurity solver.
gaunt.so, dpybind.so, maxent_routines.so, and related impurity/maxent helpers.

Shell Setup¶

setup.py automatically updates your default shell startup file so the main commands and utilities are available from the shell. It adds bin and utilities to $PATH, and adds bin to $PYTHONPATH for DMFTwDFT Python imports,

~/.zshrc when $SHELL is zsh
~/.bashrc otherwise

The block looks like the following.

# >>> DMFTwDFT setup >>>
export PATH="/path/to/DMFTwDFT3/utilities/:$PATH"
export PATH="/path/to/DMFTwDFT3/bin/:$PATH"
export PYTHONPATH="/path/to/DMFTwDFT3/bin/:$PYTHONPATH"
# <<< DMFTwDFT setup <<<

Restart your shell after setup, or source the file printed by setup.py.

External Executables¶

setup.py builds only the DMFTwDFT components listed above. It does not build Wannier90 or any DFT code, and the installation will complete successfully without them. Before running a calculation you must build these separately and make their executables available to DMFTwDFT.

Copy or symlink these executables into the DMFTwDFT bin directory. DMFTwDFT locates bin from the installed package itself. Each executable is looked up in bin first and called by absolute path when found, falling back to the bare name on $PATH otherwise. This keeps system- or module-provided builds usable without copying them, while making bin authoritative when both are present.

Wannier90¶

DMFTwDFT requires wannier90.x and w90chk2chk.x. You can get them from Wannier90. VASP workflows also require VASP to be compiled with Wannier90 support.

Note

Newer versions of w90chk2chk.x may not be compatible with DMFTwDFT, so we recommend using the v2.1.0 release of Wannier90. wannier90.x from Wannier90 v3.1.0 is compatible with DMFTwDFT.

For MPI workflows, build Wannier90 against the same MPI implementation used by DMFTwDFT and the DFT code.

DFT Codes¶

Build the DFT code you intend to use and place its executable in bin under the name DMFTwDFT expects,

VASP: vasp_std
Siesta: siesta
Quantum Espresso: pw.x and pw2wannier90.x

If they are not present in bin, DMFTwDFT will attempt to call the bare executable name from a global $PATH.

VASP uses the single vasp_std executable for both one-shot and charge self-consistent calculations. For charge self-consistent runs, build vasp_std with the DMFT source modifications and libdmft.a as described in the library mode section below. A VASP executable built this way still runs ordinary one-shot calculations, so no second executable is needed.

Quantum Espresso requires both executables. pw.x runs the SCF and NSCF steps, and pw2wannier90.x generates the overlap and projection files that Wannier90 consumes. Both ship with a standard Quantum Espresso build, but pw2wannier90.x is built only when the Wannier90 interface is enabled, so confirm it is present before running.

Build the DFT code against the same MPI implementation and architecture as DMFTwDFT and Wannier90.

Library Mode for charge self-consistent DFT+DMFT calculations¶

The compilation also generates libdmft.a, which can be linked into DFT codes to enable full charge-self-consistent DFT+DMFT calculations. Otherwise, calculations are self-consistent only within DMFT (one-shot DMFT).

For VASP,

Generate libdmft.a by compiling DMFTwDFT.
Add libdmft.a and required libraries/objects to the VASP makefile.include link line.
Install VASP once before modifying source files.
Copy the modified mlwf.F from sources/CSC-mods into the VASP source tree and rebuild (without cleaning the build) to create dependencies.
Copy the other required modified files, such as charge.F, electron.F, main.F, and us.F, from sources/CSC-mods.
Recompile VASP (without cleaning the build) and copy the resulting vasp_std executable to the DMFTwDFT bin directory.

This replaces the vasp_std used for one-shot calculations.

More information on library mode can be found in Library Mode.