polyphys.manage.utils#

Miscellaneous utility codes — polyphys.manage.utils#

The 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: read_camel_case(), to_float_if_possible(), split_alphanumeric(), normalize_exts(), and sort_filenames().

File handling: openany() and openany_context().

Numeric rounding and validation: round_down_first_non_zero(), round_to_multiple(), and invalid_keyword().

Number-density and volume-fraction conversions: number_density_cube(), volume_fraction_cube(), number_density_cylinder(), and volume_fraction_cylinder().

Dependencies#

  • Python standard library: re, gzip, contextlib, typing

  • Third-party: numpy

See also: types for the definition of InputType.

Functions

invalid_keyword(keyword, valid_keywords[, ...])

Raise an error if keyword is not in valid_keywords.

normalize_exts(exts)

Normalize a format specifier into a tuple of extensions.

number_density_cube(n_atom, d_atom, l_cube)

Compute the bulk number density of a species in a cubic box.

number_density_cylinder(n_atom, d_atom, ...)

Compute the bulk number density of a species in a cylindrical confinement.

openany(filepath[, mode])

Open a regular or gzipped file.

openany_context(filepath[, mode])

Open a regular or gzipped file, providing a file-like object.

read_camel_case(string)

Split a camelCase or CamelCase string into its component substrings.

round_down_first_non_zero(num)

Round down number num to its first non-zero digit.

round_to_multiple(dividend, divider, round_to)

Round dividend to the nearest multiple of divider, then to round_to decimal places.

sort_filenames(filenames, formats)

Group and alphanumerically sort filenames by basename across formats.

split_alphanumeric(alphanumeric)

Split an alphanumeric string into a list of strings, integers, and floats.

to_float_if_possible(string)

Convert string to a float, or return it unchanged if it is not a number.

volume_fraction_cube(n_atom, d_atom, l_cube)

Compute the volume fraction of a species in a cubic box.

volume_fraction_cylinder(n_atom, d_atom, ...)

Compute the volume fraction of spherical particles in a cylindrical confinement.

polyphys.manage.utils.invalid_keyword(keyword, valid_keywords, message=None)[source]#

Raise an error if keyword is not in valid_keywords.

Parameters:
Raises:

ValueError – If keyword is not in valid_keywords.

Return type:

None

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.
polyphys.manage.utils.normalize_exts(exts)[source]#

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 (typing.Union[str, typing.Tuple[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:

Normalized tuple of extensions, all dot-prefixed.

Return type:

typing.Tuple[str, ...]

Examples

>>> normalize_exts("npy")
('.npy',)
>>> normalize_exts(("trj", ".lammpstrj"))
('.trj', '.lammpstrj')
polyphys.manage.utils.number_density_cube(n_atom, d_atom, l_cube, pbc=False)[source]#

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, \(v_{avail} = l_{cube}^3\); otherwise, \(v_{avail} = (l_{cube} - d_{atom})^3\). Defaults to False.

Returns:

Bulk number density of the species in the cubic box.

Return type:

float

Raises:

ValueError – If the side available to particle centers, \(l_{cube}\), or \(l_{cube} - d_{atom}\) without pbc, is not positive.

Notes

The bulk number density is calculated as \(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
polyphys.manage.utils.number_density_cylinder(n_atom, d_atom, l_cyl, d_cyl, pbc=False)[source]#

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, \(v_{avail} = \pi * l_{cyl} * (d_{cyl} - d_{atom})^2 / 4\); otherwise, \(v_{avail} = \pi * (l_{cyl} - d_{atom}) * (d_{cyl} - d_{atom})^2 / 4\). Defaults to False.

Returns:

Bulk number density of the species in the cylindrical confinement.

Return type:

float

Raises:

ValueError – If the effective diameter \(d_{cyl} - d_{atom}\), or the length available to particle centers, \(l_{cyl}\), or \(l_{cyl} - d_{atom}\) without pbc, is not positive.

Notes

The bulk number density is calculated as \(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
polyphys.manage.utils.openany(filepath, mode='rt')[source]#

Open a regular or gzipped file.

Parameters:
  • filepath (str) – Path to the file.

  • mode (str) – File-opening mode, passed to gzip.open() for a path ending in .gz and to open() otherwise.

Returns:

The open file object, a gzip.GzipFile or a regular file. The caller must close it; openany_context() does that.

Return type:

typing.Union[gzip.GzipFile, typing.TextIO, typing.IO[typing.Any]]

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'
polyphys.manage.utils.openany_context(filepath, mode='rt')[source]#

Open a regular or gzipped file, providing a file-like object.

Parameters:
  • filepath (str) – Path to the file.

  • mode (str) – File-opening mode, passed to gzip.open() for a path ending in .gz and to open() otherwise.

Yields:

InputType – The open file object, a gzip.GzipFile or a regular file. The context manager closes it on exit, also after an exception.

Return type:

Generator[GzipFile | TextIO | IO[Any], None, None]

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)
polyphys.manage.utils.read_camel_case(string)[source]#

Split a camelCase or CamelCase string into its component substrings.

Parameters:

string (str) – The camelCase or CamelCase string to be split.

Returns:

The split string with substrings as elements.

Return type:

typing.List[typing.Union[str, typing.Tuple[str]]]

Examples

>>> read_camel_case("camelCase")
['camel', 'Case']
>>> read_camel_case("CamelCaseString")
['Camel', 'Case', 'String']
polyphys.manage.utils.round_down_first_non_zero(num)[source]#

Round down number num to its first non-zero digit.

Parameters:

num (float) – Number which is rounded.

Returns:

The number num rounded down to its first non-zero digit.

Return type:

float

Examples

>>> float(round_down_first_non_zero(0.0372))
0.03
>>> float(round_down_first_non_zero(472.0))
400.0
polyphys.manage.utils.round_to_multiple(dividend, divider, round_to)[source]#

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 polyphys.manage.organizer.space_tseries() and 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:

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 round() does.

Return type:

float

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 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)
polyphys.manage.utils.sort_filenames(filenames, formats)[source]#

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:
Returns:

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.

Return type:

typing.List[typing.Tuple[pathlib.Path, ...]]

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.

Parameters:
Return type:

List[Tuple[Path, …]]

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
polyphys.manage.utils.split_alphanumeric(alphanumeric)[source]#

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:

A list of components including integers, floats, and strings.

Return type:

typing.List[typing.Union[int, str, float]]

Examples

>>> split_alphanumeric("file20.5name10")
['file', 20.5, 'name', 10]
polyphys.manage.utils.to_float_if_possible(string)[source]#

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:

The converted float if the input can be converted; otherwise, the original string.

Return type:

typing.Union[float, str]

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
polyphys.manage.utils.volume_fraction_cube(n_atom, d_atom, l_cube, pbc=False)[source]#

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, \(v_{avail} = l_{cube}^3\); otherwise, \(v_{avail} = (l_{cube} - d_{atom})^3\). Defaults to False.

Returns:

Volume fraction of the species in the cubic box.

Return type:

float

Raises:

ValueError – If the side available to particle centers is not positive, as 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
polyphys.manage.utils.volume_fraction_cylinder(n_atom, d_atom, l_cyl, d_cyl, pbc=False)[source]#

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) –

    Whether periodic boundary conditions are applied along the cylinder axis. If True, the available volume is:

    \[V = \frac{\pi}{4} l_{cyl} (d_{cyl} - d_{atom})^2\]

    If False, the available volume is:

    \[V = \frac{\pi}{4} (l_{cyl} - d_{atom}) (d_{cyl} - d_{atom})^2\]

Returns:

Volume fraction of the particles, defined as:

\[\phi = \rho \cdot \frac{\pi d^3}{6}\]

where \(\rho\) is the number density of particles in the available cylindrical volume.

Return type:

float

Raises:

ValueError – If the effective diameter or the available length is not positive, as 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