Skip to article frontmatterSkip to article content
Site not loading correctly?

This may be due to an incorrect BASE_URL configuration. See the MyST Documentation for reference.

Restarting from HDF5 files

VeloxChem supports robust restart capabilities via binary HDF5 (.h5) files that capture the essential electronic‑structure state needed to resume or reuse calculations reproducibly and efficiently.

What is stored in the restart file?

The restart file is designed to be portable, compact, and self‑describing. It typically contains:

  • System definition

    • Cartesian geometry (atomic numbers, positions)

    • Charge and spin multiplicity

  • Basis and integral metadata

    • Basis‑set and ECP identifiers per atom

    • Integral conventions

    • XC grid settings

  • SCF/DFT electronic state

    • Total energies

    • Molecular‑orbital (MO) coefficients and orbital energies

    • Occupations (including fractional, if used)

    • Density matrix (α/β for unrestricted cases)

    • SCF convergence thresholds and last achieved residuals

    • Functional specification

  • Additional model context (when active)

    • Implicit solvation model and parameters (e.g., CPCM/SMD)

    • Explicit solvation model and parameters (polarizable embedding)

    • External fields (if present) and unit specifications

  • Provenance and versioning

    • VeloxChem version, build info, and I/O schema version

    • Host and timestamp metadata to aid reproducibility

What can be restarted?

  • SCF/DFT single‑point energy
    Resume from a converged density and MO set for instant re‑evaluation (e.g., with tighter thresholds or different print options).

  • Geometry optimization & PES scans
    Reuse the last converged density/MOs at a new geometry as a high‑quality initial guess to accelerate SCF convergence along a path or during restarts after wall‑time limits.

  • Vibrational analysis (IR/Raman)
    Start the property step from a converged electronic state at the optimized geometry.

  • Spectroscopies (UV/vis, optical activity)
    Provide a clean ground‑state reference (MOs, occupations, density) for TDDFT and CPP runs to reduce set‑up time and ensure consistency of state definitions.

Writing restart files

VeloxChem can write a restart file at the end of an SCF/DFT calculation (and at checkpoints for longer runs).

import veloxchem as vlx

molecule = vlx.Molecule.read_name("water")
basis = vlx.MolecularBasis.read(molecule, "def2-svp")

scf_drv = vlx.ScfRestrictedDriver()
scf_drv.xcfun = "b3lyp"

# specify name of HDF5 file
scf_drv.filename = "my_vlx_calc"

scf_results = scf_drv.compute(molecule, basis)

File content

Depending on the details of calculations, restart files contain different information. A quick overview of the information is readily available.

import h5py

with h5py.File(f"{scf_drv.filename}_scf.h5", "r") as f:
    for key in f.keys():
        print(key)
alpha_energies
alpha_occupations
alpha_orbitals
atom_basis_labels_flattened
atom_coordinates
basis_set
dft_func_label
method_settings
molecular_charge
nuclear_charges
nuclear_repulsion
number_of_alpha_electrons
number_of_atoms
number_of_beta_electrons
potfile_text
scf_settings
scf_type
spin_multiplicity

Restarting calculations

VeloxChem can read a restart file in the beginning of the calculation.

import veloxchem as vlx

fname = "../output_files/c2h4"
molecule, basis = vlx.read_molecule_and_basis(f"{fname}_scf.h5")

scf_drv = vlx.ScfRestrictedDriver()
scf_drv.filename = fname
scf_results = scf_drv.compute(molecule, basis)

rsp_drv = vlx.LinearResponseEigenSolver()
rsp_drv.nstates = 5
rsp_drv.filename = fname
rsp_results = rsp_drv.compute(molecule, basis, scf_results)
import veloxchem as vlx

fname = "../output_files/c2h4"
molecule, basis = vlx.read_molecule_and_basis(f"{fname}_scf.h5")

scf_drv = vlx.ScfRestrictedDriver()
scf_drv.filename = fname

opt_drv = vlx.OptimizationDriver(scf_drv)
opt_drv.filename = fname
opt_results = opt_drv.compute(molecule, basis)
Getting started
Running on a cluster
Getting started
Input file keywords