Probe: per-frame observables from LAMMPS trajectories#

This page explains what polyphys.probe does with a study’s LAMMPS trajectories, how a study describes its probe as data, what the chain-size, spatial-histogram, and pair-distance analyses measure, what the binder analysis counts and how its cutoff was chosen, how the analyses run in serial or in parallel, and where their outputs go.

The probe phase is the one step of PolyPhys that reads trajectories. It is built on MDAnalysis, which the rest of the package does not need, so the layer is an optional extra:

python -m pip install "polyphys[mda]"

Without MDAnalysis, import polyphys.probe raises ImportError with that hint. The parsing and reduction layers work as before. With conda, install mdanalysis from conda-forge alongside PolyPhys, as Installation shows.

Tasks on this page:

  • Open a whole’s data file and dump as one universe: “Reading a trajectory”.

  • Describe a study’s probe once, as data: “A study’s probe as data”.

  • Measure the chain’s size and shape in every frame: “The chain-size analysis”.

  • Bin every species along the geometry’s directions: “The spatial histograms”, after “Recentering a frame”.

  • Measure the distances and contacts of one species, such as the foci: “The pair distances”.

  • Count how two-patch binders bind the chain: “The binder analysis”, with “Choosing the cutoff”.

  • Run an analysis over many frames in parallel: “Parallel runs” under the chain-size analysis, and “Parallel runs and cost” under the binder analysis.

How the probe differs from the research code it replaces is gathered at the end, in “What changed from the research code”.

Notation#

whole, segment

One run’s trajectory, or one chunk of it, as the README’s “The core idea: artifact lineage” defines them. A probe reads one whole or one segment and writes one file per observable plus a stamps file.

selection

An MDAnalysis selection string, such as 'resid 1' or 'type 2', that picks the atoms of one species from the universe.

observable

One quantity measured per frame, named as its time series without the species label: gyrT for the file gyrTMon.npy.

\(N\), \(\mathbf{r}_i\), \(m_i\)

The number of beads in the chain and the position and mass of bead \(i\), in the dump’s length and mass units.

\(\mathbf{S}\), \(\lambda_1 \ge \lambda_2 \ge \lambda_3\)

The mass-weighted gyration tensor of the chain about its center of mass, and its eigenvalues.

\(D\), \(Z\), \(L\), \(a_w\)

The parser’s dcyl, lcyl, and lcube, and the size \(a_w = 1\) of the beads whose centers form a cylindrical wall, so that the LAMMPS box is \((D + a_w) \times (D + a_w) \times Z\) for a cylinder and \(L^3\) for a cube.

\(F\), \(b\), \(K = \lceil F / b \rceil\)

The frames of a run, the block length of the two-dimensional maps, and the number of blocks.

\(d_{ij}\), \(r_c\), \(g_i\)

The distance between particles \(i\) and \(j\) of the pair species, the contact cutoff, and the 0-based backbone index of particle \(i\).

\(N_m\), \(N_p\), \(N_b = N_p / 2\)

The numbers of monomers, binder patches, and binders; the two patches of binder \(k\) are the patches \(2k\) and \(2k + 1\) in atom-ID order.

\(r_{ij}\), \(r_\mathrm{thres}\)

The distance between monomer \(i\) and patch \(j\), with the minimum image along each periodic direction, and the binding threshold: the pair is in contact when \(r_{ij} \le r_\mathrm{thres}\) (inclusive) or \(r_{ij} < r_\mathrm{thres}\) (strict).

\(d\)

The genomic distance of a bridged pair of monomers, in bonds along the backbone, the shorter way round a ring; a bridge is cis when \(d \le\) cis_threshold and trans otherwise.

Reading a trajectory#

make_universe() opens a study’s LAMMPS data file and dump as one MDAnalysis universe with the four arguments the research code used in each of its probe functions: the data file as a DATA topology whose Atoms lines read id resid type x y z, so the molecule ID of the bond, angle, or molecular atom styles becomes the residue ID that 'resid 1' selects; and the dump as a LAMMPSDUMP trajectory whose coordinates are the wrapped, unscaled x y z columns. Any further keyword, such as dt, passes through to the universe; the four fixed ones cannot be overridden.

from polyphys.probe import make_universe

universe = make_universe('N200...ens1.bug.data', 'N200...ens1.bug.lammpstrj')
chain = universe.select_atoms('resid 1')

Two facts about the files matter:

  • The data file needs a Masses section. MDAnalysis weights the radius of gyration and the gyration tensor by mass, and without masses it cannot form the tensor. The studies’ data files have one.

  • MDAnalysis sorts the atoms of each dump frame by id, so positions are in atom-ID order, the order along the chain, which the end-to-end distance relies on.

The probe does not convert frames to simulation time: the universe is opened without dt, the dump reader warns that it has no time step, and the times of an analysis are the dump’s time steps.

A study’s probe as data#

A study builds a ProbeSpec beside its ProjectSpec, in its own folder, and reads the parser class and the geometry from the project spec rather than storing them twice:

from polyphys.spec import ProbeSpec

PROBE = ProbeSpec(
    project=SPEC,
    selections={'Mon': 'resid 1', 'Foci': 'type 2', 'Crd': 'resid 0',
                'Dna': 'type 1'},
    chain='Mon',
    observables=('asphericityT', 'fsdT', 'gyrT', 'shapeT', 'principalT'),
    unwrap=False,
    bin_sizes={'r': _r_bin, 'z': _z_bin, 'theta': np.pi / 36, 'x': _r_bin,
               'y': _r_bin},
    histogram_species=('Crd', 'Mon', 'Dna', 'Foci'),
    block_frames=100,
    recenter='half',
    pair_species='Foci',
    contact_cutoff=_contact_cutoff,
    minimum_image=True,
)

Field

Holds

selections

Each species label mapped to its selection, read-only, in order

chain

The label in selections of the polymer chain; its series are named <observable><chain>

observables

The chain-size observables to measure, each a name in CHAIN_SIZE_OBSERVABLES

unwrap

Whether the chain is unwrapped across the periodic boundaries for its asphericity: False in a cylinder, True in a cube

bin_sizes

The histogram bin size along each direction: a number, or a function of the whole’s parser for a size that scales with its diameters (PerWhole)

histogram_species

The species whose spatial histograms are collected, each a label in selections; empty when the study’s histograms are not probed

block_frames

The block length \(b\) of the two-dimensional maps; required with histogram_species

recenter

How a frame’s positions are moved before binning: 'half' (half the box), 'none', or a triple (RecenterT); see “Recentering a frame”

pair_species

The species whose pair distances and contacts are collected, such as the foci; None when the study has none

contact_cutoff

The center-to-center distance at or below which two particles of pair_species touch, a number or a PerWhole function; required with it

minimum_image

Whether the pair distances use the minimum image along the periodic directions: the axis of a cylinder, every direction of a cube

binders

A BinderSpec of how the study’s two-patch binders are counted (see “The binder analysis”); None for a study without binders

The spec is checked at construction: the chain label must be a selection, every observable must be known and listed once, every scalar observable with the chain label must be one of the project’s tseries_properties (principalT, a per-frame matrix, is exempt), every bin size and the contact cutoff must be a finite positive number or callable along a known direction, every histogram species and the pair species must be a selection, the histogram species need bin_sizes and block_frames as the pair species needs contact_cutoff, and a BinderSpec must name a selected label other than the chain as its patches and eight binding series that the project’s tseries_properties list. Every field after unwrap has a default, so a record that probes only the chain size is unchanged. A finite positive number is a Python or NumPy integer or float, never a bool. resolve() turns a PerWhole value into the number for one whole, given its parser, and raises ValueError naming the whole when the value, or what a callable gives, is anything but a finite positive number.

The unwrap value is the research code’s: its probes read wrapped dumps, and a cylinder is periodic along its axis only, so the chain was unwrapped for the asphericity in the cubic studies and not in the cylindrical ones. Whether the two conventions differ on a given study’s frames is a check on the data; switching a study is a spec edit, not a code change.

The chain-size analysis#

ChainSize is an MDAnalysis AnalysisBase. It measures the observables of a ProbeSpec, or any sequence of names from CHAIN_SIZE_OBSERVABLES, on one chain in every frame:

Observable

One frame’s value

From

rfloryT

\(\lvert \mathbf{r}_N - \mathbf{r}_1 \rvert\), the end-to-end distance

end_to_end()

fsdT

\(\max_i z_i - \min_i z_i\) along the cylinder axis, the span or Feret diameter

fsd()

transSizeT

Twice the mean distance from the center of geometry in the plane across the axis

transverse_size()

gyrT

\(R_g = \sqrt{\lambda_1 + \lambda_2 + \lambda_3}\), the mass-weighted radius of gyration

AtomGroup.radius_of_gyration

asphericityT

\(\tfrac{3}{2} \sum_k (\lambda_k - \bar\lambda)^2 / (\sum_k \lambda_k)^2\), from 0 (spherically symmetric) to 1 (a line)

AtomGroup.asphericity(wrap=False, unwrap=unwrap)

shapeT

\(27 \prod_k (\lambda_k - \bar\lambda) / (\sum_k \lambda_k)^3\), from \(-1/4\) to 2

AtomGroup.shape_parameter(wrap=False)

principalT

The \(3 \times 3\) matrix of principal axes of the moment of inertia, one eigenvector per row, by decreasing eigenvalue

AtomGroup.principal_axes(wrap=False)

The asphericity and shape parameter are those of Dima and Thirumalai (2004), as MDAnalysis implements them. shapeT and principalT read the positions as the dump wraps them whatever unwrap is, as the research code did; unwrap reaches the asphericity only.

Every observable except an unwrapped asphericity therefore needs the dump to hold the chain whole, as the studies’ dumps do. ChainSize checks this in each frame: if a bond of the chain spans half the box or more along any direction, which no bond can do without being split by the periodic boundary, the run raises ValueError and names the frame. The check is skipped when the frame has no box or the topology has no bonds, and when an asphericity with unwrap set is the only observable.

from polyphys.probe import ChainSize, write_stamps
from trans_foci_cyl import PROBE, TransFociCyl

parser = TransFociCyl(trajectory, 'whole', 'bug', ispath=True)
analysis = ChainSize.from_spec(universe, PROBE).run()
analysis.save(save_to, f'{parser.name}-{parser.group}')
write_stamps(parser, analysis.n_frames, save_to)

After run(), results holds one float64 array per observable, keyed by its name: shape (n_frames,) for a scalar series and (n_frames, 3, 3) for principalT. run(start, stop, step) or run(frames=...) chooses the frames as in any MDAnalysis analysis. save writes <name>-<observable><chain>.npy per observable, the research code’s layout, and write_stamps() writes <name>-<group>-stamps.csv: one row of the artifact’s lineage names, its group, every parser attribute, and n_frames, which reduce_stamps() later combines across a space.

Parallel runs#

The class is marked parallelizable and supports the serial, multiprocessing, and dask backends of MDAnalysis 2.8 and later:

analysis = ChainSize.from_spec(universe, PROBE).run(
    backend='multiprocessing', n_workers=4)

With multiprocessing, the pool is closed and joined at the end of the run rather than terminated, as the MDAnalysis backend does, so each worker exits normally and releases the semaphore that the progress bar’s lock made in it.

Each worker fills the arrays of its own frames, and the aggregator concatenates them along the frame axis (ResultsGroup.ndarray_hstack for a scalar series, ResultsGroup.ndarray_vstack for principalT), so a parallel run gives the serial arrays.

Cost#

Every observable is a sum over the beads followed by at most a \(3 \times 3\) eigenproblem, so each frame costs \(O(N)\) time, plus the \(O(N + N_\mathrm{bonds})\) unwrap of the chain when unwrap is set, and \(O(N)\) extra space for the recentered positions. Over a run of \(F\) frames the series take \(O(F)\) space each and \(O(9F)\) for principalT. Positions come from MDAnalysis as float32, so each value carries a relative round-off of about \(10^{-7}\).

Recentering a frame#

The studies’ LAMMPS scripts set the box to \([-r, r]^2 \times [-l_z, l_z]\) for a cylinder and \([-l, l]^3\) for a cube, and fix recenter keeps the polymer’s center of mass at \(z = 0\) or at the origin. The LAMMPS dump reader of MDAnalysis 2.4 and later translates every frame so that the lower box bounds sit at the origin, which undoes that recentering, and no option of the reader keeps the written frame; only the box lengths survive, as ts.dimensions. A spatial histogram therefore has to move the positions back, and ProbeSpec.recenter says how:

recenter

Subtracts, per frame

Use

'half'

Half the frame’s box lengths, ts.dimensions[:3] / 2

The default: restores the LAMMPS frame exactly, the axis at \((0, 0)\)

'none'

Nothing

Keep the reader’s frame, positions in \([0, L)\)

(dx, dy, dz)

The triple as given

Reproduce another convention, such as the research code’s

The research code subtracted half the parser’s \((D, D, Z)\) or \(L\). In a cube that is half the box. In a cylinder the box spans the wall-bead centers, \(D + a_w\) across, so the research shift of \(D / 2\) left the cylinder’s axis at \((a_w / 2, a_w / 2) = (0.5, 0.5)\) rather than at the origin, and the radial and azimuthal histograms of every cylindrical study were measured about that displaced point. The maintainer chose 'half' on 2026-11-04. The triple (D / 2, D / 2, Z / 2) reproduces the research shift but not the research histograms: histogram_edges() gives the extended ranges of the next section, centered on the origin, and SpatialHistograms raises on a position outside them. The pair distances are translation invariant and ignore recenter.

The spatial histograms#

SpatialHistograms bins every species of a ProbeSpec in every frame, after wrapping and recentering, along the directions of the geometry and in the three Cartesian planes:

Geometry

Per frame, int64 (n_frames, n_bins)

Per block, float64 (n_blocks, n_a, n_b)

cylindrical

rHistT, zHistT, thetaHistT

xyHistBlock, xzHistBlock, yzHistBlock

cubic

rHistT

xyHistBlock, xzHistBlock, yzHistBlock

each followed by the species label, with \(r = \sqrt{x^2 + y^2}\) and \(\theta = \operatorname{atan2}(y, x)\) about the \(z\) axis in a cylinder and \(r = |\mathbf{r}|\) from the box center in a cube, through the helpers of polyphys.analyze.measurer. The one-dimensional counts are kept per frame, as the maintainer decided on 2026-11-03, so the time dependence of a profile and its block statistics stay available. A map per frame would not fit in memory, so the maps are averaged over blocks of block_frames consecutive frames of the run, with blockFrames holding the frames in each block; with \(b = 100\) and \(200 \times 200\) cells the three planes cost about 1 MB per block per species. The xz map is transposed to rows along \(x\), as the research code stored it.

histogram_edges() builds a whole’s edges from the spec’s bin sizes, resolved for the whole, with fixedsize_bins():

Geometry

Direction

Range

Bins

cylindrical

r

\([0, (D + a_w) / 2]\), the wall surface

nonnegative

cylindrical

z

\([-Z / 2, Z / 2]\)

ordinary

cylindrical

theta

\([-\pi, \pi]\)

periodic

cylindrical

x, y

\([-(D + a_w) / 2, (D + a_w) / 2]\)

ordinary

cubic

r

\([0, \sqrt{3} L / 2]\), the corner

nonnegative

cubic

x, y, z

\([-L / 2, L / 2]\)

ordinary

Before recentering, each position is wrapped into the box of the reader’s frame, \([0, L)\), along the directions the geometry makes periodic: all three in a cube, \(z\) in a cylinder. LAMMPS enforces the periodic boundaries only when it rebuilds the neighbor lists, so “the coordinates of an atom written to a dump file may be slightly outside the simulation box” (LAMMPS dump); the HnsCub dumps place H-NS cores up to \(0.04\) monomer diameters past a face. The image inside the box is the same particle. A position past a wall is not wrapped.

After wrapping, a position outside the edges of a direction, or outside the Cartesian edges of the maps, raises and aborts the run, so every frame’s counts sum to the species’ particle number. The ranges reach the wall surface in a cylinder and the corner in a cube, since a repulsive wall lets a small particle’s center approach the surface closer than half a monomer and a cube’s corners lie beyond \(L / 2\). The shells of a cube beyond \(L / 2\) are only partly inside the box, which the density normalization downstream has to account for.

from polyphys.probe import SpatialHistograms

parser = TransFociCyl(trajectory, 'whole', 'all', ispath=True)
analysis = SpatialHistograms.from_spec(universe, PROBE, parser).run()
analysis.save(save_to, f'{parser.name}-{parser.group}')

save writes, per species and direction, <name>-<dir>Edge<Species>.npy, <name>-<dir>Hist<Species>.npy (summed over the frames, the research artifact), and <name>-<dir>HistT<Species>.npy (per frame); the Cartesian edges <name>-xEdge.npy, yEdge, zEdge without a species; per plane and species <name>-<plane>Hist<Species>.npy (summed) and <name>-<plane>HistBlock<Species>.npy (per block); and <name>-blockFrames.npy.

In parallel, the blocks are numbered over the frames of the whole run, so a run split across workers gives the same blocks as a serial one: each worker adds its frames’ maps into the block sums and counts of the whole run, the aggregator sums them across workers (ResultsGroup.ndarray_sum) and concatenates the per-frame rows (ResultsGroup.ndarray_vstack), and _conclude divides each block’s sum by its frame count. Per frame the cost is \(O(S N \log B)\) time for \(S\) species of \(N\) particles and \(B\) bins, from the sorted-edge search of np.histogram, and \(O(N)\) extra space for the recentered positions; over a run \(8 F B\) bytes per one-dimensional histogram and \(8 K B_a B_b\) per map.

The pair distances#

PairDistances measures, for the species pair_species of a ProbeSpec, the foci of the TransFoci studies, four quantities per frame through polyphys.analyze.clusters:

Result

Shape, dtype

Holds

distMatT<Species>

(n_frames, n, n), float64

\(d_{ij}\) for \(i < j\) above the diagonal, \(g_i\) on it, zeros below

directContactsMatT<Species>

(n_frames, n, n), bool

\(d_{ij} \le r_c\), symmetric, True on the diagonal

bondsHistT<Species>

(n_frames, n), int64

[t, d]: the particles with \(d\) contacts in frame \(t\)

clustersHistT<Species>

(n_frames, n + 1), int64

[t, s]: the clusters of size \(s\) in frame \(t\); [t, 0] is 0

The cutoff is contact_cutoff resolved for the whole, dmon_large + dcrowd in the TransFoci studies: two foci touch when a crowder no longer fits between them. With minimum_image, the distances use the minimum image along the periodic directions of the geometry with the frame’s box lengths. save writes the four arrays as <name>-<quantity><Species>.npy, with the contact matrix as bool.

Indexing. LAMMPS numbers atoms from 1 (read_data: “a unique value from 1 to Natoms for each atom”), and MDAnalysis keeps those numbers as AtomGroup.ids while numbering its own atoms from 0 as AtomGroup.indices. The research code wrote foci.atoms.ids on the diagonal of the distance matrix, so the pair tags of its analysis, loc<i>loc<j>, carry 1-based IDs. Here the diagonal carries each focus’s 0-based position among the chain’s atoms, which from_spec computes and genomic_distance(), behind the pipeline’s FociPairDistances, requires: a 1-based diagonal would raise there whenever a focus is the chain’s last monomer. A pair tag of this package is therefore one less than the research tag of the same pair; the genomic distance itself is the same under either convention. The maintainer settled this on 2026-11-04.

Per frame the cost is \(O(n^2)\) time and space; over a run, \(8 F n^2\) bytes for the distance matrices, \(F n^2\) for the contact matrices, and $8 F (2 n

  • 1)$ for the two histograms.

The binder analysis#

BinderStatistics counts, in every frame, how the two-patch binders of a study bind its chain. The binder is the bivalent patchy protein of Brackley et al. (2013): a repulsive core with a sticky patch at each pole, which the H-NS studies follow (Jung, Sadeghi, and Ha, 2024). The analysis takes the chain and the binders’ patches, forms the distance \(r_{ij}\) between every monomer and every patch, marks the pairs within the cutoff as contacts with find_direct_contacts(), and counts them with binding_statistics(), whose rules the clusters guide states: a patch within the cutoff of two adjacent monomers is one engaged patch, each bridging binder joins the lowest-index monomer of each of its patches, and cis and trans count distinct monomer pairs. The dangling, cis, and trans modes are those of Joyeux and Vreede (2013, p. 1616), whose cis bridge joins DNA beads “separated by at most two DNA beads”, and of Sadeghi Isfahani (2024, chapter 5), whose trans bridge joins sites more than two monomers apart. Both read as: at most two monomers between the bridged sites, a genomic distance of at most 3 bonds, is cis; more, 4 bonds or longer, is trans. That definition is cis_threshold=3, which the H-NS study specs state; the research probe used 4. The threshold has no default: every BinderSpec and BinderStatistics states it. “Choosing the cis threshold” below gives both values and their rationale.

A study declares the facts the analysis needs in a BinderSpec inside its ProbeSpec:

from polyphys.spec import BinderSpec, ProbeSpec

PROBE = ProbeSpec(
    project=SPEC,
    selections={'Mon': 'resid 1', 'HnsPatch': 'type 2'},
    chain='Mon',
    observables=('asphericityT', 'gyrT', 'shapeT', 'principalT'),
    unwrap=True,
    binders=BinderSpec(patches='HnsPatch', binders='HnsCore', cutoff=0.685,
                       inclusive=True, cis_threshold=3,
                       store_distances=True),
)

Field

Holds

patches

The label in selections of the patches, in atom-ID order with the two patches of binder \(k\) at \(2k\) and \(2k + 1\); names the three patch series

binders

The label of the binders, a name only, since the cores are not selected; names the five binder series

cutoff

The binding threshold \(r_\mathrm{thres}\), in monomer diameters; a study constant, never computed from the particle sizes

inclusive

Whether a pair at exactly the cutoff is a contact: True by default, the thesis criterion; the research probe compared strictly

cis_threshold

The largest genomic distance, in bonds, of a cis bridge; keyword-only, no default; 3 in the H-NS studies

patches_per_binder

2, the only valence binding_statistics counts; kept as a field so that binders of another valence can be declared later

store_distances

Whether the monomer-to-patch distance matrices are kept and saved; True in the H-NS studies, which post-process them

from polyphys.probe import BinderStatistics, write_stamps
from hns_cub import PROBE, HnsCub

parser = HnsCub(trajectory, 'whole', 'nucleoid', ispath=True)
analysis = BinderStatistics.from_spec(universe, PROBE).run()
analysis.save(save_to, f'{parser.name}-{parser.group}')

from_spec selects the chain and the patches, takes the topology from the project, and takes the periodic directions from the geometry: every direction in a periodic cube, the axis only in a cylinder, whose LAMMPS boundary is ff ff pp. Along a periodic direction the distance takes the minimum image with the frame’s box length. The research probe called distance_array without a box, so it took no image, and the box argument of distance_array wraps every direction, which is wrong for a cylinder, so the module forms the distances itself.

After run(), results holds one array per key, each with a leading frame axis, which save writes as <name>-<series>.npy under the research code’s names:

Key

Shape, dtype

Saved as, with the H-NS labels

n_patch_monomer_contacts, n_patches_free, n_patches_engaged

(n_frames,), int64

nBoundTHnsPatch, nFreeTHnsPatch, nEngagedTHnsPatch

n_binders_free, n_binders_bridging, n_binders_dangling, n_pairs_cis, n_pairs_trans

(n_frames,), int64

nFreeTHnsCore, nBridgeTHnsCore, nDangleTHnsCore, nCisTHnsCore, nTransTHnsCore

loop_length_histogram: row \(t\), column \(d\) is the number of distinct bridged pairs at \(d\) bonds in frame \(t\); \(N_m // 2 + 1\) columns on a ring, \(N_m\) on a linear chain

(n_frames, n_lengths), int64

loopLengthHistTMon

distances, with store_distances

(n_frames, N_m, N_p), float64

distMatTMonHnsPatch

The eight series are keyed by the attributes of FrameBinding and named by BINDER_SERIES, which maps each one to the stem of its time series and to the label, patches or binders, that completes the name. The loop-length rows are the maintainer’s 2026-11-03 convention for a per-frame histogram, as the 1-D histogram probes keep their int64 counts; the research probe saved their sum over the frames as loopLengthHistMon, which is rows.sum(axis=0). The H-NS analysis tables in polyphys-lab still read that research artifact through tseries('loopLengthHist', 'Mon'); reading the per-frame rows is an analysis-side change not made yet.

The distance matrices are kept because two research post-steps read them rather than the trajectory: the threshold sweep described next, and the H-NS core clustering script, which recomputes the contacts and writes the bondsHistT and clustersHistT families of HnsCore that the HnsCub analysis table lists. They are float64, as distance_array returned them, so a later sweep makes the same contact decisions as the research sweep did; at \(8 N_m N_p\) bytes per frame they are held in memory for the run, as the research list was.

Choosing the cutoff#

The cutoff is a scientific choice that the spec states; the module never computes it from the particle sizes, because three formulas give three defensible numbers and the research probe picked the one that matches no published table. The three sources of the H-NS model agree on the patch-monomer geometry. Each starts from a patch sphere whose repulsive range is \(r_{\mathrm{cut},pp} = 0.2\), buried in a core of diameter \(1\), touching a monomer of diameter \(1\), all in monomer diameters:

Step

Brackley et al. (2013), Table S2 and Fig. S4

Jung, Sadeghi, and Ha (2024), Table 1

Thesis, Table 5.1 and Fig. 5.2

Patch-patch cutoff \(r_{\mathrm{cut},pp}\)

0.2

0.2

0.2

Patch size \(\sigma_p = r_{\mathrm{cut},pp} / 2^{1/6}\)

0.178

0.178

0.178

Patch-to-core distance \((\sigma_h - r_{\mathrm{cut},pp}) / 2\)

0.4 (the patch touches the pole)

0.4

0.4

Patch-monomer contact distance \(d_{pm} = (\sigma_m + r_{\mathrm{cut},pp}) / 2\)

implied by \(\sigma_{mp}\)

0.6

0.6

Patch-monomer \(\sigma_{mp} = d_{pm} / 2^{1/6}\)

0.535

0.535

0.535

Patch-monomer cutoff \(r_{\mathrm{cut},mp} = d_{pm} + 0.085\)

0.685

0.685

0.685

Well depth \(\varepsilon_{mp}\)

50

29

29

Two checks tie the three together: the PNAS supporting information gives the interaction range as 1.71 nm for 2.5 nm beads, and \(0.685 \times 2.5\) is 1.7125; and the thesis bounds the attractive range \(\delta_\mathrm{attr} = 0.085\) by \(\sigma_h (2^{1/6} - 1) \approx 0.122\), the reach of the core’s own repulsion past its contact distance, so that a monomer feels the patch only where it would also feel the core. Outside \(r_{\mathrm{cut},mp}\) the force on the monomer is identically zero, which makes \(0.685\) a natural threshold for “bound”: thesis Section 5.3 defines a bound H-NS as one whose patch is within \(r_\mathrm{thres} = r_{\mathrm{cut},mp}\) of a monomer, with \(r \le r_\mathrm{thres}\).

The research probe used a different number: \(2^{1/6} (d_\mathrm{mon} + d_\mathrm{hns\_patch}) / 2 = 2^{1/6} (1 + 0.178) / 2 = 0.66113\), rounded to three decimals as \(0.661\), with a strict comparison. That is the Lennard-Jones minimum of an arithmetic-mean \(\sigma\) of \(0.589\), which no source uses for this pair, since each sets \(\sigma_{mp}\) from the contact geometry instead. At \(0.661\) the shifted potential is about \(-3.1\,k_B T\) against \(-8.7\,k_B T\) at the minimum, so a strict cut there drops the pairs in the outer third of the well that the published criterion counts.

The research code also measured how much the counts depend on the threshold. Its threshold sweep, which threshold_sweep() now reproduces, reloaded the saved distance matrices of the HnsCyl wholes and recounted for every cutoff from \(\sigma_{mp} = 0.535\) to \(r_{\mathrm{cut},mp} = 0.685\) in steps of \(0.01\) and for a cis threshold of 2 and of 4. Its conclusions: below a cutoff of \(0.575\) no loops of size 2 or more form; the loop-size distribution peaks at a genomic distance of 4 for every cutoff; the normalized loop-size distributions collapse for cutoffs of \(0.645\) and above; and the cis threshold of 2 against 4 changes nothing visible; “Choosing the cis threshold” below compares 3 and 4. Both \(0.661\) and \(0.685\) lie in that insensitive region, so the switch moves the ensemble averages little while the per-frame counts differ by the pairs in the outer band of the well.

The H-NS study specs therefore state the published criterion, cutoff=0.685 with inclusive=True, as the maintainer decided on 2026-11-04. A study that must reproduce the research probe’s artifacts exactly states cutoff=0.661 with inclusive=False instead; the change is one spec edit.

The sweep itself is threshold_sweep(), which takes the stored distMatT<chain><patches> array of a whole and a grid of cutoffs and cis thresholds; the clusters guide, “The threshold sweep”, describes its tables and why its inclusive keyword has no default.

Choosing the cis threshold#

cis_threshold is the largest genomic distance, in bonds, of a bridge counted as cis: a bridge between monomers \(i\) and \(j\) is cis when \(d(i, j) \le\) cis_threshold. Two values have been used.

  • 3, the H-NS studies’ value. Joyeux and Vreede (2013, p. 1616) call a dimer cis when its two terminal beads bind DNA beads “separated by at most two DNA beads”, and trans when they are strictly more than two apart; the maintainer’s thesis (Sadeghi Isfahani, 2024, chapter 5) calls a bridge trans when its sites are more than two monomers apart. Read as at most two monomers between the bridged sites, both give a cis bridge of at most 3 bonds, and a trans one of 4 bonds or more.

  • 4, the research probe’s value. The research code that PolyPhys replaces counted both H-NS probes with a cis threshold of 4, a genomic distance in bonds, not monomers, compared inclusively. It took 4 because the loop-size distribution of the bridged pairs peaks there, at a genomic distance of 4 bonds for every cutoff (see “Choosing the cutoff”). Its threshold sweep compared 2 and 4 only and found no visible difference between them.

The two differ by the bridges of exactly 4 bonds, three monomers between the sites, which 4 counts as cis and 3 as trans. The genomic distance is taken between the lowest-index monomers of the two patches, so a bridge whose lower-index patch touches two adjacent monomers is counted one bond longer than its closest contact; at 3, such a bridge with its closest contact 3 bonds apart is trans. Since the loop sizes peak at 4 bonds, the counts at 3 and at 4 can differ much more than those at 2 and 4; threshold_sweep() recounts a whole’s saved distance matrices at both. The threshold has no default, so a study that must reproduce the research probe’s cis and trans counts states cis_threshold=4 instead; the change is one spec edit.

Parallel runs and cost#

The class is marked parallelizable with the same three backends as ChainSize; each worker fills the arrays of its own frames, and the aggregator concatenates them along the frame axis (ResultsGroup.ndarray_hstack for the eight series, ResultsGroup.ndarray_vstack for the histogram rows and the distances). Per frame, the distances and the contacts cost \(O(N_m N_p)\) time and space, and making the bridged pairs distinct \(O(N_b \log N_b)\). Over a run of \(F\) frames the series take \(O(F)\) space each, the histogram \(O(F N_m / 2)\), and the distances \(8 F N_m N_p\) bytes.

What changed from the research code#

  • The research code shifted every position by half the box in every frame before measuring. Every chain-size observable is invariant under a translation of all positions, because each one recenters the chain on its center of geometry or mass first, so the shift is dropped for this family. The spatial histograms recenter by ProbeSpec.recenter, whose default 'half' restores the LAMMPS frame and corrects the research shift’s half-bead offset in a cylinder (see “Recentering a frame”).

  • The spatial histograms keep the one-dimensional counts per frame and the two-dimensional maps per block of frames, where the research code summed both over the frames; the summed arrays are still written. Their ranges reach the wall surface and the cube’s corner, a position a little past a periodic face is wrapped into the box, and a position outside the edges after that raises instead of being dropped. The research ranges stopped at \(D / 2\) in a cylinder and \(L / 2\) in a cube; the maintainer extended them on 2026-11-04.

  • The pair distances write 0-based backbone indices on the diagonal of the distance matrix, use the minimum image along the periodic directions, and store the contact matrix as bool, where the research code wrote 1-based atom IDs, used no minimum image, and stored int64 (see “The pair distances”).

  • The HnsCyl radial bin size includes the H-NS core diameter in its minimum, as HnsCub’s did; the maintainer confirmed the research code’s omission as a mistake on 2026-11-04.

  • One class, driven by a ProbeSpec, replaces the per-study loops; the collectors are preallocated per run or per worker rather than per function.

  • asphericity(wrap=False, unwrap=...) takes unwrap from the spec.

  • The stamps carry a group column; the research stamps did not, and children_stamps() adds it from their file names, <name>-<group>-stamps.csv, so either kind reduces.

  • Frames are not converted to simulation time (see “Reading a trajectory”). The research code passed dt as the dump interval times the time step times the Lennard-Jones time unit, which issue #56 lists as still to confirm.

  • The binder distances take the minimum image along the geometry’s periodic directions; the research probe took none.

  • The binding cutoff and its comparison are the spec’s. The H-NS studies state the published criterion, \(0.685\) inclusive, where the research probe used \(0.661\) strict (see “Choosing the cutoff”).

  • The H-NS studies count a bridge as cis up to 3 bonds, where the research probe counted up to 4 (see “The binder analysis”).

  • The loop-length histogram is saved per frame as loopLengthHistTMon; the research probe summed it over the frames as loopLengthHistMon, which the H-NS analysis tables still read.

  • The distance matrices are an option of the spec, on in the H-NS studies, rather than always written.

References#