.. pygslodeiv2 documentation master file, created by
   sphinx-quickstart on Wed Apr 22 14:17:35 2020.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

Welcome to pygslodeiv2's documentation!
=======================================

.. toctree::
   :maxdepth: 4
   :caption: Contents:

   pygslodeiv2


Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

Overview
========

.. image:: http://hera.physchem.kth.se:9090/api/badges/bjodah/pygslodeiv2/status.svg
   :target: http://hera.physchem.kth.se:9090/bjodah/pygslodeiv2
   :alt: Build status
.. image:: https://circleci.com/gh/bjodah/pygslodeiv2.svg?style=svg
   :target: https://circleci.com/gh/bjodah/pygslodeiv2
   :alt: Build status on CircleCI
.. image:: https://secure.travis-ci.org/bjodah/pygslodeiv2.svg?branch=master
   :target: http://travis-ci.org/bjodah/pygslodeiv2
   :alt: Build status on Travis-CI
.. image:: https://img.shields.io/pypi/v/pygslodeiv2.svg
   :target: https://pypi.python.org/pypi/pygslodeiv2
   :alt: PyPI version
.. image:: https://img.shields.io/badge/python-2.7,3.4,3.5-blue.svg
   :target: https://www.python.org/
   :alt: Python version
.. image:: https://img.shields.io/pypi/l/pygslodeiv2.svg
   :target: https://github.com/bjodah/pygslodeiv2/blob/master/LICENSE
   :alt: License
.. image:: http://hera.physchem.kth.se/~pygslodeiv2/branches/master/htmlcov/coverage.svg
   :target: http://hera.physchem.kth.se/~pygslodeiv2/branches/master/htmlcov
   :alt: coverage
.. image:: https://zenodo.org/badge/41481237.svg
   :target: https://zenodo.org/badge/latestdoi/41481237
   :alt: Zenodo DOI


`pygslodeiv2 <https://github.com/bjodah/pygslodeiv2>`_ provides a
`Python <http://www.python.org>`_ binding to the
`Ordinary Differential Equation <https://en.wikipedia.org/wiki/Ordinary_differential_equation>`_
integration routines exposed by the `odeiv2 interface <https://www.gnu.org/software/gsl/manual/html_node/Ordinary-Differential-Equations.html>`_ of
`GSL - GNU Scientific Library <http://www.gnu.org/software/gsl/>`_.
The odeiv2 interface allows a user to numerically integrate (systems of) differential equations.

The following `stepping functions <https://www.gnu.org/software/gsl/manual/html_node/Stepping-Functions.html>`_ are available:

- rk2
- rk4
- rkf45
- rkck
- rk8pd
- rk1imp
- rk2imp
- rk4imp
- bsimp
- msadams
- msbdf

Note that all implicit steppers (those ending with "imp") and msbdf require a user supplied
callback for calculating the jacobian.

You may also want to know that you can use ``pygslodeiv2`` from
`pyodesys <https://github.com/bjodah/pyodesys>`_
which can e.g. derive the Jacobian analytically (using SymPy). ``pyodesys`` also provides
plotting functions, C++ code-generation and more.

Documentation
-------------
Autogenerated API documentation for latest stable release is found here:
`<https://bjodah.github.io/pygslodeiv2/latest>`_
(and the development version for the current master branch are found here:
`<http://hera.physchem.kth.se/~pygslodeiv2/branches/master/html>`_).

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

::

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

tests should pass.

Binary distribution is available here:
`<https://anaconda.org/bjodah/pygslodeiv2>`_, conda recipes for stable releases are available here: 
`<http://hera.physchem.kth.se/~pygslodeiv2/conda-recipes>`_.

Source distribution is available here (requires GSL v1.16 or v2.1 shared lib with headers):
`<https://pypi.python.org/pypi/pygslodeiv2>`_ (with mirrored files kept here:
`<http://hera.physchem.kth.se/~pygslodeiv2/releases>`_)

Examples
--------
The classic van der Pol oscillator (see `examples/van_der_pol.py <examples/van_der_pol.py>`_)

.. code:: python

   >>> import numpy as np
   >>> from pygslodeiv2 import integrate_predefined  # also: integrate_adaptive
   >>> mu = 1.0
   >>> def f(t, y, dydt):
   ...     dydt[0] = y[1]
   ...     dydt[1] = -y[0] + mu*y[1]*(1 - y[0]**2)
   ... 
   >>> def j(t, y, Jmat, dfdt):
   ...     Jmat[0, 0] = 0
   ...     Jmat[0, 1] = 1
   ...     Jmat[1, 0] = -1 -mu*2*y[1]*y[0]
   ...     Jmat[1, 1] = mu*(1 - y[0]**2)
   ...     dfdt[0] = 0
   ...     dfdt[1] = 0
   ...
   >>> y0 = [1, 0]; dt0=1e-8; t0=0.0; atol=1e-8; rtol=1e-8
   >>> tout = np.linspace(0, 10.0, 200)
   >>> yout, info = integrate_predefined(f, j, y0, tout, dt0, atol, rtol,
   ...                                   method='bsimp')  # Implicit Bulirsch-Stoer
   >>> import matplotlib.pyplot as plt
   >>> series = plt.plot(tout, yout)
   >>> plt.show()  # doctest: +SKIP


.. image:: https://raw.githubusercontent.com/bjodah/pygslodeiv2/master/examples/van_der_pol.png

For more examples see `examples/ <https://github.com/bjodah/pygslodeiv2/tree/master/examples>`_, and rendered jupyter notebooks here:
`<http://hera.physchem.kth.se/~pygslodeiv2/branches/master/examples>`_


License
-------
The source code is Open Source and is released under GNU GPL v3. See `LICENSE <LICENSE>`_ for further details.
Contributors are welcome to suggest improvements at https://github.com/bjodah/pygslodeiv2

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

- gmail address: bjodah