Quickstart: a synthetic sweep from segments to a space#
This page runs PolyPhys on a sweep small enough to check by hand: two state
points, two replicates of each, and two segments of each replicate, each
segment a time series of two frames. It writes the probe files itself,
reduces them down the lineage with
reduce_space(), and stacks the result into
a space table with space_tseries(). Every
example on this page runs as a test, so its output is what the code gives.
Notation#
- \(e\), \(w\), \(s\), \(k\)
The indices of a state point, a replicate (a whole), a segment, and a frame within a segment; \(e\), \(w\), and \(s\) start at 1 and \(k\) at 0.
- \(x_{ewsk}\)
The value in frame \(k\) of segment \(s\) of replicate \(w\) of state point \(e\).
- \(R\)
The number of replicates of a state point, here 2.
The Lineage page defines the lineage levels, phases, and stages, and the Workflow page the steps this page runs.
The synthetic sweep#
The values follow the scheme of the test suite’s synthetic lineage trees:
so each value names its file and frame, and every average below can be
written down by hand. The files are named for the ChainCyl parser declared below, a
linear chain of 200 monomers in a cylinder among crowders; the two state
points differ only in the number of crowders, nc1000 and nc2000. Each
segment file is named <whole>.j<NN>.<group>.<property>.npy, in a directory
per whole under the space’s probe directory:
>>> import tempfile
>>> from pathlib import Path
>>> import numpy as np
>>> tmp = tempfile.TemporaryDirectory()
>>> root = Path(tmp.name)
>>> probe = root / 'probes' / 'N200D20ac2-bug-probe'
>>> for e, nc in enumerate((1000, 2000), start=1):
... state = f'N200r10.5lz25.0ac2.0nc{nc}dt0.005bdump2000adump5000'
... for w in (1, 2):
... whole = probe / f'{state}ens{w}'
... whole.mkdir(parents=True)
... for s in (1, 2):
... x = 1000 * e + 100 * w + 10 * s + np.arange(2.0)
... np.save(whole / f'{state}ens{w}.j{s:02d}.bug.gyrTMon.npy', x)
The study’s specs#
A ProjectSpec says which parser reads the
names, which particle group the polymer is, which attributes become columns
of the space table, and the step to which the crowder volume fraction is
rounded. An AnalysisTable says which
properties to reduce: here one time series, gyrTMon, read as segments:
>>> from polyphys.manage.parser import KeywordSpec, ParserBase, Species
>>> long_keys = ('N', 'r', 'lz', 'ac', 'nc', 'dt', 'bdump', 'adump')
>>> bulk = ['dmon', 'phi_bulk_m', 'rho_bulk_m', 'phi_bulk_c', 'rho_bulk_c']
>>> class ChainCyl(ParserBase):
... """A linear chain among crowders in a cylinder, periodic along z."""
... _geometry = 'cylindrical'
... _topology = 'linear'
... _groups = ['bug', 'all']
... _dump_keywords = {'bug': 'bdump', 'all': 'adump'}
... _keywords = {
... 'N': KeywordSpec('nmon', int),
... 'r': KeywordSpec('dcyl', float, scale=2.0, offset=-1.0),
... 'D': KeywordSpec('dcyl', float),
... 'lz': KeywordSpec('lcyl', float, scale=2.0),
... 'ac': KeywordSpec('dcrowd', float),
... 'nc': KeywordSpec('ncrowd', int),
... 'dt': KeywordSpec('dt', float),
... 'bdump': KeywordSpec('bdump', int),
... 'adump': KeywordSpec('adump', int),
... 'ens': KeywordSpec('ensemble_id', int),
... 'j': KeywordSpec('segment_id', int),
... }
... _patterns = {
... 'segment': (*long_keys, 'ens', 'j'),
... 'whole': (*long_keys, 'ens'),
... 'ensemble_long': long_keys,
... 'ensemble': ('N', 'D', 'ac', 'nc'),
... 'space': ('N', 'D', 'ac'),
... }
... _defaults = {'dmon': 1}
... _species = (Species('m', 'nmon', 'dmon'),
... Species('c', 'ncrowd', 'dcrowd'))
... _project_attributes = {
... 'segment': bulk, 'whole': bulk, 'ensemble_long': bulk,
... 'ensemble': ['dmon'], 'space': ['dmon']}
>>> from polyphys.spec import AnalysisTable, ProjectSpec, tseries
>>> spec = ProjectSpec(
... parser=ChainCyl, group='bug', divisor=0.025,
... crowder_attr='phi_bulk_c',
... physical_attrs=('space', 'ensemble_long', 'ncrowd'),
... species_sizes={'Mon': 'dmon', 'Crd': 'dcrowd'},
... tseries_properties=('gyrTMon',))
>>> table = AnalysisTable(group='bug', lineage='segment', stamps=False,
... properties=(tseries('gyrT', 'Mon'),))
The Studies page explains each field.
Down the lineage#
reduce_space() joins the two segments of
each whole into one series of four frames, collects the two wholes of each
state point into an ensemble, and averages each ensemble over its
replicates:
>>> from polyphys.analyze.pipeline import reduce_space
>>> result = reduce_space(probe, spec, table)
>>> state = 'N200r10.5lz25.0ac2.0nc1000dt0.005bdump2000adump5000'
>>> average = result['gyrTMon'][state]
>>> average['gyrTMon-mean'].tolist()
[1160.0, 1161.0, 1170.0, 1171.0]
>>> average['gyrTMon-var'].tolist()
[5000.0, 5000.0, 5000.0, 5000.0]
>>> average['gyrTMon-sem'].tolist()
[50.0, 50.0, 50.0, 50.0]
By hand, for \(e = 1\): whole \(w\) is segment 1 then segment 2, \((1010 + 100w,\ 1011 + 100w,\ 1020 + 100w,\ 1021 + 100w)\). The two wholes differ by 100 in every frame, so their mean is the value at \(w = 1.5\), \(1160, 1161, 1170, 1171\); their sample variance is \((50^2 + 50^2) / (R - 1) = 5000\); and the standard error of the mean is \(\sqrt{5000 / R} = 50\).
reduce_space wrote each level to its stage, in the analysis phase beside
the probes phase:
>>> for stage in sorted((root / 'analysis').iterdir()):
... print(stage.name, len(list(stage.iterdir())))
N200D20ac2-bug-ens 2
N200D20ac2-bug-ensAvg 2
N200D20ac2-bug-wholeSim 4
Four wholes, and two state points at each of the ensemble stages.
The space table#
space_tseries_from_spec() stacks the
ensemble averages of the two state points into one table and adds the time
and the state point’s attributes, with the columns and the rounding step the
spec declares:
>>> from polyphys.analyze.pipeline import space_tseries_from_spec
>>> ens_avg = root / 'analysis' / 'N200D20ac2-bug-ensAvg'
>>> space = space_tseries_from_spec(ens_avg, spec, 'gyrTMon', save=True)
>>> space['ncrowd'].tolist()
[1000, 1000, 1000, 1000, 2000, 2000, 2000, 2000]
>>> space['time'].tolist()
[0.0, 10.0, 20.0, 30.0, 0.0, 10.0, 20.0, 30.0]
>>> space['gyrTMon-mean'].tolist()
[1160.0, 1161.0, 1170.0, 1171.0, 2160.0, 2161.0, 2170.0, 2171.0]
>>> sorted(set(space['phi_bulk_c_round']))
[0.325, 0.65]
>>> sorted(p.name for p in (root / 'analysis').glob('*-space/*'))
['N200D20ac2-bug-gyrTMon-space.csv']
By hand: the bug trajectory is dumped every bdump2000 steps of
dt0.005, so one frame is \(2000 \times 0.005 = 10\) time units. The bulk
crowder volume fraction of the first state point is 0.3292 (the README’s
Quickstart computes it), and of the second, with twice the crowders, twice
that, 0.6584; rounded to the nearest multiple of the spec’s divisor,
0.025, they are 0.325 and 0.65.
>>> tmp.cleanup()
Next#
The Workflow page adds the probe step before and the equilibrium values of the wholes after.
The Statistics page explains why the error of one whole’s time average needs block averaging, where the error across replicates above does not.
The Studies page shows how to declare a study’s own parser and specs.