=======
pynleq2
=======

.. image:: http://hera.physchem.kth.se:8080/github.com/bjodah/pynleq2/status.svg?branch=master
   :target: http://hera.physchem.kth.se:8080/github.com/bjodah/pynleq2
   :alt: Build status
.. image:: https://img.shields.io/pypi/v/pynleq2.svg
   :target: https://pypi.python.org/pypi/pynleq2
   :alt: PyPI version
.. image:: https://img.shields.io/pypi/l/pynleq2.svg
   :target: https://github.com/bjodah/pynleq2/blob/master/LICENSE
   :alt: License
.. image:: http://hera.physchem.kth.se/~pynleq2/master/htmlcov/coverage.svg
   :target: http://hera.physchem.kth.se/~pynleq2/master/htmlcov
   :alt: coverage


`pynleq2 <https://github.com/bjodah/pynleq2>`_ provides a
`Python <http://www.python.org>`_ binding to the
`NLEQ2 <http://elib.zib.de/pub/elib/codelib/en/nonlin.html>`_
algorithm from `CodeLib <http://elib.zib.de/pub/elib/codelib/en/>`_ distributed
by `Zuse Institute Berlin (ZIB) <http://www.zib.de/>`_.
Note that this package does not contain the source code of NLEQ2 which has its
`own license <http://elib.zib.de/pub/elib/codelib/en/Lizenz.html>`_ (as of 2015-10-20 
it may be used for free for academic use, but not for commerical use).

The fortran to python interface is originally from the
`PySCeS project <http://pysces.sourceforge.net/>`_.

Documentation
-------------
Autogenerated API documentation is found here: `<https://bjodah.github.com/pynleq2>`_

Installation
------------
Simplest way to install is to install using pip:

::

   $ PYNLEQ2_NLEQ2_ROOT_URL=http://repo.my-univeristy.edu/mirror/nleq2/ pip install pynleq2

Note that you need to modify the environment variable ``$PYNLEQ2_NLEQ2_ROOT_URL`` to point
to the source repository at ZIB after you have ensured that your use is in line with their
license agreement.

Source distribution of the binding is available here:
`<https://pypi.python.org/pypi/pynleq2>`_

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

.. code:: python

   >>> from pynleq2 import solve
   >>> def f(x, i):
   ...     return [x[0] + (x[0] - x[1])**3/2 - 1,
   ...             (x[1] - x[0])**3/2 + x[1]], i
   >>> def j(x):
   ...     return [
   ...         [
   ...             1 + 3/2 * (x[0] - x[1])**(3-1),
   ...             -3/2 * (x[0] - x[1])**(3-1)
   ...         ],
   ...         [
   ...             -3/2 * (x[1] - x[0])**(3-1),
   ...             1 + 3/2 * (x[1] - x[0])**(3 - 1)
   ...         ]
   ...     ]
   ...
   >>> x, ierr = solve(f, j, [0, 1])
   >>> x
   array([ 0.8411639,  0.1588361])


License
-------
The pynleq2 source code (the bindings) is Open Source and is released under the
simplified 2-clause BSD license. See `LICENSE <LICENSE>`_, 
`LICENSE_pysces.txt <LICENSE_pysces.txt>`_ and NLEQ2 license for further
details.

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

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