Metadata-Version: 2.4
Name: pbalm
Version: 0.1.2
Summary: Proximal augmented Lagrangian method for nonconvex optimization with equality and inequality constraints.
Home-page: https://github.com/adeyemiadeoye/p-balm
Author: The P-BALM Developers; Adeyemi D. Adeoye et al.
Author-email: "The P-BALM Developers; Adeyemi D. Adeoye et al." <adeyemi.adeoye@imtlucca.it>
Maintainer-email: "The P-BALM Developers; Adeyemi D. Adeoye et al." <adeyemi.adeoye@imtlucca.it>
Project-URL: Documentation, https://adeyemiadeoye.github.io/p-balm/
Project-URL: Source, https://github.com/adeyemiadeoye/p-balm
Project-URL: Issue Tracker, https://github.com/adeyemiadeoye/p-balm/issues
Keywords: optimization,nonlinear optimization,constrained optimization,augmented Lagrangian
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Topic :: Scientific/Engineering
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.8
Description-Content-Type: text/markdown; charset=UTF-8
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: jax
Requires-Dist: jaxlib
Requires-Dist: alpaqa==1.1.0a1
Provides-Extra: testing
Requires-Dist: setuptools; extra == "testing"
Requires-Dist: pytest; extra == "testing"
Requires-Dist: pytest-cov; extra == "testing"
Provides-Extra: docs
Requires-Dist: sphinx; extra == "docs"
Requires-Dist: sphinx-rtd-theme; extra == "docs"
Requires-Dist: sphinx-autodoc-typehints; extra == "docs"
Requires-Dist: myst-parser; extra == "docs"
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# pbalm

<p align="center">
    <img src="https://github.com/adeyemiadeoye/p-balm/blob/main/docs/source/_static/pbalm_logo.png" alt="pbalm logo"/>
</p>
<p align="center">
    <a href="https://adeyemiadeoye.github.io/p-balm/"><img src="https://img.shields.io/badge/docs-Sphinx-blue" alt="Documentation"/></a>
    <a href="https://arxiv.org/abs/2509.02894"><img src="https://img.shields.io/badge/paper-arXiv-red" alt="arXiv"/></a>
    <a href="https://pypi.org/project/pbalm/"><img src="https://img.shields.io/pypi/v/pbalm" alt="PyPI"/></a>
    <a href="https://github.com/adeyemiadeoye/p-balm/blob/main/LICENSE"><img src="https://img.shields.io/github/license/adeyemiadeoye/p-balm" alt="License"/></a>
</p>

A Python package providing a **proximal augmented Lagrangian method** for solving nonlinear programming problems with equality and inequality constraints.

## Problem structure

**pbalm** solves optimization problems of the form:

$$
\begin{aligned}
\min_{x} \quad & f_1(x) + f_2(x) \\
\text{s.t.} \quad & g(x) \leq 0 \\
& h(x) = 0
\end{aligned}
$$

where $f_1$ is smooth (possibly nonconvex), $f_2$ is possibly nonsmooth but prox-friendly, and $g$, $h$ define smooth inequality and equality constraints, respectively.

## Key Features

- **Nonconvex optimization**: handles nonconvex objectives and constraints
- **Composite objectives**: supports smooth + nonsmooth terms
- **Flexible constraints**: both equality and inequality constraints
- **JAX-powered**: automatic differentiation and JIT compilation

## Quick Example

```python
import jax.numpy as jnp
import pbalm

# smooth part of the objective
def f1(x):
    return jnp.sum(x**2)

# L1 regularization (nonsmooth)
lbda = 0.1
f2 = pbalm.L1Norm(lbda)

# inequality constraint g_j(x) <= 0; j=1
def g_1(x):
    return x[0] - 0.8

# equality constraints h_i(x) = 0; i=1,2
def h_1(x):
    return x[0] + x[1] - 1.0

def h_2(x):
    return x[1] * x[2] - 2.0

x0 = jnp.array([1.0, 1.0, 2.0])

# create problem and solve
problem = pbalm.Problem(f1=f1, f2=f2, g=[g_1], h=[h_1, h_2])
result = pbalm.solve(problem, x0=x0, tol=1e-6)

print(f"Solution: {result.x}")
```

## Installation

```bash
python3 -m pip install pbalm
```

For development:

```bash
git clone https://github.com/adeyemiadeoye/p-balm.git
cd p-balm
python3 -m pip install -e .
```

## Documentation

Full documentation is available at **[adeyemiadeoye.github.io/p-balm](https://adeyemiadeoye.github.io/p-balm/)**.

## Citation

If you use **pbalm** in your research, please cite:

```bibtex
@article{adeoye2025pbalm,
  title={A proximal augmented Lagrangian method for nonconvex optimization with equality and inequality constraints},
  author={Adeoye, Adeyemi D. and Latafat, Puya and Bemporad, Alberto},
  journal={arXiv preprint arXiv:2509.02894},
  year={2025}
}
```

## Acknowledgements

The authors acknowledge the funding received from the European Union (ERC Advanced Research Grant COMPACT, No. 101141351). Views and opinions expressed are however those of the authors only and do not necessarily reflect those of the European Union or the European Research Council. Neither the European Union nor the granting authority can be held responsible for them.

**pbalm** depends on the efficient implementation of [PANOC](https://ieeexplore.ieee.org/document/8263933) provided by [alpaqa](https://github.com/kul-optec/alpaqa), as well as its regularizers module.

## License

See [LICENSE](LICENSE) for details.
