Keyword reference

Keywords live under the top-level keywords object. Recognized groups include:

scf, frag, ks_dft, export, regions, optimization, qmmm, gradient, guess, integrals, rtat, hessian, dynamics, boundary, machine_learning, force_field, log, debug.

Defaults in the parameter listings below reflect the EXESS command-line behavior (JSON parser defaults plus EXESS internal defaults). Rush-py defaults are listed at the end of this page.

In practice, you will spend most of your time in scf, frag, ks_dft, and the driver-specific groups (optimization, dynamics, qmmm).

Icon key:

Tip Expert Experimental Known issues

Core Electronic-Structure Keywords

scf

EXESS CLI

config.json

{
  "topologies": [{ "xyz": "molecule.xyz" }],
  "driver": "Energy",
  "model": {
    "method": "RestrictedHF",
    "basis": "cc-pVDZ"
  },
  "keywords": {
    "scf": {
      "max_iters": 40,
      "max_diis_history_length": 12,
      "convergence_threshold": 1e-8,
      "density_threshold": 1e-11,
      "fock_build_type": "RI"
    }
  },
  "schema_version": "0.2.0"
}

Python

run.py

from rush.exess import SCFKeywords, energy

energy(
    topology_path="molecule_t.json",
    scf_keywords=SCFKeywords(
        max_iters=40,
        max_diis_history_length=12,
        convergence_threshold=1e-8,
        density_threshold=1e-11,
        fock_build_type="RI",
    ),
)

max_iters — int (default: 50)Max number of SCF iterations.

max_diis_history_length — int (default: 8)Max size of DIIS window.

batch_size — int (default: 2560)Shell-pair batches per bin; use multiples of 128.

Do not go below 128. For details on the shell-pair batch bin container, see 10.1021/acs.jctc.0c00768, 10.1021/acs.jctc.1c00720, and 10.1080/00268976.2022.2112987.

convergence_metric — string (default: DIIS)Convergence metric (DIIS, Energy, Density).

convergence_threshold — float (default: 1e-6)SCF convergence threshold; tighten for higher-order fragmentation or tighter energy targets.

Suggested values:

• 1e-6 for non-fragmented RHF + RI-MP2 with Density/DIIS.

• 1e-8 for non-fragmented RHF + RI-MP2 with Energy.

• 1e-6 for dimer-level RHF + RI-MP2.

• 1e-8 for trimer/tetramer-level calculations with DIIS.

• 1e-10 for large tetramer-level calculations with DIIS.

density_threshold — float (default: 1e-10)Density screening threshold; affects SCF cost and accuracy.

Lower values speed up SCF with potential accuracy loss. Explore 1e-8 to 1e-12 and validate accuracy; too-large values can lead to NaNs.

Increasing to 1e-11 or 1e-12 will slow SCF but can improve accuracy for higher-order fragmentation (e.g., tetramers) and produce crisper MP2 orbitals. Validate results against the default before adopting more aggressive thresholds.

gradient_screening_threshold — float (default: 1e-10)Additional screening for gradient-related integrals.

bf_cutoff_threshold — float (default: density_threshold)Basis-function cutoff threshold (defaults to density_threshold if omitted).

density_basis_set_projection_fallback_enabled — bool (default: auto (fragmented))STO-3G projection fallback toggle.

If omitted, EXESS enables fallback for fragmented calculations and disables it for full-system calculations.

When triggered, EXESS reruns SCF in STO-3G and projects the density into the target basis.

allow_crap_scf — bool (default: false)Expert flag to allow lower-quality SCF.

Expert control; adjust only with validation and verify accuracy before production use.

store_ri_b_on_host — bool (default: false)Store RI B matrix on host memory.

Use this if GPU memory is insufficient for RI; this is slower but can still outperform non-RI for some systems.

compress_ri_b — bool (default: false)Compress RI B matrix.

Compression can reduce GPU memory use enough to run larger systems that would otherwise exceed available RAM.

homo_lumo_guess_rotation_angle — float (default: auto (0 or 45))HOMO/LUMO guess rotation (degrees).

Rotation in degrees (0-180) for unrestricted symmetry breaking.

If omitted, EXESS uses 45 degrees for unrestricted singlets and 0 otherwise.

fock_build_type — string (default: HGP)Fock build algorithm (HGP, UM09, RI).

Algorithm definitions:

HGP

Head-Gordon-Pople algorithm, optimized for dense systems.

UM09

Ufimtsev-Martinez algorithm, optimized for screening-heavy systems.

RI

Resolution-of-identity approximation (requires auxiliary basis, higher memory use).

Guidance: HGP is tuned for dense systems where screening is less important (e.g., compact biomolecules). UM09 is tuned for screening-heavy systems (e.g., long chains) and can scale better on large systems. RI stores integrals, can be faster on small systems, but memory usage rises substantially.

fock_build_type includes improved screening for large systems (>3000 basis functions); see https://arxiv.org/abs/2407.21445 for details.

exchange_screening_threshold — float (default: 1e-5)Exchange screening threshold (expert control).

Expert control; adjust only with validation.

group_shared_exponents — bool (default: false)Group shared basis exponents (UM09 only).

Expert control used with UM09 and shared-exponent basis sets (e.g., cc-pVDZ).

frag

EXESS CLI

config.json

{
  "topologies": [{ "xyz": "molecule.xyz" }],
  "driver": "Energy",
  "model": {
    "method": "RestrictedHF",
    "basis": "cc-pVDZ"
  },
  "keywords": {
    "frag": {
      "cutoff_type": "Centroid",
      "distance_metric": "Average",
      "level": "Tetramer",
      "cutoffs": {
        "dimer": 1000,
        "trimer": 20,
        "tetramer": 15
      },
      "included_fragments": [0, 1, 2, 3, 4]
    }
  },
  "schema_version": "0.2.0"
}

Python

run.py

from rush.exess import FragKeywords, energy

energy(
    topology_path="molecule_t.json",
    frag_keywords=FragKeywords(
        cutoff_type="Centroid",
        distance_metric="Average",
        level="Tetramer",
        dimer_cutoff=1000,
        trimer_cutoff=20,
        tetramer_cutoff=15,
        included_fragments=[0, 1, 2, 3, 4],
    ),
)

level — string (default: required)Fragment expansion order (Monomer .. Octamer).

Truncation counts scale combinatorially: dimers \(n(n-1)/2\), trimers \(n(n-1)(n-2)/6\), tetramers \(n(n-1)(n-2)(n-3)/24\).

cutoffs — object (default: unset)Distance cutoffs in Angstroms.

Keys can include dimer, trimer, tetramer, pentamer, hexamer, heptamer, octamer.

Distances are in Angstroms and should follow dimer > trimer > tetramer when using higher orders.

If omitted, the calculation proceeds without distance filtering (all \(n\)-mers up to level); be cautious with fragment counts to avoid excessive compute.

cutoff_type — string (default: ClosestPair)Distance definition (Centroid or ClosestPair).

Centroid compares fragment centroids.

ClosestPair uses the minimal inter-fragment atom distance (more accurate and generally preferred).

distance_metric — string (default: Max)Reduce pair distances (Max, Average, Min).

Controls how higher-order distances are computed from pair distances.

reference_fragment — int (default: unset)Reference fragment for interaction energies.

Enables lattice/interaction energies by summing \(n\)-mer corrections that include the reference fragment. Negative values indicate binding; positive values indicate repulsion under the usual convention.

included_fragments — array[int] (default: unset)Subset of fragments to include.

Restricts the fragment set and treats them as an independent system.

enable_speed — bool (default: false)Experimental queue optimization.

Experimental queue optimization intended for AIMD workflows; avoid unless you can validate against a baseline.

ks_dft

KSDFT is used when model.method is RestrictedKSDFT. The KSDFT methodologies are described in the following paper:

Stocks, R.; Barca, G. M. J. Efficient Algorithms for GPU Accelerated Evaluation of the DFT Exchange-Correlation Functional. J. Chem. Theory Comput. 2025. https://doi.org/10.1021/acs.jctc.5c01229.

EXESS CLI

config.json

{
  "topologies": [{ "xyz": "molecule.xyz" }],
  "driver": "Energy",
  "model": {
    "method": "RestrictedKSDFT",
    "basis": "cc-pVDZ"
  },
  "keywords": {
    "ks_dft": {
      "functional": "GGA_XC_PBE",
      "grid": {
        "default_grid": "SUPERFINE",
        "radial_quad": "TreutlerAldrichs",
        "pruning_scheme": "TREUTLER"
      }
    }
  },
  "schema_version": "0.2.0"
}

Python

run.py

from rush.exess import DefaultGridResolution, KSKeywords, XCGridParameters, energy

energy(
    topology_path="molecule_t.json",
    method="RestrictedKSDFT",
    ks_keywords=KSKeywords(
        functional="GGA_XC_PBE",
        grid=XCGridParameters(
            resolution=DefaultGridResolution("SUPERFINE"),
            radial_quad="TreutlerAldrichs",
            pruning_scheme="TREUTLER",
        ),
    ),
)

functional — string (default: required)LibXC functional name.

EXESS accepts LibXC functional names and ExchCXX linear combinations. Input is uppercased internally, so names are case-insensitive.

Built-in aliases include SVWN5, B2PLYP, REVDSD-PBEP86-D4, and REVDSD-PBEP86-D4(NOFC).

For a full list of functionals, see the LibXC documentation: https://libxc.gitlab.io/functionals

method — string (default: GauXC)XC evaluation method.

GauXC (default)

GauXC-backed XC evaluation.

Dense

Dense matrix evaluation.

BatchDense

Batched dense evaluation (recommended for most production runs).

Direct

Direct evaluation without storing intermediates.

SemiDirect

Hybrid of direct and batch-dense methods.

use_C_opt — bool (default: true)Use C-matrix optimization (Dense/BatchDense).

use_C_opt enables C-matrix based XC evaluation, reducing matrix dimensions from n_basis to n_occ for Dense/BatchDense methods. It is only valid for Dense and BatchDense.

grid — object (default: default grid (ULTRAFINE))Numerical grid settings.

Grid quality parameters

Defaults shown where applicable.

radial_quad (default: MuraKnowles)

MuraKnowles, MurrayHandyLaming, TreutlerAldrichs.

pruning_scheme (default: ROBUST)

ROBUST, UNPRUNED, TREUTLER.

consider_weight_zero (default: auto)

Defaults to \(10^{-5}\) times sp_threshold if set, otherwise dp_threshold, otherwise the SCF density_threshold.

Grid size options

Choose one:

default_grid (default: ULTRAFINE)

Preset grid: FINE, ULTRAFINE, SUPERFINE, TREUTLER_GM3, TREUTLER_GM5.

radial_size, angular_size

Custom grid sizes (use together). When set, default_grid is ignored.

Batching options

Choose one:

Closest-atom batching

Default when no batch settings are provided (non-GauXC methods).

octree

Uses max_size (default 512), max_depth (default unlimited), max_distance (default unlimited), combine_small_children (default true).

space_filling

Uses the octree parameters plus target_batch_size (default 1024). combine_small_children defaults to false for space-filling.

batch_size

GauXC batch size (default 512).

If multiple batching keys are provided, EXESS prioritizes octree, then batch_size, then space_filling. For GauXC, EXESS forces GauXC batching and ignores other schemes.

Grid guidance

• Default grid settings (ULTRAFINE with ROBUST pruning) provide a good accuracy/cost balance for most users.

• SUPERFINE grids can improve accuracy but significantly increase compute time.

• Octree batching with BatchDense is useful for large systems where linear scaling is critical.

sp_threshold — float (default: SCF density_threshold)Single-precision threshold.

Defaults to dp_threshold when set, otherwise the SCF density_threshold.

dp_threshold — float (default: SCF density_threshold)Double-precision threshold.

batches_per_batch — int (default: 20)Batches per batch for BatchDense.

Only used when method = "BatchDense".

Minimal KSDFT:

"ks_dft": {
  "functional": "GGA_XC_PBE"
}

Custom grid defaults:

"ks_dft": {
  "functional": "HYB_GGA_XC_B3LYP",
  "method": "Dense",
  "grid": {
    "default_grid": "ULTRAFINE",
    "radial_quad": "MuraKnowles",
    "pruning_scheme": "ROBUST"
  }
}

Octree batching:

"ks_dft": {
  "functional": "HYB_GGA_XC_B3LYP",
  "method": "BatchDense",
  "grid": {
    "octree": {
      "max_size": 512
    }
  }
}

export

Export controls what is written to HDF5 output files:

EXESS CLI

config.json

{
  "topologies": [{ "xyz": "molecule.xyz" }],
  "driver": "Energy",
  "model": {
    "method": "RestrictedHF",
    "basis": "cc-pVDZ"
  },
  "keywords": {
    "export": {
      "export_density": true,
      "export_fock": true,
      "descriptor_grid": {
        "regular": {
          "min": [-4.0, -4.0, -4.0],
          "max": [4.0, 4.0, 4.0],
          "spacing": [0.2, 0.2, 0.2]
        }
      }
    }
  },
  "schema_version": "0.2.0"
}

Python

run.py

from rush.exess import ExportKeywords, RegularDescriptorGrid, energy

energy(
    topology_path="molecule_t.json",
    export_keywords=ExportKeywords(
        export_density=True,
        export_fock=True,
        descriptor_grid=RegularDescriptorGrid(
            min=[-4.0, -4.0, -4.0],
            max=[4.0, 4.0, 4.0],
            spacing=[0.2, 0.2, 0.2],
        ),
    ),
)

export_density — bool (default: false)Export density.

export_relaxed_mp2_density_correction — bool (default: false)Export relaxed MP2 density correction.

export_fock — bool (default: false)Export Fock matrix.

export_overlap — bool (default: false)Export overlap matrix.

export_h_core — bool (default: false)Export H core matrix.

export_expanded_density — bool (default: false)Export expanded density.

Provides the whole density matrix for the entire fragment system, rather than per-fragment matrices.

export_expanded_gradient — bool (default: false)Export expanded gradient.

Provides the whole gradient matrix for the entire fragment system, rather than per-fragment matrices.

Requires a gradient-capable driver (Gradient, Dynamics, QMMM, Optimization).

export_molecular_orbital_coeffs — bool (default: false)Export MO coefficients.

export_gradient — bool (default: false)Export gradients.

Requires a gradient-capable driver (Gradient, Dynamics, QMMM, Optimization).

export_external_charge_gradient — bool (default: false)Export external charge gradients.

export_mulliken_charges — bool (default: false)Export Mulliken charges.

export_chelpg_charges — bool (default: false)Export CHELPG charges.

export_bond_orders — bool (default: false)Export bond orders.

export_h_caps — bool (default: false)Export H caps.

export_density_descriptors — bool (default: false)Export density descriptors.

export_esp_descriptors — bool (default: false)Export ESP descriptors.

export_expanded_esp_descriptors — bool (default: false)Export expanded ESP descriptors.

export_basis_labels — bool (default: false)Export basis labels.

export_hessian — bool (default: false)Export hessian.

Requires a Hessian calculation.

export_mass_weighted_hessian — bool (default: false)Export mass-weighted hessian.

Requires a Hessian calculation.

export_hessian_frequencies — bool (default: false)Export hessian frequencies.

Requires a Hessian calculation.

flatten_symmetric — bool (default: true)Flatten symmetric matrices.

light_json — bool (default: false)Light JSON output.

concatenate_hdf5_files — bool (default: false)Concatenate HDF5 outputs.

Post-process exports into a single HDF5 output file. This is primarily relevant for fragmented runs (particularly when configured for multinode). The concatenation may be expensive.

training_db — bool (default: false)Export training DB metadata.

descriptor_grid — object (default: unset)Grid for descriptor exports.

descriptor_grid can be one of the following structures:

standard

FINE, ULTRAFINE, SUPERFINE, TREUTLER_GM3, TREUTLER_GM5.

params

points_per_shell, order (One or Two), scale.

regular

min, max, spacing arrays (Cartesian grid).

custom

flat list of points [x1, y1, z1, x2, y2, z2, ...].

Q4ML: Optimization & Simulation

regions

EXESS CLI

config.json

{
  "topologies": [{ "xyz": "molecule.xyz" }],
  "driver": "QMMM",
  "model": {
    "method": "RestrictedHF",
    "basis": "STO-3G"
  },
  "keywords": {
    "qmmm": {
      "n_timesteps": 10,
      "dt_ps": 0.002,
      "temperature_kelvin": 290.0
    },
    "regions": {
      "qm_fragments": [0, 1],
      "mm_fragments": [2, 3]
    }
  },
  "schema_version": "0.2.0"
}

Python

run.py

from rush.exess import qmmm

qmmm(
    topology_path="molecule_t.json",
    residues_path="system.residues",
    n_timesteps=10,
    dt_ps=0.002,
    temperature_kelvin=290.0,
    qm_fragments=[0, 1],
    mm_fragments=[2, 3],
)

Rules and defaults:

• Provide at least two of the three lists; the remaining region is inferred as the fragments not mentioned elsewhere.

• If all three lists are provided, they must be disjoint and cover all fragments.

• Supplying only one list is invalid.

• If regions is omitted in JSON, mm_fragments and ml_fragments default to empty and qm_fragments is inferred as all fragments (pure QM).

• If any non-QM region exists, residues must be provided; with no residues, the entire system must be QM.

• Non-QM regions are only supported for QMMM and Optimization; other drivers (including Energy) require pure QM regions.

• Non-QM regions are not supported for batched topology inputs.

qm_fragments — array[int] (default: inferred)Fragments treated as QM.

mm_fragments — array[int] (default: inferred)Fragments treated as MM.

ml_fragments — array[int] (default: inferred)Fragments treated as ML.

optimization

EXESS CLI

config.json

{
  "topologies": [{ "xyz": "molecule.xyz" }],
  "driver": "Optimization",
  "model": {
    "method": "RestrictedHF",
    "basis": "cc-pVDZ"
  },
  "keywords": {
    "optimization": {
      "max_iters": 200,
      "algorithm": "LBFGS",
      "coordinate_system": "Cartesian",
      "lbfgs_keywords": {}
    },
    "regions": {
      "qm_fragments": [0],
      "ml_fragments": [1, 2, 3]
    },
    "machine_learning": {
      "ml_type": "AIMNet"
    }
  },
  "schema_version": "0.2.0"
}

Python

run.py

from rush.exess import LBFGSKeywords, OptimizationKeywords, optimization

optimization(
    topology_path="molecule_t.json",
    max_iters=200,
    optimization_keywords=OptimizationKeywords(
        algorithm="LBFGS",
        coordinate_system="Cartesian",
        lbfgs_keywords=LBFGSKeywords(),
    ),
    qm_fragments=[0],
    ml_fragments=[1, 2, 3],
)

Fragmentation (frag) can be used when a QM region exists; EXESS fragments only the QM region and leaves MM/ML regions intact. Residue requirements and region validation details are covered in the regions section.

max_iters — int (default: required)Max optimization iterations.

convergence_criteria — object (default: see details)Convergence metric and thresholds.

Fields:

• metric — string (default: Baker)

• gradient_threshold — float (default: 3e-4; units: Eh/a0)

• delta_energy_threshold — float (default: 1e-6; units: Eh)

• step_component_threshold — float (default: 3e-4; units: a0)

metric options:

Baker

max gradient component must be within threshold and either delta energy or step component must be within their thresholds.

GradientOnly

only the gradient threshold is enforced.

optimizer_reset_interval — int (default: unset)The coordinate system will be regenerated and the Hessian reset every \(N\) iterations.

If omitted, EXESS never regenerates the coordinate system or resets the Hessian.

coordinate_system — string (default: DelocalisedInternal)Coordinate system (Cartesian, NaturalInternal, DelocalisedInternal).

DelocalisedInternal is the default and strongly recommended.

Machine learning optimizations require Cartesian.

constraints — array[array[int]] (default: [])Constrain bond lengths, angles, or dihedrals.

Specify lists of atom indices to constrain.

hessian_guess — string (default: auto)Initial Hessian model (Identity, ScaledIdentity, Schlegel, Lindh).

Defaults to Identity for Cartesian coordinates, otherwise ScaledIdentity.

Upstream docs caution that non-default models are not recommended for general use.

algorithm — string (default: EigenvectorFollowing)Optimization algorithm (EigenvectorFollowing, TrustRegionAugmentedHessian, LBFGS).

EigenvectorFollowing is recommended for most users.

TrustRegionAugmentedHessian is available but not recommended for most workflows.

For machine learning optimizations, LBFGS is strongly recommended.

lbfgs_keywords — object (default: unset)LBFGS parameters.

Required when algorithm is LBFGS (an empty object {} is acceptable).

Fields (defaults apply when LBFGS is used; set {} to use defaults):

• linesearch — string (default: BacktrackingStrongWolfe)

• n_corrections — int (default: 6)

• epsilon — float (default: 1e-5)

• max_linesearch — int (default: 40)

• gtol — float (default: 0.9)

trust_region — object (default: see details)Trust-region parameters (for TrustRegionAugmentedHessian).

Fields (defaults apply when TrustRegionAugmentedHessian is used; set {} to use defaults):

• initial_radius — float (default: 0.4)

• max_radius — float (default: 1e5)

• min_radius — float (default: 1e-5)

• increase_factor — float (default: 1.2)

• decrease_factor — float (default: 0.7)

• constrict_factor — float (default: 0.1)

• increase_threshold — float (default: 0.75)

• decrease_threshold — float (default: 0.25)

• rejection_threshold — float (default: 0.0)

The defaults have been optimized; changing them is not recommended unless you have a validated use case.

frozen_distance_slippage_tolerance_angstroms — float (default: 1e-8)Slippage tolerance (distance).

Controls expected slippage in frozen delocalized coordinates. These tolerances account for small drift when delocalized coordinates are held fixed.

frozen_angle_slippage_tolerance_degrees — float (default: 1e-8)Slippage tolerance (angle).

Controls expected slippage in frozen delocalized coordinates. These tolerances account for small drift when delocalized coordinates are held fixed.

debug_xyz — bool (default: false)Debug XYZ output.

output_trc — string (default: unset)Output TRC path.

fixed_atoms — array[int] (default: unset)Fixed atoms.

free_atoms — array[int] (default: unset)Free atoms.

fixed_fragments — array[int] (default: unset)Fixed fragments.

free_fragments — array[int] (default: unset)Free fragments.

fix_heavy — bool (default: false)Fix heavy atoms.

qmmm

EXESS CLI

config.json

{
  "topologies": [{ "xyz": "molecule.xyz" }],
  "driver": "QMMM",
  "model": {
    "method": "RestrictedHF",
    "basis": "STO-3G"
  },
  "keywords": {
    "qmmm": {
      "n_timesteps": 1000,
      "dt_ps": 0.002,
      "temperature_kelvin": 290.0,
      "trajectory": {
        "format": "XYZ",
        "interval": 10
      },
      "restraints": {
        "k": 1500.0,
        "fix_heavy": true
      }
    }
  },
  "schema_version": "0.2.0"
}

Python

run.py

from rush.exess import Restraints, Trajectory, qmmm

qmmm(
    topology_path="molecule_t.json",
    residues_path="molecule_r.json",
    n_timesteps=1000,
    dt_ps=0.002,
    temperature_kelvin=290.0,
    trajectory=Trajectory(interval=10),
    restraints=Restraints(k=1500.0, fix_heavy=True),
)

Fragmentation (frag) can be used when a QM region exists; EXESS fragments only the QM region and leaves MM/ML regions intact. Residue requirements and region validation details are covered in the regions section.

n_timesteps — int (default: required)Number of QMMM timesteps.

dt_ps — float (default: required)Timestep size in ps.

temperature_kelvin — float (default: required)Temperature in Kelvin.

pressure_atm — float (default: unset)Optional pressure for NPT runs.

If set, EXESS runs NPT; if unset, NVT is used.

biases — array[object] (default: unset)Bias potentials for QMMM dynamics.

Each entry must provide exactly one of:

harmonic_cv

Fields: k, offset, cv.

moving_harmonic

Fields: cv, k, rate_per_ps, optional initial_offset, optional final_offset, and resolution (default 0.01).

avoid_bonds

Fields: index, optional indices (default []), optional fragments (default []), optional exceptions (default []), steepness (default 10.0), height (default 10000.0).

cv objects must provide one of:

bond (fields: index1, index2), angle (fields: index1, index2, index3), dihedral (fields: index1, index2, index3, index4), or linear_combination (field: scaled_cvs, each entry has scale and cv).

pbc_ang — array[float] (default: unset)Periodic box lengths in angstroms.

Three-element vector [a, b, c] in angstroms.

minimisation — object (default: unset)Classical minimisation settings.

Fields:

• err_tol_kj_per_mol_nm — float (default: 10)

• max_iterations — int (default: 0)

minimisation can only be used in a purely classical run (no QM/ML regions).

trajectory — object (default: unset)Trajectory output settings.

Fields:

• format — string (default: JSON)

• interval — int (default: 1)

• start — int (default: 0)

• end — int (default: max u32)

• include_waters — bool (default: false)

• forces — string (default: unset)

trajectory.format can be JSON or XYZ (default JSON).

trajectory.include_waters can be set to omit waters for smaller trajectories.

trajectory.forces can be all, standard, or biases.

energy_csv — string (default: unset)Path for energy CSV.

When set, EXESS uses a Verlet integrator and does not apply the thermostat (the temperature is not used for integration).

cv_values_csv — string (default: unset)Path for CV values CSV.

Requires at least one CV-based bias (harmonic_cv or moving_harmonic).

restraints — object (default: unset)Restraints for atoms/fragments.

Fields:

• k — float (default: 2000.0)

• fixed_atoms — array[int] (default: unset)

• free_atoms — array[int] (default: unset)

• fixed_fragments — array[int] (default: unset)

• free_fragments — array[int] (default: unset)

• fix_heavy — bool (default: false)

Only one of fixed_atoms, free_atoms, fixed_fragments, or free_fragments may be specified. Set free_atoms = [] to fix all atoms.

restraints.k scales the restraint force; larger values mean stronger restraints.

ffs — array[string] (default: unset)Additional QMMM force field files.

gradient

EXESS CLI

config.json

{
  "topologies": [{ "xyz": "molecule.xyz" }],
  "driver": "Gradient",
  "model": {
    "method": "RestrictedHF",
    "basis": "cc-pVDZ"
  },
  "keywords": {
    "gradient": {
      "method": "Numerical",
      "finite_difference_step_size": 0.004
    }
  },
  "schema_version": "0.2.0"
}

Python

Not supported.

finite_difference_step_size — float (default: 5e-3)Step size for numerical gradients.

method — string (default: Analytical)Analytical or Numerical.

Advanced & Diagnostic Keywords

guess

EXESS CLI

config.json

{
  "topologies": [{ "xyz": "molecule.xyz" }],
  "driver": "Energy",
  "model": {
    "method": "RestrictedHF",
    "basis": "cc-pVDZ"
  },
  "keywords": {
    "guess": {
      "external_initial_density_path": "guess.h5",
      "bsp": true,
      "bsp_basis": "STO-3G"
    }
  },
  "schema_version": "0.2.0"
}

Python

Not supported.

external_initial_density_path — string (default: unset)HDF5 density guess path.

Must reference an HDF5 file with a density dataset at root for RHF, or alpha/density and beta/density for UHF.

Guesses are expected to be stored as flattened lower-triangular density matrices. External guesses are not supported for fragmented calculations, and EXESS warns that guesses from other codes may be incompatible due to basis ordering and normalization.

bsp — bool (default: false)Basis set projection bootstrap.

Computes a lower-resolution SCF and projects to the target basis. Requires bsp_basis.

bsp_basis — string (default: unset)Lower-resolution basis set for BSP.

bsp_scf_keywords — object (default: unset)SCF keywords for BSP.

If omitted, EXESS reuses the base SCF keywords.

hcore — bool (default: false)Use hcore initial guess.

smd — bool (default: auto (fragmented non-RI))Superposition of monomer densities.

If omitted, EXESS enables it for fragmented calculations that are not using RI, and disables it otherwise.

ssfd — bool (default: false)Subfragment density guess.

Experimental subfragment guess. ssfd_target_size controls subfragment size (default 30).

ssfd_target_size — int (default: 30)Target atoms per subfragment.

ssfd_only_converge_in_bsp_basis — bool (default: true)Only converge subfragments in BSP basis.

Keeps subfragments unconverged in the primary basis and only projects from the bootstrap basis.

ssfd_scf_keywords — object (default: unset)SCF keywords for subfragment runs.

If omitted, EXESS reuses the base SCF keywords.

integrals

EXESS CLI

config.json

{
  "topologies": [{ "xyz": "molecule.xyz" }],
  "driver": "Energy",
  "model": {
    "method": "RestrictedHF",
    "basis": "cc-pVDZ"
  },
  "keywords": {
    "integrals": {
      "scheduler": "RoundRobin",
      "n_streams": 8
    }
  },
  "schema_version": "0.2.0"
}

Python

Not supported.

scheduler — string (default: Callback)Integral scheduler (Callback or RoundRobin).

If integrals is omitted entirely, EXESS uses Callback with 4 streams.

n_streams — int (default: 4 (CUDA) / 1 (HIP))GPU stream count.

rtat

RTAT is a runtime auto-tuner for matrix operations.

RTAT is the open-source rtatblas library. When enabled, EXESS uses it to auto-tune GPU BLAS configurations for matrix operations.

EXESS CLI

config.json

{
  "topologies": [{ "xyz": "molecule.xyz" }],
  "driver": "Energy",
  "model": {
    "method": "RestrictedHF",
    "basis": "cc-pVDZ"
  },
  "keywords": {
    "rtat": {
      "synchronous": true,
      "json_file_dump_prefix": "rtat"
    }
  },
  "schema_version": "0.2.0"
}

Python

Not supported.

enabled — bool (default: true)Enable runtime autotuning.

synchronous — bool (default: false)Use synchronous operations.

json_file_dump_prefix — string (default: unset)Prefix for RTAT JSON dumps.

hessian

EXESS CLI

config.json

{
  "topologies": [{ "xyz": "molecule.xyz" }],
  "driver": "Hessian",
  "model": {
    "method": "RestrictedHF",
    "basis": "cc-pVDZ"
  },
  "keywords": {
    "hessian": {
      "finite_difference_step_size": 0.004
    }
  },
  "schema_version": "0.2.0"
}

Python

Not supported.

finite_difference_step_size — float (default: 5e-3)Step size for numerical Hessians.

method — string (default: Numerical)Analytical or Numerical.

dynamics

EXESS CLI

config.json

{
  "topologies": [{ "xyz": "molecule.xyz" }],
  "driver": "Dynamics",
  "model": {
    "method": "RestrictedHF",
    "basis": "cc-pVDZ"
  },
  "keywords": {
    "dynamics": {
      "n_timesteps": 10,
      "use_async_timesteps": false,
      "dt": 0.002
    }
  },
  "schema_version": "0.2.0"
}

Python

Not supported.

n_timesteps — int (default: required)Number of timesteps.

dt — float (default: required)Timestep size in ps.

A typical value is 1 fs (0.001 ps); you must set dt explicitly.

reuse_orbitals — bool (default: false)Reuse orbitals between timesteps.

use_async_timesteps — bool (default: true)Run asynchronous timesteps.

Expert option; validate stability before production runs.

boundary

Boundary conditions for periodic or truncated simulations:

EXESS CLI

config.json

{
  "topologies": [{ "xyz": "molecule.xyz" }],
  "driver": "Dynamics",
  "model": {
    "method": "RestrictedHF",
    "basis": "cc-pVDZ"
  },
  "keywords": {
    "boundary": {
      "x": { "kind": "Periodic", "range": { "lower": -2, "upper": 3 } },
      "y": { "kind": "Periodic", "range": { "lower": -2, "upper": 3 } },
      "z": { "kind": "Periodic", "range": { "lower": -2, "upper": 3 } }
    }
  },
  "schema_version": "0.2.0"
}

Python

Not supported.

x — object (default: unset)Boundary configuration for the X axis.

Each axis entry has:

kind

Periodic, Rigid, or Delete.

range

lower/upper extents for periodic boundaries.

y — object (default: unset)Boundary configuration for the Y axis.

Same structure as x.

z — object (default: unset)Boundary configuration for the Z axis.

Same structure as x.

machine_learning

ml_type — string (default: AIMNet)ML model type.

AIMNet is currently the only supported value.

force_field

force_field supplies a classical force field for water/MM components in fragmented AIMD (Dynamics) and other classical MBE steps. QMMM uses qmmm.ffs for additional force fields instead.

EXESS CLI

config.json

{
  "topologies": [{ "xyz": "molecule.xyz" }],
  "driver": "Dynamics",
  "model": {
    "method": "RestrictedHF",
    "basis": "cc-pVDZ",
    "aux_basis": "cc-pVDZ-RIFIT"
  },
  "keywords": {
    "scf": {
      "fock_build_type": "RI"
    },
    "dynamics": {
      "n_timesteps": 10,
      "dt": 0.001
    },
    "frag": {
      "level": "Dimer",
      "cutoffs": {
        "dimer": 7
      }
    },
    "boundary": {
      "x": { "kind": "Periodic", "range": { "lower": -3, "upper": 4 } },
      "y": { "kind": "Periodic", "range": { "lower": -3, "upper": 6 } },
      "z": { "kind": "Periodic", "range": { "lower": -3, "upper": 6 } }
    },
    "force_field": {
      "ff_filename": "forcefield.xml"
    }
  },
  "schema_version": "0.2.0"
}

Python

Not supported.

ff_filename — string (default: required)Force field filename path.

Used for classical water/MM contributions in fragmented AIMD/MBE; QMMM uses qmmm.ffs instead.

log

EXESS CLI

config.json

{
  "topologies": [{ "xyz": "molecule.xyz" }],
  "driver": "Energy",
  "model": {
    "method": "RestrictedHF",
    "basis": "cc-pVDZ"
  },
  "keywords": {
    "log": {
      "console": { "level": "Verbose" },
      "logfiles": [
        {
          "level": "Info",
          "prefix_fmt": "[%H:%M:%S {level}] ",
          "directory": "/tmp/exess"
        }
      ]
    }
  },
  "schema_version": "0.2.0"
}

Python

Not supported.

console — object (default: see details)Console log settings.

Fields:

• level — string (default: LargeInfo). Debug builds use Debug.

• prefix_fmt — string (default: "").

Log levels: Debug, Verbose, LargeInfo, Info, Performance, Warning, Error (descending verbosity).

logfiles — array[object] (default: [])File log settings.

Fields:

• level — string (default: Verbose)

• prefix_fmt — string (default: [%Y-%m-%d %H:%M:%S.{us} r{rank} {level}] )

• directory — string (default: unset)

debug

EXESS CLI

config.json

{
  "topologies": [{ "xyz": "molecule.xyz" }],
  "driver": "Energy",
  "model": {
    "method": "RestrictedHF",
    "basis": "cc-pVDZ"
  },
  "keywords": {
    "debug": {
      "dry_run": true
    }
  },
  "schema_version": "0.2.0"
}

Python

Not supported.

dry_run — bool (default: false)Validate fragment queue without computing.

Runs queue construction only (no computation) to validate fragment counts and detect input issues.

print_subfragment_xyz — bool (default: false)Print subfragment XYZ for SSFD.

Prints subfragment geometries for SSFD debugging.

max_fragments — int (default: -1)Limit number of fragments computed.

The default -1 means “use all fragments.”

ignore_fragments — bool (default: false)Ignore fragmentation (developer validation).

Forces a full-system calculation for validation.

skip_calcs — bool (default: false)Skip computations in fragmentation routines.

Skips calculations during fragmentation to debug queue construction performance.

Rush-py defaults

Rush-py sets some defaults in Python before submitting a run. If a *_keywords argument is omitted, rush-py may pass None (no overrides) or construct a default object.

Default keyword behavior for the common entry points:

• exess.exess / exess.energy / exess.interaction_energy:

  • scf_keywords: unset (EXESS defaults apply).

  • frag_keywords: FragKeywords() (level Dimer, dimer_cutoff=100.0, trimer_cutoff=None, tetramer_cutoff=None, cutoff_type=None, distance_metric=None).

  • export_keywords: ExportKeywords() (all fields unset; no exports requested).

• exess.chelpg:

  • scf_keywords: SCFKeywords(max_diis_history_length=12, convergence_threshold=1e-8).

  • frag_keywords: FragKeywords(level="Monomer").

  • export: CHELPG charges and bond orders enabled.

• exess.qmmm:

  • scf_keywords: unset (EXESS defaults apply).

  • frag_keywords: FragKeywords() (same defaults as above).

  • trajectory: Trajectory() (all fields unset; EXESS defaults apply).

• exess.optimization:

  • optimization_keywords: OptimizationKeywords() (all fields unset; EXESS defaults apply), with required max_iters passed separately.

Rush-py entrypoint defaults (non-keyword parameters):

• exess.exess / exess.energy / exess.interaction_energy:

  • method="RestrictedHF", basis="cc-pVDZ", aux_basis=None.

• exess.chelpg:

  • method="RestrictedHF", basis="cc-pVDZ", aux_basis=None.

  • Overrides standard_orientation="None" and force_cartesian_basis_sets=false.

• exess.qmmm:

  • method="RestrictedHF", basis="STO-3G", aux_basis=None.

  • dt_ps=0.002, temperature_kelvin=290.0, pressure_atm=None.

• exess.optimization:

  • method="RestrictedHF", basis="cc-pVDZ", aux_basis=None.

FragKeywords defaults by level in rush-py:

Monomer

dimer_cutoff=100.0, trimer_cutoff=None, tetramer_cutoff=None, cutoff_type=None, distance_metric=None.

Dimer

dimer_cutoff=100.0, trimer_cutoff=None, tetramer_cutoff=None.

Trimer

dimer_cutoff=100.0, trimer_cutoff=25.0, tetramer_cutoff=None.

Tetramer

dimer_cutoff=100.0, trimer_cutoff=25.0, tetramer_cutoff=10.0.