{
    "info": {
        "author": "Ryan Nelson",
        "author_email": "rnelsonchem@gmail.com",
        "bugtrack_url": null,
        "classifiers": [
            "Development Status :: 4 - Beta",
            "Intended Audience :: Science/Research",
            "License :: OSI Approved :: BSD License",
            "Programming Language :: Python :: 2",
            "Programming Language :: Python :: 2.7",
            "Programming Language :: Python :: 3",
            "Programming Language :: Python :: 3.5"
        ],
        "description": "pHcalc\n######\n\n*pHcalc* is a Python library for systematically calculating solution pH,\ndistribution diagrams, and titration curves.\n\nThis package is Python 3.5 compatible with dependencies_ only on Numpy and\nScipy. If you will be plotting the data, then there is an `optional\ndependency`_ on Matplotlib as well.  \n\nBug fixes, questions, and update requests are encouraged and can be\nfiled at the `GitHub repo`_. \n\n.. _dependencies:\n\nDependencies\n------------\n\n* Numpy >= 1.10\n\n* Scipy >= 0.17\n\n.. _optional dependency:\n\nOptional Packages\n-----------------\n\n* Matplotlib >= 1.5\n\nInstallation\n------------\n\n*pHcalc* is only a single Python file, so installation is quite simple. After\ninstallation of the dependencies_, the most recent version of *pHcalc* is\navailable via ``pip``, either from PyPI_ (stable) or the `GitHub repo`_ (most\nrecent).\n\nFrom PyPI_::\n\n    $ pip install pHcalc\n\nIf you have ``git`` installed on your system, then you can get the most\nrecent, unrelased version from the `GitHub repo`_::\n\n    $ pip install git+https://github.com/rnelsonchem/pHcalc.git\n\n\n\nBackground\n##########\n\n*pHcalc* calculates the pH of a complex system of potentially strong and weak\nacids and bases using a systematic equilibrium solution method. This method is\ndescribed in detail in `the Journal of Chemical Education`_ and in this\n`ChemWiki article`_, for example. (There is also another, older Pascal program\ncalled PHCALC_, which uses matrix algebra to accomplish the same task. To the\nbest of my knowledge, the source code for this program is no longer\navailable.)\n\nBasically, this method finds the optimum pH for the mixture by systematically\nadjusting the pH until a charge balance is achieved, i.e. the concentrations\nof positively charged ions equals the charge for the negatively charged ions.\nFor (polyprotic) weak acids, the fractional distribution of the species\nat a given pH value is determined. Multiplying this by the concentration of\nacid in solution provides the concentration of each acidic species in the\nsystem, and these concentrations are used to balance the charge.\n\nUsing this methodology bases and strong acids can be described using neutral,\ncharged species. These are ions that do not react with water, such as |Na+|\nand |Cl-|. In this context, any |Cl-| in solution must be charged balanced\nwith an appropriate amount of |H3O|, which would define HCl in solution.\n|Na+| must be offset by an equivalent amount of |OH-|, which defines a\nsolution of NaOH. A 1:1 combination of |Na+| and |H2CO3| would describe a\nsolution of |NaHCO3|, the additional equivalent of |OH-| is implied by the\ncharge imbalance.\n\nExample Usage\n#############\n\n*pHcalc* defines three classes - Acid, Neutral, and System - which are used in\ncalculating the pH of the system. |H3O| and |OH-| are never explicitly\ndefined. The |H3O| concentration is adjusted internally, and |OH-| is\ncalculated using K\\ :sub:`W`\\ .\n\n.. code:: python\n\n    >>> from pHcalc.pHcalc import Acid, Neutral, System\n    >>> import numpy as np\n    >>> import matplotlib.pyplot as plt # Optional for plotting below\n\npH of 0.01 M HCl\n----------------\n\nFirst of all, HCl completely dissociates in water to give equal amounts of\n|H3O| and |Cl-|. Because |H3O| is adjusted internally, all you need to define\nis |Cl-|. This implies a single equivalent of |H3O| in order to balance the\ncharge of the system.\n\n.. code:: python\n\n    >>> cl = Neutral(charge=-1, conc=0.01)\n    >>> system = System(cl)\n    >>> system.pHsolve()\n    >>> print(system.pH) # Should print 1.9999\n\npH of 1e-8 M HCl\n----------------\n\nThis is a notoriously tricky example for introductory chemistry students;\nhowever, *pHcalc* handles it nicely.\n\n.. code:: python\n\n    >>> cl = Neutral(charge=-1, conc=1e-8)\n    >>> system = System(cl)\n    >>> system.pHsolve()\n    >>> print(system.pH) # Should print 6.978295898 (NOT 8!)\n\npH of 0.01 M NaOH\n-----------------\n\nThis example is very similar to our HCl example, except that our Neutral\nspecies must have a positive charge. The charge balance is achieved internally\nby the System using an equivalent amount of |OH-|.\n\n.. code:: python\n\n    >>> na = Neutral(charge=1, conc=0.01)\n    >>> system = System(na)\n    >>> system.pHsolve()\n    >>> print(system.pH) # Should print 12.00000\n\npH of 0.01 M HF\n---------------\n\nHere we will use an Acid object instance to define the weak acid HF, which has\na |Ka| of 6.76e-4 and a |pKa| of 3.17. You can use either value when you\ncreate the Acid instance. When defining an Acid species, you must always\ndefine a ``charge`` keyword argument, which is the charge of the *fully\nprotonated species*.\n\n.. code:: python\n\n    >>> hf = Acid(Ka=6.76e-4, charge=0, conc=0.01)\n    >>> # hf = Acid(pKa=3.17, charge=0, conc=0.01) will also work\n    >>> system = System(hf)\n    >>> system.pHsolve()\n    >>> print(system.pH) # Should print 2.6413261\n\npH of 0.01 M NaF\n----------------\n\nThis system consist of a 1:1 mixture of an HF Acid instance and a |Na+|\nNeutral instance. The System object can be instantiated with an arbitrary\nnumber of Acids and Neutral objects. Again, there is an implied equivalent of\n|OH-| necessary to balance the charge of the system.\n\n.. code:: python\n\n    >>> hf = Acid(Ka=6.76e-4, charge=0, conc=0.01)\n    >>> na = Neutral(charge=1, conc=0.01)\n    >>> system = System(hf, na)\n    >>> system.pHsolve()\n    >>> print(system.pH) # Should print 7.5992233\n\n\npH of 0.01 M |H2CO3|\n--------------------\n\nThe |Ka| and |pKa| attributes can also accept lists of values for polyprotic\nspecies.\n\n.. code:: python\n\n    >>> carbonic = Acid(pKa=[3.6, 10.32], charge=0, conc=0.01)\n    >>> system = System(carbonic)\n    >>> system.pHsolve()\n    >>> print(system.pH) # Should print 2.8343772\n\npH of 0.01 M Alanine Zwitterion Form\n------------------------------------\n\nAlanine has two pKa values, 2.35 and 9.69, but the fully protonated form is\npositively charged. In order to define the neutral zwitterion, only the\npositively charged Acid object needs to be defined. The charge balance in this\ncase implies a single equivalent of |OH-|.  \n\n.. code:: python \n\n    >>> ala = Acid(pKa=[2.35, 9.69], charge=1, conc=0.01)\n    >>> system = System(ala)\n    >>> system.pHsolve()\n    >>> print(system.pH) # Should print 6.0991569\n\npH of 0.01 M |NH4PO4|\n---------------------\n\nThis is equivalent to a 1:3 mixture of |H3PO4| and |NH4|, both of which are\ndefined by Acid objects. Three equivalents of |OH-| are implied to balance the\ncharge of the system.\n\n.. code:: python\n\n    >>> phos = Acid(pKa=[2.148, 7.198, 12.319], charge=0, conc=0.01)\n    >>> nh4 = Acid(pKa=9.25, charge=1, conc=0.01*3)\n    >>> system = System(phos, nh4)\n    >>> system.pHsolve()\n    >>> print(system.pH) # Should print 8.95915298\n\nDistribution Diagrams\n---------------------\n\nAcid objects also define a function called ``alpha``, which calculates the\nfractional distribution of species at a given pH. This function can be used to\ncreate distribution diagrams for weak acid species. ``alpha`` takes a single\nargument, which is a single pH value or a Numpy array of values. For a single\npH value, the function returns a Numpy array of fractional distributions\nordered from most acid to least acidic species. \n\n.. code:: python\n\n    >>> phos = Acid(pKa=[2.148, 7.198, 12.319], charge=0, conc=0.01)\n    >>> phos.alpha(7.0)\n    array([ 8.6055e-06, 6.1204e-01, 3.8795e-01, 1.8611e-06])\n    >>> # This is H3PO4, H2PO4-, HPO4_2-, and HPO4_3-\n\nFor a Numpy array og pH values, a 2D array of fractional distribution values\nis returned, where each row is a series of distributions for each given pH.\nThe 2D returned array can be used to plot a distribution diagram. \n\n.. code:: python\n\n    >>> phos = Acid(pKa=[2.148, 7.198, 12.319], charge=0, conc=0.01)\n    >>> phs = np.linspace(0, 14, 1000)\n    >>> fracs = phos.alpha(phs)\n    >>> plt.plot(phs, fracs)\n    >>> plt.show()\n\nTitration Curves\n----------------\n\nUsing a simple loop, we can also construct arbitrary titration curves as well.\nIn this example, we will titrate |H3PO4| with NaOH. The ``guess_est`` keyword\nargument for the ``System.pHsolve`` method forces the calculation of a best\nguess for starting the pH optimization algorithm. This may speed up the\nevaluation of the pH and can also be used if the minimizer throws an error\nduring the pH calculation. \n\n.. code:: python\n\n    >>> na_moles = np.linspace(1e-8, 5.e-3, 500)\n    >>> sol_volume = 1. # Liter\n    >>> phos = Acid(pKa=[2.148, 7.198, 12.375], charge=0, conc=1.e-3)\n    >>> phs = []\n    >>> for mol in na_moles:\n    >>>     na = Neutral(charge=1, conc=mol/sol_volume)\n    >>>     system = System(phos, na)\n    >>>     system.pHsolve(guess_est=True)\n    >>>     phs.append(system.pH)\n    >>> plt.plot(na_moles, phs)\n    >>> plt.show()\n\n.. Substitutions\n\n\n.. |Na+| replace:: Na\\ :sup:`+`\n.. |Cl-| replace:: Cl\\ :sup:`-`\n.. |H3O| replace:: H\\ :sub:`3`\\ O\\ :sup:`+`\n.. |OH-| replace:: OH\\ :sup:`-`\n.. |H2CO3| replace:: H\\ :sub:`2`\\ CO\\ :sub:`3`\n.. |NaHCO3| replace:: NaHCO\\ :sub:`3`\n.. |Ka| replace:: K\\ :sub:`a`\n.. |pKa| replace:: pK\\ :sub:`a`\n.. |NH4PO4| replace:: (NH\\ :sub:`4`\\ )\\ :sub:`3`\\ PO\\ :sub:`4`\n.. |H3PO4| replace:: H\\ :sub:`3`\\ PO\\ :sub:`4`\n.. |NH4| replace:: NH\\ :sub:`4`\\ :sup:`+`\n\n.. External Hyperlinks\n\n.. _GitHub repo: https://github.com/rnelsonchem/pHcalc\n.. _PyPI: https://pypi.python.org/pypi/pHcalc\n.. _the Journal of Chemical Education:\n      http://pubs.acs.org/doi/abs/10.1021/ed100784v\n.. _ChemWiki article: \n    http://chemwiki.ucdavis.edu/Core/Analytical_Chemistry/Analytical_Chemistry_2.0/06_Equilibrium_Chemistry/6G%3A_Solving_Equilibrium_Problems#6G.3_A_Systematic_Approach_to_Solving_Equilibrium_Problems\n.. _PHCALC: http://pubs.acs.org/doi/pdf/10.1021/ed071p119",
        "description_content_type": null,
        "docs_url": null,
        "download_url": "UNKNOWN",
        "downloads": {
            "last_day": -1,
            "last_month": -1,
            "last_week": -1
        },
        "home_page": "https://github.com/rnelsonchem/pHcalc",
        "keywords": "pH systematic distribution titration strong weak acid base speciation",
        "license": "BSD",
        "maintainer": "",
        "maintainer_email": "",
        "name": "pHcalc",
        "package_url": "https://pypi.org/project/pHcalc/",
        "platform": "UNKNOWN",
        "project_url": "https://pypi.org/project/pHcalc/",
        "project_urls": {
            "Download": "UNKNOWN",
            "Homepage": "https://github.com/rnelsonchem/pHcalc"
        },
        "release_url": "https://pypi.org/project/pHcalc/0.1.2/",
        "requires_dist": null,
        "requires_python": "",
        "summary": "Systemtic pH calculation package for Python.",
        "version": "0.1.2"
    },
    "last_serial": 2042137,
    "releases": {
        "0.1.0": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "9a27b2a1a78c58168c672a8028bc353f",
                    "sha256": "1ffaf0449271342da79fbef0f1d32c6d9b8baf81331f3db9c4d1407976365a37"
                },
                "downloads": -1,
                "filename": "pHcalc-0.1.0-py3.5.egg",
                "has_sig": false,
                "md5_digest": "9a27b2a1a78c58168c672a8028bc353f",
                "packagetype": "bdist_egg",
                "python_version": "3.5",
                "requires_python": null,
                "size": 9794,
                "upload_time": "2016-03-30T23:44:38",
                "url": "https://files.pythonhosted.org/packages/d9/78/ef703fe056dff7d876acb9069cd8ec063d62788e258a4ba5593e2a32bdb2/pHcalc-0.1.0-py3.5.egg"
            },
            {
                "comment_text": "",
                "digests": {
                    "md5": "5b21e23f1bf4e51e654f7867f9ce185f",
                    "sha256": "a38cd50c48a871ce1039a8ac5f7805c8b8dfa0a05ef4a0ef63566db8a59b9af5"
                },
                "downloads": -1,
                "filename": "pHcalc-0.1.0.tar.gz",
                "has_sig": false,
                "md5_digest": "5b21e23f1bf4e51e654f7867f9ce185f",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 5904,
                "upload_time": "2016-03-30T23:44:43",
                "url": "https://files.pythonhosted.org/packages/18/0d/e0233160bdbf710ead72ff6276a4598901e39b42fb2068a80043b8eb8a2a/pHcalc-0.1.0.tar.gz"
            }
        ],
        "0.1.1": [],
        "0.1.2": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "994a6199edef0f9f6bd5aa57f5ee79f2",
                    "sha256": "6df5592a780c1243a04a2c2927243330a2f33c19f7c39963bac46ee242d599fd"
                },
                "downloads": -1,
                "filename": "pHcalc-0.1.2.tar.gz",
                "has_sig": false,
                "md5_digest": "994a6199edef0f9f6bd5aa57f5ee79f2",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 9472,
                "upload_time": "2016-04-01T00:15:03",
                "url": "https://files.pythonhosted.org/packages/d3/ee/e16b21436b1260f835f3dca1dbdbdd76ffdfc8e21205cf100a06d447baef/pHcalc-0.1.2.tar.gz"
            }
        ]
    },
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "md5": "994a6199edef0f9f6bd5aa57f5ee79f2",
                "sha256": "6df5592a780c1243a04a2c2927243330a2f33c19f7c39963bac46ee242d599fd"
            },
            "downloads": -1,
            "filename": "pHcalc-0.1.2.tar.gz",
            "has_sig": false,
            "md5_digest": "994a6199edef0f9f6bd5aa57f5ee79f2",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": null,
            "size": 9472,
            "upload_time": "2016-04-01T00:15:03",
            "url": "https://files.pythonhosted.org/packages/d3/ee/e16b21436b1260f835f3dca1dbdbdd76ffdfc8e21205cf100a06d447baef/pHcalc-0.1.2.tar.gz"
        }
    ]
}