# UPOQA: Unconstraint Partially-separable Optimization by Quadratic Approximation
UPOQA is a derivative-free model-based optimizer designed for unconstrained optimization problems with **partially-separable** structures. This solver leverages quadratic interpolation models within a trust-region framework to efficiently solve complex optimization problems without requiring gradient information.
For more details, please refer to the [documentation](https://upoqa.readthedocs.io/en/latest/) or [our paper](https://arxiv.org/abs/2506.21948).
## Installation
UPOQA requires Python 3.8 or higher to be installed, and the following python packages should be installed (these will be installed automatically if using *pip*):
- NumPy ([http://www.numpy.org/](http://www.numpy.org/))
- SciPy ([http://www.scipy.org/](http://www.scipy.org/))
- tqdm ([https://github.com/tqdm/tqdm](https://github.com/tqdm/tqdm))
You can install `upoqa` using *pip:*
```bash
pip install upoqa # minimal install
pip install upoqa[profile] # + all benchmarking dependencies
```
## Basic Usage
### API in a nutshell
```python
upoqa.minimize(fun, x0, coords={}, maxiter=None, maxfev={}, weights={}, xforms={}, xform_bounds={},
extra_fun=None, npt=None, radius_init=1.0, radius_final=1e-06, noise_level=0,
seek_global_minimum=False, f_target=None, tr_shape='structured', callback=None,
disp=True, verbose=False, debug=False, return_internals=False, options={}, **kwargs)
```
Returned object (`upoqa.utils.OptimizeResult`) contains `x`, `fun`, element values `funs`, evaluation counts `nfev`, and more—see the full docstring and documentation.
### A Simple Example
Here is a simple example of using the solver to minimize a function with two elements:
$$
\min_{x,y,z\in \mathbb{R}} \quad x^2 + 2y^2 + z^2 + 2xy - (y + 1)z
$$
let's replace $[x,y,z]$ with $\mathbf{x} = [x_1,x_2,x_3]$, and rewrite this problem into
$$
\min_{\mathbf{x}\in\mathbb{R}^3} \quad f_1(x_1, x_2) + f_2(x_2, x_3)
$$
where
$$
f_1(x_1, x_2) = x_1^2 + x_2^2 + 2x_1 x_2, \quad f_2(x_2, x_3) = x_2^2 + x_3^2 - (x_2 + 1)x_3,
$$
then we can optimize it by the following code:
```python
from upoqa import minimize
def f1(x): # f1(x,y)
return x[0] ** 2 + x[1] ** 2 + 2 * x[0] * x[1] # x^2 + y^2 + 2xy
def f2(x): # f2(y,z)
return x[0] ** 2 + x[1] ** 2 - (x[0] + 1) * x[1] # y^2 + z^2 - (y+1)z
fun = {'xy': f1, 'yz': f2 }
coords = {'xy': [0, 1], 'yz': [1, 2]}
x0 = [0, 0, 0]
result = minimize(fun, x0, coords = coords, disp = False)
print(result)
```
The output will be
```
message: Success: The resolution has reached its minimum.
success: True
fun: -0.33333333333333215
funs: xy: 3.3306690738754696e-16
yz: -0.3333333333333325
extra_fun: 0.0
x: [-3.333e-01 3.333e-01 6.667e-01]
jac: [-3.137e-08 -9.089e-08 2.260e-09]
hess: [[ 1.962e+00 1.980e+00 0.000e+00]
[ 1.980e+00 4.042e+00 -1.002e+00]
[ 0.000e+00 -1.002e+00 1.997e+00]]
nit: 39
nfev: xy: 39
yz: 38
max_nfev: 39
avg_nfev: 38.5
nrun: 1
```
## Mathematical Background
UPOQA solves optimization problems with partially-separable structures:
$$
\min_{x\in\mathbb{R}^n} \quad \sum_{i=1}^q f_i(U_i x),
$$
Where:
- $f_i:\mathbb{R}^{|\mathcal{I}_i|} \to \mathbb{R}$ are black-box element functions whose gradients and hessians are unavailable
- $U_i$ are projection operators selecting relevant variables
- $|\mathcal{I}_i| < n$ (element functions depend on small subsets of variables)
The solver also supports a more general objective form:
$$
\min_{x\in\mathbb{R}^n} \quad f_0(x) + \sum_{i=1}^q w_i h_i\left(f_i(U_i x)\right),
$$
where:
- $f_0$ is a white-box component with known derivatives
- $w_i$ are element weights
- $h_i$ are smooth transformations of element outputs
## Contributing
Contributions are welcome! Please submit pull requests to our repository.
## License
This project is licensed under the GPLv3 License - see the `LICENSE` file for details.
Raw data
{
"_id": null,
"home_page": null,
"name": "upoqa",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "mathematics, optimization, derivative free optimization, partially separable problem",
"author": null,
"author_email": "Yichuan Liu <liuyichuan2020@outlook.com>, Yingzhou Li <yingzhouli@fudan.edu.cn>",
"download_url": "https://files.pythonhosted.org/packages/80/65/563b96f0d0a870e5134bdf6ae469dbd43856e8c1130c0945a96e125665b4/upoqa-1.0.1.tar.gz",
"platform": null,
"description": "# UPOQA: Unconstraint Partially-separable Optimization by Quadratic Approximation\r\n\r\nUPOQA is a derivative-free model-based optimizer designed for unconstrained optimization problems with **partially-separable** structures. This solver leverages quadratic interpolation models within a trust-region framework to efficiently solve complex optimization problems without requiring gradient information.\r\n\r\nFor more details, please refer to the [documentation](https://upoqa.readthedocs.io/en/latest/) or [our paper](https://arxiv.org/abs/2506.21948).\r\n\r\n## Installation\r\n\r\nUPOQA requires Python 3.8 or higher to be installed, and the following python packages should be installed (these will be installed automatically if using *pip*):\r\n\r\n- NumPy ([http://www.numpy.org/](http://www.numpy.org/))\r\n- SciPy ([http://www.scipy.org/](http://www.scipy.org/))\r\n- tqdm ([https://github.com/tqdm/tqdm](https://github.com/tqdm/tqdm))\r\n\r\nYou can install `upoqa` using *pip:*\r\n\r\n```bash\r\npip install upoqa # minimal install\r\npip install upoqa[profile] # + all benchmarking dependencies\r\n```\r\n\r\n## Basic Usage\r\n\r\n### API in a nutshell\r\n\r\n```python\r\nupoqa.minimize(fun, x0, coords={}, maxiter=None, maxfev={}, weights={}, xforms={}, xform_bounds={}, \r\n extra_fun=None, npt=None, radius_init=1.0, radius_final=1e-06, noise_level=0, \r\n seek_global_minimum=False, f_target=None, tr_shape='structured', callback=None, \r\n disp=True, verbose=False, debug=False, return_internals=False, options={}, **kwargs)\r\n```\r\n\r\nReturned object (`upoqa.utils.OptimizeResult`) contains `x`, `fun`, element values `funs`, evaluation counts `nfev`, and more\u2014see the full docstring and documentation.\r\n\r\n### A Simple Example\r\n\r\nHere is a simple example of using the solver to minimize a function with two elements:\r\n\r\n$$\r\n\\min_{x,y,z\\in \\mathbb{R}} \\quad x^2 + 2y^2 + z^2 + 2xy - (y + 1)z\r\n$$\r\n\r\nlet's replace $[x,y,z]$ with $\\mathbf{x} = [x_1,x_2,x_3]$, and rewrite this problem into\r\n\r\n$$\r\n\\min_{\\mathbf{x}\\in\\mathbb{R}^3} \\quad f_1(x_1, x_2) + f_2(x_2, x_3)\r\n$$\r\n\r\nwhere\r\n\r\n$$\r\nf_1(x_1, x_2) = x_1^2 + x_2^2 + 2x_1 x_2, \\quad f_2(x_2, x_3) = x_2^2 + x_3^2 - (x_2 + 1)x_3,\r\n$$\r\n\r\nthen we can optimize it by the following code:\r\n\r\n```python\r\nfrom upoqa import minimize\r\n\r\ndef f1(x): # f1(x,y)\r\n return x[0] ** 2 + x[1] ** 2 + 2 * x[0] * x[1] # x^2 + y^2 + 2xy\r\n\r\ndef f2(x): # f2(y,z)\r\n return x[0] ** 2 + x[1] ** 2 - (x[0] + 1) * x[1] # y^2 + z^2 - (y+1)z\r\n\r\nfun = {'xy': f1, 'yz': f2 }\r\ncoords = {'xy': [0, 1], 'yz': [1, 2]}\r\nx0 = [0, 0, 0]\r\n\r\nresult = minimize(fun, x0, coords = coords, disp = False)\r\nprint(result)\r\n```\r\n\r\nThe output will be\r\n\r\n```\r\n message: Success: The resolution has reached its minimum. \r\n success: True\r\n fun: -0.33333333333333215\r\n funs: xy: 3.3306690738754696e-16\r\n yz: -0.3333333333333325\r\n extra_fun: 0.0\r\n x: [-3.333e-01 3.333e-01 6.667e-01]\r\n jac: [-3.137e-08 -9.089e-08 2.260e-09]\r\n hess: [[ 1.962e+00 1.980e+00 0.000e+00]\r\n [ 1.980e+00 4.042e+00 -1.002e+00]\r\n [ 0.000e+00 -1.002e+00 1.997e+00]]\r\n nit: 39\r\n nfev: xy: 39\r\n yz: 38\r\n max_nfev: 39\r\n avg_nfev: 38.5\r\n nrun: 1\r\n```\r\n\r\n## Mathematical Background\r\n\r\nUPOQA solves optimization problems with partially-separable structures:\r\n\r\n$$\r\n\\min_{x\\in\\mathbb{R}^n} \\quad \\sum_{i=1}^q f_i(U_i x),\r\n$$\r\n\r\nWhere:\r\n\r\n- $f_i:\\mathbb{R}^{|\\mathcal{I}_i|} \\to \\mathbb{R}$ are black-box element functions whose gradients and hessians are unavailable\r\n- $U_i$ are projection operators selecting relevant variables\r\n- $|\\mathcal{I}_i| < n$ (element functions depend on small subsets of variables)\r\n\r\nThe solver also supports a more general objective form:\r\n\r\n$$\r\n\\min_{x\\in\\mathbb{R}^n} \\quad f_0(x) + \\sum_{i=1}^q w_i h_i\\left(f_i(U_i x)\\right),\r\n$$\r\n\r\nwhere:\r\n\r\n- $f_0$ is a white-box component with known derivatives\r\n- $w_i$ are element weights\r\n- $h_i$ are smooth transformations of element outputs\r\n\r\n## Contributing\r\n\r\nContributions are welcome! Please submit pull requests to our repository.\r\n\r\n## License\r\n\r\nThis project is licensed under the GPLv3 License - see the `LICENSE` file for details.\r\n",
"bugtrack_url": null,
"license": null,
"summary": "A model-based derivative-free optimizer for unconstrained partially-separable problems.",
"version": "1.0.1",
"project_urls": {
"Download": "https://github.com/Chitius/upoqa/releases/",
"Homepage": "https://github.com/Chitius/upoqa"
},
"split_keywords": [
"mathematics",
" optimization",
" derivative free optimization",
" partially separable problem"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "1f443b6b94cc9d74461f38dd37230a26b6d969992bec0be7b72dbb57e7efb753",
"md5": "ca6a93d596ee7c4aaac11090e7259700",
"sha256": "1dbf9a613b31f63268c7dfebbfd6aa7e9749593c2d003209869129efd8a64edf"
},
"downloads": -1,
"filename": "upoqa-1.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ca6a93d596ee7c4aaac11090e7259700",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 115059,
"upload_time": "2025-08-13T03:03:32",
"upload_time_iso_8601": "2025-08-13T03:03:32.584722Z",
"url": "https://files.pythonhosted.org/packages/1f/44/3b6b94cc9d74461f38dd37230a26b6d969992bec0be7b72dbb57e7efb753/upoqa-1.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "8065563b96f0d0a870e5134bdf6ae469dbd43856e8c1130c0945a96e125665b4",
"md5": "9081901776368862afab23d9bf2fb121",
"sha256": "8164bd6502ea18385d332373c42c3b4d0d35b3f24249c213bd7d18d6a2555eb5"
},
"downloads": -1,
"filename": "upoqa-1.0.1.tar.gz",
"has_sig": false,
"md5_digest": "9081901776368862afab23d9bf2fb121",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 8398104,
"upload_time": "2025-08-13T03:03:35",
"upload_time_iso_8601": "2025-08-13T03:03:35.356439Z",
"url": "https://files.pythonhosted.org/packages/80/65/563b96f0d0a870e5134bdf6ae469dbd43856e8c1130c0945a96e125665b4/upoqa-1.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-13 03:03:35",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Chitius",
"github_project": "upoqa",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "upoqa"
}
JSON
