Source code for polyphys.manage.parser

"""\
==========================================================
:mod:`polyphys.manage.parser`
==========================================================

This :mod:`~polyphys.manage.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 :class:`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.
:class:`ParserBase` does the parsing, builds the parent lineage names, and
computes the bulk values.

Contents
========

- :class:`KeywordSpec` and :class:`Species`, the two building blocks of a
  declaration.
- :class:`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.

.. versionchanged:: 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 :exc:`ImportError` that says where it went.

.. versionchanged:: 1.1.0
   The four parsers are now in the companion repository
   `polyphys-lab <https://github.com/amirhs1/polyphys-lab>`_, as
   ``polyphys_lab.<study>.parser``, and the :exc:`ImportError` points
   there.

Dependencies
============
- Python standard library: `os`, `re`, `collections`, `dataclasses`,
  `decimal`, `pathlib`, `typing`.
- :mod:`polyphys.manage.utils`: :func:`~polyphys.manage.utils.invalid_keyword`
  and the number-density and volume-fraction functions.
- :mod:`polyphys.manage.types`: domain type aliases such as
  :py:obj:`~.LineageT`.

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  # doctest: +ELLIPSIS
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 :func:`setattr`, so their names come from the declaration rather than
from the class body; :attr:`ParserBase.attributes` lists the ones a given
lineage sets.
"""
import os
import re
from collections import OrderedDict
from dataclasses import dataclass
from decimal import Context, Decimal
from pathlib import Path
from typing import ClassVar, Optional, Self
from .utils import (
    invalid_keyword,
    number_density_cube,
    number_density_cylinder,
    volume_fraction_cube,
    volume_fraction_cylinder
)
from .types import LineageT, TopologyT, GroupT, GeometryT, Pathish

__all__ = [
    'KeywordSpec',
    'ParserBase',
    'Species',
]

# The parsers of the published studies that left this module in 1.0.0,
# each with its package in polyphys-lab, polyphys_lab.<folder>.
_LAB_URL = 'https://github.com/amirhs1/polyphys-lab'
_MOVED_STUDIES: dict[str, str] = {
    'HnsCub': 'hns_cub',
    'HnsCyl': 'hns_cyl',
    'TransFociCub': 'trans_foci_cub',
    'TransFociCyl': 'trans_foci_cyl',
}

# A keyword is a run of letters (or hyphens); its value is the text up to the
# next keyword.
_TOKEN_RE = re.compile(r"([a-zA-Z\-]+)")

# A file extension, as ``ispath=True`` strips it: a dot and a run of letters
# and digits with at least one letter, such as ``.csv`` or ``.h5``, so that the
# fractional part of a trailing value, such as ``.5`` in ``ac1.5``, stays in
# the name.
_EXTENSION_RE = re.compile(r"\.[a-zA-Z0-9]*[a-zA-Z][a-zA-Z0-9]*")

# The exact decimal arithmetic of a keyword conversion; 50 digits hold the
# product of any filename value with a scale and an offset without rounding.
_DECIMAL_CONTEXT = Context(prec=50)

# The lineages whose names carry the box size, and so the bulk values.
_BULK_LINEAGES: tuple[LineageT, ...] = ('segment', 'whole', 'ensemble_long')

# The attributes that size the simulation box in each geometry.
_BOX_ATTRIBUTES: dict[GeometryT, tuple[str, ...]] = {
    'cubic': ('lcube',),
    'cylindrical': ('lcyl', 'dcyl'),
}


def _format_value(value: int | float) -> str:
    """
    Return the text of a keyword value in a short lineage name.

    A float that is a whole number prints as an integer; any other float
    prints as :func:`repr`, Python's shortest form that reads back as the
    same float, so two different values never print alike. An `int` prints
    unchanged. The cost is :math:`O(1)` per value.

    Parameters
    ----------
    value : int or float
        A parsed keyword value.

    Returns
    -------
    str
        The value as it appears after its keyword in an ``ensemble`` or
        ``space`` name.

    Examples
    --------
    >>> _format_value(2.0), _format_value(0.0), _format_value(40.0)
    ('2', '0', '40')
    >>> _format_value(1.5), _format_value(1.000001), _format_value(200)
    ('1.5', '1.000001', '200')
    """
    if isinstance(value, float) and value.is_integer():
        return str(int(value))
    return repr(value)


[docs] @dataclass(frozen=True) class KeywordSpec: """ How a parser reads the value of one filename keyword. The value :math:`x` that follows the keyword in a name is stored in the attribute `attr` as :math:`y = s x + c`, with scale :math:`s` and offset :math:`c`; the default :math:`s = 1`, :math:`c = 0` stores the value as written. Parameters ---------- attr : str Name of the parser attribute that stores the value. kind : {int, float} Type of the stored value. scale : float, default 1.0 Scale :math:`s` of the conversion. Only a `float` keyword may set it. offset : float, default 0.0 Offset :math:`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 :math:`D = 2r - 1`: >>> spec = KeywordSpec('dcyl', float, scale=2.0, offset=-1.0) >>> spec.parse('10.5') 20.0 """ attr: str kind: type[int] | type[float] scale: float = 1.0 offset: float = 0.0 def __post_init__(self) -> None: if self.kind not in (int, float): raise TypeError( f"KeywordSpec {self.attr!r}: 'kind' must be int or float, " f"not {self.kind!r}.") if self.kind is int and not self.is_identity: raise TypeError( f"KeywordSpec {self.attr!r}: only a float keyword can have a " "'scale' or an 'offset'.") @property def is_identity(self) -> bool: """ Whether the conversion stores the value as written. """ return self.scale == 1.0 and self.offset == 0.0
[docs] def parse(self, token: str) -> int | float: """ 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 ------- int or float The value as an `int` for an `int` keyword, else :math:`s x + c`. A conversion that is not the identity is done in exact decimal arithmetic on the text of `token` and of :func:`repr` of :math:`s` and :math:`c`, then rounded once to the nearest float, so ``'4.1'`` with :math:`s = 2`, :math:`c = -1` gives ``7.2`` rather than the binary result ``7.199999999999999``. The cost is :math:`O(1)` per value. 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 """ try: value = float(token) except ValueError: raise ValueError(f"{token!r} is not a number") from None if self.kind is int: if not value.is_integer(): raise ValueError(f"{token!r} is not an integer") return int(value) if self.is_identity: return value context = _DECIMAL_CONTEXT exact = context.add( context.multiply(Decimal(token), Decimal(repr(self.scale))), Decimal(repr(self.offset))) return float(exact)
[docs] @dataclass(frozen=True) class Species: """ 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' """ suffix: str number: str size: str
[docs] class ParserBase: """ 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. :meth:`from_name` constructs a parser from a name token instead of a path, with ``filepath`` and ``ext`` set to ``None``. Parameters ---------- artifact : Pathish The artifact to be parsed: a name, or, with ``ispath=True``, a relative or absolute file path (string or Path). lineage : :py:obj:`~.LineageT` The lineage of the artifact, specifying the hierarchical level within the project. Must be one of: ``'segment'``, ``'whole'``, ``'ensemble_long'``, ``'ensemble'``, or ``'space'``. group : :py:obj:`~.GroupT` The particle group the artifact describes; one of the subclass's `groups`. ispath : bool, default False Whether `artifact` is a file path. A path is expanded (``~`` and environment variables) and resolved, and its stem is parsed. Attributes ---------- 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: :attr:`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 : :py:obj:`~.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 : :py:obj:`~.LineageT` The lineage of the artifact. project_name : str The name of the parser subclass. lineage_genealogy : list of :py:obj:`~.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 :py:obj:`~.LineageT` List of valid lineage types. genealogy : dict of :py:obj:`~.LineageT` to list of :py:obj:`~.LineageT` Each lineage mapped to itself and its parent lineages. geometry : :py:obj:`~.GeometryT` Specifies the geometry of the system. topology : :py:obj:`~.TopologyT` Specifies how particles are connected (or not) in the system. groups : list of :py:obj:`~.GroupT` Allowed particle groups in the system. dump_keywords : dict of :py:obj:`~.GroupT` to str Each group mapped to the attribute that holds the dump period, in time steps, of its trajectory. genealogy_attributes : dict of :py:obj:`~.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 :py:obj:`~.LineageT` to list of str Each lineage mapped to the attributes that are fixed or computed rather than parsed. Declaration ----------- _geometry : :py:obj:`~.GeometryT` ``'cubic'`` or ``'cylindrical'``. A cubic project with species declares the attribute ``lcube``; a cylindrical one ``lcyl`` and ``dcyl``. _topology : :py:obj:`~.TopologyT` The polymer topology. _groups : list of :py:obj:`~.GroupT` The particle groups. _dump_keywords : dict of :py:obj:`~.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 :class:`KeywordSpec` Each filename keyword mapped to how its value is read. _patterns : dict of :py:obj:`~.LineageT` to tuple of str Each lineage mapped to its keywords in name order. _project_attributes : dict of :py:obj:`~.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 :class:`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, :math:`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 :math:`L` and a pattern of :math:`k` keywords, parsing costs :math:`O(L + k)` time and :math:`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) """ _lineages: ClassVar[list[LineageT]] = \ ['segment', 'whole', 'ensemble_long', 'ensemble', 'space'] _genealogy: ClassVar[dict[LineageT, list[LineageT]]] = { 'segment': ['segment', 'whole', 'ensemble_long', 'ensemble', 'space'], 'whole': ['whole', 'ensemble_long', 'ensemble', 'space'], 'ensemble_long': ['ensemble_long', 'ensemble', 'space'], 'ensemble': ['ensemble', 'space'], 'space': ['space'], } # Every concrete subclass sets these; __init_subclass__ checks them. _geometry: ClassVar[GeometryT] _topology: ClassVar[TopologyT] _groups: ClassVar[list[GroupT]] _dump_keywords: ClassVar[dict[GroupT, str]] _keywords: ClassVar[Optional[dict[str, KeywordSpec]]] = None _patterns: ClassVar[Optional[dict[LineageT, tuple[str, ...]]]] = None _defaults: ClassVar[dict[str, float]] = {} _species: ClassVar[tuple[Species, ...]] = () _totals: ClassVar[dict[str, tuple[str, ...]]] = {} _masses: ClassVar[dict[str, str]] = {} _genealogy_attributes: ClassVar[dict[LineageT, OrderedDict[str, str]]] _project_attributes: ClassVar[dict[LineageT, list[str]]] def __init_subclass__(cls) -> None: super().__init_subclass__() if cls._patterns is None: return keywords, patterns = cls._check_declaration() cls._genealogy_attributes = { lineage: OrderedDict( (keywords[keyword].attr, keyword) for keyword in patterns[lineage]) for lineage in cls._lineages } @classmethod def _check_declaration( cls ) -> tuple[dict[str, KeywordSpec], dict[LineageT, tuple[str, ...]]]: """ Check a subclass's declaration and return its keyword and pattern tables. Returns ------- tuple of (dict, dict) `_keywords` and `_patterns`. Raises ------ TypeError If a required class attribute is unset; if a lineage has no pattern or no project attributes; if a group has no dump keyword, or a dump keyword names no group; if a pattern keyword has no :class:`KeywordSpec`; if an attribute appears twice in one pattern; if the bulk recipe or a dump keyword reads an attribute a ``segment``, ``whole``, or ``ensemble_long`` name does not set; or if a total names an undeclared species. """ name = cls.__name__ keywords = cls._keywords patterns = cls._patterns geometry: Optional[GeometryT] = getattr(cls, '_geometry', None) if (geometry is None or getattr(cls, '_topology', None) is None or getattr(cls, '_groups', None) is None or getattr(cls, '_dump_keywords', None) is None or keywords is None or patterns is None or getattr(cls, '_project_attributes', None) is None): raise TypeError( f"{name} must declare '_geometry', '_topology', '_groups', " "'_dump_keywords', '_keywords', '_patterns', and " "'_project_attributes'.") for table in ('_patterns', '_project_attributes'): if set(getattr(cls, table)) != set(cls._lineages): raise TypeError( f"{name}.{table} must have one entry per lineage: " f"{cls._lineages}.") if set(cls._dump_keywords) != set(cls._groups): raise TypeError( f"{name}._dump_keywords must have one entry per group: " f"{cls._groups}.") for lineage, pattern in patterns.items(): for keyword in pattern: if keyword not in keywords: raise TypeError( f"{name}: keyword {keyword!r} in the {lineage!r} " "pattern has no KeywordSpec.") attrs = [keywords[keyword].attr for keyword in pattern] for attr in attrs: if attrs.count(attr) > 1: raise TypeError( f"{name}: attribute {attr!r} appears more than once " f"in the {lineage!r} pattern.") suffixes = {species.suffix for species in cls._species} for total, parts in cls._totals.items(): for part in parts: if part not in suffixes: raise TypeError( f"{name}: total {total!r} sums {part!r}, which is " "not a declared species.") needed: list[str] = list(cls._masses.values()) if cls._species: needed.extend(_BOX_ATTRIBUTES[geometry]) for species in cls._species: needed.extend((species.number, species.size)) for lineage in _BULK_LINEAGES: available = set(cls._defaults).union( keywords[keyword].attr for keyword in patterns[lineage]) for attr in needed: if attr not in available: raise TypeError( f"{name}: the bulk values need {attr!r}, which the " f"{lineage!r} pattern does not set.") for group, attr in cls._dump_keywords.items(): if attr not in available: raise TypeError( f"{name}: the dump keyword {attr!r} of group " f"{group!r} is not set by the {lineage!r} pattern " "or '_defaults'.") return keywords, patterns def __init__( self, artifact: Pathish, lineage: LineageT, group: GroupT, ispath: bool = False ) -> None: if self._patterns is None: raise TypeError( f"{type(self).__name__} declares no lineage patterns; " "instantiate a subclass that declares a study.") artifact_str = os.fspath(artifact) if artifact_str == '': raise ValueError("'artifact' cannot be an empty string.") invalid_keyword(lineage, self.lineages) invalid_keyword(group, self.groups) self._ispath = ispath if ispath: # Normalize: expand env/~ and convert to absolute path p = Path( os.path.expandvars(os.path.expanduser(artifact_str)) ).resolve() self._filepath: Optional[Path] = p.parent self._filename: str = p.name ext = p.suffix if _EXTENSION_RE.fullmatch(p.suffix) else '' self._name: str = p.name[:len(p.name) - len(ext)] self._ext: Optional[str] = ext else: self._filepath = None self._filename = artifact_str self._name = artifact_str self._ext = None self._project_name = self.__class__.__name__ self._lineage: LineageT = lineage self._group: GroupT = group # Update the self._name by dropping 'group' and/or any other extra # beyond the template defined above. self._find_name() self._lineage_genealogy: list[LineageT] = self._genealogy[lineage] self._lineage_attributes = \ list(self.genealogy_attributes[lineage].keys()) self._physical_attributes = self.project_attributes[lineage] self._attributes = \ self._lineage_attributes + self._physical_attributes self._set_defaults() self._parse_name() self._set_parents() if self.lineage in _BULK_LINEAGES: self._dependent_attributes() self._derived_attributes()
[docs] def __str__(self) -> str: """ Provide a formatted summary of the parser instance. """ observation = ( f"Artifact:\n" f" Name: '{self.filename}',\n" f" Geometry: '{self.geometry}',\n" f" Group: '{self.group}',\n" f" Lineage: '{self.lineage}',\n" f" Topology: '{self.topology}',\n" f" Project: '{self.project_name}'" ) return observation
def __repr__(self) -> str: return ( f"Artifact(filename='{self.filename}', " f"geometry='{self.geometry}', " f"group='{self.group}', lineage='{self.lineage}', " f"topology='{self.topology}', project='{self.project_name}')" )
[docs] @classmethod def from_name( cls, name: str, lineage: LineageT, group: GroupT ) -> Self: """ 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 cls(name, lineage, group, ispath=False)
[docs] @classmethod def pattern(cls, lineage: LineageT) -> tuple[str, ...]: """ Return the filename keywords of `lineage`, in name order. Parameters ---------- lineage : :py:obj:`~.LineageT` One of ``'segment'``, ``'whole'``, ``'ensemble_long'``, ``'ensemble'``, or ``'space'``. Returns ------- tuple of str The keywords, such as ``'N'`` or ``'ac'``, that a name of `lineage` carries, in the order they appear in it. 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') """ patterns = cls._declared_patterns() invalid_keyword(lineage, cls._lineages) return patterns[lineage]
[docs] @classmethod def attributes_at(cls, lineage: LineageT) -> frozenset[str]: """ 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 :math:`O(k + n)` for a pattern of :math:`k` keywords and :math:`n` declared defaults, species, totals, masses, and project attributes. Parameters ---------- lineage : :py:obj:`~.LineageT` One of ``'segment'``, ``'whole'``, ``'ensemble_long'``, ``'ensemble'``, or ``'space'``. Returns ------- frozenset of str The attribute names. 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 """ cls._declared_patterns() invalid_keyword(lineage, cls._lineages) names = set(cls._genealogy_attributes[lineage]) names.update(cls._defaults, cls._lineages, cls._project_attributes[lineage]) if lineage in _BULK_LINEAGES: suffixes = [species.suffix for species in cls._species] suffixes.extend(cls._totals) for suffix in suffixes: names.update((f"rho_bulk_{suffix}", f"phi_bulk_{suffix}")) names.update(cls._masses) return frozenset(names)
@classmethod def _declared_patterns(cls) -> dict[LineageT, tuple[str, ...]]: """ Return `_patterns`, or raise `TypeError` if the class declares none. """ if cls._patterns is None: raise TypeError( f"{cls.__name__} declares no lineage patterns; use a " "subclass that declares a study.") return cls._patterns @property def lineages(self) -> list[LineageT]: """ List of all the acceptable lineages. """ return self._lineages @property def genealogy(self) -> dict[LineageT, list[LineageT]]: """ Dictionary of lineages and their parent lineages. """ return self._genealogy @property def geometry(self) -> GeometryT: """ System geometry in a molecular dynamics system. """ return self._geometry @property def groups(self) -> list[GroupT]: """ List of valid group names for the subclass. """ return self._groups @property def dump_keywords(self) -> dict[GroupT, str]: """ Each group mapped to the attribute that holds the dump period, in time steps, of its trajectory. """ return self._dump_keywords @property def topology(self) -> TopologyT: """ Define the polymer topology for the parser subclass. """ return self._topology @property def genealogy_attributes(self) -> dict[LineageT, 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. """ return self._genealogy_attributes @property def project_attributes(self) -> dict[LineageT, 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. """ return self._project_attributes @property def filename(self) -> str: """ Return the filename, either extracted from the path or the name itself. """ return self._filename @property def filepath(self) -> Optional[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 """ return self._filepath @property def ispath(self) -> bool: """ Return whether the artifact was parsed as a filesystem path. """ return self._ispath @property def group(self) -> GroupT: """ Return the current group. """ return self._group @property def dump_keyword(self) -> str: """ The attribute that holds the dump period, in time steps, of the `group` trajectory. """ return self._dump_keywords[self._group] @property def ext(self) -> Optional[str]: """ Return the file extension, including the leading dot, or ``None`` if the parser was built from a name. The extension is :attr:`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 :attr:`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 """ return self._ext @property def lineage(self) -> LineageT: """ Return the current lineage. """ return self._lineage @property def name(self) -> str: """ Return the unique name parsed from the filename. """ return self._name @property def project_name(self) -> str: """ Return the project (parser class) name, """ return self._project_name @property def attributes(self) -> list[str]: """ Return lineage-specific and project attributes for an artifact. """ return self._attributes @property def lineage_genealogy(self) -> list[LineageT]: """ Return the parents of a given `lineage`. """ return self._lineage_genealogy @property def lineage_attributes(self) -> list[str]: """ Return lineage-specific attributes for an artifact with a given `lineage`. """ return self._lineage_attributes @property def physical_attributes(self) -> list[str]: """ Return project-level attributes for an artifact with a given `lineage`. """ return self._physical_attributes def _find_name(self) -> None: """ parses the unique lineage_name (the first substring of filename and/or the segment keyword middle substring) of a filename. """ if self.lineage in ['segment', 'whole']: # a 'segment' lineage only used in 'probe' phase # a 'whole' lineage used in 'probe' or 'analyze' phases # so its lineage_name is either ended by 'group' keyword or '-'. # these two combined below: base = self.name.split(f".{self.group}")[0] self._name = base.split('-')[0] else: # 'ensemble' or 'space' lineages self._name = self.name.split('-')[0] def _set_defaults(self) -> None: """ Set the attributes declared in `_defaults`. """ for attr, value in self._defaults.items(): setattr(self, attr, value) def _parse_name(self) -> None: """ Set the attributes of the lineage's pattern from the values in `name`. Raises ------ ValueError If `name` lacks a keyword of the pattern, or a keyword's value is not a number, or not a whole number for an `int` keyword. """ keywords = self._keywords patterns = self._patterns assert keywords is not None and patterns is not None # __init__ words = _TOKEN_RE.split(self.name) values: dict[str, str] = {} for keyword, token in zip(words[1::2], words[2::2]): values.setdefault(keyword, token) for keyword in patterns[self.lineage]: spec = keywords[keyword] if keyword not in values: raise ValueError( f"keyword {keyword!r} for attribute {spec.attr!r} not " f"found in {self.name!r} (lineage {self.lineage!r}).") try: value = spec.parse(values[keyword]) except ValueError as err: raise ValueError( f"value of keyword {keyword!r} in {self.name!r} " f"(lineage {self.lineage!r}): {err}.") from err setattr(self, spec.attr, value) def _set_parents(self) -> None: """ Set parent lineage names for each lineage type, following the hierarchy defined in `_genealogy`. Notes ----- The `self._genealogy` defines the following parent-child hierarchy: - space -> ensemble -> ensemble_long -> whole -> segment Each lineage on the left has all the lineages on its right. The long-form names (``segment``, ``whole``, and ``ensemble_long``) are cut from `name` after the value of the parent's last keyword, so they keep the original tokens. `_parse_name` converts some values, such as ``r`` to `dcyl` and ``l`` to `lcube`; writing those attributes back under the original keywords would convert them again at every re-parse. Because the cut ends at a keyword's value, a ``segment`` or ``whole`` name never carries the topology suffix: ``...ens1.ring`` and ``...ens1.j07.ring`` give the ``whole`` ``...ens1``, so a simulation has one ``whole`` name whichever file it was parsed from. The short-form names (``ensemble`` and ``space``) use their own keywords, such as ``D``, and are built from the attributes. A float value that is a whole number prints as an integer and any other float as :func:`repr` (``ac2``, ``epshc0``, ``epshc1.5``), whatever the name being parsed wrote, such as ``ac2.0`` or ``ac2``. Every parent attribute is read once, so an unparsed keyword raises `AttributeError`. The cost is :math:`O(L)` in the length :math:`L` of `name`. """ for lineage_name in self.lineages: lineage_value = 'N/A' if lineage_name in self.genealogy[self.lineage]: lineage_attr = self.genealogy_attributes[lineage_name] lineage_value = ''.join( f"{attr_short}{_format_value(getattr(self, attr_long))}" for attr_long, attr_short in lineage_attr.items() ) if lineage_name in ['segment', 'whole', 'ensemble_long']: last_keyword = next(reversed(lineage_attr.values())) lineage_value = self._name_through(last_keyword) setattr(self, lineage_name, lineage_value) def _name_through(self, keyword: str) -> str: """ Return `name` up to and including the value of `keyword`, without a trailing dot. Parameters ---------- keyword : str A short-form keyword, such as ``ens``, that appears in `name`. Returns ------- str The prefix of `name` that ends with the value of `keyword`. Raises ------ ValueError If `keyword` is not a keyword of `name`. """ for match in re.finditer(r"([a-zA-Z]+)([^a-zA-Z]*)", self.name): if match.group(1) == keyword: return self.name[:match.end()].rstrip('.') raise ValueError(f"'{keyword}' keyword not found in '{self.name}'.") def _bulk_values(self, number: float, size: float) -> tuple[float, float]: """ Return the bulk number density and volume fraction of `number` particles of diameter `size` in the periodic box. Parameters ---------- number : float Number of particles. size : float Particle diameter. Returns ------- tuple of (float, float) The number density and the volume fraction, from :func:`~polyphys.manage.utils.number_density_cube` and :func:`~polyphys.manage.utils.volume_fraction_cube` with the side `lcube`, or their cylinder counterparts with `lcyl` and `dcyl`, all with ``pbc=True``. """ if self.geometry == 'cubic': lcube = getattr(self, 'lcube') return (number_density_cube(number, size, lcube, pbc=True), volume_fraction_cube(number, size, lcube, pbc=True)) lcyl = getattr(self, 'lcyl') dcyl = getattr(self, 'dcyl') return (number_density_cylinder(number, size, lcyl, dcyl, pbc=True), volume_fraction_cylinder(number, size, lcyl, dcyl, pbc=True)) def _dependent_attributes(self) -> None: """ Compute the bulk values of each species, their declared totals, and the declared masses. Raises ------ ValueError If a species leaves its centers no room in the box, such as a species as wide as the cylinder; the message names the species, `name`, and the lineage. """ for species in self._species: try: rho, phi = self._bulk_values(getattr(self, species.number), getattr(self, species.size)) except ValueError as err: raise ValueError( f"species {species.suffix!r} of {self.name!r} " f"(lineage {self.lineage!r}): {err}") from err setattr(self, f"rho_bulk_{species.suffix}", rho) setattr(self, f"phi_bulk_{species.suffix}", phi) for total, parts in self._totals.items(): for quantity in ('rho_bulk', 'phi_bulk'): setattr(self, f"{quantity}_{total}", sum(getattr(self, f"{quantity}_{part}") for part in parts)) for mass, size in self._masses.items(): setattr(self, mass, getattr(self, size) ** 3) def _derived_attributes(self) -> None: """ Set the attributes that a subclass derives from parsed values outside the declaration tables; the base class sets none. It runs at every lineage, after parsing, the parent names, and the bulk values, so an override reads only attributes that the lineage's pattern, `_defaults`, or the bulk recipe set. An override costs :math:`O(1)` per attribute it sets. """
def __getattr__(name: str) -> object: """ Say where a study parser that left this module in 1.0.0 went. Python calls this (:pep:`562`) only for a name the module does not define. An :exc:`ImportError`, not an :exc:`AttributeError`, so that ``from polyphys.manage.parser import HnsCub`` shows the message: Python replaces an :exc:`AttributeError` raised here with its own. Raises ------ ImportError If `name` is the parser of a published study that left the module. AttributeError For any other name. """ if name in _MOVED_STUDIES: raise ImportError( f"{name} moved out of PolyPhys in 1.0.0, to " f"polyphys_lab.{_MOVED_STUDIES[name]}.parser in the " f"polyphys-lab repository, {_LAB_URL}; copy it into your " f"study's code.") raise AttributeError( f"module 'polyphys.manage.parser' has no attribute {name!r}")