Welcome to the tutorials! We’re thrilled to have you here. Please go through the code examples, and don’t hesitate to contact our team if you have questions or feedback.

Gaussian QM/MM ONIOM Calculations Guide

CHEMSMART provides comprehensive tools for multiscale QM/MM calculations using Gaussian’s ONIOM (Our own N-layered Integrated molecular Orbital and molecular Mechanics) methodology. This section covers various QM/MM schemes for accurate treatment of large molecular systems including enzymes, organometallic complexes, and materials.

Overview

Gaussian ONIOM calculations enable efficient treatment of large molecular systems by partitioning them into multiple layers with different levels of theory. CHEMSMART supports flexible ONIOM calculation setups:

2-Layer ONIOM: High(QM):Low(MM) - High level: Quantum mechanics (DFT, ab initio, MP2, etc.) - Low level: Molecular mechanics force fields (AMBER, UFF, DREIDING)

3-Layer ONIOM: High(QM):Medium(QM):Low(MM) - High level: High-accuracy quantum mechanics - Medium level: Lower-cost quantum mechanics - Low level: Molecular mechanics force fields

Key advantages of ONIOM methodology: - Automatic link atom handling for covalent boundaries - Customizable scale factors for accurate QM/MM interfaces - Support for multiple charge/multiplicity specifications - Integration with all major force fields available in Gaussian - Compatibility with various job types (optimization, frequencies, transition states)

Basic QM/MM Command

The basic command structure for Gaussian ONIOM QM/MM calculations is:

chemsmart sub [OPTIONS] gaussian [GAUSSIAN_OPTIONS] <JOBTYPE> qmmm [QMMM_OPTIONS]

where <JOBTYPE> is one of opt, ts, sp, scan, modred, or qrc. There is no standalone qmmm command.

QM/MM-Specific Options

Job Type and Theory Levels

Job Type and Method Options
Option	Type	Description
`-hx, --high-level-functional`	string	DFT functional for high layer (e.g., B3LYP, M06-2X, wB97X-D)
`-hb, --high-level-basis`	string	Basis set for high layer (e.g., 6-31G*, def2-TZVP, cc-pVTZ)
`-hff, --high-level-force-field`	string	Force field for high layer (if MM, rare)
`-mx, --medium-level-functional`	string	DFT functional for medium layer
`-mb, --medium-level-basis`	string	Basis set for medium layer
`-mff, --medium-level-force-field`	string	Force field for medium layer
`-lx, --low-level-functional`	string	DFT functional for low layer (if QM, uncommon)
`-lb, --low-level-basis`	string	Basis set for low layer (if QM, uncommon)
`-lff, --low-level-force-field`	string	Force field for low layer (AMBER=HardFirst, UFF, DREIDING)

Atom Partitioning

Layer Assignment Options
Option	Type	Description
`-ha, --high-level-atoms`	string	Atom indices for high layer (e.g., ‘1-15,20’ or ‘1:15 20’)
`-ma, --medium-level-atoms`	string	Atom indices for medium layer (3-layer only)
`-la, --low-level-atoms`	string	Atom indices for low layer (usually auto-assigned)
`-ba, --bonded-atoms`	string	Bonds crossing layer boundaries, e.g. `'[[3, 4], [5, 6]]'`. Optional; cut covalent bonds are assigned from molecular connectivity if omitted.
`-sf, --scale-factors`	dict	Custom link atom scale factors, e.g. `'{[3, 4]: [0.709, 0.709, 0.709]}'`.

MM Atom Types and Parameters

Required for AMBER (and similar) force fields unless the input .com already contains Element-Type-Charge labels and SoftFirst/HardFirst parameter lines.

MM Parameter Options
Option	Type	Description
`-mai, --mm-atom-info`	path	File with MM atom types and partial charges. Format: `[index] type charge [link_type link_charge]`.
`-mpf, --mm-parameters-file`	path	Optional SoftFirst/HardFirst MM parameter lines to append after the molecule specification. Not needed if already present in the input `.com`.

Charge and Multiplicity

Charge and Multiplicity Options
Option	Type	Description
`-ct, --charge-total`	int	Charge of complete molecular system
`-mt, --mult-total`	int	Spin multiplicity of complete system (2S+1)
`-ci, --charge-intermediate`	int	Charge of high+medium layers (3-layer only)
`-mi, --mult-intermediate`	int	Multiplicity of high+medium layers
`-ch, --charge-high`	int	Charge of high layer only
`-mh, --mult-high`	int	Multiplicity of high layer only

Usage Examples

2-Layer Enzyme Active Site

Basic enzyme QM/MM calculation with DFT for active site and AMBER for protein:

chemsmart sub gaussian -p enzyme_qmmm -f protein.pdb opt qmmm -hx B3LYP -hb 6-31G* -lff AMBER=HardFirst -ha 1-25 -ct 0 -mt 1 -ch 0 -mh 1 -ba '[[25, 26]]' -mai mm_atoms.dat

3-Layer Organometallic Catalyst

Multi-layer calculation with high-accuracy DFT for metal center:

chemsmart sub gaussian -p catalyst_oniom -f complex.xyz opt qmmm -hx M06-2X -hb def2-TZVP -mx B3LYP -mb 6-31G* -lff UFF -ha 1-10 -ma 11-50 -ct -1 -mt 2 -ci 0 -mi 1 -ch 0 -mh 1 -ba '[[10, 11], [50, 51]]'

Transition State Search

ONIOM transition state optimization for enzyme catalysis:

chemsmart sub gaussian -p ts_qmmm -f reactant.com ts qmmm -hx wB97X-D -hb 6-311++G(d,p) -lff AMBER=HardFirst -ha 1-30 -ct 0 -mt 1 -ch 0 -mh 1 -ba '[[30, 31]]' -sf '{[30, 31]: [0.709, 0.709, 0.709]}'

Frequency Analysis

Vibrational analysis of a QM/MM optimized structure. Enable frequencies via the project settings (freq: true). The opt qmmm parent command is used since there is no standalone freq parent command:

chemsmart sub gaussian -p freq_qmmm -f optimized.com opt qmmm -hx B3LYP -hb 6-31G* -lff AMBER=HardFirst -ha 1-20 -ct 0 -mt 1 -ch 0 -mh 1

Single Point Energy

High-accuracy single point calculation on QM/MM geometry:

chemsmart sub gaussian -p sp_qmmm -f geometry.xyz sp qmmm -hx CCSD(T) -hb aug-cc-pVDZ -lff AMBER=HardFirst -ha 1-15 -ct 0 -mt 1 -ch 0 -mh 1

GaussianQMMMJobSettings Reference

The GaussianQMMMJobSettings class provides comprehensive configuration options for Gaussian ONIOM calculations. This section provides detailed documentation for programmatic configuration.

Core Configuration Parameters

Job Type and Theory Levels

Parameter	Type	Description
`jobtype`	str	ONIOM calculation type (sp, opt, freq, ts, irc)
`high_level_functional`	str	DFT functional for high layer (B3LYP, M06-2X, wB97X-D, etc.)
`high_level_basis`	str	Basis set for high layer (6-31G*, def2-TZVP, cc-pVTZ, etc.)
`high_level_force_field`	str	Force field for high layer (if MM, uncommon)
`medium_level_functional`	str	DFT functional for medium layer
`medium_level_basis`	str	Basis set for medium layer
`medium_level_force_field`	str	Force field for medium layer
`low_level_functional`	str	DFT functional for low layer (if QM, rare)
`low_level_basis`	str	Basis set for low layer (if QM, rare)
`low_level_force_field`	str	Force field for low layer (AMBER=HardFirst, UFF, DREIDING, etc.)

Settings Atom Partitioning

Parameter	Type	Description
`high_level_atoms`	list/str	High layer atom indices (e.g., [1,2,3] or “1-10,15”)
`medium_level_atoms`	list/str	Medium layer atom indices (3-layer only)
`low_level_atoms`	list/str	Low layer atom indices (usually auto-assigned)
`bonded_atoms`	list	Bonds crossing boundaries: [(atom1, atom2), …]. Optional; cut covalent bonds are assigned from connectivity if omitted.
`scale_factors`	dict	Link atom scale factors: {(atom1, atom2): [low, med, high]}

Settings Charge and Multiplicity

Parameter	Type	Description
`charge_total`	int	Total charge of complete molecular system (legacy: real_charge)
`mult_total`	int	Spin multiplicity of complete system (legacy: real_multiplicity)
`charge_intermediate`	int	Charge of high+medium layers (legacy: int_charge, 3-layer only)
`mult_intermediate`	int	Multiplicity of high+medium layers (legacy: int_multiplicity)
`charge_high`	int	Charge of high layer only (legacy: model_charge)
`mult_high`	int	Multiplicity of high layer only (legacy: model_multiplicity)

Advanced ONIOM Features

Link Atom Handling

ONIOM automatically handles covalent bonds crossing layer boundaries by:

Link atom placement: Hydrogen atoms placed along cut bonds
Automatic assignment: Cut covalent bonds are detected from molecular connectivity unless bonded_atoms is given
Scale factor control: Distance scaling for optimal QM/MM interface
Charge redistribution: Prevents charge buildup at boundaries
Geometric constraints: Maintains chemical sensibility

Common scale factors: - 0.709: Standard C-H bond ratio (recommended for most cases) - 0.724: C-N bond ratio - 0.659: C-O bond ratio - Custom values: Can be optimized for specific systems

Force Field Integration

Gaussian supports multiple MM force fields:

Available Force Fields
Force Field	Description and Applications
`AMBER=HardFirst`	General-purpose for proteins, nucleic acids, standard organic molecules
`UFF`	Universal force field for any element combination
`DREIDING`	Good for organic and main-group compounds
`MM3`	Accurate for small organic molecules
`AMBER=SoftFirst`	Alternative AMBER parameterization

Configuration Methods

YAML Configuration Files

Create project-specific ONIOM settings in YAML format. Charge and multiplicity are not set in the project YAML; pass them on the command line (-ct, -mt, -ch, -mh, and for 3-layer jobs -ci, -mi).

Basic 2-Layer QM/MM (~/.chemsmart/gaussian/qmmm.yaml):

# Basic enzyme active site calculation
high_level_functional: "B3LYP"
high_level_basis: "6-31G*"
low_level_force_field: "AMBER=HardFirst"

3-Layer ONIOM Configuration (~/.chemsmart/gaussian/oniom3.yaml):

# Advanced organometallic catalyst
high_level_functional: "M06-2X"
high_level_basis: "def2-TZVP"
medium_level_functional: "B3LYP"
medium_level_basis: "6-31G*"
low_level_force_field: "UFF"

Transition State Configuration (~/.chemsmart/gaussian/ts_oniom.yaml):

# Enzyme transition state search
high_level_functional: "wB97X-D"
high_level_basis: "6-311++G(d,p)"
low_level_force_field: "AMBER=HardFirst"

Using Project Configuration

Use the YAML configuration with the project flag:

chemsmart sub gaussian -p qmmm -f system.pdb opt qmmm -ha 1-20 -ct 0 -mt 1 -ch 0 -mh 1 -ba '[[20,21]]'

Python Configuration

Programmatic configuration using the settings class:

from chemsmart.jobs.gaussian.settings import GaussianQMMMJobSettings

# Create basic 2-layer QM/MM settings
qmmm_settings = GaussianQMMMJobSettings(
    high_level_functional="B3LYP",
    high_level_basis="6-31G*",
    low_level_force_field="AMBER=HardFirst",
    high_level_atoms="1-25",
    bonded_atoms=[(25, 26)],
    charge_total=0,
    mult_total=1,
    charge_high=0,
    mult_high=1,
)

# 3-layer ONIOM configuration
oniom3_settings = GaussianQMMMJobSettings(
    high_level_functional="M06-2X",
    high_level_basis="def2-TZVP",
    medium_level_functional="B3LYP",
    medium_level_basis="6-31G*",
    low_level_force_field="UFF",
    high_level_atoms=[1, 2, 3, 4, 5],
    medium_level_atoms=list(range(6, 21)),
    bonded_atoms=[(5, 6), (20, 21)],
    charge_total=-1,
    mult_total=2,
    charge_intermediate=0,
    mult_intermediate=1,
    charge_high=0,
    mult_high=1,
    scale_factors={(5, 6): [0.709, 0.709, 0.709]},
)

Best Practices and Validation

Required Parameters

Layer definition: Must specify theory level for each layer (QM or MM)
Atom partitioning: Must define high_level_atoms for all calculations
Charges/multiplicities: Must specify charge and multiplicity for all layers
Boundary bonds: Cut covalent bonds are assigned as link atoms automatically; bonded_atoms may override this

Validation Rules

Theory consistency: Each layer must have consistent method specification
Charge balance: Total charges across layers must be chemically reasonable
Multiplicity rules: Multiplicity must follow 2S+1 convention
Boundary validation: Bonded atoms must span different layers
Force field availability: MM force fields must be available in Gaussian installation

Performance Considerations

Layer size optimization: Keep high-level layers small (typically < 100 atoms)
Basis set balance: Match basis set quality to chemical accuracy needs
Force field selection: Choose appropriate MM parameters for your system
Link atom placement: Optimize scale factors for critical boundaries
Job type selection: Use appropriate level for property of interest

System-Specific Guidelines

Enzyme Active Sites - High layer: Catalytic residues, substrates, cofactors (20-50 atoms) - Low layer: Protein backbone, solvent, distant residues - Recommended: B3LYP/6-31G*:AMBER=HardFirst

Organometallic Complexes - High layer: Metal center, coordinating atoms, reactive ligands - Medium layer: Extended coordination sphere, spectator ligands - Low layer: Counterions, solvent, crystal packing - Recommended: M06-2X/def2-TZVP:B3LYP/6-31G*:UFF

Surface Catalysis - High layer: Adsorbate, surface active sites (10-30 atoms) - Low layer: Extended surface, bulk material - Recommended: PBE/def2-SVP:UFF or specialized surface force fields

Error Prevention

Geometry preparation: Ensure reasonable starting geometries
Layer assignment: Verify atom layers match chemical intuition
Boundary placement: Avoid cutting through aromatic rings or conjugated systems
Charge verification: Check that layer charges sum to total system charge
Force field parameters: Confirm all atom types have MM parameters

Next Steps

For more advanced ONIOM workflows, see:

Project Configuration: Set up custom ONIOM project settings
Server Configuration: Configure HPC settings for large QM/MM jobs
Force Field Setup: Prepare custom MM parameter files
Analysis Tools: Post-process ONIOM results and extract energetics

Tip

ONIOM calculations benefit from careful system preparation. Consider pre-optimizing the MM region with pure force field calculations before running full QM/MM.

Warning

Choose QM/MM boundaries carefully. Avoid cutting through conjugated systems, and place boundaries at saturated C-C or C-H bonds when possible.

API Reference

class chemsmart.jobs.gaussian.settings.GaussianQMMMJobSettings(jobtype=None, parent_jobtype=None, high_level_functional=None, high_level_basis=None, high_level_force_field=None, medium_level_functional=None, medium_level_basis=None, medium_level_force_field=None, low_level_functional=None, low_level_basis=None, low_level_force_field=None, charge_total=None, mult_total=None, charge_intermediate=None, mult_intermediate=None, charge_high=None, mult_high=None, real_charge=None, real_multiplicity=None, int_charge=None, int_multiplicity=None, model_charge=None, model_multiplicity=None, high_level_atoms=None, medium_level_atoms=None, low_level_atoms=None, bonded_atoms=None, scale_factors=None, mm_atom_info_file=None, mm_parameters_file=None, **kwargs)[source]

Bases: GaussianJobSettings

Configuration settings for Gaussian QM/MM calculations using ONIOM methodology.

This class manages all parameters needed to set up multi-layer ONIOM calculations in Gaussian, which partition molecular systems into different regions treated with varying levels of theory. The ONIOM approach enables accurate quantum mechanical treatment of chemically active regions while efficiently handling large molecular environments with molecular mechanics.

The class supports 2-layer and 3-layer ONIOM calculations:

2-Layer ONIOM: High(QM):Low(MM)

High level: Quantum mechanics (DFT, ab initio, etc.)
Low level: Molecular mechanics force fields

3-Layer ONIOM: High(QM):Medium(QM):Low(MM)

High level: High-accuracy quantum mechanics
Medium level: Lower-cost quantum mechanics
Low level: Molecular mechanics force fields

Key Features: - Flexible layer definition with atom selection - Support for mixed QM/MM and QM/QM/MM schemes - Automatic link atom handling for covalent boundaries - Customizable scale factors for link atom placement - Integration with popular force fields (AMBER, UFF, etc.) - Multiple charge/multiplicity specifications per layer

jobtype

Type of ONIOM

Type:: str, optional

calculation ('sp', 'opt', 'freq', 'ts', 'irc',: ‘modred’, ‘scan’). When using CLI commands, this is automatically inferred from the parent command (e.g., ‘chemsmart sub gaussian opt qmmm’ sets jobtype=’opt’).

Level-specific theory parameters: high_level_functional (str): DFT functional for high layer (e.g., ‘B3LYP’, ‘M06-2X’) high_level_basis (str): Basis set for high layer (e.g., ‘6-31G*’, ‘def2-TZVP’) high_level_force_field (str): Force field for high layer (if MM) medium_level_functional (str): DFT functional for medium layer medium_level_basis (str): Basis set for medium layer medium_level_force_field (str): Force field for medium layer low_level_functional (str): DFT functional for low layer (if QM) low_level_basis (str): Basis set for low layer (if QM) low_level_force_field (str): Force field for low layer (usually MM)

Charge and multiplicity specifications: charge_total/mult_total (int): Full system properties (legacy: charge_total/real_multiplicity) charge_intermediate/mult_intermediate (int): Intermediate system properties (legacy: int_charge/int_multiplicity) charge_high/mult_high (int): Model/high-layer properties (legacy: model_charge/model_multiplicity)

Atom partitioning: high_level_atoms (list/str): Atoms in high layer (1-indexed) medium_level_atoms (list/str): Atoms in medium layer (1-indexed) low_level_atoms (list/str): Atoms in low layer (1-indexed) bonded_atoms (list): Covalent bonds crossing layer boundaries. If omitted, cut covalent bonds are assigned from connectivity. scale_factors (dict): Custom scale factors for link atom placement

Examples

2-layer enzyme active site calculation: >>> settings = GaussianQMMMJobSettings( … jobtype=’opt’, … high_level_functional=’B3LYP’, … high_level_basis=’6-31G*’, … low_level_force_field=’AMBER=HardFirst’, … charge_total=0, … real_multiplicity=1, … high_level_atoms=[1, 2, 3, 4, 5], # Active site residues … bonded_atoms=[(5, 6)], # QM-MM boundary bond … )

3-layer organometallic catalyst: >>> settings = GaussianQMMMJobSettings( … jobtype=’freq’, … high_level_functional=’M06-2X’, … high_level_basis=’def2-TZVP’, … medium_level_functional=’B3LYP’, … medium_level_basis=’6-31G*’, … low_level_force_field=’UFF’, … charge_total=-1, … real_multiplicity=2, … high_level_atoms=’1-10’, # Metal center and ligands … medium_level_atoms=’11-50’, # Extended coordination sphere … bonded_atoms=[(10,11), (50,51)], … scale_factors={(10,11): [0.709, 0.709, 0.709]} … )

Note

The real/intermediate/model charge and multiplicity specifications follow ONIOM conventions where: - Real system: Complete molecular system - Intermediate system: High+Medium layers (3-layer only) - Model system: High layer only

Scale factors control link atom placement and default to covalent radii ratios if not specified. The format is {(atom1,atom2): [low,medium,high]}.

Gaussian QM/MM ONIOM Calculations Guide

Overview

Basic QM/MM Command

QM/MM-Specific Options

Job Type and Theory Levels

Atom Partitioning

MM Atom Types and Parameters

Charge and Multiplicity

Usage Examples

2-Layer Enzyme Active Site

3-Layer Organometallic Catalyst

Transition State Search

Frequency Analysis

Single Point Energy

GaussianQMMMJobSettings Reference

Core Configuration Parameters

Job Type and Theory Levels

Settings Atom Partitioning

Settings Charge and Multiplicity

Advanced ONIOM Features

Link Atom Handling

Force Field Integration

Configuration Methods

YAML Configuration Files

Python Configuration

Best Practices and Validation

Required Parameters

Validation Rules

Performance Considerations

System-Specific Guidelines

Error Prevention

Next Steps

API Reference

See Also