pywellsfm.utils

The pywellsfm.utils package provides small helper utilities used across pyWellSFM (convenience functions, formatting, and general-purpose helpers).

Files documented

This page is built from the following Python modules:

geometry.py (pywellsfm.utils.geometry)
interpolation.py (pywellsfm.utils.interpolation)
logging_utils.py (pywellsfm.utils.logging_utils)

API reference

class pywellsfm.utils.geometry.IntervalDistanceMethod(*values)

Bases: StrEnum

static _generate_next_value_(name, start, count, last_values): Return the lower-cased version of the member name.

CENTER = 'center'

GAP = 'gap'

GAP_OVERLAPPING_WIDTH = 'gap_overlapping_width'

GAP_TIMES_CENTER = 'gap_times_center'

HAUSDORFF = 'hausdorff'

WASSERSTEIN2 = 'wasserstein2'

pywellsfm.utils.geometry.center_distance(min1: float, max1: float, min2: float, max2: float) → float

Compute the center distance between two intervals.

\[\delta = \left|\frac{\text{min}_1 + \text{max}_1}{2} - \frac{\text{min}_2 + \text{max}_2}{2}\right|\]

Returns 0 when the two intervals are identical.

pywellsfm.utils.geometry.gap_distance(min1: float, max1: float, min2: float, max2: float) → float

Compute the gap distance between two intervals.

\[\delta = \max(0, \text{min}_2 -\text{max}_1, \text{min}_1-\text{max}_2)\]

Returns 0 when the two intervals overlap.

pywellsfm.utils.geometry.gap_overlapping_width_distance(min1: float, max1: float, min2: float, max2: float) → float

Compute the distance between two intervals based on gap function.

Considering two intervals \([min_1, max_1]\) and \([min_2, max_2]\) if they do not overlap, the distance is defined as the gap distance + 1. If they overlap, the distance is defined as 1 minus the overlapping width divided by the width of the union of the two intervals such as it is comprised between 0 (same intervals) and 1.

Returns 0 when the two intervals are identical.

pywellsfm.utils.geometry.gap_times_center_distance(min1: float, max1: float, min2: float, max2: float) → float

Compute the gap times center distance between two intervals.

\[\delta = \delta_{\text{gap}} \cdot \delta_{\text{center}}\]

where \(\delta_{\text{gap}}\) is the gap distance and \(\delta_{\text{center}}\) is the center distance between the intervals.

Returns 0 when the two intervals overlap.

pywellsfm.utils.geometry.hausdorff_distance(min1: float, max1: float, min2: float, max2: float) → float

Compute the Hausdorff distance between two intervals.

\[\delta = \max\left( |\text{min}_1 - \text{min}_2|, |\text{max}_1 - \text{max}_2| \right)\]

Returns 0 when the two intervals are identical.

pywellsfm.utils.geometry.wasserstein2_distance(min1: float, max1: float, min2: float, max2: float) → float

Compute the Wasserstein-2 distance between two intervals.

\[\delta = \max\left( |\text{min}_1 - \text{min}_2|, |\text{max}_1 - \text{max}_2| \right)\]

Returns 0 when the two intervals are identical.

class pywellsfm.utils.interpolation.Interpolator

Bases: Protocol

Interpolator parent class for a 1D increasing function.

initialize(x: ndarray[tuple[Any, ...], dtype[float64]], y: ndarray[tuple[Any, ...], dtype[float64]]) → None

Initialize function sampled points.

Input points are sorted in ascending order.

Parameters:

x (npt.NDArray[np.float64]) – sampled x coordinates. Must contains at least 2 elements.
y (npt.NDArray[np.float64]) – sampled y coordinates. Must contains at least 2 elements and have the same size as x.

setAdditionalArgs(**args: Any) → None

Add any additional parameters the interpolator would require.

Parameters:: args (Any) – dictionnary of additional arguments

_abc_impl = <_abc._abc_data object>

_is_protocol = True

_x_max: float

_x_min: float

name: str = ''

x: ndarray[tuple[Any, ...], dtype[float64]]

y: ndarray[tuple[Any, ...], dtype[float64]]

class pywellsfm.utils.interpolation.LinearInterpolator

Bases: Interpolator

Linear interpolator for a 1D increasing function.

_abc_impl = <_abc._abc_data object>

_is_protocol = False

class pywellsfm.utils.interpolation.LowerBoundInterpolator

Bases: Interpolator

Lower bound interpolator for a 1D increasing function.

_abc_impl = <_abc._abc_data object>

_is_protocol = False

class pywellsfm.utils.interpolation.PolynomialInterpolator

Bases: Interpolator

Polynomial interpolator for a 1D increasing function.

initialize(x: ndarray[tuple[Any, ...], dtype[float64]], y: ndarray[tuple[Any, ...], dtype[float64]]) → None

Initialization method.

Parameters:

x (npt.NDArray[np.float64]) – sampled x coordinates. Must contains at least 2 elements.
y (npt.NDArray[np.float64]) – sampled y coordinates. Must contains at least 2 elements and have the same size as x.
deg (int) – polynom degree, defaults to 1
nbPts (int) – number of points at each side of evaluated value to compute the polynom fit. 2*nbPts must be strictly greater than the polynom degree. Defaults to 1.

setAdditionalArgs(**args: Any) → None

Set additional inputs for the Interpolator.

Parameters:: args (Any) – dictionnary of additional arguments

_abc_impl = <_abc._abc_data object>

_is_protocol = False

deg: int

nbPts: int

class pywellsfm.utils.interpolation.UpperBoundInterpolator

Bases: Interpolator

Upper bound interpolator for a 1D increasing function.

_abc_impl = <_abc._abc_data object>

_is_protocol = False

Package logging helpers and in-memory log retention.

class pywellsfm.utils.logging_utils.StoredLogsHandler

Bases: Handler

In-memory log handler storing structured records.

clear() → None: Clear retained records.

emit(record: LogRecord) → None

Emit a log record.

Parameters:: record (logging.LogRecord) – The log record to be emitted.

get_records() → list[dict[str, Any]]: Return a copy of all retained records.

pywellsfm.utils.logging_utils._default_formatter() → Formatter

pywellsfm.utils.logging_utils._ensure_handlers(level: int, enable_console: bool) → Logger

pywellsfm.utils.logging_utils.clear_stored_logs() → None: Clear retained logs from in-memory storage.

pywellsfm.utils.logging_utils.configure_logging(*, level: int = 20, enable_console: bool = True) → Logger: Configure package logging and return the package logger.

pywellsfm.utils.logging_utils.export_stored_logs(filepath: str | Path, *, format: str = 'text', append: bool = False, encoding: str = 'utf-8') → Path

Export retained logs to a file.

Supported formats are:

text: one formatted message per line
json: structured list of records

pywellsfm.utils.logging_utils.export_stored_logs_to_json_file(filepath: str | Path, *, encoding: str = 'utf-8') → Path: Export retained logs to a JSON file.

pywellsfm.utils.logging_utils.export_stored_logs_to_text_file(filepath: str | Path, *, append: bool = False, encoding: str = 'utf-8') → Path: Export retained logs to a text file.

pywellsfm.utils.logging_utils.get_logger(name: str | None = None) → Logger: Get a package logger or a package child logger.

pywellsfm.utils.logging_utils.get_stored_log_messages() → list[str]: Return retained logs as formatted single-line messages.

pywellsfm.utils.logging_utils.get_stored_logs() → list[dict[str, Any]]: Return retained logs as structured dictionaries.

pywellsfm.utils.logging_utils.set_log_level(level: int) → None: Update the package logger level.