src.utils module

Utility functions for I/O operations and data manipulation.

This module provides functions for:

• Logging messages

• Modifying NumPy structured arrays

• Exporting data to CSV/XLSX formats

• Finding closest cells in a mesh

• Creating constraint functions

Functions

write_log : Log messages at different levels. modify_structured_array : Rename/delete columns in arrays. export_structured_array : Export arrays to CSV/XLSX. find_closest_cell : Find closest mesh cell to a point. simulation_cleanup : Remove simulation output files. create_constraint_function : Create constraint functions.

src.utils.create_constraint_function(expr: str, variables: list)

Create a constraint function from a user-provided logical expression.

Parameters:

• expr (str) – The logical expression (e.g., “x > y”).

• variables (list) – Names of variables in the expression.

Returns:

A function that evaluates the constraint.

Return type:

function

Example

>>> f = create_constraint_function("x > y", ['x', 'y'])
>>> f([2, 1])
True

src.utils.export_structured_array(array, file_path)

Export a structured NumPy array to a CSV or XLSX file.

Parameters:

• array (np.ndarray) – The structured array to export.

• file_path (str) – The full output file path.

Raises:

ValueError – If input is not a structured array or format is unsupported.

src.utils.find_closest_cell(centroids: ndarray, point: tuple, npoints: int = 3, distance: bool = False) → ndarray | tuple[ndarray, ndarray]

Find the closest cell to a given point based on centroid coordinates.

Parameters:

• centroids (np.ndarray) – 2D array of shape (n, 2) with x, y coordinates.

• point (tuple) – Coordinates (x, y) of the reference point.

• npoints (int) – Number of closest cells to find.

• distance (bool) – If True, returns distances along with indices.

Returns:

Index of closest cell, or (indices, distances) if distance=True.

Return type:

int or tuple

Example

>>> centroids = np.array([[0, 0], [1, 1], [2, 2]])
>>> find_closest_cell(centroids, (1.5, 1.5))
array([2])

src.utils.modify_structured_array(arr, rename_dict=None, delete_cols=None)

Modify a structured NumPy array by renaming and/or deleting columns.

Parameters:

• arr (np.ndarray) – The structured array to modify.

• rename_dict (dict, optional) – Dictionary mapping old to new column names.

• delete_cols (list, optional) – List of column names to delete.

Returns:

The modified structured array.

Return type:

np.ndarray

src.utils.nested_defaultdict()

Create a nested defaultdict.

Returns:

A defaultdict with dict as the default factory.

Return type:

defaultdict

src.utils.print_and_export_column_names(arr)

Print and return column names from a structured array.

Parameters:

arr (np.ndarray) – A structured NumPy array.

Returns:

Set of column names.

Return type:

set

src.utils.simulation_cleanup(simulation_folder: str) → None

Clean up the simulation folder by deleting result files.

Parameters:

simulation_folder (str) – Path to the simulation folder.

Returns:

None

src.utils.write_log(logger, message: str, level: str = 'info', silent: bool = False)

Logs the message using the specified level.

Parameters:

• logger – The logger object to use for logging.

• message (str) – The message to log.

• level (str) – The logging level (‘info’, ‘debug’, ‘error’, etc.).

• silent (bool) – If True, suppresses logging (except errors).