Usage#

This page says where each task is explained. Install PolyPhys first, as Installation shows; the quickstart then runs one complete synthetic sweep, from the files of its segments to its space table.

Tasks#

To

Read

Install PolyPhys, with pip, uv, or conda, or from a source checkout

Installation

Run one sweep from its segments to its space table

Quickstart

Decode a file name into its physical attributes and lineage names

Lineage

Go from trajectories to a space table, step by step

Workflow

Declare a study: its parser, its ProjectSpec, and its ProbeSpec

Studies

Measure chain sizes, spatial histograms, pair distances, or binders from trajectories

Probe

Reduce a space’s probe artifacts down the lineage

Pipeline

Estimate the error of a time average over correlated frames

Statistics

Count contacts, clusters, and binding modes

Clusters

Compute autocorrelations, decay fits, and persistence lengths

Correlations

Turn histograms into density profiles, and check the density sum rule

Density

Read LAMMPS logs, dumps, and data files, or build a start configuration

Simulate

Color a figure the way the studies’ figures are colored

Viz

The API reference documents every public name; the README introduces the artifact-lineage model.

Measures of one frame#

polyphys.analyze.measurer holds the small functions the probes and the analysis build on, each on the positions or values it is given. The API reference documents each one; this table says which to reach for:

Kind

Functions

Chain size, on one frame’s positions

end_to_end(), transverse_size(), fsd(), max_distance()

Distances under periodic boundaries

apply_pbc_orthogonal(), pair_distance()

Bins

fixedsize_bins(), create_bin_edge_and_hist()

Histograms of one frame

radial_histogram() (spherical \(r\)), radial_cyl_histogram() (cylindrical \(r\)), axial_histogram(), azimuth_cyl_histogram(), planar_cartesian_histogram()

Volumes of a bead cut by planes or a sphere

spherical_segment(), sphere_sphere_intersection()

Statistics of independent samples

simple_stats(), sem()

simple_stats and sem treat their samples as independent, as the replicates of a state point are; for the correlated frames of one run, use the blocked error of polyphys.analyze.stats, as the Statistics page explains.

For example, the end-to-end distance and the span along z of three beads:

>>> import numpy as np
>>> from polyphys.analyze import measurer
>>> positions = np.array([[0.0, 0.0, 0.0], [3.0, 4.0, 0.0], [3.0, 4.0, 12.0]])
>>> float(measurer.end_to_end(positions))
13.0
>>> float(measurer.fsd(positions, 2))
12.0

The density sum rule, in brief#

space_profiles() scales each species’ ensemble-averaged profile by its size and normalizes it, giving one row per bin and state point with the columns <prop>-scale, <prop>-normalizer, <prop>-norm, and, under the default normalizer, <prop>-norm-sem; sum_rule_profiles() sums the species into <prop>Sum-norm. The inputs must be raw ensemble averages, and <prop>-norm-sem is not generally an uncertainty estimate for the normalized ensemble mean. The Density page, “The density sum rule”, gives the rule, the normalizers, and the error columns.