Package for numerically solving symbolically defined systems of non-linear equations.

## Project description

pyneqsys

========

.. image:: http://hera.physchem.kth.se:9090/api/badges/bjodah/pyneqsys/status.svg

:target: http://hera.physchem.kth.se:9090/bjodah/pyneqsys

:alt: Build status

.. image:: https://circleci.com/gh/bjodah/pyneqsys.svg?style=svg

:target: https://circleci.com/gh/bjodah/pyneqsys

:alt: Build status on CircleCI

.. image:: https://secure.travis-ci.org/bjodah/pyneqsys.svg?branch=master

:target: http://travis-ci.org/bjodah/pyneqsys

:alt: Build status on Travis-CI

.. image:: https://img.shields.io/pypi/v/pyneqsys.svg

:target: https://pypi.python.org/pypi/pyneqsys

:alt: PyPI version

.. image:: https://img.shields.io/badge/python-2.7,3.5,3.6-blue.svg

:target: https://www.python.org/

:alt: Python version

.. image:: https://img.shields.io/pypi/l/pyneqsys.svg

:target: https://github.com/bjodah/pyneqsys/blob/master/LICENSE

:alt: License

.. image:: http://hera.physchem.kth.se/~pyneqsys/branches/master/htmlcov/coverage.svg

:target: http://hera.physchem.kth.se/~pyneqsys/branches/master/htmlcov

:alt: coverage

`pyneqsys <https://github.com/bjodah/pyneqsys>`_ provides a convenience class for

representing and solving non-linear equation systems from symbolic expressions

(provided e.g. with the help of `SymPy <http://www.sympy.org>`_).

The numerical root finding is perfomed using either:

- scipy: `scipy.optimize.root <http://docs.scipy.org/doc/scipy/reference/generated/scipy.optimize.root.html>`_

- mpmath (arbitrary precision): `mpmath.calculus.optimization.MDNewton <http://mpmath.org/doc/1.0.0/calculus/optimization.html#mpmath.calculus.optimization.MDNewton>`_

- kinsol (from SUNDIALS): `pykinsol.solve <http://bjodah.github.io/pykinsol/latest/pykinsol.html#pykinsol.solve>`_

- nleq2 (ZIB library free for academic use): `pynleq2.solve <http://bjodah.github.io/pynleq2/pynleq2.html#pynleq2.solve>`_

- levmar (Levenberg-Marquardt): levmar.levmar `<https://bjodah.github.io/levmar/latest/levmar.html#levmar.levmar>`_

In addition to offering a unified interface to different solvers, ``pyneqsys``

can also derive the Jacobian analytically (when using ``pyneqsys.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 of `SymPy <https://www.sympy.org/>`_

expressions, but the user may choose another symbolic back-end (see `sym <https://github.com/bjodah/sym>`_).

In addition to deriving the Jacobian anyltically 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 a **single** source‒no more error prone hand-rewriting of the same

equations in another format for presentation!

Documentation

-------------

Autogenerated 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>`_).

Installation

------------

Simplest way to install pyneqsys and its dependencies is through the `conda package manager <http://conda.pydata.org/docs/>`_:

::

$ conda install -c bjodah pyneqsys pytest

$ pytest --pyargs pyneqsys

Optional dependencies

~~~~~~~~~~~~~~~~~~~~~

If you used ``conda`` to install pyneqsys_ you can skip this section.

But if you use ``pip`` you may want to know that the default installation

of ``pyneqsys`` only requires SciPy::

$ pip install pyneqsys

$ pytest --pyargs pyneqsys -rs

The 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 <https://github.com/bjodah/pykinsol>`_ (requires SUNDIALS_ ==2.7.0)

- `levar <https://github.com/bjodah/levmar>`_

- `mpmath <https://www.mpmath.org>`_

.. _SUNDIALS: https://computation.llnl.gov/projects/sundials

if you want to see what packages need to be installed on a Debian based system you may look at this

`Dockerfile <scripts/environment/Dockerfile>`_.

If you manage to install all three external libraries you may install pyneqsys with the option "all"::

$ pip install pyneqsys[all]

$ pytest --pyargs pyneqsys -rs

now 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 ``--user`` helpful 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]

see `setup.py <setup.py>`_ for the exact list of requirements.

Using Docker

~~~~~~~~~~~~

If you have `Docker <https://www.docker.com>`_ installed, you may use it to host a jupyter

notebook server::

$ ./scripts/host-jupyter-using-docker.sh . 8888

the 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 . 0

there will be one skipped test (due to symengine missing in this pip installed environment) and

quite a few instances of RintimeWarning.

Examples

--------

Example reformulated from `SciPy documentation <http://docs.scipy.org/doc/scipy/reference/generated/scipy.optimize.root.html>`_:

.. code:: python

>>> from pyneqsys.symbolic import SymbolicSys

>>> neqsys = SymbolicSys.from_callback(

... lambda x: [(x[0] - x[1])**3/2 + x[0] - 1,

... (x[1] - x[0])**3/2 + x[1]], 2)

>>> x, info = neqsys.solve([1, 0])

>>> assert info['success']

>>> print(x)

[ 0.8411639 0.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:

.. code:: python

>>> import math

>>> def powell(x, params, backend=math):

... A, exp = params[0], backend.exp

... return A*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])

>>> assert info['success']

>>> print(', '.join(['%.6e' % _ for _ in sorted(x)]))

1.477106e-04, 6.769996e+00

pyneqsys also allows the user to solve an eqauation system for a span of

values for a parameter, and optionally plot the result vs. the varied value:

.. code:: python

>>> import numpy as np

>>> all_x, all_info = powell_sys.solve_and_plot_series(x, [1000.0], np.linspace(1e3, 3e3), 0) # doctest: +SKIP

.. image:: https://raw.githubusercontent.com/bjodah/pyneqsys/master/examples/example.png

For more examples look see

`examples/ <https://github.com/bjodah/pyneqsys/tree/master/examples>`_, and rendered jupyter notebooks here:

`<http://hera.physchem.kth.se/~pyneqsys/branches/master/examples>`_

Run notebooks using binder

~~~~~~~~~~~~~~~~~~~~~~~~~~

Using only a web-browser (and an internet connection) it is possible to explore the

notebooks here: (by the courtesy of the people behind mybinder)

.. image:: http://mybinder.org/badge.svg

:target: https://mybinder.org/v2/gh/bjodah/pyneqsys/v0.5.0?filepath=index.ipynb

:alt: Binder

License

-------

The source code is Open Source and is released under the simplified 2-clause BSD license. See `LICENSE <LICENSE>`_ for further details.

Contributing

------------

Contributors are welcome to suggest improvements at https://github.com/bjodah/pyneqsys

(see further details `here <CONTRIBUTORS.rst>`_).

Author

------

Björn I. Dahlgren, contact:

- gmail address: bjodah

- kth.se address: bda

========

.. image:: http://hera.physchem.kth.se:9090/api/badges/bjodah/pyneqsys/status.svg

:target: http://hera.physchem.kth.se:9090/bjodah/pyneqsys

:alt: Build status

.. image:: https://circleci.com/gh/bjodah/pyneqsys.svg?style=svg

:target: https://circleci.com/gh/bjodah/pyneqsys

:alt: Build status on CircleCI

.. image:: https://secure.travis-ci.org/bjodah/pyneqsys.svg?branch=master

:target: http://travis-ci.org/bjodah/pyneqsys

:alt: Build status on Travis-CI

.. image:: https://img.shields.io/pypi/v/pyneqsys.svg

:target: https://pypi.python.org/pypi/pyneqsys

:alt: PyPI version

.. image:: https://img.shields.io/badge/python-2.7,3.5,3.6-blue.svg

:target: https://www.python.org/

:alt: Python version

.. image:: https://img.shields.io/pypi/l/pyneqsys.svg

:target: https://github.com/bjodah/pyneqsys/blob/master/LICENSE

:alt: License

.. image:: http://hera.physchem.kth.se/~pyneqsys/branches/master/htmlcov/coverage.svg

:target: http://hera.physchem.kth.se/~pyneqsys/branches/master/htmlcov

:alt: coverage

`pyneqsys <https://github.com/bjodah/pyneqsys>`_ provides a convenience class for

representing and solving non-linear equation systems from symbolic expressions

(provided e.g. with the help of `SymPy <http://www.sympy.org>`_).

The numerical root finding is perfomed using either:

- scipy: `scipy.optimize.root <http://docs.scipy.org/doc/scipy/reference/generated/scipy.optimize.root.html>`_

- mpmath (arbitrary precision): `mpmath.calculus.optimization.MDNewton <http://mpmath.org/doc/1.0.0/calculus/optimization.html#mpmath.calculus.optimization.MDNewton>`_

- kinsol (from SUNDIALS): `pykinsol.solve <http://bjodah.github.io/pykinsol/latest/pykinsol.html#pykinsol.solve>`_

- nleq2 (ZIB library free for academic use): `pynleq2.solve <http://bjodah.github.io/pynleq2/pynleq2.html#pynleq2.solve>`_

- levmar (Levenberg-Marquardt): levmar.levmar `<https://bjodah.github.io/levmar/latest/levmar.html#levmar.levmar>`_

In addition to offering a unified interface to different solvers, ``pyneqsys``

can also derive the Jacobian analytically (when using ``pyneqsys.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 of `SymPy <https://www.sympy.org/>`_

expressions, but the user may choose another symbolic back-end (see `sym <https://github.com/bjodah/sym>`_).

In addition to deriving the Jacobian anyltically 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 a **single** source‒no more error prone hand-rewriting of the same

equations in another format for presentation!

Documentation

-------------

Autogenerated 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>`_).

Installation

------------

Simplest way to install pyneqsys and its dependencies is through the `conda package manager <http://conda.pydata.org/docs/>`_:

::

$ conda install -c bjodah pyneqsys pytest

$ pytest --pyargs pyneqsys

Optional dependencies

~~~~~~~~~~~~~~~~~~~~~

If you used ``conda`` to install pyneqsys_ you can skip this section.

But if you use ``pip`` you may want to know that the default installation

of ``pyneqsys`` only requires SciPy::

$ pip install pyneqsys

$ pytest --pyargs pyneqsys -rs

The 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 <https://github.com/bjodah/pykinsol>`_ (requires SUNDIALS_ ==2.7.0)

- `levar <https://github.com/bjodah/levmar>`_

- `mpmath <https://www.mpmath.org>`_

.. _SUNDIALS: https://computation.llnl.gov/projects/sundials

if you want to see what packages need to be installed on a Debian based system you may look at this

`Dockerfile <scripts/environment/Dockerfile>`_.

If you manage to install all three external libraries you may install pyneqsys with the option "all"::

$ pip install pyneqsys[all]

$ pytest --pyargs pyneqsys -rs

now 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 ``--user`` helpful 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]

see `setup.py <setup.py>`_ for the exact list of requirements.

Using Docker

~~~~~~~~~~~~

If you have `Docker <https://www.docker.com>`_ installed, you may use it to host a jupyter

notebook server::

$ ./scripts/host-jupyter-using-docker.sh . 8888

the 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 . 0

there will be one skipped test (due to symengine missing in this pip installed environment) and

quite a few instances of RintimeWarning.

Examples

--------

Example reformulated from `SciPy documentation <http://docs.scipy.org/doc/scipy/reference/generated/scipy.optimize.root.html>`_:

.. code:: python

>>> from pyneqsys.symbolic import SymbolicSys

>>> neqsys = SymbolicSys.from_callback(

... lambda x: [(x[0] - x[1])**3/2 + x[0] - 1,

... (x[1] - x[0])**3/2 + x[1]], 2)

>>> x, info = neqsys.solve([1, 0])

>>> assert info['success']

>>> print(x)

[ 0.8411639 0.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:

.. code:: python

>>> import math

>>> def powell(x, params, backend=math):

... A, exp = params[0], backend.exp

... return A*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])

>>> assert info['success']

>>> print(', '.join(['%.6e' % _ for _ in sorted(x)]))

1.477106e-04, 6.769996e+00

pyneqsys also allows the user to solve an eqauation system for a span of

values for a parameter, and optionally plot the result vs. the varied value:

.. code:: python

>>> import numpy as np

>>> all_x, all_info = powell_sys.solve_and_plot_series(x, [1000.0], np.linspace(1e3, 3e3), 0) # doctest: +SKIP

.. image:: https://raw.githubusercontent.com/bjodah/pyneqsys/master/examples/example.png

For more examples look see

`examples/ <https://github.com/bjodah/pyneqsys/tree/master/examples>`_, and rendered jupyter notebooks here:

`<http://hera.physchem.kth.se/~pyneqsys/branches/master/examples>`_

Run notebooks using binder

~~~~~~~~~~~~~~~~~~~~~~~~~~

Using only a web-browser (and an internet connection) it is possible to explore the

notebooks here: (by the courtesy of the people behind mybinder)

.. image:: http://mybinder.org/badge.svg

:target: https://mybinder.org/v2/gh/bjodah/pyneqsys/v0.5.0?filepath=index.ipynb

:alt: Binder

License

-------

The source code is Open Source and is released under the simplified 2-clause BSD license. See `LICENSE <LICENSE>`_ for further details.

Contributing

------------

Contributors are welcome to suggest improvements at https://github.com/bjodah/pyneqsys

(see further details `here <CONTRIBUTORS.rst>`_).

Author

------

Björn I. Dahlgren, contact:

- gmail address: bjodah

- kth.se address: bda

## Project details

## Release history Release notifications | RSS feed

## Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Filename, size | File type | Python version | Upload date | Hashes |
---|---|---|---|---|

Filename, size pyneqsys-0.5.1.tar.gz (23.4 kB) | File type Source | Python version None | Upload date | Hashes View |