helpers package

helpers.config module

Core configuration management for the project.

This module centralises all configuration handling using the Dynaconf library. It loads settings from multiple sources, including default TOML files, local overrides, and secrets. It also provides a custom loader to import specific experimental scenarios from an Excel file based on a configuration ID.

Furthermore, it includes utility functions for: - Saving the current configuration state to a file for reproducibility. - Setting up a flexible logging system based on an external config file. - Generating standardised, run-specific output paths for both local and

remote (cluster) environments.

Authors:
settings_loader(settings, filename, config_id, delimiter=',')[source]

This function serves as a custom loader for Dynaconf. It reads a specified Excel file, finds the row matching the given config_id, and updates the settings object with the values from that row. String values containing the specified delimiter are automatically split into lists.

Parameters:
settings: Dynaconf

The Dynaconf settings object to be updated.

filename: str

The path to the Excel scenario file.

config_id: int

The ID of the configuration row to load from the Excel file.

delimiter: str, optional

The delimiter used to split string values into lists, by default “,”.

load_config_for_id(config_id)[source]

Loads a specific scenario configuration from the project’s Excel file. This is a convenience wrapper around settings_loader that uses the scenario file path defined in the global settings.

Parameters:
config_idint

The ID of the configuration to load.

output_conf(settings_to_output=None)[source]

Writes the current settings configuration and history to files. This function serialises the state of a Dynaconf settings object to disk, creating two files: one with the current configuration (including Git repo info) and another with the full settings history (how values were loaded and merged).

Parameters:
settings_to_outputDynaconf, optional

The settings object to output. If None, the global settings object is used, by default None.

Other Parameters:
settings.output.output_settings_pathstr

The subfolder within the run’s output path to save the files.

settings.output.output_settings_filenamestr

The filename for the current settings dump.

settings.output.output_settingshistory_filenamestr

The filename for the settings history dump.

Notes

The ‘other parameters’ are taken from the global settings object.

stop_dynaconf_evaluation()[source]

Disables Dynaconf’s deep evaluation feature. This function is a performance optimisation. It disables the deep evaluation of settings values in Dynaconf after all necessary configurations have been loaded, which can prevent costly re-evaluations.

config_logging()[source]

Configures the project’s logging system from a file. This function initialises the Python logging framework using a configuration file specified in the settings. It dynamically re-routes file handlers to write logs to run-specific files, ensuring that logs from different runs and modules are kept separate.

get_output_path(runid=None, subfolder=None, task=None, createfolder=True)[source]

Defines the output path for output data, logging, settings storage, slurm files. If not existing, the folder is created.

Parameters:
runid: int or string

the run ID the output data is associated with. To refer to “RS” runs, the runid may be a string such as “RS0912”.

subfolder: str

last part of the output folder

createfolder: bool

If True, the folder will be created if non-existent

Returns:
str

The absolute path to the designated output directory.

Other Parameters:
- settings.main.runid
- settings.main.task
- settings.main.output_path
- settings.main.output_path_custom
get_cluster_output_path(runid=0, subfolder=None)[source]

Returns the output folder of output data, logging, settings storage, slurm files on the cluster

Parameters:
runid: int

the run ID the output data is associated with

subfolder: str

last part of the output folder

createfolder: bool

If True, the folder will be created if non-existent

Returns:
str:

cluster output path

Other Parameters:
- settings.slurm.target_cluster_mainpath
- settings.main.project,
- settings.main.task

helpers.i18n module

Handles localisation for the project.

This module sets up the translation framework using Python’s built-in gettext library. It locates the translation files, configures the desired language based on the global settings (settings.eval.language), and provides a translation function, conventionally named _. This function can be imported and used throughout the project to mark strings for translation.

Authors:

helpers.information module

Provides functions to retrieve project and system information.

This module contains utility functions for gathering metadata about the project’s version and the runtime environment. It can retrieve the current Git version (either from a tag or commit hash) and monitor the process’s peak memory usage in a platform-independent manner.

Authors:
get_git_version()[source]

Retrieves current version from tag or commit identifier

Returns:
str

current version

get_peak_memory_use()[source]

Return the peak memory usage of the current process in bytes.

Returns:
int: Peak memory usage in bytes

helpers.utils module

A collection of miscellaneous utility functions for the project.

This module provides various helper functions that support different parts of the application. Responsibilities include dynamically loading classes, generating standardized filenames for output data and images, converting data formats, and implementing specific model-related calculations.

Authors:
load_class(module_name, class_name)[source]

This function imports a module by its string name and then retrieves a class from that module, also by its string name. This allows for flexible instantiation of objects based on configuration settings.

Parameters:
module_namestr

The name of the module to import.

class_namestr

The name of the class to retrieve from the module.

Returns:
class

The requested class object.

get_file_name(run_id: int = None) → str[source]

This function creates a unique filename based on the project’s configuration settings. The name can be a simple run ID or a more descriptive name including the scenario ID and random seeds, depending on the settings.output.simplenames flag.

Parameters:
run_idint, optional

The ID of the run. If not provided, the run_id from the global settings is used.

Returns:
str

The generated filename without an extension.

get_images_name(milieu: str = None) → str[source]

Creates a unique name for an image based on the current run ID, file prefix, and scenario ID from the global settings. An optional ‘milieu’ string can be included to further specify the image content.

Parameters:
milieustr, optional

A string identifier to append to the image name, by default None.

Returns:
str

The generated image name without an extension.

pickle_to_hdf5(resulttype='model')[source]

This function scans output directories for pickled pandas DataFrames based on a set of scenarios, run IDs, and file prefixes defined in the global settings. It reads each pickle file and stores its contents in a single HDF5 file, which is more efficient for querying and analysis.

Parameters:
resulttypestr, optional

A string that is part of the pickle filename to identify the type of result to process (e.g., ‘model’ or ‘agent’), by default “model”.

influence_by_relative_agreement(source_system, target_system, exposure=1)[source]

This function models knowledge exchange between two houseowners related to a single system type. It updates the parameters (opinion and uncertainty) of a target_system based on the parameters of a source_system. The update is governed by the overlap between their uncertainty intervals, and the strength of the influence is controlled by the exposure parameter. Based on Relative Agreement approach.

Parameters:
source_systemHeating_system

The system that exerts influence.

target_systemHeating_system

The system that is being influenced. Its parameters will be modified in-place.

exposurefloat, optional

A coefficient determining the strength of the influence, by default 1.

helpers.warnings_custom module

This module modifies how warnings are handled and displayed throughout the project. Based on configuration settings, it can simplify the format of warning messages to make them more readable or escalate specific types of warnings into exceptions to enforce stricter code quality during debugging.

Authors:
custom_formatwarning(msg, *args, **kwargs)[source]

This function overrides the default multi-line warning format. It discards all parts of the warning except for the message itself and prepends the message with its type (e.g., ‘DeprecationWarning’).

Parameters:
msg: Warning

The warning message object.

*args: tuple

Additional arguments (ignored).

**kwargs: dict

Additional keyword arguments (ignored).

Returns:
str

The formatted, single-line warning string.

Module contents