Source code for polyphys.manage.utils

"""\
===============================================================
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',
]


[docs] 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)
[docs] 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
[docs] 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 ]
[docs] 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)
[docs] 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
[docs] 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)
[docs] @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()
[docs] 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))) )
[docs] 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)
[docs] 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)
[docs] 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
[docs] 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
[docs] 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
[docs] 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