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#
KeywordSpecandSpecies, the two building blocks of a declaration.ParserBase, the base class every parser derives from.
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#
Python standard library: os, re, collections, dataclasses, decimal, pathlib, typing.
polyphys.manage.utils:invalid_keyword()and the number-density and volume-fraction functions.polyphys.manage.types: domain type aliases such asLineageT.
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
|
How a parser reads the value of one filename keyword. |
|
Base parser class for extracting information from filenames or file paths in a structured project. |
|
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:
objectHow 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:
- Raises:
TypeError – If kind is neither int nor float, or if an int keyword sets scale or offset.
Examples
The keyword
Nis a number of monomers:>>> KeywordSpec('nmon', int).parse('200') 200
The keyword
ris 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
- 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\) gives7.2rather than the binary result7.199999999999999. The cost is \(O(1)\) per value.- Return type:
- 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
- class polyphys.manage.parser.ParserBase(artifact, lineage, group, ispath=False)[source]#
Bases:
objectBase 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
Noneis abstract and cannot be instantiated.from_name()constructs a parser from a name token instead of a path, withfilepathandextset toNone.- Parameters:
artifact (
str|os.PathLike[str]) – The artifact to be parsed: a name, or, withispath=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.PathorNone) – The resolved absolute directory that holds artifact if it is a file path, orNoneif it is a name.filename (
str) – The filename extracted from artifact, or artifact itself.ext (
strorNone) – The file extension, including the leading dot, if artifact is a file path:pathlib.PurePath.suffix, which is''for a file with no extension.Noneif artifact is a name.name (
str) – The lineage name: filename without its extension, cut before.<group>(segmentandwhole) 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 (
listofLineageT) – The artifact’s lineage and its parent lineages.lineage_attributes (
listofstr) – The attributes parsed from name, in pattern order.physical_attributes (
listofstr) – The fixed and computed attributes listed for the artifact’s lineage.attributes (
listofstr) – lineage_attributes followed by physical_attributes.segment (
str) – The artifact’s name at thesegmentlineage if it is in lineage_genealogy, else'N/A'; cut from name, with no topology suffix.whole (
str) – As segment, at thewholelineage.ensemble_long (
str) – As segment, at theensemble_longlineage.ensemble (
str) – The artifact’s name at theensemblelineage 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 thespacelineage.
- Class Attributes:
genealogy (
dictofLineageTtolistofLineageT) – 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 (
listofGroupT) – Allowed particle groups in the system.dump_keywords (
dictofGroupTtostr) – Each group mapped to the attribute that holds the dump period, in time steps, of its trajectory.genealogy_attributes (
dictofLineageTtoOrderedDict) – Each lineage mapped to an OrderedDict of attribute names and their filename keywords, in pattern order; built from _keywords and _patterns.project_attributes (
dictofLineageTtolistofstr) – 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 attributelcube; a cylindrical onelcylanddcyl._topology (
TopologyT) – The polymer topology._dump_keywords (
dictofGroupTtostr) – As dump_keywords above, one entry per group. Each attribute is set atsegment,whole, andensemble_long, by the pattern or by _defaults._keywords (
dictofstrtoKeywordSpec) – Each filename keyword mapped to how its value is read._patterns (
dictofLineageTtotupleofstr) – Each lineage mapped to its keywords in name order._project_attributes (
dictofLineageTtolistofstr) – As project_attributes above._defaults (
dictofstrtofloat, optional) – Attributes set at every lineage before parsing, such as a fixed monomer size._species (
tupleofSpecies, optional) – The species whose bulk values are computed._totals (
dictofstrtotupleofstr, optional) – A suffix mapped to species suffixes;rho_bulk_<suffix>andphi_bulk_<suffix>are the sums of theirs._masses (
dictofstrtostr, 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, andensemble_longlineages, 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
bugandalltrajectories 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)
- 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 (
segmenttospace), and the lineage’s _project_attributes. Atsegment,whole, andensemble_longit also holds the bulk number densityrho_bulk_<suffix>and volume fractionphi_bulk_<suffix>of each species and each total, and the declared masses. An attribute that an override of_derived_attributessets 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:
- 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 atspace:>>> 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
Noneif 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.csvor.h5; otherwise it is''and the part stays inname. A name that ends with a value, such asac1.5, or with a dot, such asac1., 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 filepath: Optional[pathlib.Path]#
Return the resolved absolute directory that holds the artifact, or
Noneif 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
Noneand 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:
- Parameters:
- 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 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.
- 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:
- 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.
- class polyphys.manage.parser.Species(suffix, number, size)[source]#
Bases:
objectA particle species whose bulk number density and volume fraction a parser computes.
At the
segment,whole, andensemble_longlineages, a parser setsrho_bulk_<suffix>, the number of particles of the species per unit volume of the box, andphi_bulk_<suffix>, the fraction of the box volume they fill.- Parameters:
Examples
>>> crowders = Species('c', 'ncrowd', 'dcrowd') >>> crowders.suffix 'c'