1Metadata-Version: 2.1 2Name: pyneqsys 3Version: 0.5.7 4Summary: Package for numerically solving symbolically defined systems of non-linear equations. 5Home-page: https://github.com/bjodah/pyneqsys 6Author: Bjoern I. Dahlgren 7Author-email: bjodah@gmail.com 8License: BSD 9Description: pyneqsys 10 ======== 11 12 .. image:: http://hera.physchem.kth.se:9090/api/badges/bjodah/pyneqsys/status.svg 13 :target: http://hera.physchem.kth.se:9090/bjodah/pyneqsys 14 :alt: Build status 15 .. image:: https://circleci.com/gh/bjodah/pyneqsys.svg?style=svg 16 :target: https://circleci.com/gh/bjodah/pyneqsys 17 :alt: Build status on CircleCI 18 .. image:: https://secure.travis-ci.org/bjodah/pyneqsys.svg?branch=master 19 :target: http://travis-ci.org/bjodah/pyneqsys 20 :alt: Build status on Travis-CI 21 .. image:: https://img.shields.io/pypi/v/pyneqsys.svg 22 :target: https://pypi.python.org/pypi/pyneqsys 23 :alt: PyPI version 24 .. image:: https://img.shields.io/badge/python-2.7,3.5,3.6-blue.svg 25 :target: https://www.python.org/ 26 :alt: Python version 27 .. image:: http://joss.theoj.org/papers/10.21105/joss.00531/status.svg 28 :target: https://doi.org/10.21105/joss.00531 29 :alt: DOI 30 .. image:: https://img.shields.io/pypi/l/pyneqsys.svg 31 :target: https://github.com/bjodah/pyneqsys/blob/master/LICENSE 32 :alt: License file 33 .. image:: http://hera.physchem.kth.se/~pyneqsys/branches/master/htmlcov/coverage.svg 34 :target: http://hera.physchem.kth.se/~pyneqsys/branches/master/htmlcov 35 :alt: coverage 36 37 pyneqsys provides a convenience class for 38 representing and solving non-linear equation systems from symbolic expressions 39 (provided e.g. with the help of SymPy_). 40 41 The numerical root finding is perfomed using either: 42 43 - scipy: `scipy.optimize.root <http://docs.scipy.org/doc/scipy/reference/generated/scipy.optimize.root.html>`_ 44 - mpmath (arbitrary precision): `mpmath.calculus.optimization.MDNewton <http://mpmath.org/doc/1.0.0/calculus/optimization.html#mpmath.calculus.optimization.MDNewton>`_ 45 - kinsol (from SUNDIALS): `pykinsol.solve <http://bjodah.github.io/pykinsol/latest/pykinsol.html#pykinsol.solve>`_ 46 - nleq2 (ZIB library free for academic use): `pynleq2.solve <http://bjodah.github.io/pynleq2/pynleq2.html#pynleq2.solve>`_ 47 - levmar (Levenberg-Marquardt): `levmar.levmar <https://bjodah.github.io/levmar/latest/levmar.html#levmar.levmar>`_ 48 49 In addition to offering a unified interface to different solvers, pyneqsys 50 can also derive the Jacobian analytically (when using ``pyneqsys.SymbolicSys``). 51 This is useful since doing so manually is widely recognized as both tedious and error 52 prone. 53 54 The symbolic representation is usually in the form of SymPy_ expressions, 55 but the user may choose another symbolic back-end (see `sym <https://github.com/bjodah/sym>`_). 56 57 In addition to deriving the Jacobian analytically the symbolic representation can for 58 example apply row-reduce. This is usful for when you have a overdetermined system ( 59 formed from e.g. applying conservation laws) and want to solve the system by 60 root-finding rather than using a least-square optimization of e.g. Levenberg-Marquardt 61 style. 62 63 Last, but not the least having a symbolic representation of your system of equations 64 allows you to generate publication quality latex representations of your equations (through 65 SymPy's latex printer) from a **single** source‒no more error prone hand-rewriting of the same 66 equations in another format for presentation! 67 68 .. _SymPy: http://www.sympy.org 69 70 Documentation 71 ------------- 72 Autogenerated API documentation for latest stable release is found here: 73 `<https://bjodah.github.io/pyneqsys/latest>`_ 74 (and the development version for the current master branch is found here: 75 `<http://hera.physchem.kth.se/~pyneqsys/branches/master/html>`_). 76 77 Installation 78 ------------ 79 Simplest way to install pyneqsys and its dependencies is through the `conda package manager <http://conda.pydata.org/docs/>`_: 80 81 :: 82 83 $ conda install -c bjodah pyneqsys pytest 84 $ pytest --pyargs pyneqsys 85 86 Optional dependencies 87 ~~~~~~~~~~~~~~~~~~~~~ 88 If you used ``conda`` to install pyneqsys_ you can skip this section. 89 But if you use ``pip`` you may want to know that the default installation 90 of ``pyneqsys`` only requires SciPy:: 91 92 $ pip install pyneqsys 93 $ pytest --pyargs pyneqsys -rs 94 95 The above command should finish without errors but with some skipped tests. 96 The reason for why some tests are skipped should be because missing optional solvers. 97 To install the optional solvers you will first need to install third party libraries for 98 the solvers and then their python bindings. The 3rd party requirements are as follows: 99 100 - `pykinsol <https://github.com/bjodah/pykinsol>`_ (requires SUNDIALS_ ==2.7.0) 101 - `levar <https://github.com/bjodah/levmar>`_ 102 - `mpmath <http://www.mpmath.org>`_ 103 104 105 if you want to see what packages need to be installed on a Debian based system you may look at this 106 `Dockerfile <scripts/environment/Dockerfile>`_. 107 108 If you manage to install all three external libraries you may install pyneqsys with the option "all":: 109 110 $ pip install pyneqsys[all] 111 $ pytest --pyargs pyneqsys -rs 112 113 now there should be no skipped tests. If you try to install pyneqsys on a machine where you do not have 114 root permissions you may find the flag ``--user`` helpful when using pip. Also if there are multiple 115 versions of python installed you may want to invoke python for an explicit version of python, e.g.:: 116 117 $ python3.6 -m pip install --user pyneqsys[all] 118 119 see `setup.py <setup.py>`_ for the exact list of requirements. 120 121 .. _SUNDIALS: https://computation.llnl.gov/projects/sundials 122 123 Using Docker 124 ~~~~~~~~~~~~ 125 If you have `Docker <https://www.docker.com>`_ installed, you may use it to host a jupyter 126 notebook server:: 127 128 $ ./scripts/host-jupyter-using-docker.sh . 8888 129 130 the first time you run the command some dependencies will be downloaded. When the installation 131 is complete there will be a link visible which you can open in your browser. You can also run 132 the test suite using the same docker-image:: 133 134 $ ./scripts/host-jupyter-using-docker.sh . 0 135 136 there will be one skipped test (due to symengine missing in this pip installed environment) and 137 quite a few instances of RintimeWarning. 138 139 Examples 140 -------- 141 Example reformulated from `SciPy documentation <http://docs.scipy.org/doc/scipy/reference/generated/scipy.optimize.root.html>`_: 142 143 .. code:: python 144 145 >>> from pyneqsys.symbolic import SymbolicSys 146 >>> neqsys = SymbolicSys.from_callback( 147 ... lambda x: [(x[0] - x[1])**3/2 + x[0] - 1, 148 ... (x[1] - x[0])**3/2 + x[1]], 2) 149 >>> x, info = neqsys.solve([1, 0]) 150 >>> assert info['success'] 151 >>> print(x) 152 [0.8411639 0.1588361] 153 154 here we did not need to enter the jacobian manually, SymPy did that for us. 155 For expressions containing transcendental functions we need to provide a 156 "backend" keyword arguemnt to enable symbolic derivation of the jacobian: 157 158 .. code:: python 159 160 >>> import math 161 >>> def powell(x, params, backend=math): 162 ... A, exp = params[0], backend.exp 163 ... return A*x[0]*x[1] - 1, exp(-x[0]) + exp(-x[1]) - (1 + A**-1) 164 >>> powell_sys = SymbolicSys.from_callback(powell, 2, 1, names='x0 x1'.split()) 165 >>> x, info = powell_sys.solve([1, 1], [1000.0]) 166 >>> assert info['success'] 167 >>> print(', '.join(['%.6e' % _ for _ in sorted(x)])) 168 1.477106e-04, 6.769996e+00 169 170 pyneqsys also allows the user to solve a system of equations for a span of 171 values for a parameter, and optionally plot the result vs. the varied value: 172 173 .. code:: python 174 175 >>> import matplotlib.pyplot as plt 176 >>> import numpy as np 177 >>> x0_varied, x0_idx = np.linspace(1e3, 3e3), 0 178 >>> all_x, all_info = powell_sys.solve_and_plot_series(x, [1000.0], x0_varied, x0_idx) 179 >>> plt.savefig('example.png') 180 181 .. image:: https://raw.githubusercontent.com/bjodah/pyneqsys/master/examples/example.png 182 183 For more examples look see 184 `examples/ <https://github.com/bjodah/pyneqsys/tree/master/examples>`_, and rendered jupyter notebooks here: 185 `<http://hera.physchem.kth.se/~pyneqsys/branches/master/examples>`_ 186 187 Run notebooks using binder 188 ~~~~~~~~~~~~~~~~~~~~~~~~~~ 189 Using only a web-browser (and an internet connection) it is possible to explore the 190 notebooks here: (by the courtesy of the people behind mybinder) 191 192 .. image:: http://mybinder.org/badge.svg 193 :target: https://mybinder.org/v2/gh/bjodah/pyneqsys/d8775becc6f30b4d3e7920f53d5f318c0672195b?filepath=index.ipynb 194 :alt: Binder 195 196 Citing 197 ------ 198 If you make use of pyneqsys in e.g. academic work you may cite the following peer-reviewed publication: 199 200 .. image:: http://joss.theoj.org/papers/10.21105/joss.00531/status.svg 201 :target: https://doi.org/10.21105/joss.00531 202 :alt: Journal of Open Source Software DOI 203 204 Depending on what underlying solver you are using you should also cite the appropriate paper 205 (you can look at the list of references in the JOSS article). If you need to reference, 206 in addition to the paper, a specific point version of pyneqsys (for e.g. reproducibility) 207 you can get per-version DOIs from the zendodo archive: 208 209 .. image:: https://zenodo.org/badge/43504371.svg 210 :target: https://zenodo.org/badge/latestdoi/43504371 211 :alt: Zenodo DOI 212 213 214 Licensing 215 --------- 216 The source code is Open Source and is released under the simplified 2-clause BSD license. See LICENSE_ for further details. 217 218 .. _LICENSE: LICENSE 219 220 221 Contributing 222 ------------ 223 Contributors are welcome to suggest improvements at https://github.com/bjodah/pyneqsys 224 (see further details `here <CONTRIBUTING.rst>`_). 225 226 Author 227 ------ 228 Björn I. Dahlgren, contact: 229 230 - gmail address: bjodah 231 232Platform: UNKNOWN 233Classifier: Development Status :: 4 - Beta 234Classifier: License :: OSI Approved :: BSD License 235Classifier: Operating System :: OS Independent 236Classifier: Topic :: Scientific/Engineering 237Classifier: Topic :: Scientific/Engineering :: Mathematics 238Provides-Extra: symbolic 239Provides-Extra: docs 240Provides-Extra: solvers 241Provides-Extra: testing 242Provides-Extra: all 243