Package: pypolsys
PYPOLSYSThis package provides a python wrapper toPOLSYS_PLPfortran90 package from Layne T. Watson, Steven M. Wise, Andrew J. Sommese, August, 1998.POLSYS_PLPis a solver for N complex coefficients polynomial systems of equations in N unknowns by a probability-one, globally convergent homotopy method.For a quick survey onhomotopy continuationsee the very clear practical presentation available onHomotopyContinuation.jlwebsite or this nicetutorial.There are several other homotopy softwares (more recent, also with python interface, ...) allowing more advanced applications. See for instance:PHCpackBertiniHom4PSpyand the wrapper onpypiHomotopyContinuation.jlThe advantage ofPOLSYS_PLPis to be an open-source self-content single f90 file (it requires fewblasandlapackfunctions that are shipped withPOLSYS_PLPsources or that may be linked to optimized libraries). The idea ofpypolsysproject is to create aneasy to install and to deploy python package to start with Homotopy method.This wrapper has been developped to tackle polynomial systems obtained by high order perturbation of multi-parametric eigenvalue problems obtained withEasterEig. This yields to dense polynomial system. In this context, multivariate Horner algorithm has been added to quickly evaluate simultaneously the polynomial and its Jacobian matrix.POLSYS_PLPPOLSYS_PLPuse a probability-one globally convergent homotopy method,
to find all finiteisolated complex solutionsto a system
F(X) = 0 of N polynomial equations in N unknowns with complex
coefficients.  A partitioned linear product (PLP) formulation is used
for the start system of the homotopy map.The whole algorithm and its fortran90 implementation is described inWise, Steven M., Andrew J. Sommese, and Layne T. Watson. "Algorithm 801: POLSYS_PLP: A partitioned linear product homotopy code for solving polynomial systems of equations." ACM Transactions on Mathematical Software (TOMS) 26.1 (2000): 176-200.The sources are available onnetlib.The theoretical part ofPOLSYS_PLPis availableherePOLSYS_PLPis based onHOMPACKTo facilitate the build of this module, a copy ofPOLSYS_PLPoriginalsources is included in thepypolsys/801folder.InstallationYou'll need :python (tested for v >= 3.5);pip (optional);fortran compiler (tested withgfortranand withm2w64-toolchainon windows)lapack and blas installation (only on linux). The useful lapack/blas routines are also shipped withPOLSYS_PLPsources and built by default on Window or on demand on linux (see below). Optimized library are preferred and often already present on linux systems. If not, library likeopenblasand the required development files can be installed withsudo apt install libopenblas-devon debian based distribution (including ubuntu).If needed, please see the steps given in the continuous integration scriptworkflows.Using pip (preferred)You can installpypolsysfrom pip:pip install pypolsys [--user]You can also installpypolsysafter a download from github:pip install path/to/pypolsys-version.tar.gz [--user]or ineditablemode if you want to modify the sourcespip install -e path/to/pypolsysafter cloning the repos.pipwill installnumpy(mandatory) andsympyandscipy(optional, required only for tests).Note that on ubuntu, you will need to usepip3instead ofpipandpython3instead ofpython.On linux, if you want to force the building withPOLSYS_PLPlapack sources, you can tell it to pip withpip install --no-use-pep517 --install-option="--buildLapack" path/to/pypolsysThe flag--no-use-pep517avoids side effect ofinstall-optionthat disable wheels.
UsingPOLSYS_PLPlapack sources is the standard behavior on windows.TroubleshootingWith oldgfortranversion present on ubuntu 16.04 (seehere) the building may failed. To avoid this,intent(in, out)statement has to be removed from the originalpypolsys/801/polsys_plp.f90. It seems to work out of the box withgfortan-8.Running testsTo execute the full test suite, run :python -m pypolsys.testUsageNote that this projet is a work in progress and the API may change.Get startedLet us consider the following examplex**2 + y + z - 1 = 0
x + y**2 + z - 1 = 0
x + y + z**2 - 1 = 0Cox, David, John Little, and Donal O'Shea. Ideals, varieties, and algorithms: an introduction to computational algebraic geometry and commutative algebra. Springer Science & Business Media, 2013, From page 122.With 5 distinct solutions in C : (1,0,0) (0,1,0), (0,0,1), (-1+√2, -1+√2, -1+√2), (-1 -√2, -1-√2, -1-√2). The main steps ofpypolsys's workflow are:importnumpyasnpimportpypolsys# Declare the number of equation of the polynomial systemN=3# and the number of monoms of each equation (here 4 monoms for each equation).n_coef_per_eq=np.array([4,4,4],dtype=np.int32)# Provide the coefficients as 1D arrayall_coef=np.array([1,1,1,-1,1,1,1,-1,1,1,1,-1],dtype=np.complex)# then the degree of each monomall_deg=np.zeros((np.sum(n_coef_per_eq),N),dtype=np.int32)all_deg[0,0]=2all_deg[1,1]=1all_deg[2,2]=1all_deg[4,0]=1all_deg[5,1]=2all_deg[6,2]=1all_deg[8,0]=1all_deg[9,1]=1all_deg[10,2]=2# Pass it to POLSYS_PLPpypolsys.polsys.init_poly(N,n_coef_per_eq,all_coef,all_deg)# Create homogeneous partition# (N.B. Partitions are important to limit the number of paths# to track associated to solutions at infinity)part=pypolsys.utils.make_h_part(3)# Pass it to POLSYS_PLPpypolsys.polsys.init_partition(*part)# Show coefpypolsys.polsys.show_coef()# Found 8 solutions, and track 8 paths; some solutions appear twicebplp=pypolsys.polsys.solve(1e-8,1e-14,0.0)# Get the roots, array of size (N+1) x bplpr=pypolsys.polsys.myroots# Get status of the solving processpypolsys.polsys.report()Note that due to projective transformation, ther[N, :]is the homogeneous variable. All results are returned ready to used (unscaled and untransformed).Another way, sometimes more convenient, is to setup the polynomial with functionpypolsys.utils.fromSympy,importnumpyasnpimportpypolsysimportsympyassymx,y,z=sym.symbols('x, y, z')pol=pypolsys.utils.fromSympy([sym.poly(x**2+y+z-1,(x,y,z)),sym.poly(x+y**2+z-1,(x,y,z)),sym.poly(x+y+z**2-1,(x,y,z))])# Pass it to POLSYS_PLPpypolsys.polsys.init_poly(*pol)# Create homogeneous partitionpart=pypolsys.utils.make_h_part(3)# Pass it to POLSYS_PLPpypolsys.polsys.init_partition(*part)# Solvebplp=pypolsys.polsys.solve(1e-8,1e-14,0.0)# Get the roots, array of size (N+1) x bplpr=pypolsys.polsys.myroots# Get status of the solving processpypolsys.polsys.report()More examples are available in thepypolsys/test.pyfile. For dense polynomial system,denseflag can be passed to thesolvemethod to speed up evaluation.OrganisationThis python package is divided into two partspypolsys.polsyscorresponds to the interface toPOLSYS_PLPand maps the following fortran subroutines (more doc is emmbedded in the f90 files) :init_poly, initialize the polynomials monomials,init_partition, initialize the variables partition,solve, solve the polynomial system,refine, refine the given paths,bezout, compute the Bezout PLP number corresponding to the variable partition, usefull to test partition without solving,report, show a report on the homotopy solving processshow_partitionandshow_coef, show the variables partitions and the monomials respectively.some attributs are also available :myroots, containing the roots,path_statusandsolve_status, containing the status of each tracked path and of the global solving process,num_jac_eval, containing the number of evaluation of the Jacobian matrix.pypolsys.utilscontains utilities to facilitate the creation of the partition, polynomial or the estimation of the number of path (full python).View documentationThe doctrings are compatible with several Auto-generate API documentation, likepdoc3. Once the package has been installed or the atpypolsyslocation run,pdoc3 --html --force --config latex_math=True pypolsysThe html files are generated in place. Then open thepypolsys/index.htmlfile. This interactive doc is particularly useful to see latex includes.LimitationDue to shared variables in modules, only one polynomial instance can be handled. Concurrent calls to the.sofile may create unexpected behavior.
To solve several polynomials, you can useconcurrent.futures.How to contributeThis project started because we need some easy to deploy Homotopy solver. We are users but not experts on these methods.If you want to contribute topypolsys, your are welcomed! Don't hesitate toreport bugs, installation problems or ask questions onissues;propose some enhancements in the code or in documentation throughpull requests(PR);add or enhance support to other plateformsTo ensure code homogeneity among contributors, we use a source-code analyzer (eg. pylint).
Before submitting a PR, run the tests suite ;-)DeveloppementIf you need to modifywrapper.f90fortran source file. You will need to re-build the Fortran extension. This should be done into 2 stepsThe pyf file that avoid trouble with user_defined fortran type should be updated withf2pyutilities :```
f2py -m polsys -h polsys.pyf wrapper.f90 --overwrite-signature
```Re run the installLicenseThis file is part of pypolsys, a simple python wrapper to fortran package polsys_plp.
pypolsys is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
pypolsys is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with amc2moodle.  If not, seehttps://www.gnu.org/licenses/.