Simulate: LAMMPS logs, dumps, data files, and start configurations#
polyphys.simulate reads the files LAMMPS writes and writes the files a
run starts from, without MDAnalysis: a log into DataFrames, a text dump one
frame at a time, a data file of atoms, bonds, and angles, and a bead-spring
start configuration. The API reference documents each function.
Reading LAMMPS log files#
read_log reads a LAMMPS log into a LogFile record of three DataFrames:
thermo holds one row per thermo output step of every run, run_stats one
row per run from the summary LAMMPS prints after it, and wall_time the total
wall time. A log holds one run per run or minimize command, so a
production loop of run commands gives one run per iteration; the run
column, counted from 0 in log order, picks runs:
from polyphys.simulate.log import read_log
log = read_log("log.lammps")
production = log.thermo[log.thermo["run"] >= 2]
timing = log.run_stats[["run", "loop_time", "timesteps_per_s"]]
The thermo styles one, custom, multi, and yaml are all read.
WARNING and fix halt lines inside a table are skipped and logged at level
INFO, which logging.basicConfig(level=logging.INFO) shows. A log cut off
before a run’s Loop time of line, as after a walltime kill, or one that
stopped with an ERROR raises BrokenLogError, so a loop over many logs can
skip it:
from polyphys.simulate.log import BrokenLogError, read_log
for path in paths:
try:
log = read_log(path)
except BrokenLogError as err:
print(f"skipped {path}: {err}")
parse_log does the same for text already in memory, such as a member of a
tarball.
Reading LAMMPS dumps and writing data files#
iter_dump reads a text dump of dump atom or dump custom, plain or
gzipped, one frame at a time, so a long trajectory is never in memory whole.
Each DumpFrame holds its timestep, its box, the column names, and the
per-atom data, with rows sorted by atom ID unless sort_by_id=False is
passed. positions() returns Cartesian coordinates from whichever columns
the dump has: x y z, or the scaled xs ys zs that dump atom writes by
default; with unwrapped=True, xu yu zu, xsu ysu zsu, or the wrapped
coordinates moved by the image flags ix iy iz. Orthogonal and restricted
triclinic boxes are both handled:
from polyphys.simulate.dump import iter_dump
for frame in iter_dump("whole.bug.lammpstrj.gz"):
unwrapped = frame.positions(unwrapped=True)
A frame cut off by a killed run raises BrokenDumpError once the complete
frames before it have been yielded. read_dump_frame(path, index) returns a
single frame.
read_data and write_data read and write LAMMPS data files in the
atomic, bond, angle, molecular, and full atom styles, as
DataFile records of numpy arrays with a Box. with_frame gives a dump the topology
it lacks: the atom types, masses, bonds, and angles come from a template, and
the positions, box, and image flags from a dump frame, matched by atom ID:
from polyphys.simulate.data import read_data, with_frame, write_data
from polyphys.simulate.dump import read_dump_frame
template = read_data("initial.bug.data")
frame = read_dump_frame("whole.bug.lammpstrj", 0)
write_data(with_frame(template, frame), "whole.bug.data")
write_data also writes start configurations for LAMMPS. Build a
DataFile from arrays, leave masses and velocities as None for the
input script to set, and close a ring with one more bond. Sections of
force-field coefficients are skipped when read and never written, so the
input script sets the force field.
A dump frame and a data file carry the same Box from
polyphys.simulate.core, which converts scaled coordinates and applies image
flags; DataFile.unwrapped_positions() uses it too. The log, dump, and
data-file readers each read a .gz file through gzip, and each raises a
subclass of LammpsFormatError, itself a ValueError, for a broken file, so
one except LammpsFormatError skips a broken file of any kind.
Building start configurations#
polyphys.simulate.build writes the data file a run starts from: a
bead-spring polymer in a predictable, unphysical shape that the run then
equilibrates. It follows moltemplate’s confined-DNA example in four steps: a
curve, beads placed along it, the topology, then the file. The notation is
that of the module documentation: \(N\) beads a bond length \(b\) apart on a
helix of radius \(R\) and pitch \(p\), in the Lennard-Jones units of the run,
with \(\sigma\) the bead diameter and \(\theta_A\) the helical angle,
\(\tan\theta_A = 2\pi R / p\).
helix places beads on a helix and plectoneme_ring on the closed plectoneme
of Neukirch and Starostin: two coaxial helices, half a turn apart, joined by
smooth end loops. Both place each bead at the first point of the curve a
distance \(b\) from the one before, so every bond has exactly the length \(b\);
the ring also solves its height so that the \(N\) chords close, with \(R\), \(p\),
\(b\), and \(N\) exactly as given. resample_curve does the same along any
curve given as points. chain_data adds the IDs, the molecule, the bonds,
and, if asked, the angles, and check_conformation tests the file against
the conditions under which LAMMPS warns or stops before write_data writes
it:
from polyphys.simulate import Box, write_data
from polyphys.simulate.build import (
chain_data, check_conformation, helix, plectoneme_ring,
)
positions = helix(200, radius=2.0, pitch=2.5)
box = Box(lo=[-5.0, -5.0, -21.0], hi=[5.0, 5.0, 21.0])
data = chain_data(positions, box)
check_conformation(data, r0=1.5, ghost_cutoff=1.122462 + 0.3,
periodic=(False, False, True), dcyl=6.0, dmon=1.0)
write_data(data, "N200D6.data")
ring = chain_data(plectoneme_ring(200, radius=2.0, pitch=2.5),
Box(lo=[-5.0, -5.0, -13.0], hi=[5.0, 5.0, 13.0]),
ring=True, angles=True)
The default bond length is \(0.97\,\sigma\), the start bond length Kremer and
Grest used in 1990 and the mean bond length they measured in the
equilibrated melt; the force of the FENE bond with its WCA term is zero at
\(0.961\,\sigma\), so a bond of \(0.97\) stores \(0.04\,\epsilon\). The old
research default, \(0.95\,R_0 = 1.425\,\sigma\), is above the length at which
LAMMPS warns FENE bond too long, \(\sqrt{0.9}\,R_0 = 1.423\), and above the
default ghost-atom cutoff of a WCA run with a skin of \(0.3\), \(1.42\). In
runs of this model (\(K = 30\), \(R_0 = 1.5\), \(k_B T = \epsilon\), 10 000 steps)
the start bond length decided which integrator survived:
Start bond length |
plain |
|
|
|---|---|---|---|
0.97 to 1.10 |
runs, no warning |
runs |
runs |
1.15 to 1.35 |
runs, warns |
stops from 1.30 |
runs |
1.40 to 1.49 |
stops |
stops |
runs, warns |
3.0 and above |
stops at step 0 |
stops at step 0 |
stops at step 0 |
The radius and the pitch are the user’s choice, with no default. Adjacent
turns of a helix are \(p\sin\theta_A\) apart and the two strands of a
plectoneme \((p/2)\sin\theta_A\), so a helix needs \(p \ge d_{\min} /
\sin\theta_A\) and a ring \(p \ge 2 d_{\min} / \sin\theta_A\), about \(2.0\) to
\(2.1\,\sigma\) for \(R \ge 2\sigma\), to keep every pair of beads the minimum
distance \(d_{\min}\) apart; check_conformation enforces it, with
\(d_{\min} = \sigma\) by default, where the WCA energy of a pair is
\(\epsilon\). Its other rules are the FENE warning length, the ghost cutoff,
coincident atoms, the box on non-periodic axes, and, in a cylinder of
diameter \(D\) built from beads of diameter \(a\), the effective radius
\((D - a)/2\). Equilibration stays in the input script: fix nve/limit with a
Langevin thermostat, as the research runs do, or the soft pair potential
Kremer and Grest raised slowly to remove overlaps.
polyphys/tests/data/lammps_build/ holds in.kg, a Kremer-Grest input
script that runs a built start under a chosen integrator, and
check_starts.sh, which builds the three example starts and runs each
under all of them; the same matrix runs as the lammps-marked tests when a
LAMMPS executable is available (see the Testing page).