Metadata-Version: 2.4
Name: cvxlab
Version: 1.1.0
Summary: CVXlab - Open-source Python laboratory for convex algebraic modeling
Author-email: "Matteo V. Rocco" <matteovincenzo.rocco@polimi.it>
License: Apache-2.0
Project-URL: Homepage, https://github.com/cvxlab/cvxlab
Project-URL: Documentation, https://cvxlab.readthedocs.io
Project-URL: Repository, https://github.com/cvxlab/cvxlab
Project-URL: Issues, https://github.com/cvxlab/cvxlab/issues
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Scientific/Engineering :: Mathematics
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.20.0
Requires-Dist: pandas==2.3.3
Requires-Dist: scipy>=1.7.0
Requires-Dist: cvxpy>=1.9.1
Requires-Dist: openpyxl>=3.0.0
Requires-Dist: pyyaml>=5.4.0
Requires-Dist: dill>=0.3.4
Provides-Extra: dev
Requires-Dist: pytest>=6.2.0; extra == "dev"
Requires-Dist: pytest-cov>=2.12.0; extra == "dev"
Provides-Extra: docs
Requires-Dist: sphinx>=7.0; extra == "docs"
Requires-Dist: pydata-sphinx-theme; extra == "docs"
Requires-Dist: sphinx-autodoc-typehints; extra == "docs"
Requires-Dist: sphinxcontrib-mermaid; extra == "docs"
Requires-Dist: sphinx-tabs; extra == "docs"
Requires-Dist: myst-nb>=1.0.0; extra == "docs"
Provides-Extra: solvers
Requires-Dist: gurobipy>=9.5.0; extra == "solvers"
Requires-Dist: cyipopt>=1.1.0; extra == "solvers"
Provides-Extra: release
Requires-Dist: build; extra == "release"
Requires-Dist: twine; extra == "release"
Dynamic: license-file

![CVXlab Logo](https://raw.githubusercontent.com/cvxlab/cvxlab/main/docs/source/_static/CVXlab_logo_dark.png)

[![PyPI version](https://img.shields.io/pypi/v/cvxlab?label=PyPI&logo=pypi)](https://pypi.org/project/cvxlab/)
[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/cvxlab)](https://pypi.org/project/cvxlab/)
[![Documentation Status](https://readthedocs.org/projects/cvxlab/badge/?version=latest)](https://cvxlab.readthedocs.io/en/latest/?badge=latest)
[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.20644006.svg)](https://doi.org/10.5281/zenodo.20644006)

CVXlab is an open-source Python laboratory for modeling and solving convex optimization problems. 
It extends [cvxpy](https://www.cvxpy.org/) with user-friendly interfaces, integrated data 
management and support for multiple, interconnected optimization models.

## Table of Contents
- [Installation](#installation)
- [Quick Overview](#quick-overview)
- [Guided Interface](#guided-interface)
- [Documentation](#documentation)
- [Changelog](#changelog)
- [Contributing](#contributing)
- [Community & Support](#community--support)
- [License](#license)
- [Citing](#citing)

## Installation
**From PyPI**
```bash
pip install cvxlab
```
**From source (for development):**
```bash
git clone https://github.com/cvxlab/cvxlab.git
cd cvxlab
pip install -e .[dev]
```
See the [Installation Guide](https://cvxlab.readthedocs.io/en/latest/installation.html) 
for detailed instructions.

## Quick Overview
CVXlab allows you to define optimization problems using:
- **General-purpose model generator**: Model problems as you would mathematically, without restrictive solver forms.
- **Almost no-code required**: Build models using Excel or YAML—no coding required.
- **Centralized data management**: Centralized data input/output via SQLite database.
- **Multi-Model Support**: Generate and solve multiple parallel, sequential, or integrated optimization problems.
- **Powerful engine embedded**: Built on cvxpy package, leveraging its extensive solver support.

**Typical workflow:**

The figure below provides a synthetic and simplified overview of the CVXlab modeling 
process.

![CVXlab workflow](https://raw.githubusercontent.com/cvxlab/cvxlab/main/docs/source/_static/CVXlab_nutshell.png)

In generating and handling a CVXlab model, the user must follow the five fundamental
activities summarized below:

- The user **defines the model settings** and the related structure: model scope, 
  structure of variables, and list of mathematical expressions, including equalities,
  inequalities and (eventually) objective function. This activity requires almost no
  coding, as model definition can be performed via Excel files or YAML configuration 
  files.
- The user proceeds by **generating a CVXlab Model object**, consisting in a *Python* 
  class instance embedding all the model settings and the methods useful to manage 
  the model. At the same time, other items are generated, including the **SQLite 
  database file** (to store all model data), and the Excel files serving as blank 
  templates for collecting exogenous data from the user. 
- The user **feeds input data** to SQLite database through blank Excel template 
  files. Specifically, user defines the data input required to characterize exogenous 
  model variables.
- The **numerical problem is generated**, exogenous data fetched from the database, 
  and the problem is solved through CVXPY engine.
- If problem is successfuly solved, **results are finally exported** to the database.
  Due to the structure of the relational database, it can be easily linked and 
  inspected via Excel or SQL queries, or imported into Business Intelligence tools 
  (such as *PowerBI* or *Tableau*) for more elaborated data visualization and analysis.

## Guided Interface
CVXlab provides an interactive guided interface that walks you through the full 
modeling workflow, from directory setup to model solution via a terminal menu. 
Launch it with the `cvxlab.gui()` function:

```python
import cvxlab

frontend_config = {
    'model_dir_name': 'my_model',
    'main_dir_path': '/path/to/models',
    'action_settings': {
        'run_model': {
            'solution_mode': 'parallel',
            'solver': 'CLARABEL',
        },
    },
}

cvxlab.gui(**frontend_config)
```

Model settings are supplied at the top level, while API-specific values belong
under `action_settings`. All values are optional: after an action is selected,
the interface asks only for the settings that were not preconfigured. The
`use_existing_data` model option is selected through **Model session**: choose
**Create new Model instance** for `False` or **Open existing Model environment**
for `True`.

## Documentation
Full documentation is available at [cvxlab.readthedocs.io](https://cvxlab.readthedocs.io/en/latest/).
You can also browse the source documentation in the [docs/source](docs/source) directory.

## Changelog
See [CHANGELOG.md](CHANGELOG.md) for a detailed history of changes.

## Contributing
We welcome contributions from the community! Please see [CONTRIBUTING.md](CONTRIBUTING.md) 
for guidelines.

## Community & Support
Submit issues and ideas for improvements in GitHub [GitHub Issues](https://github.com/cvxlab/cvxlab/issues)

## License
Licensed under the Apache License 2.0. See [LICENSE](LICENSE) for details.

## Citing
If you use CVXlab in academic work, please cite the software as follows.

**APA**
> Rocco, M. V. (2026). *CVXlab* (Version 1.1.0) [Software]. Zenodo. https://doi.org/10.5281/zenodo.20644006

**BibTeX**
```bibtex
@software{rocco_cvxlab_2026,
  author    = {Rocco, Matteo V.},
  title     = {{CVXlab}},
  version   = {1.1.0},
  year      = {2026},
  publisher = {Zenodo},
  doi       = {10.5281/zenodo.20644006},
  url       = {https://doi.org/10.5281/zenodo.20644006}
}
```

For industry or non-academic use, we'd love to hear your feedback: reach out via
email at matteovincenzo.rocco@polimi.it.
