Package: pyproximal
:vertical_traffic_light: :vertical_traffic_light: This library is under early development.
Expect things to constantly change until version v1.0.0. :vertical_traffic_light: :vertical_traffic_light:ObjectiveThis Python library provides all the needed building blocks for solving
non-smooth convex optimization problems using the so-calledproximal algorithms.Whereas gradient based methods are first-order iterative optimization
algorithms for solving unconstrained, smooth optimization problems,
proximal algorithms can be viewed as an analogous tool for non-smooth and
possibly constrained versions of these problems. Such algorithms
sit at a higher level of abstraction than classical algorithms
like Steepest descent or Newton’s method and require a basic
operation to be performed at each iteration: the evaluation of the
so-calledproximal operatorof the functional to be optimized.Whilst evaluating a proximal operator does itself require solving a
convex optimization problem, these subproblems often admit closed form
solutions or can be solved very quickly with ad-hoc specialized methods.
Several of such proximal operators are therefore implemented in this
library.Here is a simple example showing how to compute the
proximal operator of the L1 norm of a vector:importnumpyasnpfrompyproximalimportL1l1=L1(sigma=1.)x=np.arange(-5,5,0.1)xp=l1.prox(x,1)and how this can be used to solve a basic denoising problem of the form:min ||x - y||_2^2 + ||Dx||_1:importnumpyasnpfrompylopsimportFirstDerivativefrompyproximalimportL1,L2frompyproximal.optimization.primalimportLinearizedADMMnp.random.seed(1)# Create noisy datanx=101x=np.zeros(nx)x[:nx//2]=10x[nx//2:3*nx//4]=-5n=np.random.normal(0,2,nx)y=x+n# Define functionalsl2=L2(b=y)l1=L1(sigma=5.)Dop=FirstDerivative(nx,edge=True,kind='backward')# Solve functional with L-ADMML=np.real((Dop.H*Dop).eigs(neigs=1,which='LM')[0])tau=1.mu=0.99*tau/Lxladmm,_=LinearizedADMM(l2,l1,Dop,tau=tau,mu=mu,x0=np.zeros_like(x),niter=200)Why another library for proximal algorithms?Several other projects in the Python ecosystem provide implementations of proximal
operators and/or algorithms, which present some clear overlap with this project.A (possibly not exhaustive) list of other projects is:http://proximity-operator.nethttps://github.com/ganguli-lab/proxalgs/blob/master/proxalgs/operators.pyhttps://github.com/pmelchior/proxminhttps://github.com/comp-imaging/ProxImaLhttps://github.com/matthieumeo/pycsouAll of these projects are self-contained, meaning that they implement both proximal
and linear operators as needed to solve a variety of problems in different areas
of science.The main difference with PyProximal lies in the fact that we decidenot tointertangle
linear and proximal operators within the same library. We leverage the extensive
set of linear operators provided by thePyLopsproject and focus only on the proximal part of the problem. This makes the codebase
more concise, and easier to understand and extend. Moreover many of the
problems that are solved in PyLops can now be also solved by means of
proximal algorithms!Project structureThis repository is organized as follows:pyproximal: python library containing various orthogonal projections, proximial operators, and solverspytests:    set of pyteststestdata:   sample datasets used in pytests and documentationdocs:       sphinx documentationexamples:   set of python script examples for each proximal operator to be embedded in documentation using sphinx-gallerytutorials:  set of python script tutorials to be embedded in documentation using sphinx-galleryGetting startedYou needPython 3.8 or greater.Note: Versions prior to v0.3.0 work also with Python 3.6 or greater, however they
require scipy version to be lower than v1.8.0.From PyPiyou want to use PyProximal within your codes,
install it in your Python environment by typing the following command in your terminal:To get the most out of PyLops straight out of the box, we recommendcondato install PyLops:condainstall-cconda-forgepyproximalFrom PyPiYou can also install pyproximal withpip:pipinstallpylopsFrom GithubFinally, you can also directly install from the main branch (although this is not recommended)pip install git+https://git@github.com/PyLops/pyproximal.git@mainContributingFeel like contributing to the project? Adding new operators or tutorial?We advise using theAnaconda Python distributionto ensure that all the dependencies are installed via theCondapackage manager. Follow
the following instructions and read carefully theCONTRIBUTINGfile before getting started.1. Fork and clone the repositoryExecute the following command in your terminal:git clone https://github.com/your_name_here/pyproximal.git2. Install PyLops in a new Conda environmentTo ensure that further development of PyLops is performed within the same environment (i.e., same dependencies) as
that defined byrequirements-dev.txtorenvironment-dev.ymlfiles, we suggest to work off a new Conda enviroment.The first time you clone the repository run the following command:make dev-install_condaTo ensure that everything has been setup correctly, run tests:make testsMake sure no tests fail, this guarantees that the installation has been successfull.Remember to always activate the conda environment every time you open a new terminal by typing:source activate pyproximalDocumentationThe official documentation of PyProximal is availablehere.Moreover, if you have installed PyProximal using thedeveloper environmentyou can also build the documentation locally by typing the following command:make docOnce the documentation is created, you can make any change to the source code and rebuild the documentation by
simply typingmake docupdateNote that if a new example or tutorial is created (and if any change is made to a previously available example or tutorial)
you are required to rebuild the entire documentation before your changes will be visible.ContributorsMatteo Ravasi, mrava87Nick Luiken, NickLuikenEneko Uruñuela, eurunuelaMarcus Valtonen Örnhag, marcusvaltonen