thermopt.utilities.file_utils module

exception thermopt.utilities.file_utils.DictionaryValidationError(message, key=None, value=None)

Bases: Exception

Exception raised for errors in the configuration options.

thermopt.utilities.file_utils.add_string_to_keys(input_dict, suffix)

Add a suffix to each key in the input dictionary.

Parameters:

input_dict (dict): The input dictionary.

suffix (str): The string to add to each key.

Returns:

dict: A new dictionary with modified keys.

Examples

>>> input_dict = {'a': 1, 'b': 2, 'c': 3}
>>> add_string_to_keys(input_dict, '_new')
{'a_new': 1, 'b_new': 2, 'c_new': 3}

thermopt.utilities.file_utils.check_for_unused_keys(dict_in, dict_name, raise_error=False)

Checks for unused parameters in the given dictionaries and sub-dictionaries. If unused items are found, prints them in a tree-like structure and optionally raises an error.

Parameters:

dict_indict

The dictionary of parameters to check.

dict_namestr

The name of the dictionary variable.

raise_errorbool, optional

If True, raises an exception when unused items are found, otherwise just prints a warning.

Returns:

None

thermopt.utilities.file_utils.compare_contents_or_files(file_or_content_1, file_or_content_2)

Compare the content of two inputs, which can be either file paths or strings.

This function accepts two arguments. Each argument can be: 1. A file path pointing to a file containing text content. 2. A string containing text content directly.

If the argument is a file path that exists, the function reads its content. If the argument is a string, it’s directly used for comparison.

Parameters:

file_or_content1str

First input which can be a file path or string content.

file_or_content2str

Second input which can be a file path or string content.

Returns:

bool

True if the contents of the two inputs are identical, False otherwise.

Examples

>>> content_same("path/to/file1.txt", "path/to/file2.txt")
True
>>> content_same("Hello, world!", "path/to/file_with_hello_world_content.txt")
True
>>> content_same("Hello, world!", "Goodbye, world!")
False

thermopt.utilities.file_utils.convert_numpy_to_python(data, precision=10)

Recursively converts numpy arrays, scalars, and other numpy types to their Python counterparts and rounds numerical values to the specified precision.

Parameters: - data: The numpy data to convert. - precision: The decimal precision to which float values should be rounded.

Returns: - The converted data with all numpy types replaced by native Python types and float values rounded.

thermopt.utilities.file_utils.create_logger(name, path=None, use_datetime=True)

Creates and configures a logging object for recording logs during program execution.

Parameters:

namestr

Name of the log file. Allows for differentiation when analyzing logs from different components or runs of a program.

pathstr, optional

Specifies the directory where the log files will be saved. By default, a directory named “logs” will be created in the current working directory (cwd).

use_datetimebool, optional

Determines whether the log filename should have a unique datetime identifier appended. Default is True.

Returns:

loggerobject

Configured logger object.

Notes

• By default, the function sets the log level to INFO, which means the logger will handle messages of level INFO and above (like ERROR, WARNING, etc.). The log entries will contain the timestamp, log level, and the actual log message.

• When use_datetime=True, each log file will have a unique datetime identifier. This ensures traceability, avoids overwriting previous logs, allows chronological ordering of log files, and handles concurrency in multi-instance environments.

thermopt.utilities.file_utils.dump_object_structure(obj, log_file, max_depth=5, _seen=None, _path='root', _depth=0)

Recursively print the structure, types, and values of an object into a log file.

Parameters:

objany

The object to inspect.

log_filestr

Path to the output log file.

max_depthint

Maximum recursion depth to avoid excessive nesting.

thermopt.utilities.file_utils.find_latest_results_file(results_path, prefix='performance_analysis_')

Retrieve all files that match the given prefix and extension .xlsx

thermopt.utilities.file_utils.is_dict_empty(data)

Recursively checks if a dictionary and all its sub-dictionaries are empty.

Parameters:

datadict

The dictionary to check.

Returns:

bool

True if the dictionary and all sub-dictionaries are empty, False otherwise.

thermopt.utilities.file_utils.load_from_pickle(filepath)

Load a Python object from a pickle file.

Parameters:

filepathstr or Path

Full path to the pickle file.

Returns:

Any

The Python object stored in the pickle file.

thermopt.utilities.file_utils.print_dict(data, indent=0, return_output=False)

Recursively prints nested dictionaries with indentation or returns the formatted string.

Parameters:

datadict

The dictionary to print.

indentint, optional

The initial level of indentation for the keys of the dictionary, by default 0.

return_outputbool, optional

If True, returns the formatted string instead of printing it.

Returns:

str or None

The formatted string representation of the dictionary if return_output is True, otherwise None.

thermopt.utilities.file_utils.print_object(obj)

Prints all attributes and methods of an object, sorted alphabetically.

• Methods are identified as callable and printed with the prefix ‘Method: ‘.

• Attributes are identified as non-callable and printed with the prefix ‘Attribute: ‘.

Parameters:

objobject

The object whose attributes and methods are to be printed.

Returns:

None

This function does not return any value. It prints the attributes and methods of the given object.

thermopt.utilities.file_utils.save_to_pickle(obj, filepath, timestamp=True)

Save a Python object to a pickle file.

Parameters:

objAny

The Python object to be saved.

timestampbool, optional

Whether to append a timestamp before the extension. Default is True.

Returns:

str

The full path to the saved pickle file.

thermopt.utilities.file_utils.validate_keys(checked_dict, required_keys, allowed_keys=None)

Validate the presence of required keys and check for any unexpected keys in a dictionary.

Give required keys and allowed keys to have complete control Give required keys twice to check that the list of keys is necessary and sufficient Give only required keys to allow all extra additional key

Parameters:

checked_dictdict

The dictionary to be checked.

required_keysset

A set of keys that are required in the dictionary.

allowed_keysset

A set of keys that are allowed in the dictionary.

Raises:

ConfigurationError

If either required keys are missing or unexpected keys are found.

thermopt.utilities.file_utils.wait_for_file(file_path, timeout=None, poll_interval=0.1)

Wait until the specified file is created.

This function is used to wait until a file is created.

Parameters:

file_pathstr

Path to the file to wait for.

timeoutfloat, optional

Maximum time to wait in seconds. If None, waits indefinitely.

poll_intervalint, optional

Time interval between checks in seconds.

Returns:

bool

True if the file was found, False otherwise (only if timeout is set).