Density: local number density and volume fraction#
This page explains what polyphys.analyze.density computes and why it
computes it the way it does: the local number density of a species from a
histogram of its bead centers, and the local volume fraction, which has to
account for a bead of finite size reaching into the bins next to the one
that holds its center. Every routine is a numpy or scipy kernel on arrays;
reading frames, binning positions, averaging over frames, and placing the
result in the artifact lineage are the caller’s job.
Notation#
- \(x\)
The binned coordinate: the axial position \(z\) of a cylinder, or the distance \(r\) from the axis of a cylinder or from a point in a cube. Lengths are in the monomer diameter.
- \(e_0 < e_1 < \dots < e_B\)
The bin edges,
edges; bin \(i\) is \([e_i, e_{i+1})\) and has width \(h_i\). There are \(B\) bins,n_bins.- \(w(x)\,dx\), \(V_i\)
The measure of the coordinate, \(A\,dx\) for slabs of cross-section \(A\), \(2\pi L x\,dx\) for cylindrical shells of length \(L\), \(4\pi x^2\,dx\) for spherical shells; and the bin volume \(V_i = \int_{e_i}^{e_{i+1}} w(x)\,dx\),
volumes.- \(H_i\), \(F\)
The bead centers counted in bin \(i\) over \(F\) frames,
countsandn_frames.- \(\rho_i\)
The local number density of bin \(i\),
rho, in beads per cubic length unit.- \(a\), \(R_b = a/2\), \(v = \pi a^3 / 6\)
The bead diameter,
bead_diameter, its radius, and its volume.- \(s(x \to j)\)
The share kernel: the volume of one bead whose center is at coordinate \(x\) that lies inside bin \(j\). Summed over \(j\) it is \(v\) whenever the bead is inside the domain.
- \(S_{ij}\)
The share matrix,
share, fromshare_matrix(): the volume of a test bead centered in bin \(i\) that lies in bin \(j\).- \(\phi_i\)
The local volume fraction of bin \(i\),
phi, dimensionless.
The number density#
Counting centers per bin volume,
is number_density(). Summed against the
volumes it returns the number of beads per frame,
\(\sum_i \rho_i V_i = N\), which is the first thing to check on a new profile;
pass n_particles and the function checks that no bead was lost when the
positions were binned. The volumes come from
bin_volumes() in closed form, where the
research code integrated a polynomial numerically:
Scheme |
|
\(V_i\) |
|---|---|---|
spherical shell |
|
\(\tfrac{4\pi}{3}(e_{i+1}^3 - e_i^3)\) |
cylindrical shell |
|
\(\pi L\,(e_{i+1}^2 - e_i^2)\) |
slab |
|
\(\tfrac{\pi}{4} D^2\,(e_{i+1} - e_i)\) |
The volume fraction#
What is being approximated#
The volume fraction field is the indicator of “inside some bead”, \(\Phi(\mathbf r) = \sum_n \Theta(R_b - |\mathbf r - \mathbf r_n|)\). Its exact bin average over one frame needs every bead position,
but the probe keeps only the counts \(H_j\), so the beads of a bin are treated alike: the density is piecewise constant on the bins. In the continuum, \(\phi(\mathbf r) = \int \rho(\mathbf r')\,\Theta(R_b - |\mathbf r - \mathbf r'|)\,d^3r'\), the density convolved with a ball, and with \(\rho\) piecewise constant the value at a point \(x\) is \(\sum_j \rho_j\, s(x \to j)\).
The kernels#
Slabs#
The volume of a bead below the plane at signed height \(u\) from its center
is the spherical segment \(G(u) = \int_{-R_b}^{u} \pi (R_b^2 - t^2)\,dt\)
(MathWorld, “Spherical Segment”, eq. 14, as
spherical_segment() computes it), and the
share of slab \(j\) for a bead at \(x\) is \(G(e_{j+1} - x) - G(e_j - x)\). The
average over the bead’s position is then a second antiderivative,
\(G_2(u) = \int_{-\infty}^{u} G\):
The axial direction of a cylinder is periodic: the slabs at one end are also reached, through their images shifted by the domain length, from the other end, and the same bracket is summed over the images. For a bead of diameter 1 in slabs of width 1 the shares are \(13\pi/96\) into the bead’s own slab and \(\pi/64\) into each neighbor.
Spherical shells#
The volume of a bead centered at distance \(x\) from the origin that lies
inside the ball of radius \(e\) is the sphere-sphere intersection volume
\(W(R_b, e, x)\) (MathWorld, “Sphere-Sphere Intersection”, eq. 16, as
sphere_sphere_intersection() computes it),
and the share of shell \(j\) is \(W(R_b, e_{j+1}, x) - W(R_b, e_j, x)\). In
the lens regime \(x\,W\) is a quartic in \(x\), so the position average with
weight \(4\pi x^2\) is a polynomial on each piece between the breakpoints
\(|e - R_b|\) and \(e + R_b\) of the two edges, and a Gauss-Legendre rule on
each piece integrates it exactly.
Cylindrical shells#
The kernel is the volume \(C(R_b, R, d)\) of a bead whose center is at
perpendicular distance \(d\) from the axis of the coaxial cylinder of radius
\(R\), sphere_cylinder_intersection(). Slicing the
bead by planes normal to the axis, the slice at height \(z\) is a disc of
radius \(\sqrt{R_b^2 - z^2}\) whose center is \(d\) from the axis, the
cylinder cuts the plane in a disc of radius \(R\) about the axis, and the
slice’s share is their lens area (MathWorld, “Circle-Circle Intersection”,
eq. 15):
for \(|R - r| < d < r + R\), with \(A = 0\) when the discs are apart and \(\pi \min(r, R)^2\) when one holds the other. The \(z\)-integral has no closed form; it is a 32-node Gauss-Legendre rule on each of the three pieces between the heights where the lens changes regime, and it agrees with an adaptive quadrature to about \(10^{-8}\) of the bead volume. Two limits are exact: the bead is inside for \(R \ge d + R_b\) and outside for \(R \le d - R_b\); on the axis with \(R < R_b\) the volume is \(\tfrac{4\pi}{3}[R_b^3 - (R_b^2 - R^2)^{3/2}]\).
The research code used the sphere-sphere volume \(W(R_b, R, d)\) in place of
\(C\) “for the sake of simplicity”. That is intersection='sphere', kept for
reproducing its numbers. Its error, as a fraction of the bead volume and at
the worst perpendicular distance from the axis, is about \(0.047\,a / R\),
with \(R\) the edge radius and \(a = 2 R_b\) the bead diameter:
\(R / a\) |
1 |
2 |
5 |
10 |
20 |
40 |
|---|---|---|---|---|---|---|
\(\max_d \lvert W - C \rvert / v\) |
0.0491 |
0.0237 |
0.0094 |
0.0047 |
0.0023 |
0.0012 |
It is first order in \(a / R\) and independent of the bin width, so finer
bins never remove it, and it is largest at the innermost edges, where
sumrule takes the 'first' normalizer of a radial profile. The shares
still telescope to \(v\) over all shells, so the error moves volume between
neighboring shells rather than losing it; but the symmetry
\(V_i S_{ij} = V_j S_{ji}\) needs the true indicator, so with the sphere
kernel the conservation of the averaged form holds only to the same order.
(A planar cut, the “strips” of the maintainer’s 2021 report, errs by the
same amount with the opposite sign; the mean of the two is second order in
\(a / R\), because a cylinder’s mean curvature is half a sphere’s. The exact
kernel costs about a second per space, so neither shortcut is offered.)
Conventions the kernels leave to the caller#
The slab diameter.
bin_volumes()uses the diameter it is given.density_profiles()passes \(D_\mathrm{eff} = D - a\), the diameter of the region a bead center can reach, which is how the parsers define the bulk values, \(\rho_c = N_c / (\pi D_{\mathrm{eff},c}^2 L / 4)\) and \(\phi_c = \rho_c v_c\) (thesis, chapter 3). A uniform crowder fluid then returns \(\phi_c\) exactly, so the scaled profiles ofsumrulecompare with the nominal bulk value. The research code used the full \(D\) for its slabs, so its far-field \(z\) values were \(((D - a)/D)^2\) times the bulk; its published profiles were normalized by their far-field value, which cancels the factor.Half the cube. A spherical shell beyond half the side of a periodic cube overstates the volume inside the box, so the density there is underestimated. Given
lcube,bin_volumeswarns when the outermost edge passes half the side by more than one bin, as MAICoS’sDensitySpheredoes for itsrmax, and computes the volumes regardless.Frames.
n_framesdivides the summed counts, sorhois a per-frame density comparable with \(N / V\); the research code did not divide.Normalization.
normalize='sum'divides by the sum over bins, the research code’snormalized=True;'integral'divides by \(\sum_i p_i V_i\). Profiles that feedpolyphys.analyze.sumrulemust stay unnormalized: its species sum \(\sum_\alpha \phi_\alpha / a_\alpha\) needs each profile’s physical scale, and only its own'first'and'max'normalizations are scale-free.space_profiles()warns, naming the file, when a profile’s-meansums to one, the signature ofnormalize='sum'; it cannot tell'integral'or a hand normalization from one profile, so the rule above is the caller’s contract.
Cost and use#
The share matrix depends on the edges and the bead diameter only. Building
it is \(O(B k)\) kernel evaluations, with \(k \approx a / h + 2\) the band
width (for 300 cylindrical shells with the exact kernel, about a second at
a bin width of \(a/10\) and twice that at \(a/20\), where the band is nearly twice
as wide; for 6000 periodic slabs, milliseconds), and it is returned as a sparse
csr_array of \(O(B k)\) entries. Applying it is one sparse product per
profile. So build it once per space and reuse it for every whole, frame, and
species of the same diameter:
import numpy as np
from polyphys.analyze import density
edges = np.arange(0.0, 15.01, 0.1)
volumes = density.bin_volumes(edges, 'cylindrical', 'r', lcyl=300.0)
share = density.share_matrix(edges, 1.0, 'cylindrical', 'r')
for counts in histograms: # one summed histogram per whole
rho = density.number_density(counts, volumes, n_frames=14001)
phi = density.volume_fraction(rho, share)
Per-frame counts of shape (n_frames, n_bins) go through the same two
calls row by row, which is what a per-bin error estimate at the probe step
will need. density_profiles wraps the four calls for one profile.
In the artifact lineage, rho and phi are whole-level arrays named
<direction>Rho<Species> and <direction>Phi<Species>; the organizer
averages them over replicates into the ensAvg profiles that
space_profiles() reads. The sum rule is
linear in the profiles, so averaging over wholes and summing over species
commute; its normalization is not, and the published estimator normalizes
the ensemble average. The pipeline also divides each whole’s profile by its
own value in the normalizer’s bin and writes the standard error over the
wholes as <prop>-norm-sem in the ensAvg file, which space_profiles
carries through. <prop>-norm-sem is the SEM across profiles normalized
separately for each whole. It is not generally an uncertainty estimate for
the normalized ensemble mean (see “The density sum rule” below).
The density sum rule#
The density sum rule of Jeon et al. (2016, eqns 5 to 7) says that in a
crowded polymer solution the volume fractions of the species, each divided by
its particle diameter, sum to the far-field crowder term:
sum_i phi_i(x) / a_i ~ phi_c(inf) / a_c, or equivalently
sum_i a_i**2 rho_i(x) ~ a_c**2 rho_c(inf) for the number densities. Here
x is r, the distance from the cylinder axis in a cylinder and from the
polymer’s center of mass in a periodic cube, or z, the axial distance from
the center of mass.
space_profiles in polyphys.analyze.sumrule builds one term of the sum from a space of
ensemble-averaged profiles: it scales each Phi profile by 1 / a_i and each
Rho profile by a_i**2, with a_i read from the parser attribute that the
study’s species_sizes names, normalizes the scaled profile by a reference
value, folds a z profile about z = 0, and adds the state point’s
attributes. The profiles must be the raw ensemble averages, in their
physical units: the rule relates the species through their scales, so a
profile normalized beforehand, by its sum, its integral, or its maximum
(the normalize option of polyphys.analyze.density, or by hand), enters
the sum with an arbitrary weight and its -scale column loses its unit.
space_profiles warns, naming the file, when a profile’s -mean sums to
one, the signature of a profile normalized by its sum; it cannot tell the
other normalizations from one profile.
space_profiles_from_spec reads the parser, the hierarchy glob, the
physical_attrs, the species_sizes, the divisor, and the crowder_attr
from the study’s spec, and takes the profiles from the 'all' group unless
group says otherwise. In this recipe, not a doctest, database is the
directory of the space’s ensAvg profile files and chain the study’s
ProjectSpec, built as on the Studies page:
monomers = space_profiles_from_spec(database, chain, 'Phi', 'r', 'Mon')
crowders = space_profiles_from_spec(database, chain, 'Phi', 'r', 'Crd')
space_profiles takes the same values one by one.
The reference value follows the research code unless normalizer says
otherwise: the value at r = 0 for r in a cylinder, where the outermost
bins are the crowder layers on the wall and no far field exists, and the
maximum otherwise (PROFILE_NORMALIZERS). normalizer also takes 'last',
a number, or a function of the scaled frame and the file’s parser instance,
such as lambda df, info: info.phi_bulk_c / info.dcrowd for the nominal bulk
value of a Phi profile. normalize_r and normalize_z are the two steps on
their own. For r in a cylinder, space_profiles also adds the bin center in
crowder radii, recentered so that the wall sits at an integer number of crowder
diameters and the layers of different state points overlay.
sum_rule_profiles adds the species’ scaled profiles state point by state
point and normalizes the sum by its own reference value, so that the sum is
one at the reference and its departure from one measures the rule’s failure:
total = sum_rule_profiles({'Mon': monomers, 'Crd': crowders}, 'rPhi',
chain.geometry, 'r')
The default (SUM_NORMALIZERS) is the value at r = 0 for r in a cylinder
and the far-field value otherwise, where the monomer term vanishes and the sum
is the crowder term, which for several crowders is eqn (7) of Jeon et al.
Under cylindrical confinement the radial rule holds only where the wall
layering is weak, which the ratio kappa = (D - a_c) / a_c controls (Sadeghi
Isfahani, 2024, chapter 3).
The ensAvg file’s -sem is the error of the mean profile, not of the ratio
of a bin to its normalizer. The pipeline (reduce_space with
LocalDensities) also writes <prop>-norm-sem beside the ensAvg columns:
each whole’s profile is divided by its own value in the bin the default
normalizer names, the first, the last, or the bin where the ensemble average
peaks, and the standard error is taken over the wholes, which are
independent runs. <prop>-norm-sem is the SEM across profiles normalized
separately for each whole. It is not generally an uncertainty estimate for
the normalized ensemble mean: normalization is nonlinear, so the mean of the
normalized wholes and the normalized mean differ. The curve itself stays the
normalized ensemble average, the published estimator.
space_profiles carries the column through under the default normalizer,
folding it along z, and drops it with a warning under an explicit one.
sum_rule_profiles adds the species’ columns in quadrature as
<prop>Sum-norm-sem. The quadrature sum assumes that the species’ errors
are independent, although excluded volume correlates the species within a
whole; it refers to the sum of the separately normalized species, and to
Sum-norm only when the species share one normalizer value.
References#
Weisstein, Eric W. “Spherical Segment”, “Sphere-Sphere Intersection”, and “Circle-Circle Intersection”. From MathWorld–A Wolfram Web Resource. https://mathworld.wolfram.com/
A. H. Sadeghi Isfahani, PhD thesis, University of Waterloo (2024), chapter 3 and the appendix “Discrete local distributions in the cylindrical coordinate system”.
C. Jeon, C. Hyeon, Y. Jung, and B.-Y. Ha, “How are molecular crowding and the spatial organization of a biopolymer interrelated”, Soft Matter 12, 9786-9796 (2016). https://doi.org/10.1039/c6sm01924b
MAICoS,
DensitySphere, for the half-box warning. https://maicos-analysis.org/