Skip to content

qchem

A Q-Chem calculator built on Pymatgen and Custodian functionality.

QChem 

QChem(
    atoms: Atoms,
    charge: int = 0,
    spin_multiplicity: int = 1,
    rem: dict | None = None,
    opt: dict[str, list[str]] | None = None,
    pcm: dict | None = None,
    solvent: dict | None = None,
    smx: dict | None = None,
    scan: dict[str, list] | None = None,
    van_der_waals: dict[str, float] | None = None,
    vdw_mode: Literal["atomic", "sequential"] = "atomic",
    plots: dict | None = None,
    nbo: dict | None = None,
    geom_opt: dict | None = None,
    cdft: list[list[dict]] | None = None,
    almo_coupling: (
        list[list[tuple[int, int]]] | None
    ) = None,
    svp: dict | None = None,
    pcm_nonels: dict | None = None,
    qchem_dict_set_params: dict[str, Any] | None = None,
    **fileiocalculator_kwargs
)

Bases: FileIOCalculator

Custom Q-Chem calculator built on Pymatgen and Custodian.

that class for more information.

Parameters:

  • atoms (Atoms) –

    The Atoms object to be used for the calculation.

  • charge (int, default: 0 ) –

    The total charge of the molecular system.

  • spin_multiplicity (int, default: 1 ) –

    The spin multiplicity of the molecular system.

  • rem (dict | None, default: None ) –

    A dictionary of all the input parameters for the rem section of QChem input file. e.g. rem = {'method': 'rimp2', 'basis': '6-31*G++'}

  • opt (dict[str, list[str]] | None, default: None ) –

    A dictionary of opt sections, where each opt section is a key and the corresponding values are a list of strings. Strings must be formatted as instructed by the QChem manual. The different opt sections are: CONSTRAINT, FIXED, DUMMY, and CONNECT e.g. opt = {"CONSTRAINT": ["tors 2 3 4 5 25.0", "tors 2 5 7 9 80.0"], "FIXED": ["2 XY"]}

  • pcm (dict | None, default: None ) –

    A dictionary of the PCM section, defining behavior for use of the polarizable continuum model. e.g. pcm = {"theory": "cpcm", "hpoints": 194}

  • solvent (dict | None, default: None ) –

    A dictionary defining the solvent parameters used with PCM. e.g. solvent = {"dielectric": 78.39, "temperature": 298.15}

  • smx (dict | None, default: None ) –

    A dictionary defining solvent parameters used with the SMD method, a solvent method that adds short-range terms to PCM. e.g. smx =

  • scan (dict[str, list] | None, default: None ) –

    A dictionary of scan variables. Because two constraints of the same type are allowed (for instance, two torsions or two bond stretches), each TYPE of variable (stre, bend, tors) should be its own key in the dict, rather than each variable. Note that the total number of variable (sum of lengths of all lists) CANNOT be more than two. e.g. scan = {"stre": ["3 6 1.5 1.9 0.1"], "tors": ["1 2 3 4 -180 180 15"]}

  • van_der_waals (dict[str, float] | None, default: None ) –

    A dictionary of custom van der Waals radii to be used when constructing cavities for the PCM model or when computing, e.g. Mulliken charges. They keys are strs whose meaning depends on the value of vdw_mode, and the values are the custom radii in angstroms.

  • vdw_mode (Literal['atomic', 'sequential'], default: 'atomic' ) –

    Method of specifying custom van der Waals radii - 'atomic' or 'sequential'. In 'atomic' mode (default), dict keys represent the atomic number associated with each radius (e.g., 12 = carbon). In 'sequential' mode, dict keys represent the sequential position of a single specific atom in the input structure.

  • plots (dict | None, default: None ) –

    A dictionary of all the input parameters for the plots section of the QChem input file.

  • nbo (dict | None, default: None ) –

    A dictionary of all the input parameters for the nbo section of the QChem input file.

  • geom_opt (dict | None, default: None ) –

    A dictionary of input parameters for the geom_opt section of the QChem input file. This section is required when using the libopt3 geometry optimizer.

  • cdft (list[list[dict]] | None, default: None ) –

    A list of lists of dictionaries, where each dictionary represents a charge constraint in the cdft section of the QChem input file. Each entry in the main list represents one state (allowing for multi-configuration calculations using constrained density functional theory - configuration interaction (CDFT-CI). Each state is represented by a list, which itself contains some number of constraints (dictionaries).

    1. For a single-state calculation with two constraints: cdft=[[ {"value": 1.0, "coefficients": [1.0], "first_atoms": [1], "last_atoms": [2], "types": [None]}, {"value": 2.0, "coefficients": [1.0, -1.0], "first_atoms": [1, 17], "last_atoms": [3, 19], "types": ["s"]} ]]

    Note that a type of None will default to a charge constraint (which can also be accessed by requesting a type of "c" or "charge".

    1. For a multi-reference calculation: cdft=[ [ {"value": 1.0, "coefficients": [1.0], "first_atoms": [1], "last_atoms": [27], "types": ["c"]}, {"value": 0.0, "coefficients": [1.0], "first_atoms": [1], "last_atoms": [27], "types": ["s"]}, ], [ {"value": 0.0, "coefficients": [1.0], "first_atoms": [1], "last_atoms": [27], "types": ["c"]}, {"value": -1.0, "coefficients": [1.0], "first_atoms": [1], "last_atoms": [27], "types": ["s"]}, ] ]
  • almo_coupling (list[list[tuple[int, int]]] | None, default: None ) –

    A list of lists of int 2-tuples used for calculations of diabatization and state coupling calculations relying on the absolutely localized molecular orbitals (ALMO) methodology. Each entry in the main list represents a single state (two states are included in an ALMO calculation). Within a single state, each 2-tuple represents the charge and spin multiplicity of a single fragment. e.g. almo=[[(1, 2), (0, 1)], [(0, 1), (1, 2)]]

  • svp (dict | None, default: None ) –

    of the Q-Chem input file, which is formatted as a FORTRAN namelist. Note that in pymatgen, these parameters are typically not set by the user, but rather are populated automatically by an InputSet.

    An example for water may look like: { "RHOISO": "0.001", "DIELST": "78.36", "NPTLEB": "1202", "ITRNGR": "2", "IROTGR": "2", "IPNRF": "1", "IDEFESR": "1", }

    See https://manual.q-chem.com/6.0/subsec_SS(V)PE.html in the Q-Chem manual for more details.

  • pcm_nonels (dict | None, default: None ) –

    model, corresponding to the $pcm_nonels section of the Q-Chem input file/ Note that in pymatgen, these parameters are typically not set by the user, but rather are populated automatically by an InputSet.

    An example for water may look like: { "a": "-0.006496", "b": "0.050833", "c": "-566.7", "d": "-30.503", "gamma": "3.2", "solvrho": "0.05", "delta": 7, "gaulag_n": 40, }

    See https://manual.q-chem.com/6.0/example_CMIRS-water.html in the Q-Chem manual for more details.

  • qchem_dict_set_params (dict[str, Any] | None, default: None ) –

    Keyword arguments to be passed to pymatgen.io.qchem.sets.QChemDictSet, which will generate a QCInput. If qchem_dict_set_params is specified, the resulting QCInput will be merged with the QCInput generated from the QChem calculator kwargs, with the former taking priority. Accepts all arguments that pymatgen.io.qchem.sets.QChemDictSet accepts, except for molecule, which will always be generated from atoms. By default, job_type, basis_set, and scf_algorithm will be pulled from the rem kwarg if not specified in qchem_dict_set_params. qchem_version will default to 6 if not specified in qchem_dict_set_params.

  • **fileiocalculator_kwargs –

    Additional arguments to be passed to ase.calculators.calculator.FileIOCalculator.

Returns:

  • None –
Source code in quacc/calculators/qchem/qchem.py 
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
def __init__(
    self,
    atoms: Atoms,
    charge: int = 0,
    spin_multiplicity: int = 1,
    rem: dict | None = None,
    opt: dict[str, list[str]] | None = None,
    pcm: dict | None = None,
    solvent: dict | None = None,
    smx: dict | None = None,
    scan: dict[str, list] | None = None,
    van_der_waals: dict[str, float] | None = None,
    vdw_mode: Literal["atomic", "sequential"] = "atomic",
    plots: dict | None = None,
    nbo: dict | None = None,
    geom_opt: dict | None = None,
    cdft: list[list[dict]] | None = None,
    almo_coupling: list[list[tuple[int, int]]] | None = None,
    svp: dict | None = None,
    pcm_nonels: dict | None = None,
    qchem_dict_set_params: dict[str, Any] | None = None,
    **fileiocalculator_kwargs,
) -> None:
    """
    Initialize the Q-Chem calculator. Most of the input parameters here are used to
    create a `pymatgen.io.qchem.inputs.QCInput` object. See the documentation for
    that class for more information.

    Parameters
    ----------
    atoms
        The Atoms object to be used for the calculation.
    charge
        The total charge of the molecular system.
    spin_multiplicity
        The spin multiplicity of the molecular system.
    rem
        A dictionary of all the input parameters for the rem section of
        QChem input file. e.g. rem = {'method': 'rimp2', 'basis': '6-31*G++'}
    opt
        A dictionary of opt sections, where each opt section is a key and
        the corresponding values are a list of strings. Strings must be
        formatted as instructed by the QChem manual. The different opt
        sections are: CONSTRAINT, FIXED, DUMMY, and CONNECT e.g. opt =
        {"CONSTRAINT": ["tors 2 3 4 5 25.0", "tors 2 5 7 9 80.0"], "FIXED":
        ["2 XY"]}
    pcm
        A dictionary of the PCM section, defining behavior for use of the
        polarizable continuum model. e.g. pcm = {"theory": "cpcm",
        "hpoints": 194}
    solvent
        A dictionary defining the solvent parameters used with PCM. e.g.
        solvent = {"dielectric": 78.39, "temperature": 298.15}
    smx
        A dictionary defining solvent parameters used with the SMD method, a
        solvent method that adds short-range terms to PCM. e.g. smx =
        {"solvent": "water"}
    scan
        A dictionary of scan variables. Because two constraints of the same
        type are allowed (for instance, two torsions or two bond stretches),
        each TYPE of variable (stre, bend, tors) should be its own key in
        the dict, rather than each variable. Note that the total number of
        variable (sum of lengths of all lists) CANNOT be more than two. e.g.
        scan = {"stre": ["3 6 1.5 1.9 0.1"], "tors": ["1 2 3 4 -180 180
        15"]}
    van_der_waals
        A dictionary of custom van der Waals radii to be used when
        constructing cavities for the PCM model or when computing, e.g.
        Mulliken charges. They keys are strs whose meaning depends on the
        value of vdw_mode, and the values are the custom radii in angstroms.
    vdw_mode
        Method of specifying custom van der Waals radii - 'atomic' or
        'sequential'. In 'atomic' mode (default), dict keys represent the
        atomic number associated with each radius (e.g., 12 = carbon). In
        'sequential' mode, dict keys represent the sequential position of a
        single specific atom in the input structure.
    plots
        A dictionary of all the input parameters for the plots section of
        the QChem input file.
    nbo
        A dictionary of all the input parameters for the nbo section of the
        QChem input file.
    geom_opt
        A dictionary of input parameters for the geom_opt section of the
        QChem input file. This section is required when using the libopt3
        geometry optimizer.
    cdft
        A list of lists of dictionaries, where each dictionary represents a
        charge constraint in the cdft section of the QChem input file. Each
        entry in the main list represents one state (allowing for
        multi-configuration calculations using constrained density
        functional theory - configuration interaction (CDFT-CI). Each state
        is represented by a list, which itself contains some number of
        constraints (dictionaries).

        1. For a single-state calculation with two constraints:
        cdft=[[
            {"value": 1.0, "coefficients": [1.0], "first_atoms": [1],
            "last_atoms": [2], "types": [None]}, {"value": 2.0,
            "coefficients": [1.0, -1.0], "first_atoms": [1, 17],
            "last_atoms": [3, 19],
                "types": ["s"]}
        ]]

        Note that a type of None will default to a charge constraint (which
        can also be accessed by requesting a type of "c" or "charge".

        2. For a multi-reference calculation:
        cdft=[
            [
                {"value": 1.0, "coefficients": [1.0], "first_atoms": [1],
                "last_atoms": [27],
                    "types": ["c"]},
                {"value": 0.0, "coefficients": [1.0], "first_atoms": [1],
                "last_atoms": [27],
                    "types": ["s"]},
            ], [
                {"value": 0.0, "coefficients": [1.0], "first_atoms": [1],
                "last_atoms": [27],
                    "types": ["c"]},
                {"value": -1.0, "coefficients": [1.0], "first_atoms": [1],
                "last_atoms": [27],
                    "types": ["s"]},
            ]
        ]
    almo_coupling
        A list of lists of int 2-tuples used for calculations of
        diabatization and state coupling calculations
        relying on the absolutely localized molecular orbitals (ALMO)
        methodology. Each entry in the main list represents a single
        state (two states are included in an ALMO calculation). Within a
        single state, each 2-tuple represents the charge and spin
        multiplicity of a single fragment.
        e.g. almo=[[(1, 2), (0, 1)], [(0, 1), (1, 2)]]
    svp: Settings for the ISOSVP solvent model, corresponding to the $svp section
        of the Q-Chem input file, which is formatted as a FORTRAN namelist. Note that in pymatgen, these
        parameters are typically not set by the user, but rather are populated automatically by an InputSet.

        An example for water may look like:
            {
                "RHOISO": "0.001",
                "DIELST": "78.36",
                "NPTLEB": "1202",
                "ITRNGR": "2",
                "IROTGR": "2",
                "IPNRF": "1",
                "IDEFESR": "1",
            }

        See https://manual.q-chem.com/6.0/subsec_SS(V)PE.html in the Q-Chem manual for more
        details.
    pcm_nonels: Settings for the non-electrostatic part of the CMIRS solvation
        model, corresponding to the $pcm_nonels section of the Q-Chem input file/ Note that in pymatgen,
        these parameters are typically not set by the user, but rather are populated automatically by an
        InputSet.

        An example for water may look like:
            {
                "a": "-0.006496",
                "b": "0.050833",
                "c": "-566.7",
                "d": "-30.503",
                "gamma": "3.2",
                "solvrho": "0.05",
                "delta": 7,
                "gaulag_n": 40,
            }

        See https://manual.q-chem.com/6.0/example_CMIRS-water.html in the Q-Chem manual for more details.
    qchem_dict_set_params
        Keyword arguments to be passed to `pymatgen.io.qchem.sets.QChemDictSet`,
        which will generate a `QCInput`. If `qchem_dict_set_params` is specified,
        the resulting `QCInput` will be merged with the `QCInput` generated from
        the `QChem` calculator kwargs, with the former taking priority. Accepts
        all arguments that `pymatgen.io.qchem.sets.QChemDictSet` accepts, except
        for `molecule`, which will always be generated from `atoms`. By default,
        `job_type`, `basis_set`, and `scf_algorithm` will be pulled from the `rem`
        kwarg if not specified in `qchem_dict_set_params`. `qchem_version` will
        default to 6 if not specified in `qchem_dict_set_params`.
    **fileiocalculator_kwargs
        Additional arguments to be passed to
        [ase.calculators.calculator.FileIOCalculator][].

    Returns
    -------
    None
    """
    # Assign variables to self
    self.atoms = atoms
    self.charge = charge
    self.spin_multiplicity = spin_multiplicity
    self.rem = rem or {}
    self.opt = opt
    self.pcm = pcm
    self.solvent = solvent
    self.smx = smx
    self.scan = scan
    self.van_der_waals = van_der_waals
    self.vdw_mode = vdw_mode
    self.plots = plots
    self.nbo = nbo
    self.geom_opt = geom_opt
    self.cdft = cdft
    self.almo_coupling = almo_coupling
    self.svp = svp
    self.pcm_nonels = pcm_nonels
    self.qchem_dict_set_params = qchem_dict_set_params or {}
    self.fileiocalculator_kwargs = fileiocalculator_kwargs

    # Instantiate previous orbital coefficients
    self.prev_orbital_coeffs = None

    # Clean up parameters
    cleanup_attrs(self)

    # Set default params
    self._set_default_params()

    # Instantiate the calculator
    super().__init__(
        restart=None,
        label=None,
        command="",
        atoms=self.atoms,
        profile=None,
        **self.fileiocalculator_kwargs,
    )

almo_coupling instance-attribute 

almo_coupling = almo_coupling

atoms instance-attribute 

atoms = atoms

cdft instance-attribute 

cdft = cdft

charge instance-attribute 

charge = charge

fileiocalculator_kwargs instance-attribute 

fileiocalculator_kwargs = fileiocalculator_kwargs

geom_opt instance-attribute 

geom_opt = geom_opt

implemented_properties class-attribute 

implemented_properties: list[str] = [
    "energy",
    "forces",
    "hessian",
    "taskdoc",
]

nbo instance-attribute 

nbo = nbo

opt instance-attribute 

opt = opt

pcm instance-attribute 

pcm = pcm

pcm_nonels instance-attribute 

pcm_nonels = pcm_nonels

plots instance-attribute 

plots = plots

prev_orbital_coeffs instance-attribute 

prev_orbital_coeffs = None

qchem_dict_set_params instance-attribute 

qchem_dict_set_params = qchem_dict_set_params or {}

rem instance-attribute 

rem = rem or {}

results class-attribute 

results: QchemResults = {}

scan instance-attribute 

scan = scan

smx instance-attribute 

smx = smx

solvent instance-attribute 

solvent = solvent

spin_multiplicity instance-attribute 

spin_multiplicity = spin_multiplicity

svp instance-attribute 

svp = svp

van_der_waals instance-attribute 

van_der_waals = van_der_waals

vdw_mode instance-attribute 

vdw_mode = vdw_mode

execute 

execute() -> int

Execute Q-Chem.

Returns:

  • int –

    The return code.

Source code in quacc/calculators/qchem/qchem.py 
290
291
292
293
294
295
296
297
298
299
300
def execute(self) -> int:
    """
    Execute Q-Chem.

    Returns
    -------
    int
        The return code.
    """
    run_custodian(directory=self.directory)
    return 0

read_results 

read_results() -> None

Read the Q-Chem output files. Update the .results and .prev_orbital_coeffs attributes.

Returns:

  • None –
Source code in quacc/calculators/qchem/qchem.py 
302
303
304
305
306
307
308
309
310
311
312
313
def read_results(self) -> None:
    """
    Read the Q-Chem output files. Update the .results and .prev_orbital_coeffs
    attributes.

    Returns
    -------
    None
    """
    results, prev_orbital_coeffs = read_qchem(self.directory)
    self.results = results
    self.prev_orbital_coeffs = prev_orbital_coeffs

write_input 

write_input(
    atoms: Atoms,
    properties: list[str] | None = None,
    system_changes: list[str] | None = None,
) -> None

Write the Q-Chem input files.

Parameters:

  • atoms (Atoms) –

    The Atoms object to be used for the calculation.

  • properties (list[str] | None, default: None ) –

    List of properties to calculate.

  • system_changes (list[str] | None, default: None ) –

    List of changes to the system since last calculation.

Returns:

  • None –
Source code in quacc/calculators/qchem/qchem.py 
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
def write_input(
    self,
    atoms: Atoms,
    properties: list[str] | None = None,
    system_changes: list[str] | None = None,
) -> None:
    """
    Write the Q-Chem input files.

    Parameters
    ----------
    atoms
        The Atoms object to be used for the calculation.
    properties
        List of properties to calculate.
    system_changes
        List of changes to the system since last calculation.

    Returns
    -------
    None
    """
    FileIOCalculator.write_input(self, atoms, properties, system_changes)

    qc_input = make_qc_input(self, atoms)

    write_qchem(
        qc_input, self.directory, prev_orbital_coeffs=self.prev_orbital_coeffs
    )