Generation of model directory

This step initializes a new model workspace by creating a dedicated directory containing the necessary configuration template files required to create and handle a CVXlab model. This function is typically executed once at the beginning of the modeling process, in the case of model generation from scratch.

Overview

• Creates a new directory to store all files related to a CVXlab model instance (settings, input data, database, etc.).

• Supports both YAML (.yml) and XLSX (.xlsx) templates for setup files, depending on workflow preference.

• Optionally includes template files for user-defined symbolic operators and constants, allowing customization without modifying the CVXlab repository.

API: cvxlab.create_model_dir()

Typical Usage

This function is typically used at the beginning of the modeling process, after importing the CVXlab package, to create a new model directory with the necessary template files. See the example below.

import cvxlab

# [CURRENT STEP] Create model directory and setup files
cvxlab.create_model_dir(
    model_dir_name="my_model",
    main_dir_path="path/to/parent",
    settings_file_type="yml",  # or "xlsx"
    include_user_defined_templates=False,
)

Parameters description

Parameter	Description	Default
model_dir_name	Name of the model directory to create.	"model"
main_dir_path	Parent directory where the model directory will be created.	Current working directory
settings_file_type	Format of the setup files, either "yml" or "xlsx".	"yml"
include_user_defined_templates	If True, includes template files for user-defined symbolic operators and constants in the model directory.	False
force_overwrite	If True, overwrites the directory if it already exists without confirmation.	False

Workflow

When cvxlab.create_model_dir() is called:

• The target directory is created at main_dir_path/model_dir_name. If it already exists, it is erased if force_overwrite is set, otherwise user confirmation is required.

• Setup template files are generated in the chosen format:

  • If settings_file_type='yml' three YAML files are created for sets, variables, and problem structure.

  • If settings_file_type='xlsx' a single Excel file is created with three sheets for sets, variables, and problem.

• Optionally, template files for user-defined symbolic operators and constants are copied into the directory if requested.

• The directory is ready for subsequent modeling steps.

Generated files

• Directory: my_model (or specified name) in the chosen parent path.

• Setup files depends on the selected format (settings_file_type argument):

  • YAML: structure_sets.yml, structure_variables.yml, problem.yml.

  • XLSX: model_settings.xlsx (with three tabs: structure_sets, structure_variables, problem).

• Optional templates files includes:

  • user_defined_operators.py: Template for custom symbolic operators.

  • user_defined_constants.py: Template for custom constants types.

These files provide the basic structure for defining sets, variables, and the symbolic problem, and can be edited as needed before proceeding to model initialization and data input.