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
|
Raise an error if keyword is not in valid_keywords. |
|
Normalize a format specifier into a tuple of extensions. |
|
Compute the bulk number density of a species in a cubic box. |
|
Compute the bulk number density of a species in a cylindrical confinement. |
|
Open a regular or gzipped file. |
|
Open a regular or gzipped file, providing a file-like object. |
|
Split a camelCase or CamelCase string into its component substrings. |
Round down number num to its first non-zero digit. |
|
|
Round dividend to the nearest multiple of divider, then to round_to decimal places. |
|
Group and alphanumerically sort filenames by basename across formats. |
|
Split an alphanumeric string into a list of strings, integers, and floats. |
|
Convert string to a float, or return it unchanged if it is not a number. |
|
Compute the volume fraction of a species in a cubic box. |
|
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:
keyword (
str) – The keyword to check.valid_keywords (
typing.Sequence[typing.Optional[str]]) – The accepted keywords.message (
typing.Optional[str]) – The text that follows the quoted keyword in theValueErrormessage; by default, a list of valid_keywords.
- Raises:
ValueError – If keyword is not in valid_keywords.
- Return type:
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:
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:
- 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:
- 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 togzip.open()for a path ending in.gzand toopen()otherwise.
- Returns:
The open file object, a
gzip.GzipFileor 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 togzip.open()for a path ending in.gzand toopen()otherwise.
- Yields:
InputType– The open file object, agzip.GzipFileor a regular file. The context manager closes it on exit, also after an exception.- Return type:
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:
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:
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_roundlabels thatpolyphys.manage.organizer.space_tseries()andpolyphys.manage.organizer.space_hists()add are made with it.- Parameters:
- 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:
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#roundExamples
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:
filenames (
typing.Iterable[str|os.PathLike[str]]) – Filenames/paths to sort and group.formats (
typing.Sequence[typing.Union[str,typing.Tuple[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 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:
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.0nc0and...epshc1.0nc500are 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.gzand.gz, goes to the group of the longer one.- Parameters:
- Return type:
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:
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:
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:
- 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:
- 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