Package: cvxpylayers
cvxpylayerscvxpylayers is a Python library for constructing differentiable convex
optimization layers in PyTorch, JAX, and TensorFlow using CVXPY.
A convex optimization layer solves a parametrized convex optimization problem
in the forward pass to produce a solution.
It computes the derivative of the solution with respect to
the parameters in the backward pass.This library accompanies ourNeurIPS 2019 paperon differentiable convex optimization layers.
For an informal introduction to convex optimization layers, see ourblog post.Our package usesCVXPYfor specifying
parametrized convex optimization problems.InstallationUsageExamplesContributingProjects using cvxpylayersLicenseCitingInstallationUse the package managerpipto install
cvxpylayers.pipinstallcvxpylayersOur package includes convex optimization layers for
PyTorch, JAX, and TensorFlow 2.0;
the layers are functionally equivalent. You will need to installPyTorch,JAX, orTensorFlowseparately, which can be done by following the instructions on their websites.cvxpylayers has the following dependencies:Python 3NumPyCVXPY>= 1.1.a4PyTorch>= 1.0,JAX>= 0.2.12, orTensorFlow>= 2.0diffcp>= 1.0.13UsageBelow are usage examples of our PyTorch, JAX, and TensorFlow layers.
Note that the parametrized convex optimization problems must be constructed
in CVXPY, usingDPP.PyTorchimportcvxpyascpimporttorchfromcvxpylayers.torchimportCvxpyLayern,m=2,3x=cp.Variable(n)A=cp.Parameter((m,n))b=cp.Parameter(m)constraints=[x>=0]objective=cp.Minimize(0.5*cp.pnorm(A@x-b,p=1))problem=cp.Problem(objective,constraints)assertproblem.is_dpp()cvxpylayer=CvxpyLayer(problem,parameters=[A,b],variables=[x])A_tch=torch.randn(m,n,requires_grad=True)b_tch=torch.randn(m,requires_grad=True)# solve the problemsolution,=cvxpylayer(A_tch,b_tch)# compute the gradient of the sum of the solution with respect to A, bsolution.sum().backward()Note:CvxpyLayercannot be traced withtorch.jit.JAXimportcvxpyascpimportjaxfromcvxpylayers.jaximportCvxpyLayern,m=2,3x=cp.Variable(n)A=cp.Parameter((m,n))b=cp.Parameter(m)constraints=[x>=0]objective=cp.Minimize(0.5*cp.pnorm(A@x-b,p=1))problem=cp.Problem(objective,constraints)assertproblem.is_dpp()cvxpylayer=CvxpyLayer(problem,parameters=[A,b],variables=[x])key=jax.random.PRNGKey(0)key,k1,k2=jax.random.split(key,3)A_jax=jax.random.normal(k1,shape=(m,n))b_jax=jax.random.normal(k2,shape=(m,))solution,=cvxpylayer(A_jax,b_jax)# compute the gradient of the summed solution with respect to A, bdcvxpylayer=jax.grad(lambdaA,b:sum(cvxpylayer(A,b)[0]),argnums=[0,1])gradA,gradb=dcvxpylayer(A_jax,b_jax)Note:CvxpyLayercannot be traced with the JAXjitorvmapoperations.TensorFlow 2importcvxpyascpimporttensorflowastffromcvxpylayers.tensorflowimportCvxpyLayern,m=2,3x=cp.Variable(n)A=cp.Parameter((m,n))b=cp.Parameter(m)constraints=[x>=0]objective=cp.Minimize(0.5*cp.pnorm(A@x-b,p=1))problem=cp.Problem(objective,constraints)assertproblem.is_dpp()cvxpylayer=CvxpyLayer(problem,parameters=[A,b],variables=[x])A_tf=tf.Variable(tf.random.normal((m,n)))b_tf=tf.Variable(tf.random.normal((m,)))withtf.GradientTape()astape:# solve the problem, setting the values of A, b to A_tf, b_tfsolution,=cvxpylayer(A_tf,b_tf)summed_solution=tf.math.reduce_sum(solution)# compute the gradient of the summed solution with respect to A, bgradA,gradb=tape.gradient(summed_solution,[A_tf,b_tf])Note:CvxpyLayercannot be traced withtf.function.Log-log convex programsStarting with version 0.1.3, cvxpylayers can also differentiate through log-log convex programs (LLCPs), which generalize geometric programs. Use the keyword argumentgp=Truewhen constructing aCvxpyLayerfor an LLCP. Below is a simple usage exampleimportcvxpyascpimporttorchfromcvxpylayers.torchimportCvxpyLayerx=cp.Variable(pos=True)y=cp.Variable(pos=True)z=cp.Variable(pos=True)a=cp.Parameter(pos=True,value=2.)b=cp.Parameter(pos=True,value=1.)c=cp.Parameter(value=0.5)objective_fn=1/(x*y*z)objective=cp.Minimize(objective_fn)constraints=[a*(x*y+x*z+y*z)<=b,x>=y**c]problem=cp.Problem(objective,constraints)assertproblem.is_dgp(dpp=True)layer=CvxpyLayer(problem,parameters=[a,b,c],variables=[x,y,z],gp=True)a_tch=torch.tensor(a.value,requires_grad=True)b_tch=torch.tensor(b.value,requires_grad=True)c_tch=torch.tensor(c.value,requires_grad=True)x_star,y_star,z_star=layer(a_tch,b_tch,c_tch)sum_of_solution=x_star+y_star+z_starsum_of_solution.backward()SolversAt this time, we support two open-source solvers:SCSandECOS.
SCS can be used to solve any problem expressible in CVXPY; ECOS can be used to solve problems that don't use
the positive semidefinite or exponential cone (this roughly means that if you have positive semidefinite matrices
or use atoms likecp.log, ECOS cannot be used to solve your problem viacvxpylayers).
By default,cvxpylayersuses SCS to solve the problem.Using ECOSFirst make sure that you havecvxpylayersanddiffcpup to date,
by runningpip install --upgrade cvxpylayers diffcpThen, to use ECOS, you would pass thesolver_argsargument to the layer:solution = layer(*params, solver_args={"solve_method": "ECOS"})Passing arguments to the solversOne can pass arguments to both SCS and ECOS by adding the argument as a key-value pair
in thesolver_argsargument.
For example, to increase the tolerance of SCS to1e-8one would write:layer(*parameters, solver_args={"eps": 1e-8})If SCS is not converging, we highly recommend switching to ECOS (if possible),
and if not, using the following arguments toSCS:solver_args={"eps": 1e-8, "max_iters": 10000, "acceleration_lookback": 0}ExamplesOurexamplessubdirectory contains simple applications of convex optimization
layers in IPython notebooks.ContributingPull requests are welcome. For major changes, please open an issue first to
discuss what you would like to change.Please make sure to update tests as appropriate.Please lint the code withflake8.pipinstallflake8# if not already installedflake8Running testscvxpylayers uses thepytestframework for running tests.
To installpytest, run:pipinstallpytestExecute the tests from the main directory of this repository with:pytestcvxpylayers/{torch,jax,tensorflow}Projects using cvxpylayersBelow is  a list of projects using cvxpylayers. If you have used cvxpylayers in a project, you're welcome to make a PR to add it to this list.Learning Convex Optimization Control PoliciesLearning Convex Optimization ModelsLicensecvxpylayers carries an Apache 2.0 license.CitingIf you use cvxpylayers for research, please cite our accompanyingNeurIPS paper:@inproceedings{cvxpylayers2019,
  author={Agrawal, A. and Amos, B. and Barratt, S. and Boyd, S. and Diamond, S. and Kolter, Z.},
  title={Differentiable Convex Optimization Layers},
  booktitle={Advances in Neural Information Processing Systems},
  year={2019},
}If you use cvxpylayers to differentiate through a log-log convex program, please cite the accompanyingpaper:@article{agrawal2020differentiating,
  title={Differentiating through log-log convex programs},
  author={Agrawal, Akshay and Boyd, Stephen},
  journal={arXiv},
  archivePrefix={arXiv},
  eprint={2004.12553},
  primaryClass={math.OC},
  year={2020},
}