Utility functions#

The following utility functions are available in CVXlab:

cvxlab.create_model_dir(model_dir_name: str, main_dir_path: str, force_overwrite: bool = False, include_user_operators_template: bool = False, include_user_constants_template: bool = False, template_file_type: Literal['yml', 'xlsx'] = 'yml') → None[source]#

Create a model directory with template configuration files.

This function creates a new model directory with the specified name under the given main directory path. It can generate template configuration files in either YAML or Excel format. If the directory already exists, it can be overwritten based on user confirmation or the force_overwrite flag. Optionally, supplementary files can be copied into the new model directory (user defined operators/constants functions template).

Parameters:

  • model_dir_name (str) – The name of the model directory to create.

  • main_dir_path (str) – The path to the main directory where the model directory will be created.

  • force_overwrite (bool, optional) – If True, overwrite existing directory without confirmation. Defaults to False.

  • include_user_operators_template (bool, optional) – If True, copy a user-defined operators template file into the new model directory. Defaults to False.

  • include_user_constants_template (bool, optional) – If True, copy a user-defined constants template file into the new model directory. Defaults to False.

  • template_file_type (Literal['yml', 'xlsx'], optional) – The type of template configuration file to generate (‘yml’ or ‘xlsx’). Defaults to ‘yml’.

Raises:

ValueError – If the template file type is unsupported.

cvxlab.copy_utility_files(path_destination: Path, include_custom_operators_template: bool = False, include_custom_constants_template: bool = False) → None[source]#

Copy utility files to the model directory.

This function copy utility files such as templates for user-defined custom operators and constants to a defined path, based on the provided flags.

Parameters:

  • path_destination (Path) – The path to the model directory where the files will be included.

  • include_custom_operators_template (bool, optional) – If True, include the template for user-defined custom operators to the model directory. Defaults to False.

  • include_custom_constants_template (bool, optional) – If True, include the template for user-defined custom constants to the model directory. Defaults to False.

cvxlab.transfer_setup_info_xlsx(source_file_name: str, source_dir_path: str | Path, destination_dir_path: str | Path, update: Literal['settings', 'sets', 'all'] = 'all') → None[source]#

Transfer setup information from an Excel file.

This function transfers setup information from a source Excel file to existing configuration files in a destination directory. It can update either the settings file, the sets file, or both, based on user input. If the destination files already exist, the user is prompted for confirmation before overwriting them.

This function is useful for complex model settings, in order to avoid direct modifications in setup files, allows the user to work in a separate Excel file and then transfer the relevant information to the model’s configuration files before running the model.

Parameters:

  • source_file_name (str) – The name of the source Excel file.

  • source_dir_path (str | Path) – The directory path of the source file.

  • destination_dir_path (str | Path) – The directory path where the configuration files are located.

  • update (Literal['settings', 'sets', 'all'], optional) – Specifies which files to update: ‘settings’, ‘sets’, or ‘all’. Defaults to ‘all’.

Raises:

FileNotFoundError – If the source file or destination files do not exist.

cvxlab.handle_model_instance(action: Literal['save', 'load'], file_name: str, source_dir_path: Path | str | None = None, instance: Model | None = None) → Model | None[source]#

Save or load model instances.

This function allows saving a model instance to a file or loading a model instance from a file. Model instances are automatically saved in the model’s directory (defined in instance path attribute). When loading, the user must provide the source directory path.

Parameters:

  • action (Literal['save', 'load']) – The action to perform, either ‘save’ or ‘load’.

  • file_name (str) – The name of the file to save/load the model instance.

  • source_dir_path (str | Path, optional) – The directory path to load the model instance from. Required if action is ‘load’.

  • instance (Model, optional) – The model instance to save. Required if action is ‘save’.

Returns:

The loaded model instance if action is ‘load’, otherwise None.

Return type:

Model | None

Raises:

  • ValueError – If the action is invalid or required parameters are missing.

  • ValueError – If the model instance is invalid when saving.