Installation#

MPPT combines a Python/PySCF frontend with C, C++, and Fortran executables. The supported workflow requires all parts to use the same HDF5 and numerical library environment.

Important: MPPT does not install an environment manager. Complete the environment-manager setup first if needed. It explains which commands Miniforge, Miniconda, Anaconda Distribution, Mamba, and Micromamba provide, including the correct path for glibc 2.17-2.27 servers without sudo.

Requirements#

  • Linux with GNU GCC, G++, and GFortran. The C++ compiler must support C++20; GFortran 10.1 or newer is required.

  • glibc 2.17 or newer for the supplied Linux x86-64 environment.

  • Git and outbound HTTPS access for the source and CMake dependencies.

  • CMake 3.27 or newer.

  • Python 3.11 or newer.

  • BLAS, LAPACK, OpenMP, and HDF5.

  • conda, mamba, or micromamba to create the version-pinned environment.

The verified Linux x86-64 baseline is CMake 4.4.3 with GCC, G++, and GFortran 14.4.0. These are tested versions, not hard minimums, but the supported build currently requires GNU compilers because legacy Fortran targets use GNU-specific flags. The supplied mppt_env.yaml pins the verified GNU suite together with the Python and numerical dependencies. The file and compiler-wrapper commands are ready to use only on Linux x86-64. On another architecture, create and validate an architecture-specific environment with native compiler packages and wrapper names; do not use the supplied commands unchanged.

The environment installs PySCF 2.14.0 from its official manylinux wheel. Its NumPy, SciPy, h5py, HDF5, and compiler dependencies stay pinned through conda-forge, so the compiled MPPT executables still discover one consistent numerical and HDF5 environment.

Clone The Repository#

Release snapshots include the exact pinned cipsixx source under external/cipsixx, so no private dependency checkout is required:

git clone https://gitlab.com/seregmikhail/mppt-public.git mppt
cd mppt

For another source layout, ensure external/cipsixx contains the pinned source or set MPPT_CIPSIXX_SOURCE_DIR explicitly. If cipsixx is intentionally unavailable, configure with -DMPPT_ENABLE_CIPSIXX=OFF; the unified selection stage will not be available.

Create The Environment#

The commands below deliberately use the familiar conda command provided by Miniforge, Miniconda, and Anaconda Distribution. If using mamba or micromamba, run the matching creation and activation block in the environment-manager setup, then continue with the compiler exports below.

conda env create -f mppt_env.yaml
conda activate mppt

Every supported manager sets CONDA_PREFIX after activation. Select all three compiler wrappers from that active Linux x86-64 environment:

export CC="$CONDA_PREFIX/bin/x86_64-conda-linux-gnu-gcc"
export CXX="$CONDA_PREFIX/bin/x86_64-conda-linux-gnu-g++"
export FC="$CONDA_PREFIX/bin/x86_64-conda-linux-gnu-gfortran"

Use one environment for CMake discovery, the Python packages, and runtime HDF5 libraries. Mixing system and environment-managed HDF5 installations commonly causes link or runtime loader failures. Selecting all three compiler wrappers from that same environment also avoids incompatible OpenMP and C++ runtime libraries.

Optional: block2 For PySCF DMRG-CASSCF#

Use mppt_block2_env.yaml to create a separate mppt-block2 environment. It retains the MPPT baseline pins and adds the single-node OpenMP block2==0.5.4 package and a commit-pinned pyscf-dmrgscf adapter. Git and a C compiler are included because the adapter builds a small native extension. This provides the native PySCF Python API; it does not add a DMRG solver option to MPPT YAML or an MPS-to-DIAGPT handoff. The existing DMRG external-reference example exports optimized orbitals and the Hamiltonian; CIPSIXX still builds its own model space.

The x86-64 block2 wheel uses MKL 2024.2.2 internally. Its Intel OpenMP and header dependencies are pinned to compatible 2024 releases so pip does not select newer glibc 2.28-only runtimes. This does not enable MPPT’s optional WITH_MKL build switch.

conda env create -f mppt_block2_env.yaml
conda activate mppt-block2
python -m pip check
block2main -v

Use the normal compiler exports and MPPT build steps below in this environment. Use a fresh CMake build directory, such as build-block2, if build belongs to another environment. The default mppt_env.yaml remains the standard installation. Do not install block2-mpi alongside block2 in one prefix.

Configure The PySCF Adapter#

Create a configuration file in the environment and select it explicitly for DMRG runs. This avoids editing installed packages or the user’s global PySCF configuration. Run the commands after activating mppt-block2:

mkdir -p "$CONDA_PREFIX/etc"
cat > "$CONDA_PREFIX/etc/pyscf-block2.py" <<'PY'
"""Select the active environment's single-node block2 executable."""
import sys
from pathlib import Path

dmrgscf_BLOCKEXE = str(Path(sys.prefix) / "bin" / "block2main")
dmrgscf_BLOCKSCRATCHDIR = str(Path.cwd() / "dmrg-scratch")
dmrgscf_BLOCKRUNTIMEDIR = str(Path.cwd())
dmrgscf_MPIPREFIX = ""
PY
export PYSCF_CONFIG_FILE="$CONDA_PREFIX/etc/pyscf-block2.py"

Use a separate working directory for each calculation: the adapter writes FCIDUMP, dmrg.conf, dmrg.out, and MPS/RDM scratch files. Set PYSCF_CONFIG_FILE before importing PySCF in each new shell or batch job. For custom scratch locations, set mc.fcisolver.scratchDirectory and mc.fcisolver.runtimeDir to absolute paths before kernel().

Small Native Solver Check#

The following one-thread LiH calculation exercises the external executable, integral handoff and energy readback against PySCF FCI on identical DF integrals. It is a software smoke check, not a bond-dimension convergence study.

mkdir block2-smoke
cd block2-smoke
export OMP_NUM_THREADS=1 OPENBLAS_NUM_THREADS=1 MKL_NUM_THREADS=1
python - <<'PY'
"""BLOCK2-ENV-01: compare the installed DMRG adapter with exact small-space FCI."""
import numpy as np
from pyscf import dmrgscf, gto, lib, mcscf, scf

lib.num_threads(1)
mol = gto.M(atom="Li 0 0 0; H 0 0 1.6", basis="sto-3g", verbose=3)
mf = scf.RHF(mol).density_fit().run()
reference = mcscf.CASCI(mf, 4, 2).run()
candidate = mcscf.CASCI(mf, 4, 2)
candidate.fcisolver = dmrgscf.DMRGCI(mol, maxM=100, tol=1e-10)
candidate.fcisolver.memory = 1  # GB for block2, unlike PySCF's MB.
candidate.kernel()
np.testing.assert_allclose(candidate.e_tot, reference.e_tot, atol=1e-8, rtol=0)
print("block2/PySCF energy check: passed")
PY

For orbital optimization, construct dmrgscf.DMRGSCF(mf, ncas, nelecas). The adapter selects DF-CASSCF when mf has density fitting. Set solver threads, memory, sweep schedule and state weights explicitly for real runs. mc.max_cycle_macro = 1 bounds CASSCF macroiterations, not the number of DMRG sweeps, solver calls or orbital microiterations. See the block2/PySCF guide.

Acceptance for this optional installation is defined before running the check:

Scenario: BLOCK2-ENV-01 Execute a real external solver from the alternate environment
  Given a fresh mppt-block2 environment and its explicitly selected PySCF config
  When the native solver check above runs in a new working directory
  Then block2 energy agrees with exact FCI within 1e-8 Hartree
  And pip check reports no incompatible package requirements

The independent oracle is FCI on the same active Hamiltonian. Standard MPPT tests cover the default environment; this manual check adds the optional executable/adapter boundary without making block2 a mandatory CI dependency.

Configure And Build#

From the repository root:

cmake -S . -B build \
  -UBLAS_LIBRARIES \
  -ULAPACK_LIBRARIES \
  -DCMAKE_BUILD_TYPE=Release \
  -DCMAKE_PREFIX_PATH="$CONDA_PREFIX" \
  -DCMAKE_INSTALL_PREFIX="$CONDA_PREFIX" \
  -DCMAKE_INSTALL_LIBDIR=lib \
  -DHDF5_ROOT="$CONDA_PREFIX" \
  -DOpenMP_gomp_LIBRARY="$CONDA_PREFIX/lib/libgomp.so.1" \
  -DMPPT_ENABLE_CIPSIXX=ON \
  -DMPPT_COPY_TO_HOME_BIN=ON \
  -DMPPT_HOME_BIN_DIR="$CONDA_PREFIX/bin" \
  -DINSTALL_PYSCF2MPPT=ON \
  -DWITH_LIBGRPP=ON

cmake --build build --parallel 1
cmake --install build

The serial build is intentional for the current mixed-language target graph. Core executables are written to build/bin; the main ones are cipsixx_select, diagpt, and heffso. The configuration above also copies the executables and helper scripts to $CONDA_PREFIX/bin, which is already on PATH whenever the mppt environment is active. The install step places native libgrpp in $CONDA_PREFIX/lib and installs libgrpppy together with pyscf2mppt into the same Python environment.

For a shell-independent destination, use $HOME/bin and add it permanently to PATH instead of exporting it before every run. For Bash, run this once:

echo 'export PATH="$HOME/bin:$PATH"' >> "$HOME/.bashrc"
source "$HOME/.bashrc"

For Zsh:

echo 'export PATH="$HOME/bin:$PATH"' >> "$HOME/.zshrc"
source "$HOME/.zshrc"

Then replace the CMake destination above with:

-DMPPT_HOME_BIN_DIR="$HOME/bin"

For any other destination, add that directory to the appropriate shell startup file and pass the same absolute path as MPPT_HOME_BIN_DIR.

cmake --install does not install every core executable. Use build/bin for build-tree-only configurations made with -DMPPT_COPY_TO_HOME_BIN=OFF.

Build Options#

Option

Default

Effect

MPPT_ENABLE_CIPSIXX

ON

Build the pinned HDF5 selector. Requires HDF5 and the cipsixx source tree.

MPPT_ENABLE_DIAGPT_IPO

ON

Enable compiler-supported DIAGPT interprocedural optimization in non-Debug builds.

WITH_MKL

OFF

Use oneMKL BLAS/LAPACK.

WITH_MKL_SPARSE

OFF

Build the oneMKL sparse HEFFSO backend.

WITH_CUDA_SPARSE

OFF

Build the experimental CUDA/cuSPARSE HEFFSO backend.

WITH_LIBGRPP

ON

Find or build and install native libgrpp.

MPPT_ENABLE_FORTUNO_TESTS

ON

Fetch and build DIAGPT/HEFFSO unit tests.

MPPT_COPY_TO_HOME_BIN

ON

Copy built executables and scripts after a build.

MPPT_HOME_BIN_DIR

~/bin

Destination used by the optional convenience copy.

INSTALL_PYSCF2MPPT

ON

Install bundled libgrpppy and pyscf2mppt packages.

Only enable MKL or CUDA after the portable build works. See HEFFSO build and usage for backend-specific configuration.

Verify The Installation#

First verify the installed Python packages from outside the source checkout, so the local pyscf2mppt/ directory cannot shadow the installed extension. Then return to the repository and run the compiled unit suite:

REPO_ROOT="$PWD"
cd "$HOME"
python - <<'PY'
import pyscf2mppt
from libgrpppy import libgrpp
from pyscf2mppt.integrals import _reorder_integrals

libgrpp.init()
print("MPPT Python packages: ready")
PY
cd "$REPO_ROOT"
ctest --test-dir build --output-on-failure -L Unit

The repository-level test-light target injects exact CMake target paths into workflow tests. It also runs a compact HF/STO-3G calculation with an F09 GRPP through the installed Python bindings and native library:

cmake --build build --target test-light

The GRPP test removes PYTHONPATH and LIBGRPP_ROOT and starts Python in safe path mode. A pass therefore confirms native-library discovery from the active installation prefix and a converged scientific calculation, not only that the shared library can be loaded.

When a workflow test.sh is run directly, it defaults to build/bin; set MPPT_BIN_DIR only when testing another build tree.

Continue with the quick start after the CLI and unit tests work.