Metadata-Version: 2.4
Name: admm
Version: 1.0.0
Summary: ADMM - Alternating Direction Method of Multipliers for convex optimization
Author-email: MindOPT Team <solver.damo@list.alibaba-inc.com>
Maintainer-email: MindOPT Team <solver.damo@list.alibaba-inc.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/alibaba/admm-python
Project-URL: Documentation, https://admm-python.readthedocs.io
Project-URL: Repository, https://github.com/alibaba/admm-python
Project-URL: Issues, https://github.com/alibaba/admm-python/issues
Project-URL: Changelog, https://github.com/alibaba/admm-python/blob/main/CHANGELOG.md
Keywords: optimization,convex,admm,solver,mathematics
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Cython
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.20.0
Requires-Dist: scipy>=1.7.0
Requires-Dist: admmlib
Dynamic: license-file

# ADMM - Alternating Direction Method of Multipliers

[![PyPI version](https://badge.fury.io/py/admm.svg)](https://badge.fury.io/py/admm)
[![Documentation Status](https://readthedocs.org/projects/admm-python/badge/?version=latest)](https://admm-python.readthedocs.io/en/latest/?badge=latest)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

ADMM (Alternating Direction Method of Multipliers) is a Python package for solving convex optimization problems. It combines dual decomposition with the method of multipliers, strategically leveraging the underlying problem structure for efficiency.

## Features

- 🚀 **High Performance**: Core solver implemented in C++ with Python bindings via Cython
- 📊 **Convex Optimization**: Solve large-scale convex optimization problems efficiently
- 🔧 **Flexible**: Support for variables, parameters, expressions, and constraints
- 📝 **Well Documented**: Comprehensive documentation with examples
- 🐍 **Pythonic**: Easy-to-use Python API with NumPy integration
- 💻 **Cross-Platform**: Linux x86_64, macOS ARM64, Windows x86_64

## Installation

### From PyPI

```bash
pip install admm
```

This will automatically install all dependencies including `admmlib` (the pre-built C++ core library).

### From Source

```bash
git clone https://github.com/alibaba/admm-python.git
cd admm-python

# Install admmlib dependency first (required for building)
pip install admmlib -i https://artifacts.antgroup-inc.cn/artifact/repositories/simple-dev/

# Option 1: Build wheel package (recommended)
python -m build --wheel -n

# Option 2: Build sdist (for source distribution)
python -m build --sdist -n

# Option 3: Install directly (requires admmlib)
pip install . -i https://artifacts.antgroup-inc.cn/artifact/repositories/simple-dev/

# Option 4: Install in editable mode (for development)
pip install -e . -i https://artifacts.antgroup-inc.cn/artifact/repositories/simple-dev/

# Option 5: Build extension in-place (legacy way)
python setup.py build_ext --inplace
```

## Quick Start

```python
from admm import Model
import numpy as np

# Create a model
model = Model()

# Create variables
x = model.createVar(2, 1)
y = model.createVar(2, 1)

# Set objective: minimize ||x - y||^2
model.setObjective((x - y) @ (x - y))

# Add constraints
model.addConstr(x >= 0)
model.addConstr(y >= 0)

# Solve
model.optimize()

# Get solution
print(f"x = {x.getValue()}")
print(f"y = {y.getValue()}")
```

## Documentation

Full documentation is available at [ReadTheDocs](https://admm-python.readthedocs.io).

- [Quick Start Guide](https://admm-python.readthedocs.io/en/latest/quickstart.html)
- [API Reference](https://admm-python.readthedocs.io/en/latest/api.html)
- [Examples](https://admm-python.readthedocs.io/en/latest/examples.html)

## Requirements

- Python >= 3.8
- NumPy >= 1.20.0
- SciPy >= 1.7.0
- admmlib >= 2026.3.17 (pre-built C++ core library, installed automatically)

## Building from Source

### Prerequisites

- **Python** >= 3.8
- **C++ compiler**: GCC, Clang, or MSVC
- **Cython** >= 0.29.0
- **setuptools** >= 61
- **NumPy** >= 1.20.0
- **admmlib** >= 2026.3.17 (internal C++ core library)
- **xelatex**: Required for building PDF documentation (install via TeX Live or MacTeX)
- **latexmk**: Required for automated LaTeX builds (usually included with TeX Live)

### Supported Platforms

- **Linux**: x86_64 (GCC)
- **macOS**: ARM64 (Apple Silicon, Clang)
- **Windows**: x86_64 (MSVC)

### Build

```bash
# Install admmlib dependency first (required for building)
pip install admmlib -i https://artifacts.antgroup-inc.cn/artifact/repositories/simple-dev/

# Option 1: Build wheel package (recommended)
python -m build --wheel -n

# Option 2: Build sdist (for source distribution)
python -m build --sdist -n

# Option 3: Install directly (requires admmlib)
pip install . --no-build-isolation -i https://artifacts.antgroup-inc.cn/artifact/repositories/simple-dev/

# Option 4: Install in editable mode (for development)
pip install -e . --no-build-isolation -i https://artifacts.antgroup-inc.cn/artifact/repositories/simple-dev/

# Option 5: Build extension in-place (legacy way)
python setup.py build_ext --inplace
```

### Install from Local Build

```bash
pip install dist/admm-*.whl
```

### Run Tests

```bash
pytest tests/
```

## Version Management

The package version is defined in `pyproject.toml`. To update the version:

```bash
# Edit pyproject.toml directly
vim pyproject.toml

# Or use bump2version (optional)
pip install bump2version
bump2version patch  # 1.0.0 -> 1.0.1
bump2version minor  # 1.0.0 -> 1.1.0
bump2version major  # 1.0.0 -> 2.0.0
```

After updating the version, rebuild the package:

```bash
python -m build --wheel -n
```

## Contributing

We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Acknowledgments

- This project is maintained by the MindOPT Team at Alibaba DAMO Academy.
- The core solver is based on the ADMM algorithm developed by Boyd et al.

## Support

- **Issues**: [GitHub Issues](https://github.com/alibaba/admm-python/issues)
- **Email**: solver.damo@list.alibaba-inc.com
- **Documentation**: [https://admm-python.readthedocs.io](https://admm-python.readthedocs.io)
