Protocol Configuration Guide

The protocol file is the core configuration for Ensemble Analyzer. It is structured as a JSON dictionary where each key (e.g., "0", "1") represents a sequential computational step.

Core Computational Keywords

These parameters define the level of theory and the type of calculation to be performed by the QM engine.

  • functional (str, Required) The DFT functional or semi-empirical method to use (e.g., "B97-3c", "wB97X-D4", "xtb").

  • basis (str) The basis set definition. If using composite methods (like r2SCAN-3c), this is automatically handled or can be omitted.

  • opt (bool) If true, performs a geometry optimization for the current step.

  • freq (bool) If true, performs a frequency calculation. This enables vibrational analysis and qRRHO thermochemical corrections.

  • charge (int) The total charge of the system (default: 0).

  • mult (int) The spin multiplicity of the system (default: 1).

  • solvent (dict) Configuration for implicit solvation models.

    • solvent (str): Name of the solvent (e.g., "water", "chcl3").

    • smd (bool): If true, uses the SMD solvation model; otherwise, uses CPCM.

Advanced Calculation Control

  • add_input (str) Additional keywords or blocks passed directly to the external QM engine (ORCA/Gaussian) input file. No sanity check performed.

  • read_orbitals (int) Specifies the index of a previous step to read orbitals/guess from (e.g., "0"). Useful for SCF convergence in difficult cases.

  • skip_opt_fail (bool) If true, conformers that fail to converge during optimization are automatically deactivated instead of crashing the workflow.

  • monitor_internals (list) A list of atom indices to track specific internal coordinates in the log output.

    • Example: [[0, 1], [2, 3, 4]] monitors a bond length and an angle.

  • block_on_retention_rate (bool) If true, the program will halt execution if the number of surviving conformers drops below a safety threshold (default 20%), preventing total loss of the ensemble.

Transition State Analysis

  • ts (bool) If true, enables transition state optimization. QM calculators add TS-specific keywords (OptTS for ORCA, opt=(ts,calcfc,noeigentest) for Gaussian); ML calculators use the Sella optimizer instead of LBFGS. Implies "opt": true.

  • loc_freq (list of list of int) List of atom index groups that the imaginary frequency should localize on. When set, gates the B.1–B.6 post-processing logic: validates whether each significant negative mode falls on these groups (auto-named Frag1, Frag2, …), displaces and re-optimizes when a spurious mode is detected. Without loc_freq, even with "ts": true, the TS-specific post-processing is skipped.

    • Example: [[0, 1, 2, 3], [4, 5, 6]] defines two fragments.

  • min_localization (float) Minimum percentage of squared atomic displacement that must localize on the loc_freq fragments for a negative frequency to be considered “on target”. Default: 50.0.

  • auto_displace (bool) If true, automatically displaces the geometry along the dominant imaginary mode and re-optimizes. Applies to both TS and non-TS optimizations with imaginary frequencies.

  • displace_scale (float) Displacement scale factor in Ångström. Default: 0.3.

  • neg_freq_threshold (float) Imaginary frequencies with |ν| ≤ this value (in cm⁻¹) are classified as noise and ignored. Default: 20.0.

Refinement & Pruning Settings

  • cluster (int | bool) Controls the unsupervised clustering of conformers.

    • If an integer > 1: Performs K-Means clustering to reduce the ensemble to that exact number of structures.

    • If true: Performs clustering with automatic detection of the optimal number of clusters (\(k\)).

  • no_prune (bool) If true, completely disables energy and geometric pruning for this specific step.

  • thrG / thrB (float) Overrides the default thresholds for identifying duplicates:

    • thrG: Maximum energy difference (\(\Delta E\)) [kcal/mol].

    • thrB: Maximum difference in Rotational Constants (\(\Delta B\)) [cm⁻¹].

  • thrGMAX (float) Overrides the maximum energy window cut-off. Conformers with \(\Delta E > \text{thrGMAX}\) (relative to the global minimum) are discarded.