Utility functions#

The following utility functions are available in CVXlab:

Guided interface#

CVXlab provides a guided interactive interface that walks through the entire modeling workflow via a menu-driven session. This is the simplest way to get started with CVXlab, requiring no prior knowledge of the package APIs.

cvxlab.run(
model_dir_name=None,
main_dir_path=None,
model_settings_from=None,
detailed_validation=None,
multiple_input_files=None,
input_data_files_type=None,
log_level=None,
log_format=None,
solver=None,
solver_verbose=None,
solver_settings=None,
integrated_problems=None,
convergence_monitoring=None,
convergence_norm=None,
convergence_tables_to_check=None,
convergence_tables_to_skip=None,
relative_tolerance=None,
maximum_iterations=None,
keep_previous_iteration_db=None,
model_structure_file=None,
template_file_type=None,
)[source]#

Launch the CVXlab guided user interface.

All parameters are optional. When provided, they override the corresponding defaults in Model.__init__ or Model.run_model(). Parameters left as None are omitted, letting the backend apply its own defaults (or let the user specify them at runtime).

Parameters:

  • model_dir_name (str, optional) – The name of the model directory.

  • main_dir_path (str, optional) – The main directory path where the model directory is located. If None, the current working directory is used.

  • model_settings_from (Literal['yml', 'xlsx'], optional) – The format of the model settings file. Can be either ‘yml’ or ‘xlsx’.

  • detailed_validation (bool, optional) – If True, performs detailed validation logging of data and model settings during initialization.

  • multiple_input_files (bool, optional) – If True, input data Excel files are generated as one file per data table. If False, all data tables are generated in a single Excel file with multiple tabs.

  • input_data_files_type (Literal['xlsx', 'csv'], optional) – The format of the input data files.

  • log_level (Literal['info', 'debug', 'warning', 'error'], optional) – The logging level for the logger.

  • log_format (Literal['standard', 'detailed'], optional) – The logging format for the logger.

  • solver (str, optional) – The solver to use for solving numerical problems. If None, the default solver specified in ‘Defaults.NumericalSettings.CVXPY_DEFAULT_SETTINGS’ is used.

  • solver_verbose (bool, optional) – If True, logs verbose output related to numerical solver operation during the model run.

  • solver_settings (dict[str, Any], optional) – Additional settings for the solver passed as key-value pairs.

  • integrated_problems (bool, optional) – If True, solve problems iteratively using a block Gauss-Seidel (alternating optimization) scheme, where updated endogenous variables are exchanged until convergence.

  • convergence_monitoring (bool, optional) – If True, enables convergence monitoring during the solving of integrated problems.

  • convergence_norm (Literal['max_relative', 'max_absolute', 'l1', 'l2', 'linf'], optional) – The norm type to use for convergence monitoring in integrated problems.

  • convergence_tables_to_check (Literal['all_endogenous', 'hybrid_only'] | List[str], optional) – The data tables to consider for convergence monitoring in integrated problems. Can be ‘all_endogenous’, ‘hybrid_only’, or a list of specific data table keys.

  • convergence_tables_to_skip (List[str], optional) – List of data table keys to skip for convergence checking in integrated problems.

  • relative_tolerance (float, optional) – Numerical tolerance for verifying maximum relative change between iterations in integrated problems for each data table. Overrides ‘Defaults.NumericalSettings.MODEL_COUPLING_SETTINGS’.

  • maximum_iterations (int, optional) – The maximum number of iterations for solving integrated problems. Overrides ‘Defaults.NumericalSettings.MODEL_COUPLING_SETTINGS’.

  • keep_previous_iteration_db (bool, optional) – Whether to keep the database generated during the last-1 iteration. For debugging purpose.

  • model_structure_file (str, optional) – Name of the Excel file used to transfer model structure information.

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

Return type:

None

Example:

import cvxlab
cvxlab.run(
    model_dir_name='my_model',
    main_dir_path='/path/to/models',
    log_level='debug',
    solver='ECOS',
)

Model directory and instance management#

cvxlab.create_model_dir(
model_dir_name='model',
main_dir_path=None,
force_overwrite=False,
settings_file_type='yml',
include_user_defined_templates=False,
)[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. Defaults to ‘model’.

  • main_dir_path (str) – The path to the main directory where the model directory will be created. If None, the current working directory will be used. Defaults to None.

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

  • settings_file_type (Defaults.LiteralTypes.SettingsSource, optional) – The type of template configuration file to generate (‘yml’ or ‘xlsx’). Defaults to ‘yml’.

  • include_user_defined_templates (bool, optional) – If True, copy user-defined template files into the new model directory (user-defined operators and constants templates). Defaults to False.

Raises:

ValueError – If the template file type is unsupported.

Return type:

None

cvxlab.copy_user_defined_templates(path_destination=None)[source]#

Copy user-defined template files to destination path.

This function copies user-defined template files such as templates for custom operators and constants to a defined path.

Parameters:

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

Return type:

None

cvxlab.transfer_setup_info_xlsx(
source_file_name,
source_dir_path,
destination_dir_path,
update='all',
)[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 (Defaults.LiteralTypes.TransferUpdate, 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.

Return type:

None

cvxlab.handle_model_instance(action, file_name, source_dir_path=None, instance=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 (Defaults.LiteralTypes.HandleModelInstance) – 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.