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