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.

ORCA QM/MM Multiscale Calculations Guide

ChemSmart provides comprehensive tools for multiscale QM/MM calculations using ORCA. This section covers various QM/MM schemes including additive, subtractive ONIOM, and crystal QM/MM methods for large molecular systems.

Overview

ORCA QM/MM calculations allow you to treat large systems by combining quantum mechanical (QM) methods for chemically important regions with molecular mechanical (MM) force fields for the environment. ChemSmart supports five types of multiscale calculations:

Additive QM/MM - Traditional QM/MM with electrostatic embedding
Subtractive QM/QM2 - Two-layer ONIOM scheme with different QM methods
Subtractive QM/QM2/MM - Three-layer ONIOM with QM, QM2, and MM layers
MOL-CRYSTAL-QMMM - QM/MM for molecular crystals
IONIC-CRYSTAL-QMMM - QM/MM for semiconductors and insulators

Basic QM/MM Command

The basic command structure for ORCA QM/MM calculations is:

chemsmart sub [OPTIONS] orca [ORCA_OPTIONS] qmmm [QMMM_OPTIONS]

QM/MM-Specific Options

Job Type and Theory Level

Job Type and Method Options
Option	Type	Description
`-j, --jobtype`	Choice	Multiscale calculation type: QMMM, QM/QM2, QM/QM2/MM, MOL-CRYSTAL-QMMM, IONIC-CRYSTAL-QMMM
`-hx, --high-level-functional`	string	DFT functional for high-level (QM) region (e.g., B3LYP, PBE0)
`-hb, --high-level-basis`	string	Basis set for high-level (QM) region (e.g., def2-SVP, def2-TZVP)
`-mx, --medium-level-functional`	string	DFT functional for medium-level (QM2) region
`-mb, --medium-level-basis`	string	Basis set for medium-level (QM2) region
`-mm, --medium-level-method`	string	Built-in method for medium-level (QM2) region (XTB, HF-3C, PBEH-3C)
`-lf, --low-level-force-field`	string	Force field for low-level (MM) region (MMFF, AMBER, CHARMM)

Atom Partitioning

Atom Partition Options
Option	Type	Description
`-ha, --high-level-atoms`	string	High-level atom indices (e.g., ‘1-15,20’ or ‘1:15 20’)
`-ma, --medium-level-atoms`	string	Medium-level atom indices (e.g., ‘16-30’)
`-a, --active-atoms`	string	Active atom indices for optimization

Charge and Multiplicity

Charge and Multiplicity Options
Option	Type	Description
`-ch, --charge-high`	int	High-level region charge
`-mh, --mult-high`	string	High-level region multiplicity
`-cm, --charge-medium`	int	Medium layer charge (for QM/QM2/MM)
`-mm, --mult-medium`	string	Medium layer multiplicity
`-ct, --charge-total`	int	Total system charge
`-mt, --mult-total`	string	Total system multiplicity

Advanced QM/MM Options

Advanced QM/MM Options
Option	Type	Description
`-s, --medium-level-solvation`	string	Solvation model for medium-level region (CPCM, SMD)
`-e, --embedding-type`	string	Embedding type: electronic or mechanical
`-h, --high-level-h-bond-length`	dict	Custom high-level-H bond lengths
`-d, --delete-la-double-counting`	bool	Remove bend/torsion double counting
`-db, --delete-la-bond-double-counting-atoms`	bool	Remove bond double counting

Optimization Controls

Optimization Control Options
Option	Type	Description
`-o, --optregion-fixed-atoms`	string	Fixed atom indices in optimization
`-ua, --use-active-info-from-pbc`	string	Use active atom info from PDB file

Crystal QM/MM Options

Crystal QM/MM Options
Option	Type	Description
`-cc, --conv-charges`	bool	Use converged charges for crystal QM/MM
`-xn, --conv-charges-max-n-cycles`	int	Max cycles for charge convergence
`-t, --conv-charges-conv-thresh`	float	Charge convergence threshold
`-sc, --scale-formal-charge-mm-atom`	float	MM atom charge scaling factor
`-nc, --n-unit-cell-atoms`	int	Atoms per unit cell (MOL-CRYSTAL-QMMM)
`-ecp, --ecp-layer-ecp`	string	ECP type for boundary region
`-ecpn, --ecp-layer`	int	Number of ECP layers around QM region
`-sc2, --scale-formal-charge-ecp-atom`	float	ECP atom charge scaling factor

Usage Examples

Additive QM/MM

Basic additive QM/MM calculation with B3LYP for QM region and AMBER force field:

chemsmart sub orca -p protein_qmmm -f protein.pdb qmmm -j QMMM -hx B3LYP -hb def2-SVP -lf amber99 -ha 1-20 -ch 0 -mh 1 -ct 0 -mt 1

Subtractive QM/QM2 ONIOM

Two-layer ONIOM calculation with DFT for high level and semi-empirical for low level:

chemsmart sub orca -p enzyme_oniom -f enzyme.xyz qmmm -j QM/QM2 -hx B3LYP -hb def2-TZVP -mx HF -mb STO-3G -ha 1-15 -ma 16-50 -ch 0 -mh 1 -cm 0 -mm 1

Three-Layer QM/QM2/MM ONIOM

Three-layer ONIOM with DFT, semi-empirical, and MM:

chemsmart sub orca -p complex_system -f system.pdb qmmm -j QM/QM2/MM -hx B3LYP -hb def2-SVP -mm HF-3C -lf amber99 -ha 1-10 -ma 11-30 -ch 0 -mh 1 -cm 0 -mm 1 -ct 0 -mt 1

Crystal QM/MM for Molecular Crystals

QM/MM calculation for a molecular crystal:

chemsmart sub orca -p molecular_crystal -f crystal.cif qmmm -j MOL-CRYSTAL-QMMM -hx PBE -hb def2-SVP -ha 1-20 -ch 0 -mh 1 -nc 50 -cc true -xn 30

Advanced QM/MM with Custom Settings

QM/MM with custom bond lengths and embedding options:

chemsmart sub orca -p advanced_qmmm -f system.xyz qmmm -j QMMM -hx M06-2X -hb def2-TZVP -lf charmm36 -ha 1-25 -ch -1 -mh 2 -ct -1 -mt 2 -e electronic -h "{'C_H': 1.09, 'N_H': 1.01}" -d true

Project Configuration

You can also configure QM/MM settings in your project YAML file. Create a qmmm.yaml file in your project directory:

# ~/.chemsmart/orca/qmmm.yaml
high_level_functional: B3LYP
high_level_basis: def2-SVP
low_level_force_field: amber99
jobtype: opt
embedding_type: electronic
delete_la_double_counting: true

Then use it with the project flag:

chemsmart sub orca -p qmmm -f system.pdb qmmm -ha 1-20 -ch 0 -mh 1 -ct 0 -mt 1

Next Steps

For more advanced QM/MM workflows, see:

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

Tip

QM/MM calculations can be computationally demanding. Consider using HPC clusters with adequate memory and CPU resources, especially for large systems or crystal QM/MM calculations.

Warning

Ensure proper atom partitioning between QM and MM regions. The QM region should include chemically important areas like active sites, reaction centers, or defects in crystals.

ORCAQMMMJobSettings Reference

The ORCAQMMMJobSettings class provides comprehensive configuration options for ORCA multiscale calculations. This section provides detailed documentation for programmatic configuration.

Core Configuration Parameters

Job Type and Methods

Parameter	Type	Description
`jobtype`	str	Calculation type (QMMM, QM/QM2, QM/QM2/MM, MOL-CRYSTAL-QMMM, IONIC-CRYSTAL-QMMM)
`high_level_functional`	str	DFT functional for high-level (QM) region (B3LYP, PBE0, etc.)
`high_level_basis`	str	Basis set for high-level (QM) region (def2-SVP, def2-TZVP, etc.)
`medium_level_functional`	str	DFT functional for medium-level (QM2) intermediate layer
`medium_level_basis`	str	Basis set for medium-level (QM2) intermediate layer
`medium_level_method`	str	Built-in method for medium-level (XTB, HF-3C, PBEH-3C)
`low_level_force_field`	str	Force field for low-level (MM) region (MMFF, AMBER, CHARMM)

Settings Atom Partitioning

Parameter	Type	Description
`high_level_atoms`	list/str	High-level region atom indices (e.g., [1,2,3] or “1-10,15”)
`medium_level_atoms`	list/str	Medium-level region atom indices
`active_atoms`	list/str	Active atoms for optimization (default: all atoms)

Settings Charge and Multiplicity

Parameter	Type	Description
`charge_high`	int	Charge of high-level (QM) region
`mult_high`	int	Multiplicity of high-level (QM) region
`charge_medium`	int	Charge of medium system (QM2 layer)
`mult_medium`	int	Multiplicity of medium system
`charge_total`	int	Total system charge
`mult_total`	int	Total system multiplicity

Advanced Settings Options

Embedding and Interactions

Parameter	Type	Description
`embedding_type`	str	Electronic (default) or mechanical embedding
`medium_level_solvation`	str	Solvation model for medium-level (CPCM, SMD, etc.)
`delete_la_double_counting`	bool	Remove bend/torsion double counting
`delete_la_bond_double_counting_atoms`	bool	Remove bond double counting

Custom Bond Parameters

Parameter	Type	Description
`high_level_h_bond_length`	dict	Custom high-level-H bond lengths {(atom1, atom2): length}

Settings Optimization Controls

Parameter	Type	Description
`optregion_fixed_atoms`	list/str	Fixed atom indices during optimization
`use_active_info_from_pbc`	bool	Use active atom info from PDB file

Crystal QM/MM Parameters

For MOL-CRYSTAL-QMMM and IONIC-CRYSTAL-QMMM calculations:

Parameter	Type	Description
`conv_charges`	bool	Use converged charges (default: True)
`conv_charges_max_n_cycles`	int	Max charge convergence cycles
`conv_charges_conv_thresh`	float	Charge convergence threshold
`scale_formal_charge_mm_atom`	float	MM atom charge scaling factor
`n_unit_cell_atoms`	int	Atoms per unit cell (required for MOL-CRYSTAL-QMMM)
`ecp_layer_ecp`	str	ECP type for boundary region
`ecp_layer`	int	Number of ECP layers around QM region
`scale_formal_charge_ecp_atom`	float	ECP atom charge scaling factor

Configuration Methods

YAML Configuration Files

Create project-specific QM/MM settings in YAML format:

Basic QM/MM Configuration (~/.chemsmart/orca/qmmm.yaml):

# Basic additive QM/MM settings
jobtype: "QMMM"
qm_functional: "B3LYP"
qm_basis: "def2-SVP"
mm_force_field: "amber99"
embedding_type: "electronic"
delete_la_double_counting: true

ONIOM Configuration (~/.chemsmart/orca/oniom.yaml):

# Three-layer ONIOM settings
jobtype: "QM/QM2/MM"
qm_functional: "B3LYP"
qm_basis: "def2-TZVP"
qm2_functional: "HF"
qm2_basis: "STO-3G"
mm_force_field: "amber99"
embedding_type: "electronic"

Crystal QM/MM Configuration (~/.chemsmart/orca/crystal.yaml):

# Molecular crystal QM/MM settings
jobtype: "MOL-CRYSTAL-QMMM"
qm_functional: "PBE"
qm_basis: "def2-SVP"
n_unit_cell_atoms: 50
conv_charges: true
conv_charges_max_n_cycles: 30
conv_charges_conv_thresh: 0.01

Using Project Configuration

Use the YAML configuration with the project flag:

chemsmart sub orca -p qmmm -f system.pdb qmmm -qa 1-20 -cq 0 -mq 1 -ct 0 -mt 1

Python Configuration

Programmatic configuration using the settings class:

from chemsmart.jobs.orca.settings import ORCAQMMMJobSettings

# Create basic QM/MM settings
qmmm_settings = ORCAQMMMJobSettings(
    jobtype="QMMM",
    qm_functional="B3LYP",
    qm_basis="def2-SVP",
    mm_force_field="amber99",
    qm_atoms="1-20",
    charge_qm=0,
    mult_qm=1,
    charge_total=0,
    mult_total=1,
    embedding_type="electronic",
)

# ONIOM configuration
oniom_settings = ORCAQMMMJobSettings(
    jobtype="QM/QM2/MM",
    qm_functional="B3LYP",
    qm_basis="def2-TZVP",
    qm2_method="HF-3C",
    mm_force_field="charmm36",
    qm_atoms=[1, 2, 3, 4, 5],
    qm2_atoms=list(range(6, 21)),
    charge_qm=0,
    mult_qm=1,
    charge_medium=0,
    mult_medium=1,
)

Best Practices and Validation

Required Parameters

QM region: Must specify qm_functional and qm_basis (unless using built-in methods)
Atom partitioning: Must define qm_atoms for all calculations
Charges: Must specify appropriate charge/multiplicity for each layer
Force fields: Required for calculations involving MM regions

Validation Rules

Method conflicts: Cannot specify both functional/basis and built-in methods for the same layer
Crystal QM/MM: Multiplicity should not be specified for crystal calculations
Force field requirements: MM calculations require valid force field specification
Charge/multiplicity consistency: All layers must have compatible charge/multiplicity values

Performance Considerations

QM region size: Keep QM regions manageable (typically < 100 atoms for routine calculations)
Basis set selection: Balance accuracy vs. computational cost
Crystal calculations: Can be very demanding - ensure adequate computational resources
Convergence settings: Adjust charge convergence parameters for crystal QM/MM

Error Prevention

Atom indexing: Ensure atom indices are valid and don’t overlap inappropriately
File dependencies: Verify force field parameter files exist and are accessible
Resource allocation: Ensure sufficient memory/CPU for large QM/MM systems
Boundary effects: Carefully choose QM/MM boundaries to avoid artifacts

Advanced Features

Expanded Next Steps

For more advanced QM/MM workflows, see:

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

API Reference

class chemsmart.jobs.orca.settings.ORCAQMMMJobSettings(jobtype=None, high_level_functional=None, high_level_basis=None, intermediate_level_functional=None, intermediate_level_basis=None, intermediate_level_method=None, low_level_method=None, high_level_atoms=None, intermediate_level_atoms=None, charge_total=None, mult_total=None, charge_intermediate=None, mult_intermediate=None, charge_high=None, mult_high=None, intermediate_level_solvation=None, intermediate_solv_scheme=None, active_atoms=None, use_active_info_from_pbc=False, optregion_fixed_atoms=None, high_level_h_bond_length=None, delete_la_double_counting=False, delete_la_bond_double_counting_atoms=False, embedding_type=None, conv_charges=True, conv_charges_max_n_cycles=None, conv_charges_conv_thresh=None, scale_formal_charge_mm_atom=None, n_unit_cell_atoms=None, ecp_layer_ecp=None, ecp_layer=None, scale_formal_charge_ecp_atom=None, parent_jobtype=None, **kwargs)[source]

Bases: ORCAJobSettings

Configuration for ORCA multiscale QM/MM calculations.

Supports five multiscale calculation types: 1. Additive QM/MM 2. Subtractive QM/QM2 (2-layer ONIOM) 3. Subtractive QM/QM2/MM (3-layer ONIOM) 4. MOL-CRYSTAL-QMMM (molecular crystals) 5. IONIC-CRYSTAL-QMMM (semiconductors/insulators)

jobtype

Multiscale calculation type

Type:: str

high_level_functional

DFT functional for high-level (QM) region

Type:: str

high_level_basis

Basis set for high-level (QM) region

Type:: str

intermediate_level_functional

DFT

Type:: str

functional for intermediate-level

Type:: QM2

intermediate_level_basis

Basis

Type:: str

set for intermediate-level

Type:: QM2

intermediate_level_method

Built-in

Type:: str

method for intermediate-level

Type:: XTB, HF-3C, etc.

low_level_method

Method/force field for low-level (MM) region

Type:: str

high_level_atoms

Atom indices for high-level (QM) region

Type:: list

intermediate_level_atoms

Atom

Type:: list

indices for intermediate-level

Type:: QM2

charge_total

Total system charge

Type:: int

mult_total

Total system multiplicity

Type:: int

charge_intermediate

Intermediate layer charge

Type:: int

mult_intermediate

Intermediate layer multiplicity

Type:: int

charge_high

High-level region charge

Type:: int

mult_high

High-level region multiplicity

Type:: int

intermediate_level_solvation

Type:: str

Solvation model for intermediate-level region

active_atoms

Active atoms for optimization

Type:: list

use_active_info_from_pbc

Use PDB active atom info

Type:: bool

optregion_fixed_atoms

Fixed atoms in optimization

Type:: list

high_level_h_bond_length

Custom high-level-H bond distances

Type:: dict

delete_la_double_counting

Remove bend/torsion double counting

Type:: bool

delete_la_bond_double_counting_atoms

(bool): Remove bond double counting

embedding_type

Electronic or mechanical embedding

Type:: str

conv_charges

Use converged charges for crystal QM/MM

Type:: bool

conv_charges_max_n_cycles

Max charge convergence cycles

Type:: int

conv_charges_conv_thresh

Charge convergence threshold

Type:: float

scale_formal_charge_mm_atom

MM charge scaling factor

Type:: float

n_unit_cell_atoms

Atoms per unit cell (MOL-CRYSTAL-QMMM)

Type:: int

ecp_layer_ecp

ECP type for boundary region

Type:: str

ecp_layer

Number of ECP layers

Type:: int

scale_formal_charge_ecp_atom

ECP charge scaling factor

Type:: float

INTERMEDIATE_LEVEL_BUILT_IN_METHODS = ['XTB', 'XTB0', 'XTB1', 'XTB2', 'HF-3C', 'PBEH-3C', 'R2SCAN-3C', 'PM3', 'AM1']

check_crystal_qmmm()[source]

Validate crystal QM/MM job settings.

Ensures required parameters are set for MOL-CRYSTAL-QMMM and IONIC-CRYSTAL-QMMM calculations.

Raises:: AssertionError – If required parameters are missing or invalid

property qmmm_block

property qmmm_route_string

re_init_and_validate()[source]: Recompute derived fields and rerun validation after overrides.

validate_and_assign_level(functional, basis, built_in_method, level_name)[source]

Validate and assign level of theory for high/intermediate/low-level layers.

Parameters:

functional – DFT functional
basis – Basis set
built_in_method – Built-in ORCA method (XTB, HF-3C, etc.)
level_name – Layer name (high_level, intermediate_level, low_level)

Returns:

Validated level of theory string

Return type:

str

Raises:

ValueError – If incompatible options are specified