vmol 3.0rc5

v -- A simple X11 molecular viewer

vmol: v – python binding

This package allows to

• run v from python scripts and receive its output without calling subprocesses and
• facilitate installation (especially if it is a dependency).

Inspired by @aligfellow's xyzrender.

Requirements

• X11
• numpy
• cclib (optional, to read formats without native support)

Installation

PyPI has the wheels for CPython 10 through 14 @ manylinux. See install-other.md for other ways to build and install.

pip install vmol[all]       #  install cclib to parse unsupported file formats and open them with vmol2

pip install vmol            #  base version

pip install --no-deps vmol  #  vmol script and "capture the output" will work, 
                            #  but "pass a structure" feature won't work without numpy

Usage

Scripts

The package provides two scripts to run from the command line

• vmol, a simple wrapper around v
• vmol2, a wrapper aroung v to view the file formats that are not supported natively (needs cclib (i.e., vmol[all] or vmol[cclib]))

Both have the same CLI interface as the original v (see the reference).

Native formats (xyz / Priroda):

vmol ../mol/MOL_3525.xyz cell:8.93,0.0,0.0,4.2,8.9,0.0,0.48,2.32,10
python -m vmol../mol/periodic.in bonds:0

Unsupported quantum-chemical outputs, e.g., Orca:

vmol2 ../mol/CEHZOF_1_SPE.out
python -m vmol.vmol2 ../mol/AJALIH_5_SPE.out

Library

Import the wrapper instance:

>>> from vmol import vmol

It provides the two wrapper functions capture and run along with the path to the shared library so, loaded library lib, and function namespace f.

>>> [*filter(lambda x: not str.startswith(x, '_'), dir(vmol))]
['capture', 'f', 'lib', 'run', 'so']

The shared library is automatically searched for in the current and installation directories:

>>> vmol.so
/home/xe/soft/miniconda3/lib/python3.13/site-packages/vmol/v.cpython-313-x86_64-linux-gnu.so

One can use a custom .so file by setting the attribute

>>> vmol.so = '../v.so'

or the VMOL_SO_PATH environment variable:

export VMOL_SO_PATH=`readlink -m ../v.so`

1. Simple wrapper

Analogous to running vmol script:

from vmol import vmol
vmol.run(['../mol/MOL_3525.xyz', 'cell:8.93,0.0,0.0,4.2,8.9,0.0,0.48,2.32,10'])

The arguments are the same as the CLI ones and should be an array of strings.

2. Capture the output

See example 1.

from vmol import vmol
out = vmol.capture(args=['../mol/MOL_3525.xyz', 'cell:8.93,0.0,0.0,4.2,8.9,0.0,0.48,2.32,10'])
# look at the molecule, press `x`/`z`/`p` to produce an output, close with `q`/`esc`
print(out)

The arguments args are the same as the CLI ones and should be an array of strings.

The return code can be captured as well:

ret, out = vmol.capture(args=['../mol/MOL_3525.xyz', 'cell:8.93,0.0,0.0,4.2,8.9,0.0,0.48,2.32,10'], return_code=True)

Headless mode also works:

>>> vmol.capture(args=['../mol/S8.qm.out', 'gui:0', 'com:.'])
'D8h'
>>> vmol.capture(args=['../mol/S8.qm.out', 'gui:0', 'com:.', 'frame:-1'])
'D4d'

Tell the viewer to automatically print the coordinates before exit:

>>> out = vmol.capture(args=['../mol/rotation1.in', 'exitcom:z'])
>>> print(out)

3. Pass a structure

One can pass a structure (or several structures) as an argument. See example 2.

from vmol import vmol
name = 'HF molecule'
q = [1, 'F']
r = [[0,0,0],[0.9,0,0]]
out = vmol.capture(mols={'q': q, 'r': r, 'name': name}, args=['shell:0.6,0.7'])
# look at the molecule, press `x`/`z`/`p` to produce an output, close with `q`/`esc`
print(out)

Without capturing the output:

vmol.run(args=['shell:0.6,0.7'], mols={'q': [1, 'F'], 'r': [[0,0,0],[0.9,0,0]], 'name': 'hydrogen fluoride'})

ASE Atoms (or anything with .numbers and .positions) are also supported:

import ase.io
mols = ase.io.read('../mol/mol0002.xyz', index=':')
out = vmol.capture(mols=mols)

File formats which are not supported natively can be read with cclib and passed (see example and vmol2 source).