"""\
===============================================================
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