Perturbation Files (pertfiles)¶
Perturbation files (or pertfiles) are an older mechanism that was used
in somd to create a merged molecule from a passed input molecule.
They are a simple text file that describes the perturbation in terms
of changing forcefield parameters. You can create a merged molecule
from a single molecule plus pertfile using the
sire.morph.create_from_pertfile() function.
>>> merged_mol = sr.morph.create_from_pertfile(mol, "neopentane_methane.pert")
>>> print(merged_mol.property("charge0"))
>>> print(merged_mol.property("charge1"))
Note
This is an older mechanism that has many limitations due to the
inherent limits of the pertfile format. It is provided to aid
compatibility with older somd workflows, but is not
recommended for new use cases.
Updating internals involving ghost atoms¶
Sometimes you want to update the internals (bonds, angles, torsions) when one or more of the atoms involved are ghosts in either the reference or perturbed states.
The function sire.morph.zero_ghost_torsions() will automatically add
torsion perturbations that zero the force constant of any torsions that
involve ghost atoms in that state. This is useful when you want to
fade in or out torsion forces as ghost atoms appear or disappear.
>>> mols = sr.morph.zero_ghost_torsions(mols)
>>> print(mols[0].perturbation().to_openmm().changed_torsions())
torsion k0 k1 periodicity0 periodicity1 phase0 phase1
0 C5:5-C2:2-C3:3-H11:11 0.66944 0.0 3 3 -0.0 -0.0
1 C1:1-C2:2-C3:3-H11:11 0.66944 0.0 3 3 -0.0 -0.0
2 C5:5-C2:2-C3:3-H10:10 0.66944 0.0 3 3 -0.0 -0.0
3 C3:3-C2:2-C4:4-H12:12 0.66944 0.0 3 3 -0.0 -0.0
4 C1:1-C2:2-C3:3-H10:10 0.66944 0.0 3 3 -0.0 -0.0
5 C1:1-C2:2-C5:5-H16:16 0.66944 0.0 3 3 -0.0 -0.0
6 C5:5-C2:2-C3:3-H9:9 0.66944 0.0 3 3 -0.0 -0.0
7 C1:1-C2:2-C3:3-H9:9 0.66944 0.0 3 3 -0.0 -0.0
8 C3:3-C2:2-C1:1-H7:7 0.66944 0.0 3 3 -0.0 -0.0
9 C3:3-C2:2-C1:1-H8:8 0.66944 0.0 3 3 -0.0 -0.0
10 C3:3-C2:2-C1:1-H6:6 0.66944 0.0 3 3 -0.0 -0.0
11 C1:1-C2:2-C5:5-H15:15 0.66944 0.0 3 3 -0.0 -0.0
12 C4:4-C2:2-C5:5-H17:17 0.66944 0.0 3 3 -0.0 -0.0
13 C4:4-C2:2-C3:3-H11:11 0.66944 0.0 3 3 -0.0 -0.0
14 C4:4-C2:2-C3:3-H10:10 0.66944 0.0 3 3 -0.0 -0.0
15 C4:4-C2:2-C5:5-H16:16 0.66944 0.0 3 3 -0.0 -0.0
16 C4:4-C2:2-C3:3-H9:9 0.66944 0.0 3 3 -0.0 -0.0
17 C5:5-C2:2-C4:4-H14:14 0.66944 0.0 3 3 -0.0 -0.0
18 C5:5-C2:2-C4:4-H13:13 0.66944 0.0 3 3 -0.0 -0.0
19 C1:1-C2:2-C4:4-H14:14 0.66944 0.0 3 3 -0.0 -0.0
20 C4:4-C2:2-C5:5-H15:15 0.66944 0.0 3 3 -0.0 -0.0
21 C3:3-C2:2-C5:5-H17:17 0.66944 0.0 3 3 -0.0 -0.0
22 C1:1-C2:2-C4:4-H13:13 0.66944 0.0 3 3 -0.0 -0.0
23 C5:5-C2:2-C4:4-H12:12 0.66944 0.0 3 3 -0.0 -0.0
24 C1:1-C2:2-C4:4-H12:12 0.66944 0.0 3 3 -0.0 -0.0
25 C3:3-C2:2-C5:5-H16:16 0.66944 0.0 3 3 -0.0 -0.0
26 C5:5-C2:2-C1:1-H7:7 0.66944 0.0 3 3 -0.0 -0.0
27 C5:5-C2:2-C1:1-H8:8 0.66944 0.0 3 3 -0.0 -0.0
28 C5:5-C2:2-C1:1-H6:6 0.66944 0.0 3 3 -0.0 -0.0
29 C3:3-C2:2-C5:5-H15:15 0.66944 0.0 3 3 -0.0 -0.0
30 C3:3-C2:2-C4:4-H14:14 0.66944 0.0 3 3 -0.0 -0.0
31 C3:3-C2:2-C4:4-H13:13 0.66944 0.0 3 3 -0.0 -0.0
32 C4:4-C2:2-C1:1-H7:7 0.66944 0.0 3 3 -0.0 -0.0
33 C4:4-C2:2-C1:1-H8:8 0.66944 0.0 3 3 -0.0 -0.0
34 C4:4-C2:2-C1:1-H6:6 0.66944 0.0 3 3 -0.0 -0.0
35 C1:1-C2:2-C5:5-H17:17 0.66944 0.0 3 3 -0.0 -0.0
Similarly, the sire.morph.shrink_ghost_atoms() function will automatically
adjust the bond lengths of bonds that involve ghost atoms, so that they will
either be pulled into, or emerge from their connected atoms.
>>> mols = sr.morph.shrink_ghost_atoms(mols)
>>> print(mols[0].perturbation().to_openmm(constraint="bonds").changed_constraints())
atompair length0 length1
0 C2:2-C3:3 0.15375 0.06000
1 C5:5-H17:17 0.10969 0.06000
2 C2:2-C4:4 0.15375 0.10969
3 C1:1-C2:2 0.15375 0.06000
4 C1:1-H7:7 0.10969 0.06000
5 C2:2-C5:5 0.15375 0.06000
6 C1:1-H8:8 0.10969 0.06000
7 C1:1-H6:6 0.10969 0.06000
8 C3:3-H11:11 0.10969 0.06000
9 C5:5-H15:15 0.10969 0.06000
10 C3:3-H9:9 0.10969 0.06000
11 C5:5-H16:16 0.10969 0.06000
12 C3:3-H10:10 0.10969 0.06000
Note
You can control the length of the ghost bond using the length
argument, e.g. shrink_ghost_atoms(mols, length="0.2A") would
shrink the bond to 0.2 Å. The default length is 0.6 Å.
Note
In general, you don’t often need to pull ghost atoms into or out from their connected atoms. This is because a soft-core potential is used to soften interactions involving ghost atoms, such that they fade away smoothly as they disappear.