ChemPy
======

.. image:: http://hera.physchem.kth.se:9090/api/badges/bjodah/chempy/status.svg
   :target: http://hera.physchem.kth.se:9090/bjodah/chempy
   :alt: Build status
.. image:: https://img.shields.io/pypi/v/chempy.svg
   :target: https://pypi.python.org/pypi/chempy
   :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/chempy.svg
   :target: https://github.com/bjodah/chempy/blob/master/LICENSE
   :alt: License
.. image:: http://img.shields.io/badge/benchmarked%20by-asv-green.svg?style=flat
   :target: http://hera.physchem.kth.se/~chempy/benchmarks
   :alt: airspeedvelocity
.. image:: http://hera.physchem.kth.se/~chempy/branches/master/htmlcov/coverage.svg
   :target: http://hera.physchem.kth.se/~chempy/branches/master/htmlcov
   :alt: coverage

`ChemPy <https://github.com/bjodah/chempy>`_ is a `Python <https://www.python.org>`_ package useful for
chemistry (mainly phyiscal/inorganic/analytical chemistry). Currently it includes:

- Solver for equilibria (including multiphase systems)
- Numerical integration routines for chemical kinetics (ODE solver frontend)
- Integrated rate expressions (and convenience fitting routines)
- Relations in Physical chemistry

  - Debye-Hückel expressions
  - Arrhenius equation
  - Einstein-Smoluchowski equation

- Properties

  - water density as function of temperature
  - water permittivity as function of temperature and pressure
  - water diffusivity as function of temperature
  - sulfuric acid density as function of temperature & weight fraction H₂SO₄


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

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

::

   $ conda install -c bjodah chempy pytest

alternatively you may also use `pip`:

::

   $ python -m pip install --user chempy

(you can skip the ``--user`` flag if you have got root permissions), to run the
tests you need ``pytest`` too:

::

   $ python -m pip install --user --upgrade pytest
   $ python -m pytest --pyargs chempy


Examples
--------
See `examples/ <https://github.com/bjodah/chempy/tree/master/examples>`_, and rendered jupyter notebooks here:
`<http://hera.physchem.kth.se/~chempy/branches/master/examples>`_. You may also browse the documentation for
more examples. Here are a few code snippets:

Parsing formulae
~~~~~~~~~~~~~~~~
.. code:: python

   >>> from chempy import Substance
   >>> Substance.from_formula('Fe(CN)6-3').composition == {0: -3, 26: 1, 6: 6, 7: 6}
   True


as you see, the atomic numbers (and 0 for charge) is used as keys and the count of each kind
became respective value.

Chemical equilibria
~~~~~~~~~~~~~~~~~~~
.. code:: python

   >>> from chempy import Equilibrium
   >>> from chempy.chemistry import Species
   >>> water_autop = Equilibrium({'H2O': 1}, {'H+': 1, 'OH-': 1}, 10**-14)
   >>> ammonia_prot = Equilibrium({'NH4+': 1}, {'NH3': 1, 'H+': 1}, 10**-9.24)
   >>> from chempy.equilibria import EqSystem
   >>> substances = map(Species.from_formula, 'H2O OH- H+ NH3 NH4+'.split())
   >>> eqsys = EqSystem([water_autop, ammonia_prot], substances)
   >>> print('\n'.join(map(str, eqsys.rxns)))
   H2O = H+ + OH-; 1e-14
   NH4+ = H+ + NH3; 5.75e-10
   >>> from collections import defaultdict
   >>> init_conc = defaultdict(float, {'H2O': 1, 'NH3': 0.1})
   >>> x, sol, sane = eqsys.root(init_conc)
   >>> assert sol['success'] and sane
   >>> print(', '.join('%.2g' % v for v in x))
   1, 0.0013, 7.6e-12, 0.099, 0.0013

Please note that the API of the ``chempy.equilibria`` module is not finalized at
the moment.


License
-------
The source code is Open Source and is released under the very permissive
`"simplified (2-clause) BSD license" <https://opensource.org/licenses/BSD-2-Clause>`_.
See `LICENSE <LICENSE>`_ for further details.

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

Author
------
Björn Dahlgren, contact:
 - gmail adress: bjodah
 - kth.se adress: bda
