From 628fe20efc042907e468c792ac8385f00e13e463 Mon Sep 17 00:00:00 2001 From: Martin Hanicinec Date: Thu, 27 Jan 2022 18:07:12 +0100 Subject: [PATCH] fix the doc/formula.rst to be recognised by pytest and up to date. --- doc/formula.rst | 117 +++++++++++++++--------- pyproject.toml | 2 +- src/pyvalem/states/vibrational_state.py | 2 - 3 files changed, 76 insertions(+), 45 deletions(-) diff --git a/doc/formula.rst b/doc/formula.rst index 6136466..b606aaf 100644 --- a/doc/formula.rst +++ b/doc/formula.rst @@ -1,56 +1,76 @@ Formula ******* -A ``Formula`` object instance represents the chemical formula of an atom, isotope, ion, molecule, molecular ion, or certain sorts of other particle. The ``Formula`` class has methods for producing representations of the formula in HTML, LaTeX and plain text. +A ``Formula`` object instance represents the chemical formula of an atom, isotope, ion, +molecule, molecular ion, or certain sorts of other particle. +The ``Formula`` class has methods for producing representations of the formula in HTML, +LaTeX and plain text. -``Formula`` objects are not supposed to be unique (different ``Formula`` objects can represent the same formula); nor is their syntax or this library designed to be applied to large or complex molecules. PyValem is intended as a lightweight, easy-to-use library with an expressive syntax for representing many common small atoms and molecules and their isotopes, states and reactions. +``Formula`` objects are not supposed to be unique (different ``Formula`` objects can +represent the same formula); nor is their syntax or this library designed to be applied +to large or complex molecules. +PyValem is intended as a lightweight, easy-to-use library with an expressive syntax +for representing many common small atoms and molecules and their isotopes, +states and reactions. -Furthermore, whilst some validation functionality is built into the library, PyValem does not attempt to verify that a provided formula is chemically plausible. In particular, it knows nothing about valence or oxidation state. +Furthermore, whilst some validation functionality is built into the library, +PyValem does not attempt to verify that a provided formula is chemically plausible. +In particular, it knows nothing about valence or oxidation state. Instantiation ============= -A ``Formula`` object may be instantiated by passing a valid string, conforming to the following grammar: - -* Single atoms, with atomic weights given by a default natural isotopic abundance are specfied with their element symbol, e.g. ``H``, ``Be``, ``Fr``. - -* Isotopes are specified in parentheses (round brackets) with the isotope mass number preceding the element symbol, e.g. ``(12C)``, ``(35Cl)``, ``(235U)``. Note that no caret (``^``) is used to indicate a superscript. - -* Charged species are specified with the charge following the formula in the format ``+n`` or ``-n``, where ``n`` may be omitted if it is 1. Do not use a caret (``^``) to indicate a superscript. For example, ``He+``, ``C+2``, ``W-``, ``(79Br)-2``. - -* Molecular formulas are written as a sequence of element symbols (which may be repeated for clarity over the structure), with their stoichiometries specified as an integer following the symbol. No underscore (``_``) character is used. For example, ``H2O``, ``(1H)2(16O)``, ``C2H6OH``, ``CH3CH2OH``, ``NH+``, ``CO3+2``. - +A ``Formula`` object may be instantiated by passing a valid string, conforming to the +following grammar: + +* Single atoms, with atomic weights given by a default natural isotopic abundance are + specified with their element symbol, e.g. ``H``, ``Be``, ``Fr``. +* Isotopes are specified in parentheses (round brackets) with the isotope mass number + preceding the element symbol, e.g. ``(12C)``, ``(35Cl)``, ``(235U)``. + Note that no caret (``^``) is used to indicate a superscript. +* Charged species are specified with the charge following the formula in the format + ``+n`` or ``-n``, where ``n`` may be omitted if it is 1. + Do not use a caret (``^``) to indicate a superscript. + For example, ``He+``, ``C+2``, ``W-``, ``(79Br)-2``. +* Molecular formulas are written as a sequence of element symbols (which may be + repeated for clarity over the structure), with their stoichiometries specified as + an integer following the symbol. No underscore (``_``) character is used. + For example, ``H2O``, ``(1H)2(16O)``, ``C2H6OH``, ``CH3CH2OH``, ``NH+``, ``CO3+2``. * Moieties within formula can be bracketed for clarity, for example ``CH3C(CH3)2CH3``. - -* A limited number of formula prefixes are supported, for example ``L-CH3CH(NH2)CO2H``, ``cis-CH3CHCHCH3``, ``ortho-C6H4(CH3)2`` - +* A limited number of formula prefixes are supported, for example ``L-CH3CH(NH2)CO2H``, + ``cis-CH3CHCHCH3``, ``ortho-C6H4(CH3)2`` * There are some special species: * ``e-`` is the electron; * ``e+`` is the positron; - * ``M`` is a generic third-body with no specific identity (and no defined mass or charge); + * ``M`` is a generic third-body with no specific identity (and no defined mass or + charge); * ``hν`` (or ``hv``) is the photon. Output as HTML, LaTeX and slugs =============================== -The ``Formula`` attributes ``html`` and ``latex`` return strings representing the formula in HTML and LaTeX respectively. The attribute ``slug`` returns a URL-safe slug which uniquely identifies the formula's plain text string. For example:: +The ``Formula`` attributes ``html`` and ``latex`` return strings representing the +formula in HTML and LaTeX respectively. +The attribute ``slug`` returns a URL-safe slug which uniquely identifies the +formula's plain text string. For example: - In [1]: from pyvalem.formula import Formula +.. code-block:: pycon - In [2]: f = Formula('') - In [3]: print(f.formula) # or simply print(f) + >>> from pyvalem.formula import Formula + >>> f = Formula("Co(H2O)6+2") + >>> print(f.formula) # or simply print(f) Co(H2O)6+2 - In [4]: print(f.html) + >>> print(f.html) Co(H2O)62+ - In [5]: print(f.latex) + >>> print(f.latex) \mathrm{Co}(\mathrm{H}_{2}\mathrm{O})_{6}^{2+} - In [6]: print(f.slug) - Co-_l_H2O_r_6_p2 + >>> print(f.slug) + Co-_l_H2O_r_6_p2 The HTML and LaTeX representations render as: @@ -66,25 +86,32 @@ The HTML and LaTeX representations render as: Formula Attributes ================== -``Formula`` objects can count atoms, calculate masses and record the total species charge:: +``Formula`` objects can count atoms, calculate masses, record the total species charge, +etc: + +.. code-block:: pycon - In [7]: f = Formula('CO3-2') - In [8]: print(f.natoms) + >>> f = Formula('CO3-2') + >>> f.natoms 4 - In [9]: print(f.rmm) + + >>> round(f.rmm, 3) # relative molecular mass 60.008 - In [10]: print(f.charge) + >>> f.charge -2 - In [11]: lys = Formula('(NH3+)(CH2)4CH(NH2)CO2-') - In [12]: print(lys.natoms) + >>> dict(f.atom_stoich) + {'C': 1, 'O': 3} + + >>> lys = Formula('(NH3+)(CH2)4CH(NH2)CO2-') + >>> lys.natoms 24 - In [13]: print(lys.rmm) # relative molecular mass + >>> round(lys.rmm, 2) 146.19 - In [14]: print(lys.charge) + >>> lys.charge 0 This last example is the Lysine zwitterion, @@ -97,16 +124,22 @@ This last example is the Lysine zwitterion, $(\mathrm{N}\mathrm{H}_{3}^{+})(\mathrm{C}\mathrm{H}_{2})_{4}\mathrm{C}\mathrm{H}(\mathrm{N}\mathrm{H}_{2})\mathrm{C}\mathrm{O}_{2}^{-}$ -The same applies to isotopes and isotopically-pure molecules, in which case the exact mass is held by the ``mass`` attribute:: +The same applies to isotopes and isotopically-pure molecules, in which case the exact +mass is held by the ``mass`` attribute: + +.. code-block:: pycon - In [15]: f = formula('(1H)(35Cl)+') - In [16]: print(f.mass) + >>> f = Formula('(1H)(35Cl)+') + >>> f.mass 35.9766777262 -The stoichiometric formula can be output either in order of increasing atomic number (the default) or in alphabetical order:: +The stoichiometric formula can be output either in order of increasing atomic number +(the default) or in alphabetical order: + +.. code-block:: pycon - In [17]: print(lys.stoichiometric_formula()) - H14C6N2O2 + >>> lys.stoichiometric_formula() + 'H14C6N2O2' - In [18]: print(lys.stoichiometric_formula('alphabetical')) - C6H14N2O2 + >>> lys.stoichiometric_formula('alphabetical') + 'C6H14N2O2' diff --git a/pyproject.toml b/pyproject.toml index e4e9fb5..40d5b93 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -3,7 +3,7 @@ requires = ["setuptools>=43", "wheel"] build-backend = "setuptools.build_meta" [tool.pytest.ini_options] -addopts = "--doctest-modules --doctest-glob='README.rst'" +addopts = "--doctest-modules --doctest-glob='**/*.rst'" [tool.tox] legacy_tox_ini = """ diff --git a/src/pyvalem/states/vibrational_state.py b/src/pyvalem/states/vibrational_state.py index 5743002..5477c20 100644 --- a/src/pyvalem/states/vibrational_state.py +++ b/src/pyvalem/states/vibrational_state.py @@ -31,8 +31,6 @@ def __init__(self, n, mode): def __repr__(self): return "{}ν{:d}".format(self.n if self.n != 1 else "", self.mode) - __str__ = __repr__ - @property def html(self): return "{}ν{:d}".format(self.n if self.n != 1 else "", self.mode)