polyphys.simulate.build#

Start configurations — polyphys.simulate.build#

The 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 write_data() as a 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.

Added in version 0.6.0.

Contents#

helix() and plectoneme_ring() place beads on the two built-in shapes; resample_curve() places them along any curve given as points. chain_bonds() and chain_angles() give the topology of a linear or ring chain, and chain_data() wraps positions and topology in a DataFile. check_conformation() tests a data file against the conditions under which LAMMPS stops or warns, and raises ConformationError or returns a ConformationReport.

Notation#

\(N\)

The number of beads.

\(b\)

The bond length, the distance between bonded bead centers.

\(\sigma\), \(\epsilon\)

The bead diameter and the energy unit of the Lennard-Jones (LJ) units of the run; all lengths here are in \(\sigma\).

\(R\), \(p\)

The radius and the pitch (the axial rise per turn) of a helix; \(c = p / 2\pi\) is the rise per radian.

\(\Delta t\)

The angle between neighboring beads on a helix.

\(\theta_A\)

The helical angle, between a strand’s tangent and the axis: \(\tan\theta_A = 2\pi R / p\).

\(L_A\)

The arclength of one strand of a plectoneme.

\(K\), \(R_0\)

The spring constant and the maximum extension of a FENE bond.

\(d_{\min}\)

The smallest distance check_conformation() allows between two beads that are not bonded.

\(D\), \(a\)

The diameter of a cylindrical confinement and the bead diameter; \(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 \(2^{1/6}\sigma\) and shifted up by \(\epsilon\) (Weeks, Chandler, and Andersen, 1971, Eq. 4). Bonded beads add the finitely extensible nonlinear elastic (FENE) spring, whose force \(K r / (1 - (r/R_0)^2)\) diverges at \(R_0\) (Warner, 1972, Eq. 4). Grest and Kremer (1986, Eqs. 8 and 9) set \(K = 30\, \epsilon/\sigma^2\) and \(R_0 = 1.5\,\sigma\) so that chains cannot cross; with these values at \(k_B T = \epsilon\) the bond never exceeds \(1.2\,\sigma\) (Kremer and Grest, 1990, Appendix). The LAMMPS bond_style fene holds both terms of the bond,

\[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 \(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 \(0.97 \sigma\), kept beads two apart more than \(1.02\,\sigma\) from each other, and measured a mean bond length of \(0.97\,\sigma\) in the equilibrated melt. The force of the FENE and WCA terms together is zero at \(0.961\,\sigma\), so a bond of \(0.97\,\sigma\) stores \(0.04\,\epsilon\); the same \(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 \(1 - (r/R_0)^2 < 0.1\), that is for \(r > \sqrt{0.9}\,R_0 = 1.423\,\sigma\) at \(R_0 = 1.5\,\sigma\), and stops with Bad FENE bond at \(r \ge 2R_0\) (bond_fene.cpp). A bond longer than the ghost-atom cutoff, the pair cutoff plus the neighbor skin (\(1.42\,\sigma\) for a WCA cutoff and a skin of \(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 \(1.425\, \sigma\), that is \(0.95\,R_0\), is above both the warning length and the default ghost cutoff; in test runs of this model (\(K = 30\), \(R_0 = 1.5\), skin 0.3, \(k_B T = \epsilon\)) starts whose bonds were all between \(0.97\) and \(1.10\,\sigma\) ran under plain nve, under Langevin dynamics, and under nve/limit alike, while a start with every bond at \(1.40\,\sigma\) stopped a plain nve run within 70 steps. check_conformation() tests each of these conditions.

Shapes#

Helix. Bead \(k\) sits at \((R\cos k\Delta t, R\sin k\Delta t, c k\Delta t)\), centered on \(z = 0\). The distance between neighboring beads is the chord

\[b^2 = 4R^2 \sin^2(\Delta t / 2) + c^2 \Delta t^2,\]

whose right side increases on \((0, \pi]\), so \(\Delta t\) is its one root there whenever \(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 \(p\sin\theta_A\) apart, so a helix needs \(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 \(R\) and helical angle \(\theta_A\) (strand A), an end loop (B), the same helix rotated by \(\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 \(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 \(b\) from the one before, and the strand arclength \(L_A\) is solved so that the \(N\) chords close the ring exactly, the bond between the last bead and the first included. \(R\), \(p\), \(b\), and \(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 \(p \ge 2 d_{\min} / \sin\theta_A\) (about \(2.0\) to \(2.1\,\sigma\) for \(R \ge 2\sigma\) and \(d_{\min} = \sigma\)) to pass the pair check.

Any curve. 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 \(N\) chords close it; the shape is kept and the size changes by about \((N b - \ell) / \ell\) for a polyline of length \(\ell\). Closing needs a curve whose features are large compared with \(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, \(A[1 + \cos(\pi r / 2^{1/6}\sigma)]\), raising \(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#

helix() takes \(O(N)\) time and memory. plectoneme_ring() and a closed resample_curve() take \(O(N)\) time and memory per march along the curve, and about ten marches to close the ring. check_conformation() takes \(O(N^2)\) time, in row chunks, so its memory is \(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: 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: 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: 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: 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: 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: 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, and its example confined_viral_DNA.

  • The LAMMPS documentation of bond_style fene, special_bonds, read_data, comm_modify, fix wall/region, and fix nve/limit, and the LAMMPS source at release stable_30Sep2026_update1: bond_fene.cpp, lines 89 to 94 (the warning and the stop) and bond_fene.cpp, lines 192 to 195 (the equilibrium distance \(0.97\,\sigma\)).

  • Plimpton, S., Pizza.py chain.py (2005) and LAMMPS tools/def.chain: bond 0.97 and 1-3 distance 1.02.

Dependencies#

Module Attributes

FENE_WARNING_FRACTION

LAMMPS warns FENE bond too long when \(1 - (r/R_0)^2 < 0.1\), that is for a bond longer than \(\sqrt{0.9}\,R_0\) (bond_fene.cpp, lines 89 to 94).

Functions

chain_angles(n_beads, *[, ring, angle_type])

Return the angles of a linear or ring chain of beads numbered from 1.

chain_bonds(n_beads, *[, ring, bond_type])

Return the bonds of a linear or ring chain of beads numbered from 1.

chain_data(positions, box, *[, ring, ...])

Return a data file of one chain from bead positions.

check_conformation(data, *, r0, ...[, ...])

Check that LAMMPS can start a Kremer-Grest run from a data file.

helix(n_beads, *, radius, pitch[, bond_length])

Place beads a fixed distance apart along a helix.

plectoneme_ring(n_beads, *, radius, pitch[, ...])

Place beads a fixed distance apart along a closed plectoneme.

resample_curve(points, n_beads[, ...])

Place beads a fixed distance apart along a curve given as points.

Classes

ConformationReport(n_atoms, min_bond, ...)

The extremes check_conformation() measured on a passing file.

Exceptions

ConformationError

A start configuration would make LAMMPS stop or warn.

exception polyphys.simulate.build.ConformationError[source]#

Bases: ValueError

A start configuration would make LAMMPS stop or warn.

Raised by check_conformation(); the message names every failed condition with its worst value and the atoms involved.

Added in version 0.6.0.

Examples

>>> box = Box(lo=np.full(3, -5.0), hi=np.full(3, 5.0))
>>> pair = chain_data([[0.0, 0.0, 0.0], [1.5, 0.0, 0.0]], box)
>>> try:
...     check_conformation(pair, r0=1.5, ghost_cutoff=1.42,
...                        periodic=(True, True, True))
... except ConformationError as err:
...     print(err)
1 bond at or above sqrt(0.9) R0 = 1.423: longest 1.5 (atoms 1 2); 1 bond at or above the ghost cutoff 1.42: longest 1.5 (atoms 1 2)
class polyphys.simulate.build.ConformationReport(n_atoms, min_bond, max_bond, min_pair, max_radial)[source]#

Bases: object

The extremes check_conformation() measured on a passing file.

Added in version 0.6.0.

Variables:
  • n_atoms (int) – The number of atoms.

  • max_bond (min_bond,) – The shortest and the longest bond, in the length unit of the file; NaN when there are no bonds.

  • min_pair (float) – The shortest distance between two atoms that are not bonded, with the minimum image on the periodic axes; NaN when there is no such pair.

  • max_radial (float or None) – The largest distance of an atom from the cylinder axis, or None when no cylinder was given.

Parameters:
max_bond: float#
max_radial: float | None#
min_bond: float#
min_pair: float#
n_atoms: int#
polyphys.simulate.build.FENE_WARNING_FRACTION = 0.9486832980505138#

LAMMPS warns FENE bond too long when \(1 - (r/R_0)^2 < 0.1\), that is for a bond longer than \(\sqrt{0.9}\,R_0\) (bond_fene.cpp, lines 89 to 94).

polyphys.simulate.build.chain_angles(n_beads, *, ring=False, angle_type=1)[source]#

Return the angles of a linear or ring chain of beads numbered from 1.

Added in version 0.6.0.

Parameters:
  • n_beads (int) – The number of beads, 3 or more.

  • ring (bool) – Whether to add the two angles that span the closing bond; False by default.

  • angle_type (int) – The angle type of every angle, 1 or more; 1 by default.

Returns:

Shape (n_angles, 4), int64: type, atom1, atom2, atom3 per angle with atom2 the vertex, the layout of angles, with n_angles equal to n_beads minus two, or to n_beads for a ring. Time and memory are \(O(N)\).

Return type:

numpy.typing.NDArray[numpy.int_]

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]])
polyphys.simulate.build.chain_bonds(n_beads, *, ring=False, bond_type=1)[source]#

Return the bonds of a linear or ring chain of beads numbered from 1.

Added in version 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) – Whether to add the bond from the last bead to the first; False by default.

  • bond_type (int) – The bond type of every bond, 1 or more; 1 by default.

Returns:

Shape (n_bonds, 3), int64: type, atom1, atom2 per bond, the layout of bonds, with n_bonds equal to n_beads minus one, or to n_beads for a ring. Time and memory are \(O(N)\).

Return type:

numpy.typing.NDArray[numpy.int_]

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]])
polyphys.simulate.build.chain_data(positions, box, *, ring=False, angles=False, types=None)[source]#

Return a data file of one chain from bead positions.

The atoms get the IDs 1 to \(N\) in the order of positions, molecule 1, and the bonds of chain_bonds() and, if asked, the angles of chain_angles(), all of type 1. The masses and the velocities are left to the input script.

Added in version 0.6.0.

Parameters:
Returns:

With n_atom_types the largest type, n_bond_types 1, and n_angle_types 1 if angles else 0. Time and memory are \(O(N)\).

Return type:

polyphys.simulate.data.DataFile

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 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])
polyphys.simulate.build.check_conformation(data, *, r0, ghost_cutoff, periodic, min_distance=1.0, dcyl=None, dmon=None)[source]#

Check that LAMMPS can start a Kremer-Grest run from a data file.

Each condition is one that makes LAMMPS warn or stop (see the module documentation). The file fails if any holds:

  1. A bond is at or above the FENE warning length \(\sqrt{0.9}\, R_0\), where LAMMPS warns FENE bond too long and clamps the force (and stops at \(2R_0\)).

  2. A bond is at or above ghost_cutoff, the pair cutoff plus the neighbor skin, beyond which a bond across a periodic face or a processor boundary stops the run.

  3. Two atoms, bonded or not, are closer than \(10^{-9}\), which gives a non-finite force.

  4. Two atoms that are not bonded are closer than min_distance; beads two apart along the chain count, as special_bonds fene treats them.

  5. An atom lies outside the box, or on its upper face, along a non-periodic axis, where read_data loses it. Along a periodic axis read_data remaps it, and the distances above use the minimum image.

  6. With a cylinder, an atom lies farther than \((D - a)/2\) from the \(z\) axis through the box center, the effective radius the bead centers can reach; a bead there is one bead diameter from a wall of diameter \(D\) built from beads of diameter \(a\).

Added in version 0.6.0.

Parameters:
  • data (polyphys.simulate.data.DataFile) – The start configuration; its positions as written, in the length unit of the run.

  • r0 (float) – The FENE maximum extension \(R_0\) of the run, positive; 1.5 in the Kremer-Grest model.

  • ghost_cutoff (float) – The ghost-atom cutoff of the run, positive: the largest pair cutoff plus the neighbor skin, unless comm_modify cutoff sets more; \(2^{1/6} + 0.3 = 1.42\) for a WCA run with the LJ default skin.

  • periodic (collections.abc.Sequence[bool]) – Which of the x, y, and z axes are periodic in the run; a data file does not record it.

  • min_distance (float) – \(d_{\min}\), the smallest allowed distance between two atoms that are not bonded, 0 or more; by default 1.0, one bead diameter, where the WCA energy of the pair is \(\epsilon\).

  • dcyl (float | None) – The cylinder diameter \(D\) and the bead diameter \(a\), given together or not at all, with \(D > a\).

  • dmon (float | None) – The cylinder diameter \(D\) and the bead diameter \(a\), given together or not at all, with \(D > a\).

Returns:

The extremes measured, when every condition passes.

Return type:

polyphys.simulate.build.ConformationReport

Raises:
  • ConformationError – If a condition fails; the message lists every failed condition with its count, its worst value, and the atoms involved.

  • ValueError – If an argument is out of range, periodic does not have three entries, only one of dcyl and dmon is given, or the box is triclinic and an axis is periodic.

Notes

Bonds are checked for length only; the builders never make a short bond, and a bond below about \(0.9\,\sigma\) stores several \(\epsilon\) in the WCA term of the FENE bond that this check does not see. Time is \(O(N^2)\), in row chunks, so memory is \(O(N)\) beyond the positions.

Examples

>>> box = Box(lo=np.array([-4.0, -4.0, -8.0]),
...           hi=np.array([4.0, 4.0, 8.0]))
>>> data = chain_data(helix(12, radius=2.0, pitch=2.5), box)
>>> report = check_conformation(data, r0=1.5, ghost_cutoff=1.42,
...                             periodic=(False, False, True),
...                             dcyl=6.0, dmon=1.0)
>>> round(report.max_bond, 6), round(report.max_radial, 6)
(0.97, 2.0)
polyphys.simulate.build.helix(n_beads, *, radius, pitch, bond_length=0.97)[source]#

Place beads a fixed distance apart along a helix.

Bead \(k\) sits at \((R\cos k\Delta t, R\sin k\Delta t, c k \Delta t)\) on a right-handed helix of radius \(R\) and pitch \(p\) about the \(z\) axis, with \(c = p/2\pi\), centered on \(z = 0\). The angle step \(\Delta t\) is the root of the chord equation \(b^2 = 4R^2\sin^2(\Delta t/2) + c^2\Delta t^2\), so every bond has the length \(b\) exactly.

Added in version 0.6.0.

Parameters:
  • n_beads (int) – The number of beads \(N\), 1 or more.

  • radius (float) – The helix radius \(R\), positive, in the length unit of the run.

  • pitch (float) – The pitch \(p\), the rise per turn, positive. Adjacent turns are \(p\sin\theta_A\) apart, with \(\tan\theta_A = 2\pi R/p\).

  • bond_length (float) – The bond length \(b\), positive; by default \(0.97\), the start bond length of Kremer and Grest (1990) in units of the bead diameter.

Returns:

Shape (n_beads, 3), float64: the bead positions, the first at angle zero.

Return type:

numpy.typing.NDArray[numpy.double]

Raises:

ValueError – If n_beads is below 1, a length is not positive, or the bond does not fit in half a turn, \(b^2 > 4R^2 + c^2\pi^2\).

Notes

The chord equation’s right side increases on \((0, \pi]\), so scipy.optimize.brentq() finds its one root there. Time and memory are \(O(N)\).

Examples

A bond of \(\sqrt 2\) on a helix of radius 1 and pitch 6 steps by \(\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     ]])
polyphys.simulate.build.plectoneme_ring(n_beads, *, radius, pitch, bond_length=0.97)[source]#

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 \(R\) and pitch \(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 \(b\) from the one before, and the strand arclength \(L_A\) is solved so that \(N\) chords close the curve: every bond, the one between the last bead and the first included, has the length \(b\), and \(R\) and \(p\) are exactly as given. The ring is centered on the origin with its axis along \(z\); no bead lies farther than \(R\) from the axis.

Added in version 0.6.0.

Parameters:
  • n_beads (int) – The number of beads \(N\). The two end loops alone take about \(7.7 R / b\) beads each; fewer raises.

  • radius (float) – The helix radius \(R\), positive, in the length unit of the run.

  • pitch (float) – The pitch \(p\) of each strand, positive. The two strands are \((p/2)\sin\theta_A\) apart and adjacent turns of one strand \(p\sin\theta_A\), with \(\tan\theta_A = 2\pi R/p\); a pitch of about \(2\sigma\) or more keeps the strands a bead diameter apart.

  • bond_length (float) – The bond length \(b\), positive; by default \(0.97\), as in helix().

Returns:

Shape (n_beads, 3), float64: the bead positions, from the foot of the first strand up and around.

Return type:

numpy.typing.NDArray[numpy.double]

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 \(b\), grows with \(L_A\) and is continuous, so scipy.optimize.brentq() finds its root in a bracket around the estimate \((N s - \ell_{loops}) / 2\), with \(s\) the arc a chord of \(b\) spans on the helix and \(\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, \(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
polyphys.simulate.build.resample_curve(points, n_beads, bond_length=0.97, *, closed=False)[source]#

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 \(b\) from the bead before (the first crossing of the sphere of radius \(b\) about it), so every bond has the length \(b\) exactly. On an open curve the beads cover the first \(N - 1\) chords and the rest of the curve is unused. A closed curve is scaled uniformly about the centroid of its points until \(N\) chords close it, the bond from the last bead to the first included; the shape is kept and the size changes by about \((Nb - \ell)/\ell\) for a polyline of length \(\ell\).

Added in version 0.6.0.

Parameters:
  • points (numpy.typing.ArrayLike) – 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 \(N\): 1 or more on an open curve, 3 or more on a closed one.

  • bond_length (float) – The bond length \(b\), positive; by default \(0.97\), as in helix().

  • closed (bool) – Whether the curve is closed and the ring must close with the bond length too; False by default.

Returns:

Shape (n_beads, 3), float64: the bead positions, in the order of the curve.

Return type:

numpy.typing.NDArray[numpy.double]

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 \(O(N + n_{points})\) time and memory; closing a curve takes about ten marches, the scale found by scipy.optimize.brentq(). The polyline, not the smooth curve it may stand for, carries the beads: sample a smooth curve finely compared with \(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 \(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 \(\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.]])