"""\
=====================================================================
Start configurations --- :mod:`polyphys.simulate.build`
=====================================================================
The :mod:`~polyphys.simulate.build` module builds LAMMPS start
configurations of a bead-spring polymer in a predictable, unphysical shape,
a helix or a closed plectoneme, which a LAMMPS run then equilibrates. It
places beads along a curve a fixed bond length apart, adds the chain
topology, checks that LAMMPS can start from the result, and hands the
configuration to :func:`~polyphys.simulate.data.write_data` as a
:class:`~polyphys.simulate.data.DataFile`. The design follows moltemplate's
confined-DNA example (Jewett et al., 2021): a curve, beads placed along it,
the topology, then the file. Nothing is copied from moltemplate.
.. versionadded:: 0.6.0
Contents
========
:func:`helix` and :func:`plectoneme_ring` place beads on the two built-in
shapes; :func:`resample_curve` places them along any curve given as points.
:func:`chain_bonds` and :func:`chain_angles` give the topology of a linear
or ring chain, and :func:`chain_data` wraps positions and topology in a
:class:`~polyphys.simulate.data.DataFile`. :func:`check_conformation` tests
a data file against the conditions under which LAMMPS stops or warns, and
raises :class:`ConformationError` or returns a :class:`ConformationReport`.
Notation
========
:math:`N`
The number of beads.
:math:`b`
The bond length, the distance between bonded bead centers.
:math:`\\sigma`, :math:`\\epsilon`
The bead diameter and the energy unit of the Lennard-Jones (LJ) units of
the run; all lengths here are in :math:`\\sigma`.
:math:`R`, :math:`p`
The radius and the pitch (the axial rise per turn) of a helix;
:math:`c = p / 2\\pi` is the rise per radian.
:math:`\\Delta t`
The angle between neighboring beads on a helix.
:math:`\\theta_A`
The helical angle, between a strand's tangent and the axis:
:math:`\\tan\\theta_A = 2\\pi R / p`.
:math:`L_A`
The arclength of one strand of a plectoneme.
:math:`K`, :math:`R_0`
The spring constant and the maximum extension of a FENE bond.
:math:`d_{\\min}`
The smallest distance :func:`check_conformation` allows between two
beads that are not bonded.
:math:`D`, :math:`a`
The diameter of a cylindrical confinement and the bead diameter;
:math:`D - a` is the effective diameter, the diameter the bead centers
can reach.
Physical background
===================
The chains are Kremer-Grest bead-spring chains. Every pair of beads repels
through the Weeks-Chandler-Andersen (WCA) potential, the LJ potential cut
at its minimum :math:`2^{1/6}\\sigma` and shifted up by :math:`\\epsilon`
(Weeks, Chandler, and Andersen, 1971, Eq. 4). Bonded beads add the finitely
extensible nonlinear elastic (FENE) spring, whose force
:math:`K r / (1 - (r/R_0)^2)` diverges at :math:`R_0` (Warner, 1972, Eq.
4). Grest and Kremer (1986, Eqs. 8 and 9) set :math:`K = 30\\,
\\epsilon/\\sigma^2` and :math:`R_0 = 1.5\\,\\sigma` so that chains cannot
cross; with these values at :math:`k_B T = \\epsilon` the bond never
exceeds :math:`1.2\\,\\sigma` (Kremer and Grest, 1990, Appendix). The LAMMPS
``bond_style fene`` holds both terms of the bond,
.. math::
E = -\\tfrac{1}{2} K R_0^2 \\ln\\left[1 - \\left(\\frac{r}{R_0}\\right)^2
\\right] + 4\\epsilon\\left[\\left(\\frac{\\sigma}{r}\\right)^{12} -
\\left(\\frac{\\sigma}{r}\\right)^{6}\\right] + \\epsilon,
the second part cut at :math:`2^{1/6}\\sigma`, and ``special_bonds fene``
switches the pair interaction off between bonded beads only, so beads two
apart along the chain repel like any other pair.
*The start bond length.* Kremer and Grest (1990, Sec. II.B) built their
start configurations as random walks with a bond length of :math:`0.97
\\sigma`, kept beads two apart more than :math:`1.02\\,\\sigma` from each
other, and measured a mean bond length of :math:`0.97\\,\\sigma` in the
equilibrated melt. The force of the FENE and WCA terms together is zero at
:math:`0.961\\,\\sigma`, so a bond of :math:`0.97\\,\\sigma` stores
:math:`0.04\\,\\epsilon`; the same :math:`0.97` is the default of Pizza.py's
``chain.py``, of LAMMPS's ``tools/def.chain``, and of
``BondFENE::equilibrium_distance``. The builders here use it as their
default, `bond_length` ``= 0.97``.
*What stops a LAMMPS run.* LAMMPS warns ``FENE bond too long`` and clamps
the bond force when :math:`1 - (r/R_0)^2 < 0.1`, that is for :math:`r >
\\sqrt{0.9}\\,R_0 = 1.423\\,\\sigma` at :math:`R_0 = 1.5\\,\\sigma`, and
stops with ``Bad FENE bond`` at :math:`r \\ge 2R_0` (``bond_fene.cpp``). A
bond longer than the ghost-atom cutoff, the pair cutoff plus the neighbor
skin (:math:`1.42\\,\\sigma` for a WCA cutoff and a skin of :math:`0.3`),
stops a run with ``Bond atoms missing`` or a wrong periodic image as soon
as it crosses a periodic face or a processor boundary. ``read_data`` loses
an atom outside the box on a non-periodic axis, and ``fix wall/region``
stops when a bead sits on or outside its surface. Two beads at one position
give a non-finite force under every integrator. A bond of :math:`1.425\\,
\\sigma`, that is :math:`0.95\\,R_0`, is above both the warning length and
the default ghost cutoff; in test runs of this model (:math:`K = 30`,
:math:`R_0 = 1.5`, skin 0.3, :math:`k_B T = \\epsilon`) starts whose bonds
were all between :math:`0.97` and :math:`1.10\\,\\sigma` ran under plain
``nve``, under Langevin dynamics, and under ``nve/limit`` alike, while a
start with every bond at :math:`1.40\\,\\sigma` stopped a plain ``nve`` run
within 70 steps. :func:`check_conformation` tests each of these conditions.
Shapes
======
*Helix.* Bead :math:`k` sits at :math:`(R\\cos k\\Delta t, R\\sin k\\Delta
t, c k\\Delta t)`, centered on :math:`z = 0`. The distance between
neighboring beads is the chord
.. math::
b^2 = 4R^2 \\sin^2(\\Delta t / 2) + c^2 \\Delta t^2,
whose right side increases on :math:`(0, \\pi]`, so :math:`\\Delta t` is
its one root there whenever :math:`b^2 \\le 4R^2 + c^2\\pi^2`, that is
whenever a bond spans at most half a turn. Stepping by arclength instead
would give bonds shorter than the arc, by an amount that depends on the
curvature. Adjacent turns are :math:`p\\sin\\theta_A` apart, so a helix
needs :math:`p \\ge d_{\\min} / \\sin\\theta_A` to pass the pair check.
*Plectoneme ring.* The closed curve is the plasmid of Neukirch and
Starostin (2008, Appendix A, Eqs. A1 to A4): a right-handed helix of radius
:math:`R` and helical angle :math:`\\theta_A` (strand A), an end loop
(B), the same helix rotated by :math:`\\pi` about the axis and run back
down (strand C), and a second end loop (D). The loops pass through the axis
and keep the curve inside the cylinder of radius :math:`R`; the tangent is
continuous everywhere and the curvature jumps at the four joints. It is the
interwound superhelix of Boles, White, and Cozzarelli (1990, Fig. 3), with
their semicircular end caps replaced by the smooth loops. Beads are placed
along the curve by chord stepping, each at the first point of the curve a
distance :math:`b` from the one before, and the strand arclength
:math:`L_A` is solved so that the :math:`N` chords close the ring exactly,
the bond between the last bead and the first included. :math:`R`,
:math:`p`, :math:`b`, and :math:`N` are therefore exactly as given, and only
the height of the ring is a result. The two strands are half a pitch apart
along the axis, so a ring needs :math:`p \\ge 2 d_{\\min} / \\sin\\theta_A`
(about :math:`2.0` to :math:`2.1\\,\\sigma` for :math:`R \\ge 2\\sigma` and
:math:`d_{\\min} = \\sigma`) to pass the pair check.
*Any curve.* :func:`resample_curve` applies the same chord stepping to a
polyline. A closed polyline has no height to solve for, so it is scaled
uniformly about its centroid until :math:`N` chords close it; the shape is
kept and the size changes by about :math:`(N b - \\ell) / \\ell` for a
polyline of length :math:`\\ell`. Closing needs a curve whose features are
large compared with :math:`b`; a curve with smaller corners or teeth is
refused rather than closed with one odd bond.
Equilibration
=============
A start configuration only has to be one LAMMPS runs from; the run removes
its memory. Kremer and Grest (1990, Sec. II.B) relaxed their starts with a
soft pair potential, :math:`A[1 + \\cos(\\pi r / 2^{1/6}\\sigma)]`, raising
:math:`A` from 1 to about 60, and moltemplate's confined-DNA example uses
``fix nve/limit`` with a Langevin thermostat and recommends soft potentials
for a long confined chain; LAMMPS provides both (``pair_style soft`` with
``fix adapt``, and ``fix nve/limit``). Neither is part of this module.
Complexity
==========
:func:`helix` takes :math:`O(N)` time and memory. :func:`plectoneme_ring`
and a closed :func:`resample_curve` take :math:`O(N)` time and memory per
march along the curve, and about ten marches to close the ring.
:func:`check_conformation` takes :math:`O(N^2)` time, in row chunks, so
its memory is :math:`O(N)` beyond the positions.
References
==========
- Kremer, K. and Grest, G. S., "Dynamics of entangled linear polymer melts:
A molecular-dynamics simulation", J. Chem. Phys. 92, 5057 (1990),
`doi:10.1063/1.458541 <https://doi.org/10.1063/1.458541>`_: Sec. II.B,
Eqs. (2.3) and (2.4), p. 5060, and the Appendix, Eqs. (A1) and (A2).
- Grest, G. S. and Kremer, K., "Molecular dynamics simulation for polymers
in the presence of a heat bath", Phys. Rev. A 33, 3628 (1986),
`doi:10.1103/PhysRevA.33.3628
<https://doi.org/10.1103/PhysRevA.33.3628>`_: Eqs. (8) and (9).
- Weeks, J. D., Chandler, D., and Andersen, H. C., "Role of repulsive
forces in determining the equilibrium structure of simple liquids",
J. Chem. Phys. 54, 5237 (1971), `doi:10.1063/1.1674820
<https://doi.org/10.1063/1.1674820>`_: Eq. (4).
- Warner, H. R., "Kinetic theory and rheology of dilute suspensions of
finitely extendible dumbbells", Ind. Eng. Chem. Fundam. 11, 379 (1972),
`doi:10.1021/i160043a017 <https://doi.org/10.1021/i160043a017>`_: Eq. (4).
- Neukirch, S. and Starostin, E. L., "Writhe formulas and antipodal points
in plectonemic DNA configurations", Phys. Rev. E 78, 041912 (2008),
`doi:10.1103/PhysRevE.78.041912
<https://doi.org/10.1103/PhysRevE.78.041912>`_: Appendix A.
- Boles, T. C., White, J. H., and Cozzarelli, N. R., "Structure of
plectonemically supercoiled DNA", J. Mol. Biol. 213, 931 (1990),
`doi:10.1016/s0022-2836(05)80272-4
<https://doi.org/10.1016/s0022-2836(05)80272-4>`_: Fig. 3 and Sec. 2(f).
- Jewett, A. I. et al., "Moltemplate: A tool for coarse-grained modeling of
complex biological matter and soft condensed matter physics", J. Mol.
Biol. 433, 166841 (2021), `doi:10.1016/j.jmb.2021.166841
<https://doi.org/10.1016/j.jmb.2021.166841>`_, and its example
`confined_viral_DNA
<https://github.com/jewettaij/moltemplate/tree/031ecd4efc7abdad8d49238404de2d3ef388b37b/examples/coarse_grained/DNA_models/dsDNA_only/2strands/3bp_2particles/confined_viral_DNA>`_.
- The LAMMPS documentation of `bond_style fene
<https://docs.lammps.org/bond_fene.html>`_, `special_bonds
<https://docs.lammps.org/special_bonds.html>`_, `read_data
<https://docs.lammps.org/read_data.html>`_, `comm_modify
<https://docs.lammps.org/comm_modify.html>`_, `fix wall/region
<https://docs.lammps.org/fix_wall_region.html>`_, and `fix nve/limit
<https://docs.lammps.org/fix_nve_limit.html>`_, and the LAMMPS source at
release ``stable_30Sep2026_update1``: `bond_fene.cpp, lines 89 to 94
<https://github.com/lammps/lammps/blob/098ffdefa525cabc82272925de02e9884f58c657/src/MOLECULE/bond_fene.cpp#L89-L94>`_
(the warning and the stop) and `bond_fene.cpp, lines 192 to 195
<https://github.com/lammps/lammps/blob/098ffdefa525cabc82272925de02e9884f58c657/src/MOLECULE/bond_fene.cpp#L192-L195>`_
(the equilibrium distance :math:`0.97\\,\\sigma`).
- Plimpton, S., `Pizza.py chain.py
<https://github.com/thatgeeman/pizza/blob/master/src/chain.py>`_ (2005)
and LAMMPS `tools/def.chain
<https://github.com/lammps/lammps/blob/098ffdefa525cabc82272925de02e9884f58c657/tools/def.chain>`_:
bond 0.97 and 1-3 distance 1.02.
Dependencies
============
- Python standard library: `dataclasses`, `logging`, `math`
- Third-party: `numpy`, `scipy` (:func:`scipy.optimize.brentq`)
- PolyPhys: :mod:`polyphys.simulate.core`, :mod:`polyphys.simulate.data`
"""
import logging
import math
from collections.abc import Callable, Sequence
from dataclasses import dataclass
import numpy as np
import numpy.typing as npt
from scipy.optimize import brentq
from polyphys.simulate.core import Box, FloatArray, IntArray
from polyphys.simulate.data import DataFile
__all__ = [
"FENE_WARNING_FRACTION",
"ConformationError",
"ConformationReport",
"chain_angles",
"chain_bonds",
"chain_data",
"check_conformation",
"helix",
"plectoneme_ring",
"resample_curve",
]
logger = logging.getLogger(__name__)
#: LAMMPS warns ``FENE bond too long`` when :math:`1 - (r/R_0)^2 < 0.1`,
#: that is for a bond longer than :math:`\sqrt{0.9}\,R_0`
#: (``bond_fene.cpp``, lines 89 to 94).
FENE_WARNING_FRACTION = math.sqrt(0.9)
_Curve = Callable[[FloatArray], FloatArray]
_SAMPLES_PER_BOND = 64
_COINCIDENT = 1e-9
_TINY = 1e-9
[docs]
def helix(
n_beads: int, *, radius: float, pitch: float, bond_length: float = 0.97
) -> FloatArray:
r"""Place beads a fixed distance apart along a helix.
Bead :math:`k` sits at :math:`(R\cos k\Delta t, R\sin k\Delta t, c k
\Delta t)` on a right-handed helix of radius :math:`R` and pitch
:math:`p` about the :math:`z` axis, with :math:`c = p/2\pi`, centered on
:math:`z = 0`. The angle step :math:`\Delta t` is the root of the chord
equation :math:`b^2 = 4R^2\sin^2(\Delta t/2) + c^2\Delta t^2`, so every
bond has the length :math:`b` exactly.
.. versionadded:: 0.6.0
Parameters
----------
n_beads : int
The number of beads :math:`N`, 1 or more.
radius : float
The helix radius :math:`R`, positive, in the length unit of the run.
pitch : float
The pitch :math:`p`, the rise per turn, positive. Adjacent turns are
:math:`p\sin\theta_A` apart, with :math:`\tan\theta_A = 2\pi R/p`.
bond_length : float, optional
The bond length :math:`b`, positive; by default :math:`0.97`, the
start bond length of Kremer and Grest (1990) in units of the bead
diameter.
Returns
-------
numpy.ndarray
Shape ``(n_beads, 3)``, float64: the bead positions, the first at
angle zero.
Raises
------
ValueError
If `n_beads` is below 1, a length is not positive, or the bond does
not fit in half a turn, :math:`b^2 > 4R^2 + c^2\pi^2`.
Notes
-----
The chord equation's right side increases on :math:`(0, \pi]`, so
:func:`scipy.optimize.brentq` finds its one root there. Time and memory
are :math:`O(N)`.
Examples
--------
A bond of :math:`\sqrt 2` on a helix of radius 1 and pitch 6 steps by
:math:`\pi/3` and rises by 1 per bead:
>>> beads = helix(4, radius=1.0, pitch=6.0, bond_length=2 ** 0.5)
>>> np.round(beads, 6) + 0.0
array([[ 1. , 0. , -1.5 ],
[ 0.5 , 0.866025, -0.5 ],
[-0.5 , 0.866025, 0.5 ],
[-1. , 0. , 1.5 ]])
"""
_check_count("n_beads", n_beads, 1)
for name, value in (("radius", radius), ("pitch", pitch),
("bond_length", bond_length)):
_check_positive(name, value)
rise = pitch / (2.0 * math.pi)
step = _chord_angle(bond_length, radius, rise)
angles = np.arange(n_beads, dtype=np.float64) * step
z = rise * angles
z -= 0.5 * (z[0] + z[-1])
positions: FloatArray = np.column_stack(
[radius * np.cos(angles), radius * np.sin(angles), z])
return positions
[docs]
def plectoneme_ring(
n_beads: int, *, radius: float, pitch: float, bond_length: float = 0.97
) -> FloatArray:
r"""Place beads a fixed distance apart along a closed plectoneme.
The curve is the plasmid of Neukirch and Starostin (2008, Appendix A):
two coaxial right-handed helices of radius :math:`R` and pitch
:math:`p`, half a turn apart, one run up and one run down, joined at
each end by a smooth loop through the axis. The beads are placed by
chord stepping, each at the first point of the curve a distance
:math:`b` from the one before, and the strand arclength :math:`L_A` is
solved so that :math:`N` chords close the curve: every bond, the one
between the last bead and the first included, has the length :math:`b`,
and :math:`R` and :math:`p` are exactly as given. The ring is centered on
the origin with its axis along :math:`z`; no bead lies farther than
:math:`R` from the axis.
.. versionadded:: 0.6.0
Parameters
----------
n_beads : int
The number of beads :math:`N`. The two end loops alone take about
:math:`7.7 R / b` beads each; fewer raises.
radius : float
The helix radius :math:`R`, positive, in the length unit of the run.
pitch : float
The pitch :math:`p` of each strand, positive. The two strands are
:math:`(p/2)\sin\theta_A` apart and adjacent turns of one strand
:math:`p\sin\theta_A`, with :math:`\tan\theta_A = 2\pi R/p`; a
pitch of about :math:`2\sigma` or more keeps the strands a bead
diameter apart.
bond_length : float, optional
The bond length :math:`b`, positive; by default :math:`0.97`, as in
:func:`helix`.
Returns
-------
numpy.ndarray
Shape ``(n_beads, 3)``, float64: the bead positions, from the foot
of the first strand up and around.
Raises
------
ValueError
If `n_beads` is too small for the loops, a length is not positive,
or the bond does not fit in half a turn of the helix.
Notes
-----
The closing gap, the distance from the last bead back to the first
minus :math:`b`, grows with :math:`L_A` and is continuous, so
:func:`scipy.optimize.brentq` finds its root in a bracket around the
estimate :math:`(N s - \ell_{loops}) / 2`, with :math:`s` the arc a
chord of :math:`b` spans on the helix and :math:`\ell_{loops}` the
length of the two loops; the root lies within a fraction of a bond of
the estimate. Each evaluation is one march along the curve, :math:`O(N)`
in time and memory, and the solve takes about ten marches.
Examples
--------
>>> ring = plectoneme_ring(60, radius=2.0, pitch=2.5)
>>> ring.shape
(60, 3)
>>> bonds = np.linalg.norm(np.roll(ring, -1, axis=0) - ring, axis=1)
>>> bool(np.allclose(bonds, 0.97, rtol=1e-12, atol=0.0))
True
>>> round(float(np.hypot(ring[:, 0], ring[:, 1]).max()), 6)
2.0
"""
_check_count("n_beads", n_beads, 3)
for name, value in (("radius", radius), ("pitch", pitch),
("bond_length", bond_length)):
_check_positive(name, value)
theta = math.atan2(2.0 * math.pi * radius, pitch)
bond = bond_length / radius # in units of R
cot = 1.0 / math.tan(theta)
arc_per_chord = _chord_angle(bond, 1.0, cot) / math.sin(theta)
sample_step = min(bond, 1.0) / _SAMPLES_PER_BOND
loops = _plectoneme_loop_length(theta, sample_step)
estimate = (n_beads * arc_per_chord - loops) / 2.0
def closing_gap(strand: float) -> float:
beads, gap = _march_curve(
lambda u: _plectoneme_curve(u, strand, theta),
2.0 * strand + 2.0 * math.pi, n_beads, bond, sample_step)
return -bond if gap is None else gap - bond
too_few = ValueError(
f"'n_beads' must be at least about "
f"{math.ceil((loops + 2 * arc_per_chord) / arc_per_chord)} for a "
f"plectoneme ring of radius {radius} and pitch {pitch} with bonds "
f"of {bond_length}, got {n_beads}")
if estimate <= 0.0:
raise too_few
lo, hi = _bracket(closing_gap, estimate, arc_per_chord)
strand = brentq(closing_gap, lo, hi, xtol=1e-14, maxiter=200)
beads, gap = _march_curve(
lambda u: _plectoneme_curve(u, strand, theta),
2.0 * strand + 2.0 * math.pi, n_beads, bond, sample_step)
_check_closed(gap, bond)
beads *= radius
beads[:, 2] -= 0.5 * (beads[:, 2].min() + beads[:, 2].max())
logger.debug("plectoneme_ring: strand arclength %.6f, height %.6f",
strand * radius, strand * radius * math.cos(theta))
return beads
[docs]
def resample_curve(
points: npt.ArrayLike, n_beads: int, bond_length: float = 0.97, *,
closed: bool = False,
) -> FloatArray:
r"""Place beads a fixed distance apart along a curve given as points.
The curve is the polyline through `points`. The first bead sits on the
first point, and each next bead at the first point of the polyline a
distance :math:`b` from the bead before (the first crossing of the
sphere of radius :math:`b` about it), so every bond has the length
:math:`b` exactly. On an open curve the beads cover the first
:math:`N - 1` chords and the rest of the curve is unused. A closed
curve is scaled uniformly about the centroid of its points until
:math:`N` chords close it, the bond from the last bead to the first
included; the shape is kept and the size changes by about :math:`(Nb -
\ell)/\ell` for a polyline of length :math:`\ell`.
.. versionadded:: 0.6.0
Parameters
----------
points : array_like
Shape ``(n_points, 3)``: the vertices of the polyline, 2 or more,
in the length unit of the run. Repeated consecutive points are
dropped. A closed curve may or may not repeat its first point last.
n_beads : int
The number of beads :math:`N`: 1 or more on an open curve, 3 or more
on a closed one.
bond_length : float, optional
The bond length :math:`b`, positive; by default :math:`0.97`, as in
:func:`helix`.
closed : bool, optional
Whether the curve is closed and the ring must close with the bond
length too; False by default.
Returns
-------
numpy.ndarray
Shape ``(n_beads, 3)``, float64: the bead positions, in the order of
the curve.
Raises
------
ValueError
If `points` is not ``(n_points, 3)`` with 2 or more distinct
consecutive points, a value is not finite, `n_beads` is too small,
`bond_length` is not positive, an open curve is too short for
`n_beads` beads, or a closed curve cannot be closed with equal
bonds (see Notes).
Notes
-----
Each chord is a line-sphere intersection, exact to round-off. A march
takes :math:`O(N + n_{points})` time and memory; closing a curve takes
about ten marches, the scale found by :func:`scipy.optimize.brentq`.
The polyline, not the smooth curve it may stand for, carries the beads:
sample a smooth curve finely compared with :math:`b`. Closing needs the
beads to move continuously as the curve is scaled, which holds when the
curve's features, its radius of curvature and the spacing of its
corners, are large compared with :math:`b`; on a curve with corners or
teeth smaller than a bond the closing gap jumps, no scale closes the
curve exactly, and ``ValueError`` is raised rather than a ring with one
odd bond.
Examples
--------
A corner: the second bead is where the sphere of radius :math:`\sqrt 2`
about the origin first meets the polyline, past the corner.
>>> corner = [[0.0, 0.0, 0.0], [1.0, 0.0, 0.0], [1.0, 5.0, 0.0]]
>>> np.round(resample_curve(corner, 3, 2 ** 0.5), 6)
array([[0. , 0. , 0. ],
[1. , 1. , 0. ],
[1. , 2.414214, 0. ]])
A closed square of side 4 holds 16 bonds of length 1 as it is:
>>> square = [[0, 0, 0], [4, 0, 0], [4, 4, 0], [0, 4, 0]]
>>> beads = resample_curve(square, 16, 1.0, closed=True)
>>> np.round(beads[3:6], 6)
array([[3., 0., 0.],
[4., 0., 0.],
[4., 1., 0.]])
"""
vertices = np.array(points, dtype=np.float64)
if vertices.ndim != 2 or vertices.shape[1] != 3:
raise ValueError(
f"'points' must have shape (n_points, 3), got {vertices.shape}")
if not np.all(np.isfinite(vertices)):
raise ValueError("'points' must be finite")
_check_count("n_beads", n_beads, 3 if closed else 1)
_check_positive("bond_length", bond_length)
keep = np.ones(vertices.shape[0], dtype=bool)
keep[1:] = np.any(np.diff(vertices, axis=0) != 0.0, axis=1)
vertices = vertices[keep]
if closed and vertices.shape[0] > 1 and np.array_equal(
vertices[0], vertices[-1]
):
vertices = vertices[:-1]
if vertices.shape[0] < 2:
raise ValueError("'points' must hold 2 or more distinct points")
if not closed:
beads, _ = _march_polyline(vertices, n_beads, bond_length)
if beads.shape[0] < n_beads:
raise ValueError(
f"the curve holds {beads.shape[0]} beads {bond_length} "
f"apart, not {n_beads}")
return beads
centroid = vertices.mean(axis=0)
polyline = np.vstack([vertices, vertices[:1]])
length = float(np.linalg.norm(np.diff(polyline, axis=0), axis=1).sum())
def closing_gap(scale: float) -> float:
beads, gap = _march_polyline(
centroid + scale * (polyline - centroid), n_beads, bond_length)
return -bond_length if gap is None else gap - bond_length
lo, hi = _bracket(closing_gap, n_beads * bond_length / length,
2.0 * bond_length / length)
scale = brentq(closing_gap, lo, hi, xtol=1e-15, maxiter=200)
beads, gap = _march_polyline(
centroid + scale * (polyline - centroid), n_beads, bond_length)
_check_closed(gap, bond_length)
logger.debug("resample_curve: scaled the closed curve by %.9f", scale)
return beads
[docs]
def chain_bonds(n_beads: int, *, ring: bool = False,
bond_type: int = 1) -> IntArray:
"""Return the bonds of a linear or ring chain of beads numbered from 1.
.. versionadded:: 0.6.0
Parameters
----------
n_beads : int
The number of beads, 2 or more for a linear chain and 3 or more for
a ring.
ring : bool, optional
Whether to add the bond from the last bead to the first; False by
default.
bond_type : int, optional
The bond type of every bond, 1 or more; 1 by default.
Returns
-------
numpy.ndarray
Shape ``(n_bonds, 3)``, int64: ``type, atom1, atom2`` per bond, the
layout of :attr:`~polyphys.simulate.data.DataFile.bonds`, with
``n_bonds`` equal to `n_beads` minus one, or to `n_beads` for a
ring. Time and memory are :math:`O(N)`.
Raises
------
ValueError
If `n_beads` or `bond_type` is too small.
Examples
--------
>>> chain_bonds(4, ring=True)
array([[1, 1, 2],
[1, 2, 3],
[1, 3, 4],
[1, 4, 1]])
"""
_check_count("n_beads", n_beads, 3 if ring else 2)
_check_count("bond_type", bond_type, 1)
first = np.arange(1, n_beads + 1 if ring else n_beads, dtype=np.int64)
second = first % n_beads + 1
bonds: IntArray = np.column_stack(
[np.full_like(first, bond_type), first, second])
return bonds
[docs]
def chain_angles(n_beads: int, *, ring: bool = False,
angle_type: int = 1) -> IntArray:
"""Return the angles of a linear or ring chain of beads numbered from 1.
.. versionadded:: 0.6.0
Parameters
----------
n_beads : int
The number of beads, 3 or more.
ring : bool, optional
Whether to add the two angles that span the closing bond; False by
default.
angle_type : int, optional
The angle type of every angle, 1 or more; 1 by default.
Returns
-------
numpy.ndarray
Shape ``(n_angles, 4)``, int64: ``type, atom1, atom2, atom3`` per
angle with ``atom2`` the vertex, the layout of
:attr:`~polyphys.simulate.data.DataFile.angles`, with ``n_angles``
equal to `n_beads` minus two, or to `n_beads` for a ring. Time and
memory are :math:`O(N)`.
Raises
------
ValueError
If `n_beads` or `angle_type` is too small.
Examples
--------
>>> chain_angles(4, ring=True)
array([[1, 1, 2, 3],
[1, 2, 3, 4],
[1, 3, 4, 1],
[1, 4, 1, 2]])
"""
_check_count("n_beads", n_beads, 3)
_check_count("angle_type", angle_type, 1)
first = np.arange(1, n_beads + 1 if ring else n_beads - 1,
dtype=np.int64)
angles: IntArray = np.column_stack(
[np.full_like(first, angle_type), first, first % n_beads + 1,
(first + 1) % n_beads + 1])
return angles
[docs]
def chain_data(
positions: npt.ArrayLike, box: Box, *, ring: bool = False,
angles: bool = False, types: npt.ArrayLike | None = None,
) -> DataFile:
"""Return a data file of one chain from bead positions.
The atoms get the IDs 1 to :math:`N` in the order of `positions`,
molecule 1, and the bonds of :func:`chain_bonds` and, if asked, the
angles of :func:`chain_angles`, all of type 1. The masses and the
velocities are left to the input script.
.. versionadded:: 0.6.0
Parameters
----------
positions : array_like
Shape ``(n_beads, 3)``: the bead positions along the chain, as
:func:`helix`, :func:`plectoneme_ring`, or :func:`resample_curve`
return them.
box : Box
The simulation box; it is not checked against the positions here,
:func:`check_conformation` does that.
ring : bool, optional
Whether the chain is a ring; False by default.
angles : bool, optional
Whether to add the angles and use the atom style ``angle`` instead
of ``bond``; False by default.
types : array_like, optional
Shape ``(n_beads,)``: the atom types, from 1; all 1 by default.
Returns
-------
DataFile
With ``n_atom_types`` the largest type, ``n_bond_types`` 1, and
``n_angle_types`` 1 if `angles` else 0. Time and memory are
:math:`O(N)`.
Raises
------
ValueError
If `positions` is not ``(n_beads, 3)`` with enough beads for the
topology, or `types` has the wrong shape or a type below 1.
TypeError
If `box` is not a :class:`~polyphys.simulate.core.Box`.
Examples
--------
>>> box = Box(lo=np.full(3, -5.0), hi=np.full(3, 5.0))
>>> data = chain_data(helix(6, radius=1.0, pitch=2.0), box, angles=True)
>>> data.atom_style, data.n_atoms, data.n_bonds, data.n_angles
('angle', 6, 5, 4)
>>> data.masses is None, data.mol_ids.tolist()
(True, [1, 1, 1, 1, 1, 1])
"""
coordinates = np.array(positions, dtype=np.float64)
if coordinates.ndim != 2 or coordinates.shape[1] != 3:
raise ValueError(
f"'positions' must have shape (n_beads, 3), got "
f"{coordinates.shape}")
n_beads = coordinates.shape[0]
if types is None:
atom_types = np.ones(n_beads, dtype=np.int64)
else:
atom_types = np.array(types)
if atom_types.shape != (n_beads,):
raise ValueError(
f"'types' must have shape ({n_beads},), got "
f"{atom_types.shape}")
return DataFile(
atom_style="angle" if angles else "bond",
box=box,
ids=np.arange(1, n_beads + 1),
types=atom_types,
positions=coordinates,
n_atom_types=int(atom_types.max()) if n_beads else 1,
mol_ids=np.ones(n_beads, dtype=np.int64),
bonds=chain_bonds(n_beads, ring=ring),
angles=chain_angles(n_beads, ring=ring) if angles else np.empty(
(0, 4), dtype=np.int64),
n_bond_types=1,
n_angle_types=1 if angles else 0,
)
def _count(n: int, singular: str, plural: str) -> str:
"""Return `n` with the fitting one of `singular` and `plural`."""
return f"{n} {singular if n == 1 else plural}"
def _check_count(name: str, value: int, minimum: int) -> None:
"""Raise unless `value` is an integer of at least `minimum`."""
if isinstance(value, bool) or not isinstance(value, (int, np.integer)):
raise ValueError(f"'{name}' must be an integer, got {value!r}")
if value < minimum:
raise ValueError(f"'{name}' must be {minimum} or more, got {value}")
def _check_positive(name: str, value: float) -> None:
"""Raise unless `value` is a finite positive number."""
if not (math.isfinite(value) and value > 0.0):
raise ValueError(f"'{name}' must be positive, got {value}")
def _bracket(
gap: Callable[[float], float], estimate: float, width: float
) -> tuple[float, float]:
"""Return ``(lo, hi)`` about `estimate` with ``gap(lo) < 0 <= gap(hi)``
for a closing gap that grows with its argument: a bound with the wrong
sign moves outward by a doubling `width`, `lo` never below ``_TINY``.
Raises ``ValueError`` when the gap is still non-negative at ``_TINY``."""
lo, hi = max(estimate - width, _TINY), estimate + width
while gap(lo) >= 0.0:
if lo <= _TINY:
raise ValueError("the closing gap has no sign change")
width *= 2.0
lo = max(lo - width, _TINY)
while gap(hi) <= 0.0:
width *= 2.0
hi += width
return lo, hi
def _check_closed(gap: float | None, bond: float) -> None:
"""Raise unless the closing chord `gap` equals `bond` to round-off; the
root finder lands on a jump of the closing gap otherwise, which happens
when a curve has features smaller than the bond."""
if gap is None or abs(gap - bond) > 1e-9 * bond:
raise ValueError(
"the curve cannot be closed with equal bonds: its corners or "
"features are smaller than the bond length")
def _chord_angle(bond: float, radius: float, rise: float) -> float:
"""Return the angle step at which the chord of the helix of `radius`
and rise per radian `rise` equals `bond`; the root of the chord
equation on (0, pi]."""
def chord_excess(angle: float) -> float:
return (4.0 * radius * radius * math.sin(0.5 * angle) ** 2
+ rise * rise * angle * angle - bond * bond)
if chord_excess(math.pi) < 0.0:
raise ValueError(
f"a bond of {bond} does not fit in half a turn of a helix of "
f"radius {radius} and pitch {2 * math.pi * rise}")
angle: float = brentq(chord_excess, 0.0, math.pi, xtol=1e-14,
maxiter=200)
return angle
def _plectoneme_curve(u: FloatArray, strand: float,
theta: float) -> FloatArray:
"""Return points of the unit-radius Neukirch-Starostin plasmid at the
parameters `u` in [0, 2 strand + 2 pi]: strand A for u in [0, strand),
loop B for the next pi, strand C for the next `strand`, loop D for the
last pi (Neukirch and Starostin, 2008, Eqs. A1 to A4)."""
u = np.asarray(u, dtype=np.float64)
sin_t, cos_t = math.sin(theta), math.cos(theta)
turn = 1.0 + 2.0 * theta / math.pi
twist = strand * sin_t # the angle strand A turns
points = np.empty(u.shape + (3,), dtype=np.float64)
in_a = u < strand
s = u[in_a]
points[in_a] = np.stack(
[np.sin(s * sin_t), -np.cos(s * sin_t), s * cos_t], axis=-1)
in_b = (u >= strand) & (u < strand + math.pi)
s = u[in_b] - strand
theta_b = theta - s * turn
points[in_b] = np.stack([
math.sin(twist) * np.cos(s)
+ math.cos(twist) * sin_t * np.sin(s) * np.cos(s),
-math.cos(twist) * np.cos(s)
+ math.sin(twist) * sin_t * np.sin(s) * np.cos(s),
strand * cos_t + (sin_t - np.sin(theta_b)) / turn], axis=-1)
in_c = (u >= strand + math.pi) & (u < 2.0 * strand + math.pi)
s = u[in_c] - strand - math.pi
psi = twist - s * sin_t
points[in_c] = np.stack(
[-np.sin(psi), np.cos(psi), (strand - s) * cos_t], axis=-1)
in_d = u >= 2.0 * strand + math.pi
s = np.minimum(u[in_d] - 2.0 * strand - math.pi, math.pi)
theta_d = -math.pi - theta + s * turn
points[in_d] = np.stack([
sin_t * np.sin(s) * np.cos(s), np.cos(s),
(np.sin(theta_d) - sin_t) / turn], axis=-1)
return points
def _plectoneme_loop_length(theta: float, step: float) -> float:
"""Return the arclength of the two end loops of the unit-radius
plasmid, the whole curve when the strands have zero length."""
u = np.arange(0.0, 2.0 * math.pi + step, step)
points = _plectoneme_curve(u, 0.0, theta)
return float(np.linalg.norm(np.diff(points, axis=0), axis=1).sum())
def _march_curve(
curve: _Curve, u_end: float, n_beads: int, bond: float, step: float
) -> tuple[FloatArray, float | None]:
"""Place up to `n_beads` beads `bond` apart along `curve`, sampled at
parameter steps of `step` from 0 to `u_end`, each bead at the first
crossing of the sphere about the bead before; return the beads and the
distance from the last bead back to the first, or None when the curve
ran out. O(n_beads + u_end / step) time and memory."""
u = np.arange(0.0, u_end, step)
if u[-1] < u_end:
u = np.append(u, u_end)
samples = curve(u)
beads = np.empty((n_beads, 3), dtype=np.float64)
beads[0] = samples[0]
window = int(3.0 * bond / step) + 16
index = 0
for k in range(1, n_beads):
last = beads[k - 1]
beyond = _first_beyond(samples, index, window, last, bond)
if beyond is None:
return beads[:k], None
beyond = max(beyond, index + 1)
def excess(parameter: float) -> float:
point = curve(np.array([parameter]))[0]
return float(np.dot(point - last, point - last)) - bond * bond
lo, hi = u[beyond - 1], u[beyond]
if excess(lo) >= 0.0:
crossing = lo
else:
crossing = brentq(excess, lo, hi, xtol=1e-14, maxiter=200)
beads[k] = curve(np.array([crossing]))[0]
index = beyond - 1
return beads, float(np.linalg.norm(beads[-1] - beads[0]))
def _first_beyond(
samples: FloatArray, start: int, window: int, center: FloatArray,
radius: float,
) -> int | None:
"""Return the index of the first sample from `start` on that is farther
than `radius` from `center`, scanning `window` samples at a time."""
while True:
block = samples[start:start + window]
delta = block - center
outside = np.flatnonzero(
np.einsum("ij,ij->i", delta, delta) > radius * radius)
if outside.size:
return start + int(outside[0])
if start + window >= samples.shape[0]:
return None
start += window - 1
def _march_polyline(
vertices: FloatArray, n_beads: int, bond: float
) -> tuple[FloatArray, float | None]:
"""Place up to `n_beads` beads `bond` apart along the polyline through
`vertices`, each at the first crossing of the sphere about the bead
before, by exact line-sphere intersection; return the beads and the
distance from the last bead back to the first vertex, or None when the
polyline ran out. O(n_beads + n_vertices) time and memory."""
segments = np.diff(vertices, axis=0)
beads = np.empty((n_beads, 3), dtype=np.float64)
beads[0] = vertices[0]
segment = 0
for k in range(1, n_beads):
last = beads[k - 1]
end = _first_beyond_vertex(vertices, segment + 1, last, bond)
if end is None:
return beads[:k], None
segment = end - 1
offset = vertices[segment] - last
along = segments[segment]
alpha = float(np.dot(along, along))
beta = float(np.dot(offset, along))
gamma = float(np.dot(offset, offset)) - bond * bond
root = math.sqrt(max(beta * beta - alpha * gamma, 0.0))
if beta <= 0.0:
fraction = (root - beta) / alpha
else:
fraction = -gamma / (beta + root)
beads[k] = vertices[segment] + fraction * along
return beads, float(np.linalg.norm(beads[-1] - vertices[0]))
def _first_beyond_vertex(
vertices: FloatArray, start: int, center: FloatArray, radius: float
) -> int | None:
"""Return the index of the first vertex from `start` on that is at
least `radius` from `center`, scanning 256 vertices at a time."""
while start < vertices.shape[0]:
block = vertices[start:start + 256]
delta = block - center
outside = np.flatnonzero(
np.einsum("ij,ij->i", delta, delta) >= radius * radius)
if outside.size:
return start + int(outside[0])
start += 256
return None