polyphys.manage.parser#

polyphys.manage.parser#

This parser module turns the name of a simulation artifact into typed attributes. A name such as N200r10.5lz25.0ac2.0nc1000dt0.005bdump2000adump5000ens1 is a run of keyword-value pairs; each project has its own keywords, and each level of the lineage segment, whole, ensemble_long, ensemble, and space uses its own subset of them, in its own order.

A parser class is a declaration. It states the project’s geometry, polymer topology, and particle groups; one KeywordSpec per filename keyword; the keyword pattern of each lineage; fixed values; and the particle species whose bulk number density and volume fraction the parser computes. ParserBase does the parsing, builds the parent lineage names, and computes the bulk values.

Contents#

The module ships no study’s parser: a study declares its own, as the “Studies” page shows.

Changed in version 1.0.0: The parsers of nine studies left this module. TransFociCyl, TransFociCub, HnsCub, and HnsCyl went to the projects/ folder of the PolyPhys repository, which is not installed; those of five unpublished studies were removed. Importing any of the four from here raises ImportError that says where it went.

Changed in version 1.1.0: The four parsers are now in the companion repository polyphys-lab, as polyphys_lab.<study>.parser, and the ImportError points there.

Dependencies#

Examples

>>> from polyphys.tests.synthetic import ChainCyl
>>> artifact = ChainCyl('N200D10.0ac2.0nc0', 'ensemble', 'all')
>>> print(artifact.dcrowd)
2.0
>>> import polyphys.manage.parser as parser
>>> parser.HnsCub
Traceback (most recent call last):
...
ImportError: HnsCub moved out of PolyPhys in 1.0.0, to polyphys_lab.hns_cub...

Notes

The parsed and computed attributes are set on the instance at construction with setattr(), so their names come from the declaration rather than from the class body; ParserBase.attributes lists the ones a given lineage sets.

Classes

KeywordSpec(attr, kind[, scale, offset])

How a parser reads the value of one filename keyword.

ParserBase(artifact, lineage, group[, ispath])

Base parser class for extracting information from filenames or file paths in a structured project.

Species(suffix, number, size)

A particle species whose bulk number density and volume fraction a parser computes.

class polyphys.manage.parser.KeywordSpec(attr, kind, scale=1.0, offset=0.0)[source]#

Bases: object

How a parser reads the value of one filename keyword.

The value \(x\) that follows the keyword in a name is stored in the attribute attr as \(y = s x + c\), with scale \(s\) and offset \(c\); the default \(s = 1\), \(c = 0\) stores the value as written.

Parameters:
  • attr (str) – Name of the parser attribute that stores the value.

  • kind (type[int] | type[float]) – Type of the stored value.

  • scale (float) – Scale \(s\) of the conversion. Only a float keyword may set it.

  • offset (float) – Offset \(c\) of the conversion. Only a float keyword may set it.

Raises:

TypeError – If kind is neither int nor float, or if an int keyword sets scale or offset.

Examples

The keyword N is a number of monomers:

>>> KeywordSpec('nmon', int).parse('200')
200

The keyword r is the radius of the cylinder on which the centers of the wall beads of size 1 lie, so the cylinder size is \(D = 2r - 1\):

>>> spec = KeywordSpec('dcyl', float, scale=2.0, offset=-1.0)
>>> spec.parse('10.5')
20.0
attr: str#
property is_identity: bool#

Whether the conversion stores the value as written.

kind: type[int] | type[float]#
offset: float = 0.0#
parse(token)[source]#

Convert the text that follows a keyword into the stored value.

Parameters:

token (str) – The text between the keyword and the next keyword, such as '10.5' or '1.'.

Returns:

The value as an int for an int keyword, else \(s x + c\). A conversion that is not the identity is done in exact decimal arithmetic on the text of token and of repr() of \(s\) and \(c\), then rounded once to the nearest float, so '4.1' with \(s = 2\), \(c = -1\) gives 7.2 rather than the binary result 7.199999999999999. The cost is \(O(1)\) per value.

Return type:

int | float

Raises:

ValueError – If token is not a number, or if the keyword is an int keyword and token is not a whole number, such as '1.5'.

Examples

>>> KeywordSpec('ncrowd', int).parse('1000.')
1000
>>> KeywordSpec('lcube', float, scale=2.0).parse('25.0')
50.0
>>> KeywordSpec('dcyl', float, scale=2.0, offset=-1.0).parse('4.1')
7.2
scale: float = 1.0#
class polyphys.manage.parser.ParserBase(artifact, lineage, group, ispath=False)[source]#

Bases: object

Base parser class for extracting information from filenames or file paths in a structured project.

A subclass declares a project’s filename grammar and physics through the class attributes listed under “Declaration”; this class parses the name, builds the names of the parent lineages, and computes the bulk number densities and volume fractions. A declaration is checked when the subclass is created; a class whose _patterns is None is abstract and cannot be instantiated. from_name() constructs a parser from a name token instead of a path, with filepath and ext set to None.

Parameters:
  • artifact (str | os.PathLike[str]) – The artifact to be parsed: a name, or, with ispath=True, a relative or absolute file path (string or Path).

  • lineage (typing.Literal['segment', 'whole', 'ensemble_long', 'ensemble', 'space']) – The lineage of the artifact, specifying the hierarchical level within the project. Must be one of: 'segment', 'whole', 'ensemble_long', 'ensemble', or 'space'.

  • group (str) – The particle group the artifact describes; one of the subclass’s groups.

  • ispath (bool) – Whether artifact is a file path. A path is expanded (~ and environment variables) and resolved, and its stem is parsed.

Variables:
  • filepath (pathlib.Path or None) – The resolved absolute directory that holds artifact if it is a file path, or None if it is a name.

  • filename (str) – The filename extracted from artifact, or artifact itself.

  • ext (str or None) – The file extension, including the leading dot, if artifact is a file path: pathlib.PurePath.suffix, which is '' for a file with no extension. None if artifact is a name.

  • name (str) – The lineage name: filename without its extension, cut before .<group> (segment and whole) and before the first hyphen.

  • group (GroupT) – Particle group type in the project.

  • dump_keyword (str) – The attribute that holds the dump period, in time steps, of the group trajectory: dump_keywords[group].

  • lineage (LineageT) – The lineage of the artifact.

  • project_name (str) – The name of the parser subclass.

  • lineage_genealogy (list of LineageT) – The artifact’s lineage and its parent lineages.

  • lineage_attributes (list of str) – The attributes parsed from name, in pattern order.

  • physical_attributes (list of str) – The fixed and computed attributes listed for the artifact’s lineage.

  • attributes (list of str) – lineage_attributes followed by physical_attributes.

  • segment (str) – The artifact’s name at the segment lineage if it is in lineage_genealogy, else 'N/A'; cut from name, with no topology suffix.

  • whole (str) – As segment, at the whole lineage.

  • ensemble_long (str) – As segment, at the ensemble_long lineage.

  • ensemble (str) – The artifact’s name at the ensemble lineage if it is in lineage_genealogy, else 'N/A'; built from the parsed values, so a whole-number float prints without .0.

  • space (str) – As ensemble, at the space lineage.

Class Attributes:
  • lineages (list of LineageT) – List of valid lineage types.

  • genealogy (dict of LineageT to list of LineageT) – Each lineage mapped to itself and its parent lineages.

  • geometry (GeometryT) – Specifies the geometry of the system.

  • topology (TopologyT) – Specifies how particles are connected (or not) in the system.

  • groups (list of GroupT) – Allowed particle groups in the system.

  • dump_keywords (dict of GroupT to str) – Each group mapped to the attribute that holds the dump period, in time steps, of its trajectory.

  • genealogy_attributes (dict of LineageT to OrderedDict) – Each lineage mapped to an OrderedDict of attribute names and their filename keywords, in pattern order; built from _keywords and _patterns.

  • project_attributes (dict of LineageT to list of str) – Each lineage mapped to the attributes that are fixed or computed rather than parsed.

Declaration:
  • _geometry (GeometryT) – 'cubic' or 'cylindrical'. A cubic project with species declares the attribute lcube; a cylindrical one lcyl and dcyl.

  • _topology (TopologyT) – The polymer topology.

  • _groups (list of GroupT) – The particle groups.

  • _dump_keywords (dict of GroupT to str) – As dump_keywords above, one entry per group. Each attribute is set at segment, whole, and ensemble_long, by the pattern or by _defaults.

  • _keywords (dict of str to KeywordSpec) – Each filename keyword mapped to how its value is read.

  • _patterns (dict of LineageT to tuple of str) – Each lineage mapped to its keywords in name order.

  • _project_attributes (dict of LineageT to list of str) – As project_attributes above.

  • _defaults (dict of str to float, optional) – Attributes set at every lineage before parsing, such as a fixed monomer size.

  • _species (tuple of Species, optional) – The species whose bulk values are computed.

  • _totals (dict of str to tuple of str, optional) – A suffix mapped to species suffixes; rho_bulk_<suffix> and phi_bulk_<suffix> are the sums of theirs.

  • _masses (dict of str to str, optional) – A mass attribute mapped to a size attribute; the mass is the size cubed, \(m = d^3\), for a uniform mass density.

Raises:
  • TypeError – On instantiation of a class with no _patterns, such as ParserBase itself; on creation of a subclass whose declaration is incomplete or inconsistent.

  • ValueError – If artifact is empty; if lineage or group is not valid; if name lacks a keyword of the lineage’s pattern; or if a keyword’s value is not a number, or not a whole number for an int keyword.

Notes

Parsing splits name once into keyword-value pairs and keeps the first value of each keyword, so a name may carry keywords the pattern does not use. For a name of length \(L\) and a pattern of \(k\) keywords, parsing costs \(O(L + k)\) time and \(O(L)\) memory.

The bulk values are computed only at the segment, whole, and ensemble_long lineages, whose names carry the box size.

A value that is a function of parsed values but fits none of the tables above, such as a complementary percentage, is set by overriding _derived_attributes, which runs at every lineage after the bulk values.

Examples

A parser for a hypothetical study of a linear chain among crowders in a periodic cube, whose bug and all trajectories are dumped every 1000 and 5000 time steps:

>>> class ChainCub(ParserBase):
...     _geometry = 'cubic'
...     _topology = 'linear'
...     _groups = ['bug', 'all']
...     _dump_keywords = {'bug': 'bdump', 'all': 'adump'}
...     _keywords = {
...         'N': KeywordSpec('nmon', int),
...         'ac': KeywordSpec('dcrowd', float),
...         'nc': KeywordSpec('ncrowd', int),
...         'l': KeywordSpec('lcube', float, scale=2.0),
...         'ens': KeywordSpec('ensemble_id', int),
...         'j': KeywordSpec('segment_id', int),
...     }
...     _patterns = {
...         'segment': ('N', 'ac', 'nc', 'l', 'ens', 'j'),
...         'whole': ('N', 'ac', 'nc', 'l', 'ens'),
...         'ensemble_long': ('N', 'ac', 'nc', 'l'),
...         'ensemble': ('N', 'ac', 'nc'),
...         'space': ('N', 'ac'),
...     }
...     _defaults = {'dmon': 1.0, 'bdump': 1000, 'adump': 5000}
...     _species = (Species('m', 'nmon', 'dmon'),
...                 Species('c', 'ncrowd', 'dcrowd'))
...     _project_attributes = {
...         'segment': ['dmon', 'phi_bulk_m', 'rho_bulk_m',
...                     'phi_bulk_c', 'rho_bulk_c'],
...         'whole': ['dmon', 'phi_bulk_m', 'rho_bulk_m',
...                   'phi_bulk_c', 'rho_bulk_c'],
...         'ensemble_long': ['dmon', 'phi_bulk_m', 'rho_bulk_m',
...                           'phi_bulk_c', 'rho_bulk_c'],
...         'ensemble': ['dmon'],
...         'space': ['dmon'],
...     }
>>> artifact = ChainCub('N100ac2.0nc50l10.0ens1.bug', 'whole', 'bug')
>>> artifact.lcube
20.0
>>> artifact.ensemble_long, artifact.ensemble, artifact.space
('N100ac2.0nc50l10.0', 'N100ac2nc50', 'N100ac2')
>>> artifact.filepath is None, artifact.ext is None
(True, True)
>>> artifact.dump_keyword, getattr(artifact, artifact.dump_keyword)
('bdump', 1000)
__str__()[source]#

Provide a formatted summary of the parser instance.

Return type:

str

property attributes: list[str]#

Return lineage-specific and project attributes for an artifact.

classmethod attributes_at(lineage)[source]#

Return the names of the attributes that a parser of lineage sets.

The set holds the attributes parsed from the lineage’s pattern, the _defaults, the five lineage names (segment to space), and the lineage’s _project_attributes. At segment, whole, and ensemble_long it also holds the bulk number density rho_bulk_<suffix> and volume fraction phi_bulk_<suffix> of each species and each total, and the declared masses. An attribute that an override of _derived_attributes sets counts only if _project_attributes lists it.

The set is built from the declaration, without parsing a name; the cost is \(O(k + n)\) for a pattern of \(k\) keywords and \(n\) declared defaults, species, totals, masses, and project attributes.

Parameters:

lineage (typing.Literal['segment', 'whole', 'ensemble_long', 'ensemble', 'space']) – One of 'segment', 'whole', 'ensemble_long', 'ensemble', or 'space'.

Returns:

The attribute names.

Return type:

frozenset[str]

Raises:
  • TypeError – If the class declares no patterns, such as ParserBase itself.

  • ValueError – If lineage is not a valid lineage.

Examples

The bulk values exist at ensemble_long, not at space:

>>> from polyphys.tests.synthetic import ChainCyl
>>> 'phi_bulk_c' in ChainCyl.attributes_at('ensemble_long')
True
>>> 'phi_bulk_c' in ChainCyl.attributes_at('space')
False
property dump_keyword: str#

The attribute that holds the dump period, in time steps, of the group trajectory.

property dump_keywords: dict[str, str]#

Each group mapped to the attribute that holds the dump period, in time steps, of its trajectory.

property ext: Optional[str]#

Return the file extension, including the leading dot, or None if the parser was built from a name.

The extension is pathlib.PurePath.suffix, the part from the last dot, when that part holds a letter, such as .csv or .h5; otherwise it is '' and the part stays in name. A name that ends with a value, such as ac1.5, or with a dot, such as ac1., so keeps its last value whatever the Python version.

Examples

>>> from polyphys.tests.synthetic import ChainCyl
>>> import tempfile
>>> with tempfile.TemporaryDirectory() as folder:
...     path = Path(folder, 'N200D10ac2')
...     path.touch()
...     ChainCyl(path, 'space', 'bug', ispath=True).ext
''
>>> with tempfile.TemporaryDirectory() as folder:
...     path = Path(folder, 'N200D10ac1.5')
...     path.touch()
...     parser = ChainCyl(path, 'space', 'bug', ispath=True)
...     parser.ext, parser.dcrowd
('', 1.5)
>>> ChainCyl('N200D10.0ac2.0', 'space', 'bug').ext is None
True
property filename: str#

Return the filename, either extracted from the path or the name itself.

property filepath: Optional[pathlib.Path]#

Return the resolved absolute directory that holds the artifact, or None if the parser was built from a name.

Examples

>>> from polyphys.tests.synthetic import ChainCyl
>>> import tempfile
>>> with tempfile.TemporaryDirectory() as folder:
...     path = Path(folder, 'N200D10.0ac2.0.csv')
...     path.touch()
...     parser = ChainCyl(path, 'space', 'bug', ispath=True)
...     parser.filepath == Path(folder).resolve()
True
>>> ChainCyl('N200D10.0ac2.0', 'space', 'bug').filepath is None
True
classmethod from_name(name, lineage, group)[source]#

Construct a parser from a name token (not a path).

Sets filepath and ext to None and keeps the token as both filename and name before _find_name() normalization.

Examples

>>> from polyphys.tests.synthetic import ChainCyl
>>> parser = ChainCyl.from_name('N200D10.0ac2.0', 'space', 'bug')
>>> parser.filepath is None, parser.ext is None
(True, True)
Return type:

typing.Self

Parameters:
  • name (str)

  • lineage (Literal['segment', 'whole', 'ensemble_long', 'ensemble', 'space'])

  • group (str)

property genealogy: dict[Literal['segment', 'whole', 'ensemble_long', 'ensemble', 'space'], list[Literal['segment', 'whole', 'ensemble_long', 'ensemble', 'space']]]#

Dictionary of lineages and their parent lineages.

property genealogy_attributes: dict[Literal['segment', 'whole', 'ensemble_long', 'ensemble', 'space'], collections.OrderedDict[str, str]]#

Dictionary of lineage-specific attributes. Each key is a lineage type, and each value is an OrderedDict mapping attribute names to their filename keywords, in pattern order.

property geometry: Literal['cubic', 'cylindrical']#

System geometry in a molecular dynamics system.

property group: str#

Return the current group.

property groups: list[str]#

List of valid group names for the subclass.

property ispath: bool#

Return whether the artifact was parsed as a filesystem path.

property lineage: Literal['segment', 'whole', 'ensemble_long', 'ensemble', 'space']#

Return the current lineage.

property lineage_attributes: list[str]#

Return lineage-specific attributes for an artifact with a given lineage.

property lineage_genealogy: list[Literal['segment', 'whole', 'ensemble_long', 'ensemble', 'space']]#

Return the parents of a given lineage.

property lineages: list[Literal['segment', 'whole', 'ensemble_long', 'ensemble', 'space']]#

List of all the acceptable lineages.

property name: str#

Return the unique name parsed from the filename.

classmethod pattern(lineage)[source]#

Return the filename keywords of lineage, in name order.

Parameters:

lineage (typing.Literal['segment', 'whole', 'ensemble_long', 'ensemble', 'space']) – One of 'segment', 'whole', 'ensemble_long', 'ensemble', or 'space'.

Returns:

The keywords, such as 'N' or 'ac', that a name of lineage carries, in the order they appear in it.

Return type:

tuple[str, ...]

Raises:
  • TypeError – If the class declares no patterns, such as ParserBase itself.

  • ValueError – If lineage is not a valid lineage.

Examples

>>> from polyphys.tests.synthetic import ChainCyl
>>> ChainCyl.pattern('space')
('N', 'D', 'ac')
property physical_attributes: list[str]#

Return project-level attributes for an artifact with a given lineage.

property project_attributes: dict[Literal['segment', 'whole', 'ensemble_long', 'ensemble', 'space'], list[str]]#

Dictionary of project attributes. Each key is a lineage type, and each value is the list of attributes that are fixed or computed rather than parsed at that lineage.

property project_name: str#

Return the project (parser class) name,

property topology: str#

Define the polymer topology for the parser subclass.

class polyphys.manage.parser.Species(suffix, number, size)[source]#

Bases: object

A particle species whose bulk number density and volume fraction a parser computes.

At the segment, whole, and ensemble_long lineages, a parser sets rho_bulk_<suffix>, the number of particles of the species per unit volume of the box, and phi_bulk_<suffix>, the fraction of the box volume they fill.

Parameters:
  • suffix (str) – Suffix of the two attribute names, such as 'm' for monomers or 'c' for crowders.

  • number (str) – Name of the attribute that holds the number of particles.

  • size (str) – Name of the attribute that holds the particle diameter.

Examples

>>> crowders = Species('c', 'ncrowd', 'dcrowd')
>>> crowders.suffix
'c'
number: str#
size: str#
suffix: str#