pykinsol
========

.. image:: http://hera.physchem.kth.se:9090/api/badges/bjodah/pykinsol/status.svg
   :target: http://hera.physchem.kth.se:9090/bjodah/pykinsol
   :alt: Build status
.. image:: https://img.shields.io/pypi/v/pykinsol.svg
   :target: https://pypi.python.org/pypi/pykinsol
   :alt: PyPI version
.. image:: https://img.shields.io/pypi/l/pykinsol.svg
   :target: https://github.com/bjodah/pykinsol/blob/master/LICENSE
   :alt: License
.. image:: http://hera.physchem.kth.se/~pykinsol/branches/master/htmlcov/coverage.svg
   :target: http://hera.physchem.kth.se/~pykinsol/branches/master/htmlcov
   :alt: coverage


`pykinsol <https://github.com/bjodah/pykinsol>`_ provides a
`Python <http://www.python.org>`_ binding to the
`Nonlinear system of equation <https://en.wikipedia.org/wiki/Nonlinear_system>`_
solver algorithms from `kinsol <https://computation.llnl.gov/casc/sundials/description/description.html#descr_kinsol>`_ in the
`SUNDIALS suite <https://computation.llnl.gov/casc/sundials/main.html>`_. ``pykinsol`` allows a user to numerically solve
(systems of) non-linear equations. Note that not all functionality of KINSOL are currently exposed in the python wrapper. Additional functinoality is however easy to add if needed.


Documentation
-------------
Autogenerated API documentation is found `here <http://hera.physchem.kth.se/~pykinsol/branches/master/html>`_.

Installation
------------
Simplest way to install pykinsol is to use the
`conda package manager <http://conda.pydata.org/docs/>`_:

::

   $ conda install -c bjodah pykinsol pytest
   $ python -m pytest --pyargs pykinsol

tests should pass.

Binary distribution is available here:
`<https://anaconda.org/bjodah/pykinsol>`_

Source distribution is available here:
`<https://pypi.python.org/pypi/pykinsol>`_

To compile from source you may proceed e.g. as follows:

::

   $ LLAPACK=openblas python3.4 setup.py install --user

where we specified specifically what LAPACK implementation we used for building SUNDIALS.

Examples
--------
See `examples/ <https://github.com/bjodah/pykinsol/tree/master/examples>`_, and rendered jupyter notebooks here:
`<http://hera.physchem.kth.se/~pykinsol/branches/master/examples>`_

Here is a simple example:

.. code:: python

   >>> def f(x, fout):
   ...     fout[0] = x[0] + (x[0] - x[1])**3/2 - 1
   ...     fout[1] = x[1] + (x[1] - x[0])**3/2
   ... 
   >>> def j(x, Jout, fx):
   ...     Jout[0, 0] =  1 + 3/2 * (x[0] - x[1])**2
   ...     Jout[0, 1] =  -3/2 * (x[0] - x[1])**2   
   ...     Jout[1, 0] =  -3/2 * (x[1] - x[0])**2   
   ...     Jout[1, 1] =  1 + 3/2 * (x[1] - x[0])**2
   ...
   >>> from pykinsol import solve
   >>> result = solve(f, j, [0, 0])
   >>> assert result['success']
   >>> print(result['x'])
   [ 0.84116389  0.15883611]


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

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

Author
------
Björn I. Dahlgren, contact:

- gmail address: bjodah
- kth.se address: bda
