|Tests action| |GitHub license| |PyPI version| |PyPI pyversions| |Code style|
.. |Tests action| image:: https://github.com/xnx/pyvalem/workflows/tests/badge.svg
:target: https://github.com/xnx/pyvalem/actions
.. |GitHub license| image:: https://img.shields.io/github/license/xnx/pyvalem.svg
:target: https://github.com/xnx/pyvalem/blob/master/LICENSE
.. |PyPI version| image:: https://img.shields.io/pypi/v/pyvalem.svg
:target: https://pypi.python.org/pypi/pyvalem/
.. |PyPI pyversions| image:: https://img.shields.io/pypi/pyversions/pyvalem.svg
:target: https://pypi.python.org/pypi/pyvalem/
.. |Code style| image:: https://img.shields.io/badge/code%20style-black-000000.svg
:target: https://github.com/psf/black
***********************
Introduction to PyValem
***********************
PyValem is a Python package for parsing, validating, manipulating and
interpreting the chemical formulas, quantum states and labels of atoms, ions
and small molecules.
Species and states are specified as strings using a simple and flexible syntax,
and may be compared, output in different formats and manipulated using a
variety of predefined Python methods.
Installation:
=============
The PyValem package can be installed either from PyPI_ using pip
.. code-block:: bash
python3 -m pip install pyvalem
or from the source by running (one of the two) from the project source directory.
.. code-block:: bash
# either
python setup.py install
# or
python3 -m pip install .
Examples:
=========
Formula
-------
The basic (state-less) chemical formulas are represented by the ``Formula`` class.
A ``Formula`` object is instantiated from a valid formula string and supports ions,
isotopologues, as well as a few special species.
The object contains attributes with its HTML and LaTeX representations,
and its molar mass.
.. code-block:: pycon
>>> from pyvalem.formula import Formula
>>> # neutral formulas:
>>> Formula('C2H5OH')
C2H5OH
>>> # isotopes:
>>> Formula('(14C)')
(14C)
>>> # ions
>>> [Formula('H3O+'), Formula('(1H)(2H)+'), Formula('Co(H2O)6+2')]
[H3O+, (1H)(2H)+, Co(H2O)6+2]
>>> # special species
>>> [Formula('e-'), Formula('hv')]
[e-, hν]
>>> # formula attributes:
>>> Formula('Ar+2').charge
2
>>> Formula('H2(18O)').html
'H<sub>2</sub><sup>18</sup>O'
>>> print(Formula('H2(18O)').latex)
\mathrm{H}_{2}{}^{18}\mathrm{O}
>>> Formula('(235U)').mass
235.04392819
"Stateful" Species
------------------
The "stateful" species represent species with (or without) any number of states
attached.
The ``StatefulSpecies`` object can be instantiated from a valid string, which consist
of a valid ``Formula`` string, followed by a whitespace, followed by a
semicolon-delimited sequence of valid ``State`` strings.
PyValem supports several different types of state notation.
For further information on valid PyValem ``State`` strings, consult the documentation.
Examples:
.. code-block:: pycon
>>> from pyvalem.stateful_species import StatefulSpecies
>>> stateful_species = StatefulSpecies('Ne+ 1s2.2s2.2p5; 2P_1/2')
>>> stateful_species.formula
Ne+
>>> type(stateful_species.formula)
<class 'pyvalem.formula.Formula'>
>>> stateful_species.states
[1s2.2s2.2p5, 2P_1/2]
>>> state1, state2 = stateful_species.states
>>> type(state1)
<class 'pyvalem.states.atomic_configuration.AtomicConfiguration'>
>>> state1.orbitals
[1s2, 2s2, 2p5]
>>> type(state2)
<class 'pyvalem.states.atomic_term_symbol.AtomicTermSymbol'>
>>> state2.L, state2.J
(1, 0.5)
As ``Formula``, also ``StatefulSpecies`` have ``html`` and ``latex`` attributes.
.. code-block:: pycon
>>> print(stateful_species.latex)
\mathrm{Ne}^{+} \; 1s^{2}2s^{2}2p^{5} \; {}^{2}\mathrm{P}_{1/2}
>>> StatefulSpecies('(52Cr)(1H) 1sigma2.2sigma1.1delta2.1pi2; 6SIGMA+; v=0; J=2').html
'<sup>52</sup>Cr<sup>1</sup>H 1σ<sup>2</sup>.2σ<sup>1</sup>.1δ<sup>2</sup>.1π<sup>2</sup> <sup>6</sup>Σ<sup>+</sup> v=0 J=2'
Reaction
--------
Finally, the ``Reaction`` class represents a reaction or a collisional process between
species. A ``Reaction`` object is instantiated with a string consisting of valid
``Formula`` or ``StatefulSpecies`` strings delimited by ``' + '``, and reaction sides
separated by ``' -> '``, such as
.. code-block:: pycon
>>> from pyvalem.reaction import Reaction
>>> reaction = Reaction('He+2 + H -> He+ 3p1 + H+ + hv')
>>> reaction
He+2 + H → He+ 3p + H+ + hν
>>> reaction.html
'He<sup>2+</sup> + H → He<sup>+</sup> 3p + H<sup>+</sup> + hν'
>>> print(reaction.latex)
\mathrm{He}^{2+} + \mathrm{H} \rightarrow \mathrm{He}^{+} \; 3p + \mathrm{H}^{+} + h\nu
The ``Reaction`` class also watches out for charge balance and stoichiometry
conservation during instantiation.
.. code-block:: pycon
>>> Reaction('(2H) + (3H) -> (4He)')
Traceback (most recent call last):
...
pyvalem.reaction.ReactionStoichiometryError: Stoichiometry not preserved for reaction: (2H) + (3H) -> (4He)
>>> Reaction('e- + Ar -> Ar+ + e-')
Traceback (most recent call last):
...
pyvalem.reaction.ReactionChargeError: Charge not preserved for reaction: e- + Ar -> Ar+ + e-
For Developers:
===============
It goes without saying that any development should be done in a clean virtual
environment.
After cloning or forking the project from its GitHub_ page, ``pyvalem`` might be
installed into the virtual environment in editable mode with
.. code-block:: bash
pip install -e .[dev]
or on zsh:
.. code-block:: zsh
pip install -e .'[dev]'
The ``[dev]`` extra installs (apart from the package dependencies) also several
development-related packages, such as ``pytest``, ``black``, ``tox`` or ``ipython.``
The tests can then be executed by running (from the project root directory)
.. code-block:: bash
# either
pytest
# or
tox
The project does not have ``requirements.txt`` by design, all the package dependencies
are rather handled by ``setup.py``.
The package needs to be installed to run the tests, which grants the testing process
another layer of usefulness.
Docstrings in the project adhere to the numpydoc_ styling.
The project code is formatted by ``black``.
Always make sure to format your code before submitting a pull request, by running
``black`` on all your python files.
.. _GitHub: https://github.com/xnx/pyvalem
.. _PyPI: https://pypi.org/project/pyvalem/
.. _numpydoc: https://numpydoc.readthedocs.io/en/latest/format.html
Raw data
{
"_id": null,
"home_page": "https://github.com/xnx/pyvalem",
"name": "pyvalem",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": "",
"keywords": "chemistry,formula,species,state,reaction",
"author": "Christian Hill",
"author_email": "ch.hill@iaea.org",
"download_url": "https://files.pythonhosted.org/packages/76/3e/4502198476ff8197021602f4818fc880bbf919ab712add325e949d829419/pyvalem-2.5.16.tar.gz",
"platform": null,
"description": "|Tests action| |GitHub license| |PyPI version| |PyPI pyversions| |Code style|\n\n.. |Tests action| image:: https://github.com/xnx/pyvalem/workflows/tests/badge.svg\n :target: https://github.com/xnx/pyvalem/actions\n.. |GitHub license| image:: https://img.shields.io/github/license/xnx/pyvalem.svg\n :target: https://github.com/xnx/pyvalem/blob/master/LICENSE\n.. |PyPI version| image:: https://img.shields.io/pypi/v/pyvalem.svg\n :target: https://pypi.python.org/pypi/pyvalem/\n.. |PyPI pyversions| image:: https://img.shields.io/pypi/pyversions/pyvalem.svg\n :target: https://pypi.python.org/pypi/pyvalem/\n.. |Code style| image:: https://img.shields.io/badge/code%20style-black-000000.svg\n :target: https://github.com/psf/black\n\n***********************\nIntroduction to PyValem\n***********************\n\n\n\nPyValem is a Python package for parsing, validating, manipulating and\ninterpreting the chemical formulas, quantum states and labels of atoms, ions\nand small molecules.\n\nSpecies and states are specified as strings using a simple and flexible syntax,\nand may be compared, output in different formats and manipulated using a\nvariety of predefined Python methods.\n\n\n\nInstallation:\n=============\n\nThe PyValem package can be installed either from PyPI_ using pip\n\n.. code-block:: bash\n\n python3 -m pip install pyvalem\n\nor from the source by running (one of the two) from the project source directory.\n\n.. code-block:: bash\n\n # either\n python setup.py install\n\n # or\n python3 -m pip install .\n\n\n\nExamples:\n=========\n\nFormula\n-------\nThe basic (state-less) chemical formulas are represented by the ``Formula`` class.\nA ``Formula`` object is instantiated from a valid formula string and supports ions,\nisotopologues, as well as a few special species.\nThe object contains attributes with its HTML and LaTeX representations,\nand its molar mass.\n\n.. code-block:: pycon\n\n >>> from pyvalem.formula import Formula\n\n >>> # neutral formulas:\n >>> Formula('C2H5OH')\n C2H5OH\n\n >>> # isotopes:\n >>> Formula('(14C)')\n (14C)\n\n >>> # ions\n >>> [Formula('H3O+'), Formula('(1H)(2H)+'), Formula('Co(H2O)6+2')]\n [H3O+, (1H)(2H)+, Co(H2O)6+2]\n\n >>> # special species\n >>> [Formula('e-'), Formula('hv')]\n [e-, h\u03bd]\n\n >>> # formula attributes:\n >>> Formula('Ar+2').charge\n 2\n\n >>> Formula('H2(18O)').html\n 'H<sub>2</sub><sup>18</sup>O'\n\n >>> print(Formula('H2(18O)').latex)\n \\mathrm{H}_{2}{}^{18}\\mathrm{O}\n\n >>> Formula('(235U)').mass\n 235.04392819\n\n\n\"Stateful\" Species\n------------------\nThe \"stateful\" species represent species with (or without) any number of states\nattached.\nThe ``StatefulSpecies`` object can be instantiated from a valid string, which consist\nof a valid ``Formula`` string, followed by a whitespace, followed by a\nsemicolon-delimited sequence of valid ``State`` strings.\nPyValem supports several different types of state notation.\nFor further information on valid PyValem ``State`` strings, consult the documentation.\n\nExamples:\n\n.. code-block:: pycon\n\n >>> from pyvalem.stateful_species import StatefulSpecies\n\n >>> stateful_species = StatefulSpecies('Ne+ 1s2.2s2.2p5; 2P_1/2')\n >>> stateful_species.formula\n Ne+\n\n >>> type(stateful_species.formula)\n <class 'pyvalem.formula.Formula'>\n\n >>> stateful_species.states\n [1s2.2s2.2p5, 2P_1/2]\n\n >>> state1, state2 = stateful_species.states\n >>> type(state1)\n <class 'pyvalem.states.atomic_configuration.AtomicConfiguration'>\n\n >>> state1.orbitals\n [1s2, 2s2, 2p5]\n\n >>> type(state2)\n <class 'pyvalem.states.atomic_term_symbol.AtomicTermSymbol'>\n\n >>> state2.L, state2.J\n (1, 0.5)\n\nAs ``Formula``, also ``StatefulSpecies`` have ``html`` and ``latex`` attributes.\n\n.. code-block:: pycon\n\n >>> print(stateful_species.latex)\n \\mathrm{Ne}^{+} \\; 1s^{2}2s^{2}2p^{5} \\; {}^{2}\\mathrm{P}_{1/2}\n\n >>> StatefulSpecies('(52Cr)(1H) 1sigma2.2sigma1.1delta2.1pi2; 6SIGMA+; v=0; J=2').html\n '<sup>52</sup>Cr<sup>1</sup>H 1\u03c3<sup>2</sup>.2\u03c3<sup>1</sup>.1\u03b4<sup>2</sup>.1\u03c0<sup>2</sup> <sup>6</sup>\u03a3<sup>+</sup> v=0 J=2'\n\n\nReaction\n--------\nFinally, the ``Reaction`` class represents a reaction or a collisional process between\nspecies. A ``Reaction`` object is instantiated with a string consisting of valid\n``Formula`` or ``StatefulSpecies`` strings delimited by ``' + '``, and reaction sides\nseparated by ``' -> '``, such as\n\n.. code-block:: pycon\n\n >>> from pyvalem.reaction import Reaction\n >>> reaction = Reaction('He+2 + H -> He+ 3p1 + H+ + hv')\n >>> reaction\n He+2 + H \u2192 He+ 3p + H+ + h\u03bd\n\n >>> reaction.html\n 'He<sup>2+</sup> + H \u2192 He<sup>+</sup> 3p + H<sup>+</sup> + h\u03bd'\n\n >>> print(reaction.latex)\n \\mathrm{He}^{2+} + \\mathrm{H} \\rightarrow \\mathrm{He}^{+} \\; 3p + \\mathrm{H}^{+} + h\\nu\n\nThe ``Reaction`` class also watches out for charge balance and stoichiometry\nconservation during instantiation.\n\n.. code-block:: pycon\n\n >>> Reaction('(2H) + (3H) -> (4He)')\n Traceback (most recent call last):\n ...\n pyvalem.reaction.ReactionStoichiometryError: Stoichiometry not preserved for reaction: (2H) + (3H) -> (4He)\n\n >>> Reaction('e- + Ar -> Ar+ + e-')\n Traceback (most recent call last):\n ...\n pyvalem.reaction.ReactionChargeError: Charge not preserved for reaction: e- + Ar -> Ar+ + e-\n\n\n\nFor Developers:\n===============\nIt goes without saying that any development should be done in a clean virtual\nenvironment.\nAfter cloning or forking the project from its GitHub_ page, ``pyvalem`` might be\ninstalled into the virtual environment in editable mode with\n\n.. code-block:: bash\n\n pip install -e .[dev]\n\nor on zsh:\n\n.. code-block:: zsh\n\n pip install -e .'[dev]'\n\nThe ``[dev]`` extra installs (apart from the package dependencies) also several\ndevelopment-related packages, such as ``pytest``, ``black``, ``tox`` or ``ipython.``\nThe tests can then be executed by running (from the project root directory)\n\n.. code-block:: bash\n\n # either\n pytest\n\n # or\n tox\n\nThe project does not have ``requirements.txt`` by design, all the package dependencies\nare rather handled by ``setup.py``.\nThe package needs to be installed to run the tests, which grants the testing process\nanother layer of usefulness.\n\nDocstrings in the project adhere to the numpydoc_ styling.\nThe project code is formatted by ``black``.\nAlways make sure to format your code before submitting a pull request, by running\n``black`` on all your python files.\n\n\n.. _GitHub: https://github.com/xnx/pyvalem\n.. _PyPI: https://pypi.org/project/pyvalem/\n.. _numpydoc: https://numpydoc.readthedocs.io/en/latest/format.html\n",
"bugtrack_url": null,
"license": "",
"summary": "A package for managing simple chemical species and states",
"version": "2.5.16",
"project_urls": {
"Bug Reports": "https://github.com/xnx/pyvalem/issues",
"Homepage": "https://github.com/xnx/pyvalem"
},
"split_keywords": [
"chemistry",
"formula",
"species",
"state",
"reaction"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "99956b1df805e4d6e1d20424f9015eb1acd6084e81825033487ca3e9f069d288",
"md5": "663b485c56d2bfdfa7dfb3cd49290ba1",
"sha256": "ed80a44df549c1e54428100f6a0a577e52cbccda3203232cbccbb425951d1cf4"
},
"downloads": -1,
"filename": "pyvalem-2.5.16-py3-none-any.whl",
"has_sig": false,
"md5_digest": "663b485c56d2bfdfa7dfb3cd49290ba1",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 96987,
"upload_time": "2024-03-01T16:46:52",
"upload_time_iso_8601": "2024-03-01T16:46:52.809580Z",
"url": "https://files.pythonhosted.org/packages/99/95/6b1df805e4d6e1d20424f9015eb1acd6084e81825033487ca3e9f069d288/pyvalem-2.5.16-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "763e4502198476ff8197021602f4818fc880bbf919ab712add325e949d829419",
"md5": "9e943aead032b4ed86411e17233b62d8",
"sha256": "bf1b74cd172264e2231b7dee844f4669e0c5da983cb321ea25cd746356f53a59"
},
"downloads": -1,
"filename": "pyvalem-2.5.16.tar.gz",
"has_sig": false,
"md5_digest": "9e943aead032b4ed86411e17233b62d8",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 101924,
"upload_time": "2024-03-01T16:46:54",
"upload_time_iso_8601": "2024-03-01T16:46:54.370513Z",
"url": "https://files.pythonhosted.org/packages/76/3e/4502198476ff8197021602f4818fc880bbf919ab712add325e949d829419/pyvalem-2.5.16.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-03-01 16:46:54",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "xnx",
"github_project": "pyvalem",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "pyvalem"
}
JSON
