Input format¶

EXESS inputs are JSON files loosely based on MolSSI QCSchema. In EXESS, the molecular group is called topology, and input files use a topologies array to allow batched runs (multiple systems evaluated with the same driver/model/keywords).

This page is organized by the top-level input groups (topologies, model, system, keywords, driver) and follows QC-JSON conventions where possible.

Schema overview¶

Top-level EXESS input fields:

topologies — array[Topology] (default: required)One or more molecular systems.

residues — array[Residues] (default: unset)TRC residue definitions aligned to topologies.

external_charges — object (default: unset)External point charges (positions + charges).

driver — string (default: required)Calculation type (Energy, Gradient, Dynamics, Optimization, Hessian, QMMM).

model — object (default: required)Level of theory (method) + basis configuration.

system — object (default: unset)Hardware configuration.

keywords — object (default: required)Calculation parameters; may be {}.

schema_version — string (default: 0.2.0)Input schema version.

title — string (default: unset)Printed in output files.

check_schema — bool (default: true (when enabled))Enable schema validation when supported.

In the EXESS CLI JSON, keywords is required, but can be an empty object because defaults are applied by the parser. check_schema is only honored when schema checks are enabled; otherwise it is ignored.

Icon key:

Tip Expert

Input System Specification¶

topologies¶

topologies is an array of topology objects. Each topology provides molecular data and optional fragmentation/connectivity. See topologies for the full reference and validation rules.

Rush-py accepts the JSON topology format only (symbols + geometry). It does not accept xyz paths directly.

Example with inline geometry and symbols:

EXESS CLI

config.json¶

{
  "topologies": [
    {
      "symbols": ["O", "H", "H"],
      "geometry": [
        -1.1570, 0.0630, -0.4817,
        -1.1570, 0.8180, -1.0766,
        -1.1570, -0.6920, -1.0766
      ]
    }
  ],
  "driver": "Energy",
  "model": { "method": "RestrictedHF", "basis": "cc-pVDZ" },
  "keywords": {}
}

Python

run.py¶

from pathlib import Path

from rush.exess import energy
from rush.mol import Element, Topology

topology = Topology(
    symbols=[Element.O, Element.H, Element.H],
    geometry=[
        -1.1570, 0.0630, -0.4817,
        -1.1570, 0.8180, -1.0766,
        -1.1570, -0.6920, -1.0766,
    ],
)

Path("molecule_t.json").write_text(topology.to_json())

energy(topology_path="molecule_t.json")

Example using an XYZ file:

EXESS CLI

config.json¶

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

Python

run.py¶

from pathlib import Path

from rush.exess import energy
from rush.mol import Element, Topology

lines = Path("molecule.xyz").read_text().splitlines()
symbols = []
geometry = []
for line in lines[2:]:
    if not line.strip():
        continue
    symbol, x, y, z = line.split()[:4]
    symbols.append(Element.from_str(symbol))
    geometry.extend([float(x), float(y), float(z)])

topology = Topology(symbols=symbols, geometry=geometry)
Path("molecule_t.json").write_text(topology.to_json())

energy(topology_path="molecule_t.json")

residues¶

residues is typically aligned one-to-one with topologies (same index). It is required for QMMM and other workflows that rely on residues. See residues for the full reference.

insertion_codes is required; use empty strings when there are no insertion codes.

Example:

EXESS CLI

config.json¶

{
  "topologies": [
    {
      "xyz": "molecule.xyz",
      "fragments": [[0, 1, 2], [3, 4, 5]]
    }
  ],
  "residues": [
    {
      "residues": [[0, 1, 2], [3, 4, 5]],
      "seqs": ["HOH", "HOH"],
      "seq_ns": [1, 2],
      "insertion_codes": ["", ""]
    }
  ],
  "driver": "QMMM",
  "model": { "method": "RestrictedHF", "basis": "STO-3G" },
  "keywords": {
    "regions": {
      "qm_fragments": [0],
      "mm_fragments": [1]
    },
    "qmmm": {
      "n_timesteps": 100
    }
  }
}

Python

run.py¶

from pathlib import Path

from rush.exess import qmmm
from rush.mol import Element, Fragment, Residue, Residues, Topology

topology = Topology(
    symbols=[Element.O, Element.H, Element.H, Element.O, Element.H, Element.H],
    geometry=[
        0.0000, 0.0000, 0.0000,
        0.7570, 0.5860, 0.0000,
        -0.7570, 0.5860, 0.0000,
        2.8000, 0.0000, 0.0000,
        3.5570, 0.5860, 0.0000,
        2.0430, 0.5860, 0.0000,
    ],
    fragments=[Fragment([0, 1, 2]), Fragment([3, 4, 5])],
)

residues = Residues(
    residues=[Residue([0, 1, 2]), Residue([3, 4, 5])],
    seqs=["HOH", "HOH"],
    seq_ns=[1, 2],
    insertion_codes=["", ""],
)

Path("molecule_t.json").write_text(topology.to_json())
Path("molecule_r.json").write_text(residues.to_json())

qmmm(
    topology_path="molecule_t.json",
    residues_path="molecule_r.json",
    n_timesteps=100,
    qm_fragments=[0],
    mm_fragments=[1],
)

external_charges¶

External charges are supported for non-Dynamics drivers. EXESS errors if they are provided for Dynamics.

EXESS CLI

config.json¶

{
  "topologies": [{ "xyz": "molecule.xyz" }],
  "external_charges": {
    "positions": [0.0, 0.0, 0.0, 1.5, 0.0, 0.0],
    "charges": [0.5, -0.5]
  },
  "driver": "Energy",
  "model": { "method": "RestrictedHF", "basis": "cc-pVDZ" },
  "keywords": {}
}

Python

Not supported.

charges — array[float] (default: required)Charge values aligned to positions.

Configuration¶

driver¶

The driver field selects the calculation type:

Energy: Single-point energy and related properties.
Optimization: Geometry optimization. See optimization, plus regions when using Q4ML regions.
QMMM: QM/MM or QM/ML/MM workflows. See qmmm, plus regions as needed.
Gradient: Analytic or finite-difference gradients. See gradient for gradient options.
Hessian: Hessian and vibrational analysis. See hessian, plus SCF/DFT keywords as needed.
Dynamics: Molecular dynamics. See dynamics and force_field.

model¶

EXESS CLI

config.json¶

{
  "topologies": [{ "xyz": "molecule.xyz" }],
  "driver": "Energy",
  "model": {
    "method": "RestrictedRIMP2",
    "basis": "cc-pVDZ",
    "aux_basis": "cc-pVDZ-RIFIT",
    "standard_orientation": "None",
    "force_cartesian_basis_sets": false
  },
  "keywords": {}
}

Python

run.py¶

from rush.exess import energy

energy(
    topology_path="molecule_t.json",
    method="RestrictedRIMP2",
    basis="cc-pVDZ",
    aux_basis="cc-pVDZ-RIFIT",
    standard_orientation="None",  # String value, not None.
    force_cartesian_basis_sets=False,
)

system¶

EXESS CLI

config.json¶

{
  "topologies": [{ "xyz": "molecule.xyz" }],
  "driver": "Energy",
  "model": { "method": "RestrictedHF", "basis": "cc-pVDZ" },
  "system": {
    "max_gpu_memory_mb": 24000,
    "teams_per_node": 4,
    "gpus_per_team": 1
  },
  "keywords": {}
}

Python

run.py¶

from rush.exess import System, energy

energy(
    topology_path="molecule_t.json",
    system=System(
        max_gpu_memory_mb=24000,
        teams_per_node=4,
        gpus_per_team=1,
    ),
)

keywords¶

keywords contains method- and run-specific settings. See the keyword reference for full details. In the EXESS CLI JSON, keywords must be present even if empty; rush-py supplies defaults when omitted.

Default resolution order¶

Defaults are applied in the following order:

rush-py defaults: any non-None values set in Python (function defaults or dataclass defaults) are explicit values.
EXESS JSON parser defaults (as defined in the C++ input parser) for omitted fields.
EXESS internal defaults for values that remain unset after parsing.

Rush-py input mapping¶

The Rush Python client does not submit the full EXESS input JSON directly. Instead, it accepts a topology path (and sometimes residues path) plus keyword objects and constructs the EXESS params internally.

Key differences:

Model in rush-py only includes standard_orientation and force_cartesian_basis_sets; method, basis, and aux_basis are function parameters.
keywords in rush-py are passed as Python dataclasses (for SCFKeywords, FragKeywords, ExportKeywords, OptimizationKeywords, etc.).
frag_keywords defaults to a dimer fragmentation setup; pass frag_keywords=None to run a full-system calculation.
external_charges and some keyword groups (e.g., rtat, integrals) are not yet exposed in the rush-py API.

See the Rush guides for TRC objects and conversions: Objects and TRC Files.

Rush-py defaults¶

Default values set by the rush-py entry points:

exess.exess / exess.energy / exess.interaction_energy: driver="Energy" (for exess.exess), method="RestrictedHF", basis="cc-pVDZ", aux_basis=None, standard_orientation unset (EXESS default FullSystem), force_cartesian_basis_sets unset (EXESS default true).
exess.chelpg: method="RestrictedHF", basis="cc-pVDZ", standard_orientation="None", force_cartesian_basis_sets=false.
exess.qmmm: method="RestrictedHF", basis="STO-3G", aux_basis=None, standard_orientation unset (EXESS default FullSystem), force_cartesian_basis_sets unset (EXESS default true), dt_ps=0.002, temperature_kelvin=290.0, pressure_atm=None, gradient method Analytical with default step size.
exess.optimization: method="RestrictedHF", basis="cc-pVDZ", aux_basis=None, standard_orientation unset (EXESS default FullSystem), force_cartesian_basis_sets unset (EXESS default true), max_iters required.

Keyword defaults for rush-py are documented in the keyword reference page.

Input conversion tools¶

Several helpers can generate EXESS inputs:

parley.py (https://github.com/JorgeG94/parley_exess) converts between XYZ and EXESS JSON. It can also add minimal defaults for Dynamics and Optimization drivers.
tools/input_transformer/create_json_input.jl in the EXESS source repository is a Julia helper for generating RHF inputs:

julia -E 'include("create_json_input.jl"); create_input_rhf("molecule.xyz", "BASIS")'