polyphys 1.0.0__py3-none-any.whl

polyphys/manage/utils.py

@@ -0,0 +1,777 @@
+"""\
+===============================================================
+Miscellaneous utility codes --- :mod:`polyphys.manage.utils`
+===============================================================
+
+The :mod:`~polyphys.manage.utils` module provides shared utility functions
+used across various parts of the PolyPhys package. These functions handle
+string processing, file handling, numeric rounding, error checking, and
+conversions between particle counts, number densities, and volume fractions.
+
+Contents
+========
+
+String parsing and filename sorting:
+:func:`read_camel_case`, :func:`to_float_if_possible`,
+:func:`split_alphanumeric`, :func:`normalize_exts`, and
+:func:`sort_filenames`.
+
+File handling:
+:func:`openany` and :func:`openany_context`.
+
+Numeric rounding and validation:
+:func:`round_down_first_non_zero`, :func:`round_to_multiple`, and
+:func:`invalid_keyword`.
+
+Number-density and volume-fraction conversions:
+:func:`number_density_cube`, :func:`volume_fraction_cube`,
+:func:`number_density_cylinder`, and :func:`volume_fraction_cylinder`.
+
+Dependencies
+============
+- Python standard library: `re`, `gzip`, `contextlib`, `typing`
+- Third-party: `numpy`
+
+See also: :mod:`~polyphys.manage.types` for the definition of
+:py:obj:`~polyphys.manage.types.InputType`.
+"""
+
+import re
+from pathlib import Path
+import gzip
+from typing import Generator, Optional, List, Union, Tuple, Sequence, cast
+import warnings
+from contextlib import contextmanager
+import numpy as np
+from .types import InputType, PathIter
+
+__all__ = [
+    'invalid_keyword',
+    'normalize_exts',
+    'number_density_cube',
+    'number_density_cylinder',
+    'openany',
+    'openany_context',
+    'read_camel_case',
+    'round_down_first_non_zero',
+    'round_to_multiple',
+    'sort_filenames',
+    'split_alphanumeric',
+    'to_float_if_possible',
+    'volume_fraction_cube',
+    'volume_fraction_cylinder',
+]
+
+
+def read_camel_case(string: str) -> List[Union[str, Tuple[str]]]:
+    """
+    Split a *camelCase* or *CamelCase* `string` into its component substrings.
+
+    Parameters
+    ----------
+    string : str
+        The *camelCase* or *CamelCase* `string` to be split.
+
+    Returns
+    -------
+    List[str]
+        The split `string` with substrings as elements.
+
+    Examples
+    --------
+    >>> read_camel_case("camelCase")
+    ['camel', 'Case']
+    >>> read_camel_case("CamelCaseString")
+    ['Camel', 'Case', 'String']
+    """
+    return re.findall(r"[A-Z]?[a-z]+|[A-Z]+(?=[A-Z]|$)", string)
+
+
+def to_float_if_possible(string: str) -> Union[float, str]:
+    """
+    Convert `string` to a float, or return it unchanged if it is not a
+    number.
+
+    Parameters
+    ----------
+    string : str
+        The `string` to attempt to convert to a float.
+
+    Returns
+    -------
+    Union[float, str]
+        The converted float if the input can be converted; otherwise,
+        the original `string`.
+
+    Examples
+    --------
+    >>> to_float_if_possible("3.14")
+    3.14
+    >>> to_float_if_possible("not_a_float")
+    'not_a_float'
+    >>> to_float_if_possible("42")
+    42.0
+    """
+    try:
+        return float(string)
+    except ValueError:
+        return string
+
+
+def split_alphanumeric(alphanumeric: str) -> List[Union[int, str, float]]:
+    """
+    Split an *alphanumeric* string into a list of strings, integers, and
+    floats.
+
+    This function identifies contiguous sections of digits, letters, and
+    decimal numbers, returning them as separate elements in a list, making the
+    string suitable for alphanumeric sorting.
+
+    Parameters
+    ----------
+    alphanumeric : str
+        An alphanumeric string to be split.
+
+    Returns
+    -------
+    List[Union[int, str, float]]
+        A list of components including integers, floats, and strings.
+
+    Examples
+    --------
+    >>> split_alphanumeric("file20.5name10")
+    ['file', 20.5, 'name', 10]
+    """
+    number_pattern = re.compile(r"(\d+\.*\d*)")
+    parts = number_pattern.split(alphanumeric)
+    return [
+        int(part) if part.isdigit() else to_float_if_possible(part)
+        for part in parts
+        if part
+    ]
+
+
+def normalize_exts(exts: Union[str, Tuple[str, ...]]) -> Tuple[str, ...]:
+    """
+    Normalize a format specifier into a tuple of extensions.
+
+    Ensures each extension starts with a leading dot ('.').
+    A single extension (with or without a dot) is converted to a
+    1-tuple; a tuple is normalized element-wise.
+
+    Parameters
+    ----------
+    exts : str or tuple of str
+        Extension specifier. Can be:
+        - A string representing a single extension (e.g., ``"npy"`` or
+        ``".npy"``).
+        - A tuple of equivalent extensions (e.g., ``("trj", "lammpstrj")``).
+
+    Returns
+    -------
+    tuple of str
+        Normalized tuple of extensions, all dot-prefixed.
+
+    Examples
+    --------
+    >>> normalize_exts("npy")
+    ('.npy',)
+    >>> normalize_exts(("trj", ".lammpstrj"))
+    ('.trj', '.lammpstrj')
+    """
+    if isinstance(exts, str):
+        exts = (exts,)
+    return tuple(e if e.startswith(".") else f".{e}" for e in exts)
+
+
+def sort_filenames(
+    filenames: PathIter,
+    formats: Sequence[Union[str, Tuple[str, ...]]],
+) -> List[Tuple[Path, ...]]:
+    """
+    Group and alphanumerically sort `filenames` by basename across `formats`.
+
+    Files are paired by the same basename, the full file name with the
+    matched extension removed, such that each tuple contains exactly one
+    file for each format group. A format group may list multiple,
+    equivalent extensions, e.g. ``("trj", "lammpstrj")``. Only complete
+    basenames (with all slots present) are returned.
+
+    Parameters
+    ----------
+    filenames : sequence of path-like or str
+        Filenames/paths to sort and group.
+    formats : sequence of str or tuple of str
+        Each entry specifies one output slot. It can be a single extension
+        (e.g. ``"data"``) or a tuple of equivalent extensions
+        (e.g. ``("trj", "lammpstrj")``). Extensions are matched exactly
+        (except a leading dot is added if missing).
+
+    Returns
+    -------
+    list of tuple of Path
+        List of tuples, one per matched basename, ordered by natural
+        (alphanumeric) sort of the basename. Each tuple has length
+        ``len(formats)`` and contains `Path` objects in the same order
+        as `formats`.
+
+    Notes
+    -----
+    - **Case sensitivity:** extension matching is exact and case-sensitive.
+      For example, ``".data"`` ≠ ``".DATA"``. If you want case-insensitive
+      behavior, normalize your inputs beforehand.
+    - **Slot order preserved:** the files in each returned tuple **follow the
+      order of `formats`**. For example, with
+      ``formats = ['data', 'trj', 'npy']`` the tuple is
+      ``(file.data, file.trj, file.npy)``.
+    - **Compound extensions:** ``".tar.gz"`` is **different** from ``".gz"``.
+      They are only treated as equivalent if you explicitly group them in
+      the same slot, e.g. ``('tar.gz', 'gz')``.
+    - Only basenames that have a file in every slot are returned, so if
+      any format group matches no files, no basename is complete and the
+      returned list is empty.
+    - Incomplete basenames are **ignored** and a warning is emitted for each
+      present file mentioning its missing counterpart(s).
+    - Grouping is by **basename**: the full file name without the matched
+      extension, dots included, never the part before the last dot, so
+      ``...epshc1.0nc0`` and ``...epshc1.0nc500`` are two basenames.
+      Directory paths are not used.
+    - Let n be the number of files and k the number of extensions in
+      `formats`. Time is O(n k) to match the extensions plus
+      O(n log n) to sort the basenames; memory is O(n).
+
+    Raises
+    ------
+    ValueError
+        If an extension is assigned to multiple format groups, or if there
+        are duplicate files for the same basename and format slot. A file
+        whose name ends in extensions of two groups, such as ``.tar.gz`` and
+        ``.gz``, goes to the group of the longer one.
+
+    Examples
+    --------
+    >>> from pathlib import Path
+    >>> result = sort_filenames(
+    ...     ['file1.data', 'file2.trj', 'file1.trj', 'file2.data'],
+    ...     ['data', ('lammpstrj', 'trj')]
+    ... )
+    >>> result == [
+    ...     (Path('file1.data'), Path('file1.trj')),
+    ...     (Path('file2.data'), Path('file2.trj')),
+    ... ]
+    True
+    """
+    # Normalize inputs
+    paths = [Path(p) for p in filenames]
+    norm_formats: List[Tuple[str, ...]] = \
+        [normalize_exts(spec) for spec in formats]
+
+    # Build extension → slot map once; validate no overlaps across slots
+    ext_to_slot: dict[str, int] = {}
+    for i, exts in enumerate(norm_formats):
+        for e in exts:
+            prev = ext_to_slot.get(e)
+            if prev is not None and prev != i:
+                raise ValueError(
+                    f"Extension '{e}' appears in multiple format groups: "
+                    f"{norm_formats[prev]} and {norm_formats[i]}"
+                )
+            ext_to_slot[e] = i
+
+    # basename -> {slot_index -> Path}
+    by_base: dict[str, dict[int, Path]] = {}
+
+    for p in paths:
+        name = p.name  # case-sensitive
+        # Collect all matching (ext, slot)
+        matches = [(e, s) for e, s in ext_to_slot.items() if name.endswith(e)]
+        if not matches:
+            continue
+        # Longest-suffix-wins disambiguation. Two matching extensions of
+        # equal length are the same string, and an extension sits in one
+        # slot only, so the longest match is unique.
+        win_ext, slot = max(matches, key=lambda match: len(match[0]))
+
+        # The basename is the full name without the winning extension; it
+        # keeps every dot of the name, such as the one in 'epshc1.0nc500'.
+        base = name[:-len(win_ext)]
+
+        slot_map = by_base.setdefault(base, {})
+        if slot in slot_map:
+            raise ValueError(
+                f"Duplicate files for basename '{base}' in slot {slot} "
+                f"{norm_formats[slot]}: '{slot_map[slot].name}' and '{p.name}'"
+            )
+        slot_map[slot] = p
+
+    # Identify complete basenames (all slots present)
+    nslots = len(norm_formats)
+    comp_bases = \
+        [base for base, slots in by_base.items() if len(slots) == nslots]
+
+    # Warn about incomplete basenames and ignore them
+    for base, slots in by_base.items():
+        if base in comp_bases:
+            continue
+        missing_slot_idxs = [i for i in range(nslots) if i not in slots]
+        for present_path in slots.values():
+            for miss_idx in missing_slot_idxs:
+                want_ext = norm_formats[miss_idx][0]
+                warnings.warn(
+                    f"'{present_path.name}' does not have matching "
+                    f"'{base}{want_ext}' so it is ignored",
+                    UserWarning,
+                )
+
+    # Natural (alphanumeric) sort by basename
+    comp_bases.sort(key=split_alphanumeric)
+    # Build result tuples in the order of `formats`
+    result: List[Tuple[Path, ...]] = [
+        tuple(by_base[base][i] for i in range(nslots)) for base in comp_bases
+    ]
+    return result
+
+
+def openany(filepath: str, mode: str = "rt") -> InputType:
+    """
+    Open a regular or gzipped file.
+
+    Parameters
+    ----------
+    filepath : str
+        Path to the file.
+    mode : str, default 'rt'
+        File-opening mode, passed to :func:`gzip.open` for a path ending in
+        ``.gz`` and to :func:`open` otherwise.
+
+    Returns
+    -------
+    :py:obj:`~.InputType`
+        The open file object, a :class:`gzip.GzipFile` or a regular file.
+        The caller must close it; :func:`openany_context` does that.
+
+    Examples
+    --------
+    >>> import gzip, os, tempfile
+    >>> with tempfile.TemporaryDirectory() as tmp:
+    ...     path = os.path.join(tmp, 'log.txt.gz')
+    ...     with gzip.open(path, 'wt') as out:
+    ...         _ = out.write('step 0\\n')
+    ...     handle = openany(path)
+    ...     line = handle.readline()
+    ...     handle.close()
+    >>> line
+    'step 0\\n'
+    """
+    open_func = gzip.open if filepath.endswith(".gz") else open
+    return open_func(filepath, mode=mode)
+
+
+@contextmanager
+def openany_context(
+    filepath: str, mode: str = "rt"
+) -> Generator[InputType, None, None]:
+    """
+    Open a regular or gzipped file, providing a file-like object.
+
+    Parameters
+    ----------
+    filepath : str
+        Path to the file.
+    mode : str, default 'rt'
+        File-opening mode, passed to :func:`gzip.open` for a path ending in
+        ``.gz`` and to :func:`open` otherwise.
+
+    Yields
+    ------
+    :py:obj:`~.InputType`
+        The open file object, a :class:`gzip.GzipFile` or a regular file.
+        The context manager closes it on exit, also after an exception.
+
+    Examples
+    --------
+    >>> import os, tempfile
+    >>> with tempfile.TemporaryDirectory() as tmp:
+    ...     path = os.path.join(tmp, 'log.txt')
+    ...     with open(path, 'w') as out:
+    ...         _ = out.write('step 0\\n')
+    ...     with openany_context(path) as handle:
+    ...         line = handle.readline()
+    >>> line, handle.closed
+    ('step 0\\n', True)
+    """
+    open_func = gzip.open if filepath.endswith(".gz") else open
+    file = open_func(filepath, mode=mode)
+    try:
+        yield file
+    finally:
+        file.close()
+
+
+def round_down_first_non_zero(num: float) -> float:
+    """
+    Round down number `num` to its first non-zero digit.
+
+    Parameters
+    ----------
+    num : float
+        Number which is rounded.
+
+    Returns
+    -------
+    float
+        The number `num` rounded down to its first non-zero digit.
+
+    Examples
+    --------
+    >>> float(round_down_first_non_zero(0.0372))
+    0.03
+    >>> float(round_down_first_non_zero(472.0))
+    400.0
+    """
+    if num == 0:
+        return num
+    exponent = np.floor(np.log10(abs(num)))
+    non_zero = 10**exponent
+    # cast: numpy's stubs return Any. The value is a NumPy floating scalar
+    # (np.float32 for float32 input), not always a float; the cast only
+    # restates the existing annotation and changes nothing at runtime.
+    return cast(
+        float, round(np.floor(num / non_zero) * non_zero, int(abs(exponent)))
+    )
+
+
+def round_to_multiple(dividend: float, divider: float, round_to: int) -> float:
+    """
+    Round `dividend` to the nearest multiple of `divider`, then to
+    `round_to` decimal places.
+
+    The result can lie below `dividend`. The ``phi_bulk_c_round`` labels that
+    :func:`polyphys.manage.organizer.space_tseries` and
+    :func:`polyphys.manage.organizer.space_hists` add are made with it.
+
+    Parameters
+    ----------
+    dividend : float
+        The number to round.
+    divider : float
+        The step of the grid of multiples, ``k * divider`` for integer ``k``.
+    round_to : int
+        The number of decimal places of the result; it removes the float
+        round-off of ``k * divider``.
+
+    Returns
+    -------
+    float
+        The multiple of `divider` closest to `dividend`, rounded to
+        `round_to` decimal places. When `dividend` lies exactly halfway
+        between two multiples, the even multiple is chosen, as Python's
+        built-in :func:`round` does.
+
+    Notes
+    -----
+    Ties are decided on the float64 quotient ``dividend / divider``, which is
+    deterministic: IEEE 754 division is correctly rounded on every platform.
+    A value that is halfway in decimal, such as 0.0375 with a `divider` of
+    0.025, has a quotient (1.4999999999999998) that is not an exact tie, so it
+    rounds to the side the quotient falls on rather than to the even multiple.
+
+    References
+    ----------
+    Python documentation, built-in function :func:`round`:
+    https://docs.python.org/3/builtins/functions.html#round
+
+    Examples
+    --------
+    Crowder volume fractions on a grid of 0.025, rounded to 3 decimals:
+
+    >>> round_to_multiple(0.0874, 0.025, 3)
+    0.075
+    >>> round_to_multiple(0.0876, 0.025, 3)
+    0.1
+    >>> round_to_multiple(0.11, 0.025, 3)
+    0.1
+
+    An exact tie goes to the even multiple:
+
+    >>> round_to_multiple(2.5, 1.0, 0), round_to_multiple(3.5, 1.0, 0)
+    (2.0, 4.0)
+    """
+    return round(round(dividend / divider) * divider, round_to)
+
+
+def invalid_keyword(
+    keyword: str,
+    valid_keywords: Sequence[Optional[str]],
+    message: Optional[str] = None,
+) -> None:
+    """
+    Raise an error if `keyword` is not in `valid_keywords`.
+
+    Parameters
+    ----------
+    keyword : str
+        The keyword to check.
+    valid_keywords : sequence of str or None
+        The accepted keywords.
+    message : str, optional
+        The text that follows the quoted `keyword` in the
+        :exc:`ValueError` message; by default, a list of `valid_keywords`.
+
+    Raises
+    ------
+    ValueError
+        If `keyword` is not in `valid_keywords`.
+
+    Examples
+    --------
+    >>> invalid_keyword('ring', ['ring', 'cube'])
+    >>> invalid_keyword('loop', ['ring', 'cube'])
+    Traceback (most recent call last):
+    ...
+    ValueError: 'loop' is an invalid option. Please select one of: ring, cube.
+    """
+    if message is None:
+        message = (
+            " is an invalid option. Please select one of: "
+            + f"{', '.join(map(str, valid_keywords))}."
+        )
+    if keyword not in valid_keywords:
+        raise ValueError(f"'{keyword}'" + message)
+
+
+def number_density_cube(
+    n_atom: float, d_atom: float, l_cube: float, pbc: bool = False
+) -> float:
+    """
+    Compute the bulk number density of a species in a cubic box.
+
+    Parameters
+    ----------
+    n_atom : float
+        Number of particles.
+    d_atom : float
+        Diameter of the particle of the species.
+    l_cube : float
+        Length of one side of the cubic box.
+    pbc : bool
+        Periodic boundary conditions along all box sides. If `True`,
+        :math:`v_{avail} = l_{cube}^3`; otherwise,
+        :math:`v_{avail} = (l_{cube} - d_{atom})^3`. Defaults to `False`.
+
+    Returns
+    -------
+    float
+        Bulk number density of the species in the cubic box.
+
+    Raises
+    ------
+    ValueError
+        If the side available to particle centers, :math:`l_{cube}`, or
+        :math:`l_{cube} - d_{atom}` without `pbc`, is not positive.
+
+    Notes
+    -----
+    The bulk number density is calculated as :math:`n_{atom} / v_{avail}`,
+    where `v_{avail}` is the available volume to the center of geometry of a
+    particle based on the presence of periodic boundary conditions.
+
+    Examples
+    --------
+    >>> number_density_cube(1000, 1.0, 10.0)
+    1.3717421124828533
+    >>> number_density_cube(1000, 1.0, 10.0, pbc=True)
+    1.0
+    """
+    l_avail = l_cube - int(not pbc) * d_atom
+    if l_avail <= 0:
+        raise ValueError(
+            f"no room for particle centers: a particle of diameter {d_atom} "
+            f"in a cube of side {l_cube} (pbc={pbc}) leaves its center the "
+            f"side {l_avail}, which must be positive.")
+    v_avail = l_avail ** 3
+    return n_atom / v_avail
+
+
+def volume_fraction_cube(
+    n_atom: float, d_atom: float, l_cube: float, pbc: bool = False
+) -> float:
+    """
+    Compute the volume fraction of a species in a cubic box.
+
+    Parameters
+    ----------
+    n_atom : float
+        Number of particles.
+    d_atom : float
+        Diameter of the particle of the species.
+    l_cube : float
+        Length of one side of the cubic box.
+    pbc : bool
+        Periodic boundary conditions along all box sides. If `True`,
+        :math:`v_{avail} = l_{cube}^3`; otherwise,
+        :math:`v_{avail} = (l_{cube} - d_{atom})^3`. Defaults to `False`.
+
+    Returns
+    -------
+    float
+        Volume fraction of the species in the cubic box.
+
+    Raises
+    ------
+    ValueError
+        If the side available to particle centers is not positive, as
+        :func:`number_density_cube` raises.
+
+    Notes
+    -----
+    The available volume accounts for the excluded-volume boundary effect if
+    `pbc=False`, meaning particles cannot cross the box boundary. If
+    `pbc=True`, particles are assumed to wrap around, and the full box volume
+    is used.
+
+    The fraction is nominal: the particle volume over the volume available
+    to particle centers. It can exceed one, such as for a species nearly as
+    wide as the box, and is returned as it is.
+
+    Examples
+    --------
+    >>> volume_fraction_cube(1000, 1.0, 10.0)
+    0.718242490532646
+
+    >>> volume_fraction_cube(1000, 1.0, 10.0, pbc=True)
+    0.5235987755982988
+    """
+    rho = number_density_cube(n_atom, d_atom, l_cube, pbc)
+    return rho * np.pi * d_atom**3 / 6
+
+
+def number_density_cylinder(
+    n_atom: float, d_atom: float, l_cyl: float, d_cyl: float, pbc: bool = False
+) -> float:
+    """
+    Compute the bulk number density of a species in a cylindrical confinement.
+
+    Parameters
+    ----------
+    n_atom : float
+        Number of particles.
+    d_atom : float
+        Diameter of the particle of the species.
+    l_cyl : float
+        Length of the cylindrical confinement.
+    d_cyl : float
+        Diameter of the cylindrical confinement.
+    pbc : bool
+        Periodic boundary conditions along the longitudinal axis. If `True`,
+        :math:`v_{avail} = \\pi * l_{cyl} * (d_{cyl} - d_{atom})^2 / 4`;
+        otherwise, :math:`v_{avail} = \\pi * (l_{cyl} - d_{atom}) * (d_{cyl}
+        - d_{atom})^2 / 4`. Defaults to `False`.
+
+    Returns
+    -------
+    float
+        Bulk number density of the species in the cylindrical confinement.
+
+    Raises
+    ------
+    ValueError
+        If the effective diameter :math:`d_{cyl} - d_{atom}`, or the length
+        available to particle centers, :math:`l_{cyl}`, or
+        :math:`l_{cyl} - d_{atom}` without `pbc`, is not positive.
+
+    Notes
+    -----
+    The bulk number density is calculated as :math:`n_{atom} / v_{avail}`,
+    where `v_{avail}` is the available volume to the center of geometry of a
+    particle based on the presence of periodic boundary conditions.
+
+    Examples
+    --------
+    >>> number_density_cylinder(100, 1.0, 10.0, 5.0)
+    0.8841941282883075
+    >>> number_density_cylinder(100, 1.0, 10.0, 5.0, pbc=True)
+    0.7957747154594768
+    """
+    l_avail = l_cyl - int(not pbc) * d_atom
+    d_avail = d_cyl - d_atom
+    if l_avail <= 0 or d_avail <= 0:
+        raise ValueError(
+            f"no room for particle centers: a particle of diameter {d_atom} "
+            f"in a cylinder of length {l_cyl} and diameter {d_cyl} "
+            f"(pbc={pbc}) leaves its center the length {l_avail} and the "
+            f"diameter {d_avail}, which must both be positive.")
+    v_avail = np.pi * l_avail * d_avail ** 2 / 4
+    return n_atom / v_avail
+
+
+def volume_fraction_cylinder(
+    n_atom: float, d_atom: float, l_cyl: float, d_cyl: float, pbc: bool = False
+) -> float:
+    """
+    Compute the volume fraction of spherical particles in a cylindrical
+    confinement.
+
+    Parameters
+    ----------
+    n_atom : float
+        Number of particles.
+    d_atom : float
+        Diameter of a single particle.
+    l_cyl : float
+        Length of the cylindrical confinement (along the longitudinal axis).
+    d_cyl : float
+        Diameter of the cylindrical confinement (transverse direction).
+    pbc : bool, default False
+        Whether periodic boundary conditions are applied along the cylinder
+        axis. If `True`, the available volume is:
+
+        .. math::
+
+            V = \\frac{\\pi}{4} l_{cyl} (d_{cyl} - d_{atom})^2
+
+        If `False`, the available volume is:
+
+        .. math::
+
+            V = \\frac{\\pi}{4} (l_{cyl} - d_{atom}) (d_{cyl} - d_{atom})^2
+
+    Returns
+    -------
+    float
+        Volume fraction of the particles, defined as:
+
+        .. math::
+
+            \\phi = \\rho \\cdot \\frac{\\pi d^3}{6}
+
+        where :math:`\\rho` is the number density of particles in the
+        available cylindrical volume.
+
+    Raises
+    ------
+    ValueError
+        If the effective diameter or the available length is not positive,
+        as :func:`number_density_cylinder` raises.
+
+    Notes
+    -----
+    The available volume excludes regions where the particle centers cannot
+    access due to finite size. When `pbc=False`, particles are excluded from
+    the cylinder ends; when `pbc=True`, they are not.
+
+    The fraction is nominal: the particle volume over the volume available
+    to particle centers. It can exceed one, such as for large monomers in
+    single file in a cylinder barely wider than they are, and is returned as
+    it is.
+
+    Examples
+    --------
+    >>> volume_fraction_cylinder(100, 1.0, 10.0, 5.0)
+    0.46296296296296297
+
+    >>> volume_fraction_cylinder(100, 1.0, 10.0, 5.0, pbc=True)
+    0.4166666666666667
+    """
+    rho = number_density_cylinder(n_atom, d_atom, l_cyl, d_cyl, pbc)
+    return rho * np.pi * d_atom**3 / 6