NICE Lab Molecule Editor

For full documentation, see Arcas.github.io/nme.

nme is a Python library that provides a simple, programmatic interface to XYZ files. nme can also export LAMMPS input data files.

Contents:

• API
  • Functions
  • Atom
  • Molecule
  • Workspace

Quick Start

import nme

Basic usage of nme involves loading and manipulating molecules from XYZ files. A single molecule can be loaded with the function read_xyz.

nme provides three main classes: Atom, Molecule, and Workspace. An Atom is the basic unit of nme and can be initialized as such:

# The first argument is the atomic number; the second argument is a list of
# the atom's X, Y, and Z coordinates.
carbon = nme.Atom(6, [0, 0, 1])

# All Atoms, Molecules, and Workspaces can hold attributes which can be
# set and accessed via indexing. These attributes are ignored when saving
# to disk.
carbon["used"] = False
print(carbon["used"])

Molecule objects consist of Atom objects and can either be constructed by hand or loaded from an XYZ file. You can append atoms or other molecules to Molecule objects - this can be done by using either the Molecule.append function or the += operator. Additionlly, Molecule objects can be saved to XYZ files using Molecule.write_xyz.

glucose = nme.read_xyz("./samples/glucose.xyz")
glucose.move_to([0, 0, 0])
glucose += carbon
glucose.write_xyz("./glucose_with_extra_carbon.xyz")

(glucose + nme.Atom(6, [0, 0, -1])).write_xyz("./glucose_plus_2_carbon.xyz")

Workspace objects consist of Molecule and Atom objects. The primary purpose of a Workspace is to allow writing of multiple objects to a single output file.

Workspace objects have a Workspace.write_xyz function that writes the entire workspace to a single XYZ file as a single molecule. Additionally the write_lammps <nme.nme.write_lammps() method writes the entire workspace to a LAMMPS input data file.

workspace = nme.Workspace()

glucose = nme.read_xyz("./samples/glucose.xyz")
glucose.move_to([0, 0, 0])
workspace += glucose

# Create an independent copy of the glucose molecule so that we can edit it
# without affecting the state of the other glucose molecule
glucose_2 = glucose.copy()
glucose_2.move_to([0, 0, 1])
workspace += glucose_2

# Because we still have an independent reference to the original glucose
# molecule, we can still access it directly
glucose.move_to([0, 0, -2])

workspace.write_xyz("2_glucose.xyz")
workspace.write_lammps("2_glucose.dat")