#!/usr/bin/env python3
#
# species.py
"""
Class to represent a formula with phase information (e.g. solid, liquid, gas, or aqueous).
"""
#
# Copyright (c) 2020 Dominic Davis-Foster <dominic@davis-foster.co.uk>
#
# This program is free software; you can redistribute it and/or modify
# it under the terms of the GNU Lesser General Public License as published by
# the Free Software Foundation; either version 3 of the License, or
# (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
# GNU Lesser General Public License for more details.
#
# You should have received a copy of the GNU Lesser General Public License
# along with this program; if not, write to the Free Software
# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
# MA 02110-1301, USA.
#
# Based on ChemPy (https://github.com/bjodah/chempy)
# | Copyright (c) 2015-2018, Björn Dahlgren
# | All rights reserved.
# |
# | Redistribution and use in source and binary forms, with or without modification,
# | are permitted provided that the following conditions are met:
# |
# | Redistributions of source code must retain the above copyright notice, this
# | list of conditions and the following disclaimer.
# |
# | Redistributions in binary form must reproduce the above copyright notice, this
# | list of conditions and the following disclaimer in the documentation and/or
# | other materials provided with the distribution.
# |
# | THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
# | ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
# | WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
# | DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
# | ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
# | (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
# | LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
# | ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
# | (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
# | SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
#
# Also based on Pyteomics (https://github.com/levitsky/pyteomics)
# | Copyright (c) 2011-2015, Anton Goloborodko & Lev Levitsky
# | Licensed under the Apache License, Version 2.0 (the "License");
# | you may not use this file except in compliance with the License.
# | You may obtain a copy of the License at
# |
# | http://www.apache.org/licenses/LICENSE-2.0
# |
# | Unless required by applicable law or agreed to in writing, software
# | distributed under the License is distributed on an "AS IS" BASIS,
# | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# | See the License for the specific language governing permissions and
# | limitations under the License.
# |
# | See also:
# | Goloborodko, A.A.; Levitsky, L.I.; Ivanov, M.V.; and Gorshkov, M.V. (2013)
# | "Pyteomics - a Python Framework for Exploratory Data Analysis and Rapid Software
# | Prototyping in Proteomics", Journal of The American Society for Mass Spectrometry,
# | 24(2), 301–304. DOI: `10.1007/s13361-012-0516-6 <http://dx.doi.org/10.1007/s13361-012-0516-6>`_
# |
# | Levitsky, L.I.; Klein, J.; Ivanov, M.V.; and Gorshkov, M.V. (2018)
# | "Pyteomics 4.0: five years of development of a Python proteomics framework",
# | Journal of Proteome Research.
# | DOI: `10.1021/acs.jproteome.8b00717 <http://dx.doi.org/10.1021/acs.jproteome.8b00717>`_
#
# Also based on molmass (https://github.com/cgohlke/molmass)
# | Copyright (c) 1990-2020, Christoph Gohlke
# | All rights reserved.
# | Licensed under the BSD 3-Clause License
# | Redistribution and use in source and binary forms, with or without
# | modification, are permitted provided that the following conditions are met:
# |
# | 1. Redistributions of source code must retain the above copyright notice,
# | this list of conditions and the following disclaimer.
# |
# | 2. Redistributions in binary form must reproduce the above copyright notice,
# | this list of conditions and the following disclaimer in the documentation
# | and/or other materials provided with the distribution.
# |
# | 3. Neither the name of the copyright holder nor the names of its
# | contributors may be used to endorse or promote products derived from
# | this software without specific prior written permission.
# |
# | THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
# | AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
# | IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
# | ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
# | LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
# | CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
# | SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
# | INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
# | CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
# | ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
# | POSSIBILITY OF SUCH DAMAGE.
# |
# stdlib
from typing import Dict, List, Optional, Type, TypeVar, cast
# 3rd party
from cawdrey import frozendict # nodep
from typing_extensions import Literal # nodep
# this package
from chemistry_tools.formulae.formula import Formula
__all__ = ["Species", 'S']
S = TypeVar('S', bound="Species")
[docs]class Species(Formula):
"""
Formula with phase information (e.g. solid, liquid, gas, or aqueous).
Species extends :class:`~chemistry_tools.formulae.formula.Formula` with the new attribute :attr:`~.phase`
:param composition: A :class:`~chemistry_tools.formulae.formula.Formula` object with the elemental
composition of a substance, or a :class:`python:dict` representing the same.
If :py:obj:`None` an empty object is created
:param charge:
:param phase: Either ``'s'``, ``'l'``, ``'g'``, or ``'aq'``. :py:obj:`None` represents an unknown phase.
"""
_phases: frozendict[str, str] = frozendict(s="Solid", l="Liquid", g="Gas", aq="Aqueous")
#: The phase of the species (e.g. solid, liquid, gas, or aqueous). :py:obj:`None` represents an unknown phase.
phase: Optional[Literal["s", "l", "g", "aq"]]
def __init__(
self,
composition: Optional[Dict[str, int]] = None,
charge: int = 0,
phase: Optional[Literal['s', 'l', 'g', "aq"]] = None,
):
super().__init__(composition, charge)
self.phase = phase
[docs] @classmethod
def from_kwargs(
cls: Type['S'],
*,
charge: int = 0,
phase: Optional[Literal['s', 'l', 'g', "aq"]] = None,
**kwargs
) -> S:
"""
Create a new :class:`~chemistry_tools.formulae.species.Species` object from keyword
arguments representing the elements in the compound.
:param charge: The charge of the compound
:param phase: The phase of the compound (e.g. ``'s'`` for solid)
""" # noqa: D400
return cls(kwargs, charge=charge, phase=phase)
[docs] @classmethod
def from_string(
cls: Type['S'],
formula: str,
charge: int = 0,
phase: Optional[Literal['s', 'l', 'g', "aq"]] = None,
) -> S:
"""
Create a new :class:`~chemistry_tools.formulae.species.Species` object by parsing a string.
.. note:: Isotopes cannot (currently) be parsed using this method
:param formula: A string with a chemical formula
:param phase: Either ``'s'``, ``'l'``, ``'g'``, or ``'aq'``. :py:obj:`None` represents an unknown phase.
:param charge:
:rtype:
.. latex:clearpage::
:bold-title:`Examples:`
.. code-block:: python
>>> water = Species.from_string('H2O')
>>> water.phase
None
>>> NaCl = Species.from_string('NaCl(s)')
>>> NaCl.phase
s
>>> Hg_l = Species.from_string('Hg(l)')
>>> Hg_l.phase
l
>>> CO2g = Species.from_string('CO2(g)')
>>> CO2g.phase
g
>>> CO2aq = Species.from_string('CO2(aq)')
>>> CO2aq.phase
aq
"""
if phase is None:
for p in cls._phases:
if formula.endswith(f"({p})"):
phase = cast(Optional[Literal['s', 'l', 'g', "aq"]], p)
break
f = super().from_string(formula, charge)
f.phase = phase
return f
[docs] def copy(self: S) -> S:
"""
Returns a copy of the :class:`~.Species`.
"""
return self.__class__(
self,
charge=self.charge,
phase=cast(Optional[Literal['s', 'l', 'g', "aq"]], self.phase),
)
[docs] def __eq__(self, other) -> bool: # noqa: MAN001
"""
Returns ``self == other``.
"""
if isinstance(other, Species):
if super().__eq__(other):
return self.phase == other.phase
return super().__eq__(other)
def _repr_elements(self) -> List[str]:
elements = super()._repr_elements()
if self.phase:
elements.append(f"phase={self.phase}")
return elements
@property
def hill_formula(self) -> str:
"""
Returns the formula in Hill notation.
:bold-title:`Examples:`
.. code-block:: python
>>> Species.from_string('BrC2H5').hill_formula
'C2H5Br'
>>> Species.from_string('HBr').hill_formula
'BrH'
>>> Species.from_string('[(CH3)3Si2]2NNa').hill_formula
'C6H18NNaSi4'
"""
hill = super().hill_formula
if self.phase:
return f"{hill}({self.phase})"
else:
return hill
@property
def empirical_formula(self) -> str:
"""
Returns the empirical formula in Hill notation.
The empirical formula has the simplest whole number ratio of atoms
of each element present in the formula.
:bold-title:`Examples:`
.. code-block:: python
>>> Formula.from_string('H2O').empirical_formula
'H2O'
>>> Formula.from_string('S4').empirical_formula
'S'
>>> Formula.from_string('C6H12O6').empirical_formula
'CH2O'
"""
hill = super().empirical_formula
if self.phase:
return f"{hill}({self.phase})"
else:
return hill