User Guide#

This guide explains the complete CVXlab workflow for defining algebraic models, preparing their data, solving numerical problems, and exporting results. Read this page for an overview of all ten steps, then follow each step’s link for file formats, code examples, and configuration options.

For a first practical example, start with the Quick Start or the production-planning tutorial. If you prefer interactive prompts, the Guided Interface provides a menu-driven way to carry out the same workflow.

The diagram summarizes how model specification, data management, and solving fit together, including workflows involving linked models.

CVXlab workflow from specification and data to solving and linked models CVXlab workflow from specification and data to solving and linked models

Modelling workflow#

A new model follows the steps below in order. They are grouped into three phases: define the model, prepare the model and data, then solve and inspect results. When reopening an existing model, enter at step 4 as described there. The left sidebar links to the detailed step pages; the right sidebar navigates between the phases on this overview page.

Define the model#

1. Conceptual model definition

Define the mathematical structure before creating files: sets describe model dimensions, data tables hold numerical data, variables refer to those data, and expressions and problems describe the relationships to solve. A problem may represent a system of equations or an optimization problem.

Details: Conceptual model definition.

2. Create the model directory

Generate the model directory and its setup templates with cvxlab.create_model_dir(). Choose YAML or Excel for the setup files; optionally include Python templates for custom operators and constant types.

Details: Generation of model directory.

3. Fill the model setup files

Translate the conceptual model into definitions of sets, data tables, variables, and problem expressions. Use the three YAML setup files or the corresponding tabs in model_settings.xlsx; both describe the same model structure.

Details: Fill model setup file(s).

Prepare the model and data#

4. Create or reopen the Model instance

Create a cvxlab.Model instance to load and validate the setup files. For a new model, the constructor generates sets.xlsx; the Model instance then provides the methods used throughout the remaining workflow.

Details: Model class instance generation.

Starting with an existing model?

Begin at step 4 with use_existing_data=True when the setup files, populated sets.xlsx, model SQLite database, and input data files are already available. The constructor restores the model coordinates and initializes numerical problems using the data stored in SQLite.

Skip the initial creation of set coordinates and blank data structures (steps 5 and 6). If you change input data files, follow steps 7 and 8 to refresh the database and numerical problems before solving again. Otherwise, continue to step 9. See Reusing existing settings and data for the requirements.

5. Fill the set coordinates

Fill sets.xlsx with the members of each set, including any filters and aggregation categories. These coordinates define the actual scope of the model and the valid combinations represented in its data tables.

Details: Fill sets data (model coordinates).

6. Initialize the data structures

Call initialize_model_environment() to load the set coordinates, validate variable definitions, and create the SQLite database and blank Excel or CSV input files. These files contain the exogenous tables that will receive numerical data in the next step.

Details: Initialization of data structures.

7. Fill or update exogenous data

Provide numerical values in the generated input tables, keeping the coordinate columns unchanged. This is also the entry point for updating inputs in an existing model; input files can be regenerated with generate_input_data_files() when needed.

Details: Fill exogenous model data.

Solve and inspect results#

8. Initialize or refresh the numerical problems

Call refresh_database_and_initialize_problem() to import input data into SQLite, validate symbolic expressions, and prepare numerical problems for solving. Repeat this step after changing input data files so that the next solve uses the updated values.

Details: Initialization of numerical problem(s).

9. Solve the numerical problems

Run run_model() with the solver and numerical settings appropriate to the model. Choose parallel for independent problems, sequential for an ordered chain of problems with data exchange, or integrated for iterative coordination of linked sub-problems.

Details: Solution of numerical problem(s).

10. Export and inspect results

After a successful solve, call load_results_to_database() to write results to the endogenous tables in SQLite. Inspect the stored data directly or use external analysis tools; the model utilities help inspect model properties and check results against a reference database.

Details: Export endogenous model data.

Tools and further reading#

  • Guided interface: perform the workflow through interactive prompts instead of calling each API directly.

  • Inspecting and managing models: inspect sets and variables, maintain database tables, and compare results with reference data.

  • Tutorials: follow worked examples that apply these steps to specific modeling problems.

  • API reference: look up signatures and options when implementing your own workflow.