Package: pyneqsys
pyneqsys provides a convenience class for
representing and solving non-linear equation systems from symbolic expressions
(provided e.g. with the help ofSymPy).The numerical root finding is perfomed using either:scipy:scipy.optimize.rootmpmath (arbitrary precision):mpmath.calculus.optimization.MDNewtonkinsol (from SUNDIALS):pykinsol.solvenleq2 (ZIB library free for academic use):pynleq2.solvelevmar (Levenberg-Marquardt):levmar.levmarIn addition to offering a unified interface to different solvers, pyneqsys
can also derive the Jacobian analytically (when usingpyneqsys.SymbolicSys).
This is useful since doing so manually is widely recognized as both tedious and error
prone.The symbolic representation is usually in the form ofSymPyexpressions,
but the user may choose another symbolic back-end (seesym).In addition to deriving the Jacobian analytically the symbolic representation can for
example apply row-reduce. This is usful for when you have a overdetermined system (
formed from e.g. applying conservation laws) and want to solve the system by
root-finding rather than using a least-square optimization of e.g. Levenberg-Marquardt
style.Last, but not the least having a symbolic representation of your system of equations
allows you to generate publication quality latex representations of your equations (through
SymPy’s latex printer) from asinglesource‒no more error prone hand-rewriting of the same
equations in another format for presentation!DocumentationAutogenerated API documentation for latest stable release is found here:https://bjodah.github.io/pyneqsys/latest(and the development version for the current master branch is found here:http://hera.physchem.kth.se/~pyneqsys/branches/master/html).InstallationSimplest way to install pyneqsys and its dependencies is through theconda package manager:$ conda install -c bjodah pyneqsys pytest
$ pytest --pyargs pyneqsysOptional dependenciesIf you usedcondato installpyneqsysyou can skip this section.
But if you usepipyou may want to know that the default installation
ofpyneqsysonly requires SciPy:$ pip install pyneqsys
$ pytest --pyargs pyneqsys -rsThe above command should finish without errors but with some skipped tests.
The reason for why some tests are skipped should be because missing optional solvers.
To install the optional solvers you will first need to install third party libraries for
the solvers and then their python bindings. The 3rd party requirements are as follows:pykinsol(requiresSUNDIALS==2.7.0)levarmpmathif you want to see what packages need to be installed on a Debian based system you may look at thisDockerfile.If you manage to install all three external libraries you may install pyneqsys with the option “all”:$ pip install pyneqsys[all]
$ pytest --pyargs pyneqsys -rsnow there should be no skipped tests. If you try to install pyneqsys on a machine where you do not have
root permissions you may find the flag--userhelpful when using pip. Also if there are multiple
versions of python installed you may want to invoke python for an explicit version of python, e.g.:$ python3.6 -m pip install --user pyneqsys[all]seesetup.pyfor the exact list of requirements.Using DockerIf you haveDockerinstalled, you may use it to host a jupyter
notebook server:$ ./scripts/host-jupyter-using-docker.sh . 8888the first time you run the command some dependencies will be downloaded. When the installation
is complete there will be a link visible which you can open in your browser. You can also run
the test suite using the same docker-image:$ ./scripts/host-jupyter-using-docker.sh . 0there will be one skipped test (due to symengine missing in this pip installed environment) and
quite a few instances of RintimeWarning.ExamplesExample reformulated fromSciPy documentation:>>>frompyneqsys.symbolicimportSymbolicSys>>>neqsys=SymbolicSys.from_callback(...lambdax:[(x[0]-x[1])**3/2+x[0]-1,...(x[1]-x[0])**3/2+x[1]],2)>>>x,info=neqsys.solve([1,0])>>>assertinfo['success']>>>print(x)[0.84116390.1588361]here we did not need to enter the jacobian manually, SymPy did that for us.
For expressions containing transcendental functions we need to provide a
“backend” keyword arguemnt to enable symbolic derivation of the jacobian:>>>importmath>>>defpowell(x,params,backend=math):...A,exp=params[0],backend.exp...returnA*x[0]*x[1]-1,exp(-x[0])+exp(-x[1])-(1+A**-1)>>>powell_sys=SymbolicSys.from_callback(powell,2,1,names='x0 x1'.split())>>>x,info=powell_sys.solve([1,1],[1000.0])>>>assertinfo['success']>>>print(', '.join(['%.6e'%_for_insorted(x)]))1.477106e-04,6.769996e+00pyneqsys also allows the user to solve a system of equations for a span of
values for a parameter, and optionally plot the result vs. the varied value:>>>importmatplotlib.pyplotasplt>>>importnumpyasnp>>>x0_varied,x0_idx=np.linspace(1e3,3e3),0>>>all_x,all_info=powell_sys.solve_and_plot_series(x,[1000.0],x0_varied,x0_idx)>>>plt.savefig('example.png')For more examples look seeexamples/, and rendered jupyter notebooks here:http://hera.physchem.kth.se/~pyneqsys/branches/master/examplesRun notebooks using binderUsing only a web-browser (and an internet connection) it is possible to explore the
notebooks here: (by the courtesy of the people behind mybinder)CitingIf you make use of pyneqsys in e.g. academic work you may cite the following peer-reviewed publication:Depending on what underlying solver you are using you should also cite the appropriate paper
(you can look at the list of references in the JOSS article). If you need to reference,
in addition to the paper, a specific point version of pyneqsys (for e.g. reproducibility)
you can get per-version DOIs from the zendodo archive:LicensingThe source code is Open Source and is released under the simplified 2-clause BSD license. SeeLICENSEfor further details.ContributingContributors are welcome to suggest improvements athttps://github.com/bjodah/pyneqsys(see further detailshere).AuthorBjörn I. Dahlgren, contact:gmail address: bjodah