repESP.respin_format module

Parsing and writing resp program instruction file format (“respin”)

class Respin(title: str, cntrl: repESP.respin_format.Respin.Cntrl, subtitle: str, charge: int, molecule: repESP.types.Molecule[repESP.types.Atom][repESP.types.Atom], ivary: repESP.respin_format.Respin.Ivary)[source]

Bases: object

Dataclass describing the resp program instructions

Note that the functionality is currently limited to a single molecule and a single structure.

Parameters:
  • title (str) – The title of the calculation to be performed.
  • cntrl (Cntrl) – Dataclass representing the “cntrl” section of the input.
  • subtitle (str) – Subtitle describing the considered molecular structure.
  • charge (int) – The total charge of the molecule.
  • molecule (Molecule[Atom]) – The molecule which charges are being fitted. Only atom identities are required.
  • ivary (Ivary) – The “ivary” values for fitting the considered structure. These determine how the charge on each atom is allowed to vary during the fitting.
title

See initialization parameter

cntrl

See initialization parameter

subtitle

See initialization parameter

charge

See initialization parameter

molecule

See initialization parameter

ivary

See initialization parameter

class Cntrl(inopt: int = 0, ioutopt: int = 0, iqopt: int = 1, ihfree: int = 1, irstrnt: int = 1, qwt: float = 0)[source]

Bases: object

Dataclass describing the “cntrl” section of a “respin” file

See resp program documentation for more details.

Parameters:
  • inopt (int, optional) – If equal to 1, resp will cycle through different “qwt” values from the file specified with the -w option. Defaults to 0.
  • ioutopt (int, optional) – If equal to 1, resp will write restart info of new ESP field to the file specified with the -s option. Defaults to 0.
  • iqopt (int, optional) – Controls setting initial charges. If equal to 1 (default), all initial charges will be set to zero. If equal to 2, initial charges are read from the file specified with the -q option. If equal to 3, charges are read as with the previous option and will additionally be averaged according to “ivary” values (normally not used).
  • ihfree (int, optional) – If equal to 0, the charge magnitude restraint is applied to all charges. If equal to 1 (default), the restraint does not apply to hydrogen atoms.
  • irstrnt (int, optional) – Controls the type of charge magnitude restraint. If equal to 0, harmonic restraints are used (old-style). If equal to 1 (default), hyperbolic restraints are used. If equal to 2, no charge fitting is carried out and only analysis of input charges is performed.
  • qwt (float, optional) –

    The weight of the charge magnitude restraint to be used during the fitting. Defaults to 0.0 (no charge magnitude restraint).

    Warning

    The default used here is different from the default used by resp.

    That the resp documentation specifies that it uses the Amber force field values by default. However, it is not clear how it can determine the fitting stage. Thus, to remove the ambiguity, this dataclass assumes a weight of zero by default.

    Note

    Amber force fields use values of 0.0005 and 0.001 for stages 1 and 2, respectively. The Glycam force field is derived with one stage fitting with a value of 0.01.
inopt

See initialization parameter

ioutopt

See initialization parameter

iqopt

See initialization parameter

ihfree

See initialization parameter

irstrnt

See initialization parameter

qwt

See initialization parameter

nmol

Number of structures in a multiple structure fit.

With the current implementation this will always be equal to 1.

class Ivary(values: List[int])[source]

Bases: object

Dataclass representing per-atom fitting instructions for resp

The fitting instructions are represented as a list of values stored in the values attribute. The length of this list must be the same as the number of atoms in the molecule it describes. Consecutive values refer to consecutive atoms of the molecule.

The values determine how the charge on the atom can vary during the fitting and the allowed values are:

  • -1, meaning that the atom’s charge is “frozen” at the initial value
  • 0, meaning that this atom will be varied freely
  • Larger than zero, representing the 1-based index of the atom in the molecule to which this atom is to be equivalenced.

Example

Consider fitting RESP charges in a molecule of methylamine:

>>> methylamine = Molecule([Atom(atomic_number) for atomic_number in [6, 1, 1, 1, 7, 1, 1]])

Fitting RESP charges consists of two stages. The ivary section for the second stage of the fitting for the methylamine molecule should be as follows:

>>> ivary = Respin.Ivary([0, 0, 2, 2, -1, -1, -1])

The carbon atom is free to vary during the fitting. The first of the methyl hydrogens is equivalenced to the remaining two but they haven’t been specified yet, so it also has a value of 0. These two hydrogen atoms are equivalenced to the first one, and thus are assigned its one-based index in the molecule, i.e. 2 (meaning “equivalenced to the second atom of the molecule”). The nitrogen atom and the two hydrogen atoms attached to it are frozen during the second stage of the fitting and are thus assigned values of -1.

Parameters:values (List[int]) – The per-atom instructions for the resp program.
values

See initialization parameter

describe(molecule: Optional[repESP.types.Molecule[repESP.types.Atom][repESP.types.Atom]] = None) → str[source]

Verbosely report the “ivary” actions

Example

>>> print(ivary.describe(methylamine))
Atom (C) number 1
Atom (H) number 2
Atom (H) number 3, equivalenced to atom 2
Atom (H) number 4, equivalenced to atom 2
Atom (N) number 5, frozen
Atom (H) number 6, frozen
Atom (H) number 7, frozen
Parameters:molecule (Optional[Molecule[Atom]], optional) – The molecule to which the ivary information refers. This argument is optional and defaults to None. If it is provided, atom identities will be included in the output.
Raises:ValueError – Raised when the number of atoms in the molecule does not match the length of the list of values in this object.
Returns:A verbose description of the “ivary” instructions.
Return type:str
classmethod from_equivalence(equivalence: repESP.equivalence.Equivalence) → IvaryT[source]

Alternative initialization from equivalence information

Parameters:equivalence (Equivalence) – Information about chemical equivalence of atoms in a molecule.
wtmol

Relative weight of the structure in a multistructure fitting.

A value of 1.0 is always returned in the current implementation.

iuniq

The number of atoms in the fitted structure

get_equivalence_from_two_stage_resp_ivary(ivary1: repESP.respin_format.Respin.Ivary, ivary2: repESP.respin_format.Respin.Ivary) → repESP.equivalence.Equivalence[source]

Get atom equivalence from input files for two 2-stage RESP

Derive atom equivalence based on the data in two “respin” files (represented by the Respin objects) created for the purpose of two-stage RESP fitting with the resp program. The files can be generated with the respgen program with the following commands:

respgen -i methane.ac -o methane.respin1 -f resp1
respgen -i methane.ac -o methane.respin2 -f resp2

Warning

The correctness of this function relies on:

  1. Antechamber and respgen correctly recognizing the symmetry relations between atoms. Fast-exchanging atoms may not be identified.
  2. The author’s understanding of how respgen generates the “respin” files for two-stage RESP fitting.

Thus it is advised to always check that the result of this function agrees with the domain knowledge about the studied molecule.

parse_respin(f: TextIO) → repESP.respin_format.Respin[source]

Parse a file in the “respin” format (input format of resp)

Note that only files describing a single structure fit are currently supported.

Parameters:f (TextIO) – File object opened in read mode containing the “respin” file.
Raises:InputFormatError – Raised when the file does not follow the expected format.
Returns:Object representing the fitting instructions for the resp program.
Return type:Respin
write_respin(f: TextIO, respin: repESP.respin_format.Respin, skip_cntrl_defaults: bool = True) → None[source]

Write a “respin” file described by the given input data

Parameters:
  • f (TextIO) – The file object to which the instructions are to be saved. The file must be opened for writing.
  • respin (Respin) – The dataclass representing all the instructions needed by the resp program.
  • skip_cntrl_defaults (bool, optional) – When this option is set to True (default), fitting options in the “cntrl” section with default values will not be written to the file.