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,
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
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#
Python standard library: dataclasses, logging, math
Third-party: numpy, scipy (
scipy.optimize.brentq())PolyPhys:
polyphys.simulate.core,polyphys.simulate.data
Module Attributes
LAMMPS warns |
Functions
|
Return the angles of a linear or ring chain of beads numbered from 1. |
|
Return the bonds of a linear or ring chain of beads numbered from 1. |
|
Return a data file of one chain from bead positions. |
|
Check that LAMMPS can start a Kremer-Grest run from a data file. |
|
Place beads a fixed distance apart along a helix. |
|
Place beads a fixed distance apart along a closed plectoneme. |
|
Place beads a fixed distance apart along a curve given as points. |
Classes
|
The extremes |
Exceptions
A start configuration would make LAMMPS stop or warn. |
- exception polyphys.simulate.build.ConformationError[source]#
Bases:
ValueErrorA 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:
objectThe 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 (
floatorNone) – The largest distance of an atom from the cylinder axis, or None when no cylinder was given.
- Parameters:
- polyphys.simulate.build.FENE_WARNING_FRACTION = 0.9486832980505138#
LAMMPS warns
FENE bond too longwhen \(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:
- Returns:
Shape
(n_angles, 4), int64:type, atom1, atom2, atom3per angle withatom2the vertex, the layout ofangles, withn_anglesequal to n_beads minus two, or to n_beads for a ring. Time and memory are \(O(N)\).- Return type:
- 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:
- Returns:
Shape
(n_bonds, 3), int64:type, atom1, atom2per bond, the layout ofbonds, withn_bondsequal to n_beads minus one, or to n_beads for a ring. Time and memory are \(O(N)\).- Return type:
- 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 ofchain_angles(), all of type 1. The masses and the velocities are left to the input script.Added in version 0.6.0.
- Parameters:
positions (
numpy.typing.ArrayLike) – Shape(n_beads, 3): the bead positions along the chain, ashelix(),plectoneme_ring(), orresample_curve()return them.box (
polyphys.simulate.core.Box) – The simulation box; it is not checked against the positions here,check_conformation()does that.ring (
bool) – Whether the chain is a ring; False by default.angles (
bool) – Whether to add the angles and use the atom styleangleinstead ofbond; False by default.types (
numpy.typing.ArrayLike|None) – Shape(n_beads,): the atom types, from 1; all 1 by default.
- Returns:
With
n_atom_typesthe largest type,n_bond_types1, andn_angle_types1 if angles else 0. Time and memory are \(O(N)\).- Return type:
- 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.
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:
A bond is at or above the FENE warning length \(\sqrt{0.9}\, R_0\), where LAMMPS warns
FENE bond too longand clamps the force (and stops at \(2R_0\)).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.
Two atoms, bonded or not, are closer than \(10^{-9}\), which gives a non-finite force.
Two atoms that are not bonded are closer than min_distance; beads two apart along the chain count, as
special_bonds fenetreats them.An atom lies outside the box, or on its upper face, along a non-periodic axis, where
read_dataloses it. Along a periodic axisread_dataremaps it, and the distances above use the minimum image.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, unlesscomm_modify cutoffsets 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:
- 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:
- 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 inhelix().
- Returns:
Shape
(n_beads, 3), float64: the bead positions, from the foot of the first strand up and around.- Return type:
- 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 inhelix().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:
- 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, andValueErroris 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.]])