just-psf

Just get me a topology, for god’s sake!

Purpose

This package gives a quick and dirty way to get PDB, RTF or PSF files (used by CHARMM, NAMD and VMD) from a XYZ geometry. In particular,

1. It uses the distance matrix between atoms to infer bonds (using the covalent radii from 10.1039/B801115J, though they may be redefined using -r, see below).
2. then it extracts the connected components of the corresponding molecular graph to create resdidues.
3. If the topologies of two residues are similar (i.e., their molecular graphs are isomorphic), they are considered as the same residue.
4. If needed, angles and dihedrals are also inferred from bonds obtained in step 1.

Thus, everything depends on step 1: if some bonds are too large for the algorithm to detect them (e.g., metalic bonds), this will lead to incorrect results.

Note: for developers, this packages contains parsers that more or less faithfully extract data from said files, see just_psf.parers.

Install

To install this package, you need a running Python 3 installation (Python >= 3.10 recommended), and

pip3 install git+https://github.com/pierre-24/just-psf.git

Note: as this script install programs, you might need to add their location (such as $HOME/.local/bin, if you use --user) to your $PATH, if any.

Usage

You can directly obtain a PSF using just-psf:

just-psf tests/tests_files/7H2O.xyz -o 7H2O.psf 

In this example, all waters molecules are recognized as one residue, called RES1. Atom names are assigned sequentially in said residue (so: O1, H2 and H3). You may want to do find/replace, but don't forget that the PSF format is a column-based format, so keep the alignment when doing so.

If you prefer, you can also use psfgen to build your PSF file. For that, you need a PDB:

just-pdb tests/tests_files/7H2O.xyz -o 7H2O.pdb

... And a topology (also referred to as RTF, RTop, or toppar file):

just-rtf tests/tests_files/7H2O.xyz -o 7H2O.rtf

In this RTF file, you can more easily control things like residue name, atom names, and atom types. Note that in this example, it only contains one residue.

When you are happy, use psfgen available in VMD:

# See the manual at https://www.ks.uiuc.edu/Research/vmd/plugins/psfgen/ug.pdf
# load topology
topology 7H2O.rtf

# use aliases if any
pdbalias residue RES1 HOH 

# load PDB
segment X { pdb 7H2O.pdb }

# write psf
writepsf 7H2O_psfgen.psf

# if you want, you can generate a more complete PDB:
coordpdb 7H2O.pdb X
writepdb 7H2O_psfgen.pdb

You can notice that 7H2O_psfgen.psf and 7H2O_psfgen.pdb are pretty similar to their just-* counterpart. One main difference is that psfgen changes the order of the atom to match the one found in the topology (which can be an issue if you try to analyse a trajectory a posteriori).

All 3 scripts can take two extra arguments:

• -r / --radii: redefine some covalent radii used in geometry analysis. The argument must be provided in the form "Symbol=value Symbol=value (...)", where Symbol is a valid atomic symbol (starting by an upercase letter, such as C, H, or Na) and value is a number. For example,

  just-rtf tests/tests_files/Ca6THF.xyz -r "Ca=0.1"

  ... results in two residues (one for THF and one for the Ca atom) instead of one big residue for the complex with 6 THF and 1 Ca.

• -R / --residues: redefine the names of the resulting (unique) residues. The argument must be provided in the form "name1 name2 ...", and should contain enough names. For example,

  just-rtf tests/tests_files/7H2O.xyz -R "HOH"

  ... results in a single residue named HOH instead of RES1.

Who?

My name is Pierre Beaujean, and I have a Ph.D. in quantum chemistry from the University of Namur (Belgium). I'm the main (and only) developer of this project, used in our lab. I use AIMD in the frame of my post-doctoral research in order to study batteries and solid electrolyte interphrase, and I developed this project to ease my life (because to analyse an AIMD trajectory, a PSF might also be useful!).