polyphys 1.0.0__py3-none-any.whl

polyphys/tests/strategies.py

@@ -0,0 +1,120 @@
+"""\
+==========================================================
+:mod:`polyphys.tests.strategies`
+==========================================================
+
+Hypothesis strategies shared by the package's tests and the study tests in
+``projects/``.
+
+:func:`lineage_names` draws an artifact name of one lineage of a parser
+class from the parser's own declaration: one value per keyword of the
+lineage's pattern, written in the text a parser rebuilds a short name with,
+so that parsing the name and rebuilding it is the identity.
+
+Examples
+========
+>>> from hypothesis import find
+>>> from polyphys.tests.strategies import lineage_names
+>>> from polyphys.tests.synthetic import ChainCyl
+>>> name, values = find(lineage_names(ChainCyl, 'space'), lambda _: True)
+>>> sorted(values)
+['D', 'N', 'ac']
+"""
+from decimal import Decimal
+
+from hypothesis import assume
+from hypothesis import strategies as st
+
+from polyphys.manage.parser import KeywordSpec, ParserBase
+from polyphys.manage.types import LineageT
+
+__all__ = ['keyword_text', 'lineage_names', 'stored_values']
+
+
+def keyword_text(value: int | Decimal) -> str:
+    """
+    Return the text of a keyword value as a parser rebuilds it in a short
+    name: an `int` unchanged, and a float that is a whole number as an
+    integer, any other as its :func:`repr`.
+
+    Examples
+    --------
+    >>> from decimal import Decimal
+    >>> keyword_text(200), keyword_text(Decimal('2.000')), \\
+    ...     keyword_text(Decimal('1.250'))
+    ('200', '2', '1.25')
+    """
+    if isinstance(value, int):
+        return str(value)
+    number = float(value)
+    return str(int(number)) if number.is_integer() else repr(number)
+
+
+def _values(spec: KeywordSpec) -> st.SearchStrategy[int | Decimal]:
+    """The values of one keyword: integers from 0 to 100000, or decimals
+    with up to three places from 0.001 to 1000."""
+    if spec.kind is int:
+        return st.integers(min_value=0, max_value=100_000)
+    return st.decimals(min_value=Decimal('0.001'), max_value=Decimal('1000'),
+                       places=3, allow_nan=False, allow_infinity=False)
+
+
+@st.composite
+def lineage_names(
+    draw: st.DrawFn, parser_class: type[ParserBase], lineage: LineageT
+) -> tuple[str, dict[str, int | Decimal]]:
+    """
+    Draw a name of `lineage` for `parser_class` and the value of each of
+    its keywords.
+
+    The keywords follow the lineage's pattern, each followed by the text of
+    its value (:func:`keyword_text`); in a ``segment`` name the segment
+    keyword ``j`` follows a dot, as the probes write it. In a cylinder,
+    a name is kept only when the cylinder size exceeds every species' size,
+    so that each species' centers have room and the parser's bulk values
+    exist (:func:`~polyphys.manage.utils.number_density_cylinder`).
+
+    Returns
+    -------
+    tuple of (str, dict)
+        The name, and each keyword of the pattern mapped to its value.
+    """
+    keywords = parser_class._keywords
+    patterns = parser_class._patterns
+    assert keywords is not None and patterns is not None
+    values = {keyword: draw(_values(keywords[keyword]))
+              for keyword in patterns[lineage]}
+    if parser_class._geometry == 'cylindrical':
+        stored = {**parser_class._defaults,
+                  **stored_values(parser_class, values)}
+        if 'dcyl' in stored:
+            assume(all(stored.get(species.size, 0.0) < stored['dcyl']
+                       for species in parser_class._species))
+    parts = [('.' if keyword == 'j' else '') + keyword + keyword_text(value)
+             for keyword, value in values.items()]
+    return ''.join(parts), values
+
+
+def stored_values(
+    parser_class: type[ParserBase], values: dict[str, int | Decimal]
+) -> dict[str, int | float]:
+    """
+    Map each keyword's attribute to the value a parser stores for it,
+    :math:`y = s x + c` (:class:`~polyphys.manage.parser.KeywordSpec`), in
+    float arithmetic.
+
+    Examples
+    --------
+    >>> from decimal import Decimal
+    >>> from polyphys.tests.synthetic import ChainCyl
+    >>> stored_values(ChainCyl, {'N': 200, 'r': Decimal('10.5')})
+    {'nmon': 200, 'dcyl': 20.0}
+    """
+    keywords = parser_class._keywords
+    assert keywords is not None
+    stored: dict[str, int | float] = {}
+    for keyword, value in values.items():
+        spec = keywords[keyword]
+        stored[spec.attr] = (value if isinstance(value, int)
+                             else spec.scale * float(value) + spec.offset)
+    return stored

polyphys/tests/synthetic.py

@@ -0,0 +1,410 @@
+"""\
+==========================================================
+:mod:`polyphys.tests.synthetic`
+==========================================================
+
+Synthetic parsers for the package's own tests and examples. PolyPhys ships
+no study parser (see the "Studies" page); these classes declare made-up
+studies, so that the tests and the examples of the library do not depend on
+any study's naming scheme.
+
+- :class:`ChainCyl`: a linear chain among crowders in a cylinder that is
+  periodic along its axis.
+- :class:`RingCub`: a ring of small and large monomers among crowders in a
+  periodic cube.
+- :class:`RingCubTwoCrowders`: a ring of small and large monomers among
+  crowders of two sizes in a periodic cube.
+- :class:`RingCubBinders`: a ring of monomers with binders and crowders in
+  a periodic cube.
+- :class:`RingCyl`: a ring of small and large monomers among crowders in a
+  cylinder that is periodic along its axis.
+- :class:`RingCylBinders`: a ring of monomers with binders and crowders in
+  a cylinder that is periodic along its axis.
+
+In each name, ``#`` stands for a value. The cylinder size is
+:math:`D = 2r - 1` from the radius :math:`r` (keyword ``r``) of a wall of
+beads of size 1, the cylinder length :math:`Z = 2 l_z` from the half-length
+:math:`l_z` (keyword ``lz``), and the cube side :math:`L = 2l` from the
+half-side :math:`l` (keyword ``l``).
+
+Examples
+========
+>>> from polyphys.tests.synthetic import ChainCyl
+>>> artifact = ChainCyl('N200D10.0ac2.0nc0', 'ensemble', 'all')
+>>> artifact.nmon, artifact.dcyl, artifact.dcrowd
+(200, 10.0, 2.0)
+"""
+from polyphys.manage.parser import KeywordSpec, ParserBase, Species
+
+__all__ = [
+    'ChainCyl', 'RingCub', 'RingCubBinders', 'RingCubTwoCrowders', 'RingCyl',
+    'RingCylBinders',
+]
+
+_MONOMER_BULK = ['phi_bulk_m', 'rho_bulk_m']
+_RING_BULK = ['phi_bulk_m_small', 'rho_bulk_m_small', 'phi_bulk_m_large',
+              'rho_bulk_m_large', 'phi_bulk_m', 'rho_bulk_m']
+
+
+class ChainCyl(ParserBase):
+    """
+    Parse a name of the synthetic *ChainCyl* study: a linear chain among
+    crowders in a cylinder that is periodic along its axis.
+
+    - ``segment``: N#r#lz#ac#nc#dt#bdump#adump#ens#.j#
+    - ``whole``: N#r#lz#ac#nc#dt#bdump#adump#ens#
+    - ``ensemble_long``: N#r#lz#ac#nc#dt#bdump#adump#
+    - ``ensemble``: N#D#ac#nc#
+    - ``space``: N#D#ac#
+
+    The monomer diameter `dmon` is 1 and not in the name. The bulk number
+    densities and volume fractions of monomers and crowders exist at
+    ``segment``, ``whole``, and ``ensemble_long``.
+
+    Examples
+    --------
+    >>> artifact = ChainCyl(
+    ...     'N200r10.5lz25.0ac2.0nc100dt0.005bdump1000adump5000ens1',
+    ...     'whole', 'bug')
+    >>> artifact.dcyl, artifact.lcyl, artifact.ensemble
+    (20.0, 50.0, 'N200D20ac2nc100')
+    """
+    _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': ('N', 'r', 'lz', 'ac', 'nc', 'dt', 'bdump', 'adump',
+                    'ens', 'j'),
+        'whole': ('N', 'r', 'lz', 'ac', 'nc', 'dt', 'bdump', 'adump', 'ens'),
+        'ensemble_long': ('N', 'r', 'lz', 'ac', 'nc', 'dt', 'bdump',
+                          'adump'),
+        'ensemble': ('N', 'D', 'ac', 'nc'),
+        'space': ('N', 'D', 'ac'),
+    }
+    _defaults = {'dmon': 1}
+    _species = (Species('m', 'nmon', 'dmon'), Species('c', 'ncrowd', 'dcrowd'))
+    _project_attributes = {
+        'segment': ['dmon', *_MONOMER_BULK, 'phi_bulk_c', 'rho_bulk_c'],
+        'whole': ['dmon', *_MONOMER_BULK, 'phi_bulk_c', 'rho_bulk_c'],
+        'ensemble_long': ['dmon', *_MONOMER_BULK, 'phi_bulk_c',
+                          'rho_bulk_c'],
+        'ensemble': ['dmon'],
+        'space': ['dmon'],
+    }
+
+
+class RingCub(ParserBase):
+    """
+    Parse a name of the synthetic *RingCub* study: a ring of small and large
+    monomers among crowders in a periodic cube.
+
+    - ``segment``: al#nl#ml#ns#ac#nc#l#dt#bdump#adump#ens#.j#
+    - ``whole``: al#nl#ml#ns#ac#nc#l#dt#bdump#adump#ens#
+    - ``ensemble_long``: al#nl#ml#ns#ac#nc#l#dt#bdump#adump#
+    - ``ensemble``: ns#nl#al#ac#nc#
+    - ``space``: ns#nl#al#ac#
+
+    The small monomers have diameter and mass 1, and the crowders a mass
+    set by their diameter; none is in the name.
+
+    Examples
+    --------
+    >>> artifact = RingCub(
+    ...     'al2.0nl2ml8.0ns20ac1.0nc100l10.0dt0.005bdump1000adump5000ens1',
+    ...     'whole', 'bug')
+    >>> artifact.nmon_small, artifact.nmon_large, artifact.lcube
+    (20, 2, 20.0)
+    """
+    _geometry = 'cubic'
+    _topology = 'ring'
+    _groups = ['bug', 'all']
+    _dump_keywords = {'bug': 'bdump', 'all': 'adump'}
+    _keywords = {
+        'al': KeywordSpec('dmon_large', float),
+        'nl': KeywordSpec('nmon_large', int),
+        'ml': KeywordSpec('mmon_large', float),
+        'ns': KeywordSpec('nmon_small', int),
+        'ac': KeywordSpec('dcrowd', float),
+        'nc': KeywordSpec('ncrowd', int),
+        'l': KeywordSpec('lcube', float, scale=2.0),
+        'dt': KeywordSpec('dt', float),
+        'bdump': KeywordSpec('bdump', int),
+        'adump': KeywordSpec('adump', int),
+        'ens': KeywordSpec('ensemble_id', int),
+        'j': KeywordSpec('segment_id', int),
+    }
+    _patterns = {
+        'segment': ('al', 'nl', 'ml', 'ns', 'ac', 'nc', 'l', 'dt', 'bdump',
+                    'adump', 'ens', 'j'),
+        'whole': ('al', 'nl', 'ml', 'ns', 'ac', 'nc', 'l', 'dt', 'bdump',
+                  'adump', 'ens'),
+        'ensemble_long': ('al', 'nl', 'ml', 'ns', 'ac', 'nc', 'l', 'dt',
+                          'bdump', 'adump'),
+        'ensemble': ('ns', 'nl', 'al', 'ac', 'nc'),
+        'space': ('ns', 'nl', 'al', 'ac'),
+    }
+    _defaults = {'dmon_small': 1, 'mmon_small': 1, 'mcrowd': -1}
+    _species = (Species('m_small', 'nmon_small', 'dmon_small'),
+                Species('m_large', 'nmon_large', 'dmon_large'),
+                Species('c', 'ncrowd', 'dcrowd'))
+    _totals = {'m': ('m_small', 'm_large')}
+    _masses = {'mcrowd': 'dcrowd'}
+    _project_attributes = {
+        'segment': ['dmon_small', 'mmon_small', 'mcrowd', *_RING_BULK,
+                    'phi_bulk_c', 'rho_bulk_c'],
+        'whole': ['dmon_small', 'mmon_small', 'mcrowd', *_RING_BULK,
+                  'phi_bulk_c', 'rho_bulk_c'],
+        'ensemble_long': ['dmon_small', 'mmon_small', 'mcrowd', *_RING_BULK,
+                          'phi_bulk_c', 'rho_bulk_c'],
+        'ensemble': ['dmon_small', 'mmon_small', 'mcrowd'],
+        'space': ['dmon_small', 'mmon_small', 'mcrowd'],
+    }
+
+
+class RingCubTwoCrowders(ParserBase):
+    """
+    Parse a name of the synthetic *RingCubTwoCrowders* study: a ring of
+    small and large monomers among crowders of two sizes in a periodic cube.
+
+    - ``segment``: al#nl#ns#ac#ab#nc#nb#l#dt#bdump#adump#ens#.j#
+    - ``whole``: al#nl#ns#ac#ab#nc#nb#l#dt#bdump#adump#ens#
+    - ``ensemble_long``: al#nl#ns#ac#ab#nc#nb#l#dt#bdump#adump#
+    - ``ensemble``: al#nl#ns#ac#ab#nc#nb#
+    - ``space``: al#nl#ns#ac#ab#
+
+    The crowders of type one have diameter `dcrowd_one` (keyword ``ac``)
+    and number `ncrowd_one` (``nc``); those of type two `dcrowd_two`
+    (``ab``) and `ncrowd_two` (``nb``). `phi_bulk_c` sums the two.
+
+    Examples
+    --------
+    >>> artifact = RingCubTwoCrowders(
+    ...     'al2.0nl2ns20ac1.0ab2.0nc100nb10l10.0dt0.005bdump1000adump5000',
+    ...     'ensemble_long', 'all')
+    >>> artifact.dcrowd_one, artifact.dcrowd_two, artifact.ncrowd_two
+    (1.0, 2.0, 10)
+    """
+    _geometry = 'cubic'
+    _topology = 'ring'
+    _groups = ['bug', 'all']
+    _dump_keywords = {'bug': 'bdump', 'all': 'adump'}
+    _keywords = {
+        'al': KeywordSpec('dmon_large', float),
+        'nl': KeywordSpec('nmon_large', int),
+        'ns': KeywordSpec('nmon_small', int),
+        'ac': KeywordSpec('dcrowd_one', float),
+        'ab': KeywordSpec('dcrowd_two', float),
+        'nc': KeywordSpec('ncrowd_one', int),
+        'nb': KeywordSpec('ncrowd_two', int),
+        'l': KeywordSpec('lcube', float, scale=2.0),
+        'dt': KeywordSpec('dt', float),
+        'bdump': KeywordSpec('bdump', int),
+        'adump': KeywordSpec('adump', int),
+        'ens': KeywordSpec('ensemble_id', int),
+        'j': KeywordSpec('segment_id', int),
+    }
+    _patterns = {
+        'segment': ('al', 'nl', 'ns', 'ac', 'ab', 'nc', 'nb', 'l', 'dt',
+                    'bdump', 'adump', 'ens', 'j'),
+        'whole': ('al', 'nl', 'ns', 'ac', 'ab', 'nc', 'nb', 'l', 'dt',
+                  'bdump', 'adump', 'ens'),
+        'ensemble_long': ('al', 'nl', 'ns', 'ac', 'ab', 'nc', 'nb', 'l',
+                          'dt', 'bdump', 'adump'),
+        'ensemble': ('al', 'nl', 'ns', 'ac', 'ab', 'nc', 'nb'),
+        'space': ('al', 'nl', 'ns', 'ac', 'ab'),
+    }
+    _defaults = {'dmon_small': 1}
+    _species = (Species('m_small', 'nmon_small', 'dmon_small'),
+                Species('m_large', 'nmon_large', 'dmon_large'),
+                Species('c_one', 'ncrowd_one', 'dcrowd_one'),
+                Species('c_two', 'ncrowd_two', 'dcrowd_two'))
+    _totals = {'m': ('m_small', 'm_large'), 'c': ('c_one', 'c_two')}
+    _project_attributes = {
+        'segment': ['dmon_small', *_RING_BULK, 'phi_bulk_c_one',
+                    'rho_bulk_c_one', 'phi_bulk_c_two', 'rho_bulk_c_two',
+                    'phi_bulk_c', 'rho_bulk_c'],
+        'whole': ['dmon_small', *_RING_BULK, 'phi_bulk_c_one',
+                  'rho_bulk_c_one', 'phi_bulk_c_two', 'rho_bulk_c_two',
+                  'phi_bulk_c', 'rho_bulk_c'],
+        'ensemble_long': ['dmon_small', *_RING_BULK, 'phi_bulk_c_one',
+                          'rho_bulk_c_one', 'phi_bulk_c_two',
+                          'rho_bulk_c_two', 'phi_bulk_c', 'rho_bulk_c'],
+        'ensemble': ['dmon_small'],
+        'space': ['dmon_small'],
+    }
+
+
+class RingCubBinders(ParserBase):
+    """
+    Parse a name of the synthetic *RingCubBinders* study: a ring of
+    monomers with binders and crowders in a periodic cube, whose particle
+    groups are ``nucleoid`` (the ring and the binders) and ``all``.
+
+    - ``segment``: N#nh#ac#nc#l#ens#.j#
+    - ``whole``: N#nh#ac#nc#l#ens#
+    - ``ensemble_long``: N#nh#ac#nc#l#
+    - ``ensemble``: N#nh#ac#nc#
+    - ``space``: N#nh#ac#
+
+    The monomers and the binder cores have diameter 1, and the time step
+    and dump periods are fixed; none is in the name.
+
+    Examples
+    --------
+    >>> artifact = RingCubBinders('N200nh30ac2.0nc0l25.0ens1', 'whole',
+    ...                           'nucleoid')
+    >>> artifact.nmon, artifact.nhns, artifact.lcube
+    (200, 30, 50.0)
+    """
+    _geometry = 'cubic'
+    _topology = 'ring'
+    _groups = ['nucleoid', 'all']
+    _dump_keywords = {'nucleoid': 'ndump', 'all': 'adump'}
+    _keywords = {
+        'N': KeywordSpec('nmon', int),
+        'nh': KeywordSpec('nhns', 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', 'nh', 'ac', 'nc', 'l', 'ens', 'j'),
+        'whole': ('N', 'nh', 'ac', 'nc', 'l', 'ens'),
+        'ensemble_long': ('N', 'nh', 'ac', 'nc', 'l'),
+        'ensemble': ('N', 'nh', 'ac', 'nc'),
+        'space': ('N', 'nh', 'ac'),
+    }
+    _defaults = {'dmon': 1, 'dhns': 1, 'dt': 0.005, 'ndump': 5000,
+                 'adump': 10000}
+    _species = (Species('m', 'nmon', 'dmon'), Species('hns', 'nhns', 'dhns'),
+                Species('c', 'ncrowd', 'dcrowd'))
+    _project_attributes = {
+        'segment': ['dmon', 'dhns', *_MONOMER_BULK, 'phi_bulk_c',
+                    'rho_bulk_c', 'phi_bulk_hns', 'rho_bulk_hns', 'dt',
+                    'ndump', 'adump'],
+        'whole': ['dmon', 'dhns', *_MONOMER_BULK, 'phi_bulk_c', 'rho_bulk_c',
+                  'phi_bulk_hns', 'rho_bulk_hns', 'dt', 'ndump', 'adump'],
+        'ensemble_long': ['dmon', 'dhns', *_MONOMER_BULK, 'phi_bulk_c',
+                          'rho_bulk_c', 'phi_bulk_hns', 'rho_bulk_hns', 'dt',
+                          'ndump', 'adump'],
+        'ensemble': ['dmon', 'dhns', 'dt', 'ndump', 'adump'],
+        'space': ['dmon', 'dhns', 'dt', 'ndump', 'adump'],
+    }
+
+
+class RingCyl(ParserBase):
+    """
+    Parse a name of the synthetic *RingCyl* study: a ring of small and large
+    monomers among crowders in a cylinder that is periodic along its axis.
+
+    - ``segment``: r#al#nl#ml#ns#ac#nc#lz#dt#bdump#adump#ens#.j#
+    - ``whole``: r#al#nl#ml#ns#ac#nc#lz#dt#bdump#adump#ens#
+    - ``ensemble_long``: r#al#nl#ml#ns#ac#nc#lz#dt#bdump#adump#
+    - ``ensemble``: ns#nl#al#D#ac#nc#
+    - ``space``: ns#nl#al#D#ac#
+
+    Examples
+    --------
+    >>> artifact = RingCyl(
+    ...     'r5al2nl3ml8ns7ac1.5nc0lz10dt0.005bdump1adump1ens1', 'whole',
+    ...     'bug')
+    >>> artifact.dcyl, artifact.dmon_large, artifact.space
+    (9.0, 2.0, 'ns7nl3al2D9ac1.5')
+    """
+    _geometry = 'cylindrical'
+    _topology = 'ring'
+    _groups = ['bug', 'all']
+    _dump_keywords = {'bug': 'bdump', 'all': 'adump'}
+    _keywords = {
+        'r': KeywordSpec('dcyl', float, scale=2.0, offset=-1.0),
+        'D': KeywordSpec('dcyl', float),
+        'al': KeywordSpec('dmon_large', float),
+        'nl': KeywordSpec('nmon_large', int),
+        'ml': KeywordSpec('mmon_large', float),
+        'ns': KeywordSpec('nmon_small', int),
+        'ac': KeywordSpec('dcrowd', float),
+        'nc': KeywordSpec('ncrowd', int),
+        'lz': KeywordSpec('lcyl', float, scale=2.0),
+        'dt': KeywordSpec('dt', float),
+        'bdump': KeywordSpec('bdump', int),
+        'adump': KeywordSpec('adump', int),
+        'ens': KeywordSpec('ensemble_id', int),
+        'j': KeywordSpec('segment_id', int),
+    }
+    _patterns = {
+        'segment': ('r', 'al', 'nl', 'ml', 'ns', 'ac', 'nc', 'lz', 'dt',
+                    'bdump', 'adump', 'ens', 'j'),
+        'whole': ('r', 'al', 'nl', 'ml', 'ns', 'ac', 'nc', 'lz', 'dt',
+                  'bdump', 'adump', 'ens'),
+        'ensemble_long': ('r', 'al', 'nl', 'ml', 'ns', 'ac', 'nc', 'lz',
+                          'dt', 'bdump', 'adump'),
+        'ensemble': ('ns', 'nl', 'al', 'D', 'ac', 'nc'),
+        'space': ('ns', 'nl', 'al', 'D', 'ac'),
+    }
+    _defaults = {'dmon_small': 1, 'mmon_small': 1, 'mcrowd': -1}
+    _species = RingCub._species
+    _totals = {'m': ('m_small', 'm_large')}
+    _masses = {'mcrowd': 'dcrowd'}
+    _project_attributes = RingCub._project_attributes
+
+
+class RingCylBinders(ParserBase):
+    """
+    Parse a name of the synthetic *RingCylBinders* study: a ring of
+    monomers with binders and crowders in a cylinder that is periodic along
+    its axis, with the groups ``nucleoid`` and ``all``.
+
+    - ``segment``: N#r#nh#ac#nc#lz#ens#.j#
+    - ``whole``: N#r#nh#ac#nc#lz#ens#
+    - ``ensemble_long``: N#r#nh#ac#nc#lz#
+    - ``ensemble``: N#D#nh#ac#nc#
+    - ``space``: N#D#nh#ac#
+
+    Examples
+    --------
+    >>> artifact = RingCylBinders('N200r4.5nh30ac2.0nc0lz75.0ens1', 'whole',
+    ...                           'nucleoid')
+    >>> artifact.dcyl, artifact.lcyl, artifact.space
+    (8.0, 150.0, 'N200D8nh30ac2')
+    """
+    _geometry = 'cylindrical'
+    _topology = 'ring'
+    _groups = ['nucleoid', 'all']
+    _dump_keywords = {'nucleoid': 'ndump', 'all': 'adump'}
+    _keywords = {
+        'N': KeywordSpec('nmon', int),
+        'r': KeywordSpec('dcyl', float, scale=2.0, offset=-1.0),
+        'D': KeywordSpec('dcyl', float),
+        'nh': KeywordSpec('nhns', int),
+        'ac': KeywordSpec('dcrowd', float),
+        'nc': KeywordSpec('ncrowd', int),
+        'lz': KeywordSpec('lcyl', float, scale=2.0),
+        'ens': KeywordSpec('ensemble_id', int),
+        'j': KeywordSpec('segment_id', int),
+    }
+    _patterns = {
+        'segment': ('N', 'r', 'nh', 'ac', 'nc', 'lz', 'ens', 'j'),
+        'whole': ('N', 'r', 'nh', 'ac', 'nc', 'lz', 'ens'),
+        'ensemble_long': ('N', 'r', 'nh', 'ac', 'nc', 'lz'),
+        'ensemble': ('N', 'D', 'nh', 'ac', 'nc'),
+        'space': ('N', 'D', 'nh', 'ac'),
+    }
+    _defaults = RingCubBinders._defaults
+    _species = RingCubBinders._species
+    _project_attributes = RingCubBinders._project_attributes