Guided Interface#

CVXlab provides a menu-driven interface for users who want to follow the modeling workflow without writing calls to every API. The interface guides the user through model creation, data initialization, problem solution, results export, and common maintenance and inspection operations.

Each menu action corresponds to one public CVXlab API. Actions are deliberately kept separate: for example, Run model calls run_model() but does not refresh the database or initialize the numerical problem first. If a required earlier step has not been completed, the interface reports the resulting error and returns to the menu.

It is highly recommended to read the User Guide main page for an overview of the fundamental concepts and the modeling workflow before using the interface.

Starting the interface#

The interface can be started without arguments:

import cvxlab

cvxlab.gui()

After an action is selected, the interface asks for the settings required by that action. Pressing Enter accepts the displayed default. Boolean values can be entered as true or false; lists and dictionaries use normal Python syntax, for example ["demand", "cost"] or {"problem": "CLARABEL"}.

Answers are retained for the remainder of the session. Consequently, a setting is requested only when it is missing and is first needed.

Every menu includes Quit CVXlab, which closes the interface from any level. Nested menus also include Back, which returns to the previous menu without closing the interface.

API: cvxlab.gui()

Preconfiguring the session#

Basic settings can be passed directly to cvxlab.gui():

cvxlab.gui(
    model_dir_name="my_model",
    main_dir_path="/path/to/models",
    model_settings_from="yml",
    log_level="info",
)

For a reusable configuration, the same arguments can be collected in a dictionary and expanded when calling cvxlab.gui(). Settings used to construct a cvxlab.Model are placed at the top level. Arguments belonging to a specific action are placed under action_settings, using the public API method name as the key. This also applies to utility-specific settings, such as the source file used by cvxlab.transfer_setup_info_xlsx().

import cvxlab

config = {
    "model_dir_name": "my_model",
    "main_dir_path": "/path/to/models",
    "model_settings_from": "yml",
    "multiple_input_files": False,
    "input_data_files_type": "xlsx",
    "action_settings": {
        "generate_input_data_files": {
            "table_key_list": ["demand", "cost"],
            "force_overwrite": False,
        },
        "refresh_database_and_initialize_problem": {
            "table_key_list": ["demand", "cost"],
            "force_overwrite": False,
        },
        "run_model": {
            "solution_mode": "parallel",
            "solver": "CLARABEL",
            "solver_verbose": False,
        },
        "load_results_to_database": {
            "force_overwrite": True,
        },
    },
}

cvxlab.gui(**config)

Only settings omitted from this dictionary are requested interactively. Action names and their arguments are validated before the menu is opened, so spelling errors are reported immediately.

The interface does not accept an existing cvxlab.Model instance. Models are created, opened, or loaded explicitly from the Model session menu.

use_existing_data is therefore intentionally not accepted as a top-level cvxlab.gui() setting. Choose Create new Model instance to pass use_existing_data=False to cvxlab.Model, or Open existing Model environment to pass use_existing_data=True. Keeping this choice in the menu prevents a configured boolean from contradicting the selected session action.

API: cvxlab.gui()

Guided modeling workflow#

For a model generated from scratch, use the interface actions in the following order. Steps that require editing model files remain user operations outside the interface.

Guided workflow for a new model#

Step

Interface action or user operation

API called

Detailed modeling step

1

Utilities / Create model directory

cvxlab.create_model_dir()

Generation of model directory

2

Fill the generated model setup file(s)

User operation

Fill model setup file(s)

3

Model session / Create new Model instance

cvxlab.Model

Model class instance generation

4

Fill sets.xlsx with the model coordinates

User operation

Fill sets data (model coordinates)

5

Model operations / Initialize model environment

initialize_model_environment()

Initialization of data structures

6

Fill the generated exogenous input data file(s)

User operation

Fill exogenous model data

7

Model operations / Refresh database and initialize problem

refresh_database_and_initialize_problem()

Initialization of numerical problem(s)

8

Model operations / Run model

run_model()

Solution of numerical problem(s)

9

Model operations / Load results to database

load_results_to_database()

Export endogenous model data

For a model whose settings and data structures already exist, select Model session / Open existing Model environment. The action constructs cvxlab.Model with use_existing_data=True. Exogenous data can then be updated, followed by the refresh, run, and results-export actions when required. See Model generation from existing settings/data for the corresponding programmatic workflow.

Note

Creating or opening a model is an explicit session action. Selecting an operation without an active model produces an error rather than creating a model implicitly.

Behavioral notes and further information#

Each action invokes only the API shown in the menu tree. Prerequisite operations are not run automatically, and an action that fails returns control to the menu. Settings entered interactively are retained for the rest of the GUI session.

See the API reference for complete argument descriptions. For conceptual and programmatic explanations of the modeling steps, continue with the User Guide.