triplot 1.1.0__py3-none-any.whl

dscpanel/core/molar.py

@@ -0,0 +1,344 @@
+"""Molar masses from what a chemist types: a sum formula, a SMILES, or a
+composition of building blocks.
+
+A small calculator beside the molar mass. Three readings:
+
+* **a sum formula**: element symbols and counts, brackets with a count
+  after them, decimals, and adducts after `*` (or the
+  middle dot; a "." is a decimal point): `C6H6`, `Zn(C3H3N2)2`,
+  `C14.2H12.6N4O2Zn`, `CuSO4*5H2O`;
+* **a SMILES**: hydrogens added, as RDKit counts them: `O=C(O)c1ccccc1`;
+* **a composition**: components `(key)coefficient` or `key[coefficient]`,
+  joined by `+` or nothing, where a key is a building block of
+  `BUILDING_BLOCKS` - or any sum formula or SMILES written in the
+  brackets: `Zn(im)1.70(bim)0.30`.
+
+`calculate(text)` reads it the way that fits (`read` says which) or the
+way asked for. The atomic weights are RDKit's. RDKit is a dependency;
+without it the calculator says so rather than guessing.
+
+UI-free.
+"""
+
+import re
+from collections import OrderedDict
+
+#: The building blocks of a composition: a key, as it is typed, and its
+#: SMILES.
+BUILDING_BLOCKS = OrderedDict((
+    ("im", "C1=NC=C[N-]1"),
+    ("imH", "C1=NC=CN1"),
+    ("Clim", "ClC1=C[N-]C=N1"),
+    ("Brim", "BrC1=C[N-]C=N1"),
+    ("Iim", "IC1=C[N-]C=N1"),
+    ("Fim", "FC1=C[N-]C=N1"),
+    ("dClim", "ClC1=C(Cl)[N-]C=N1"),
+    ("mim", "CC1=C[N-]C=N1"),
+    ("mimH", "CC1=CNC=N1"),
+    ("mbim", "CC1=CC=C2C(N=C[N-]2)=C1"),
+    ("CNim", "N#CC1=C[N-]C=N1"),
+    ("dCNim", "N#CC1=C(C#N)N=C[N-]1"),
+    ("bim", "C12=CC=CC=C1[N-]C=N2"),
+    ("Zn", "[Zn++]"),
+    ("Co", "[Co++]"),
+    ("bc", "C1=CC=CC=C1C(=O)[O-]"),
+    ("Hbc", "C1=CC=CC=C1C(=O)O"),
+    ("H2bdc", "O=C(O)C1=CC=C(C(O)=O)C=C1"),
+    ("bdc", "O=C([O-])C1=CC=C(C([O-])=O)C=C1"),
+    ("Hpc", "O=C(O)C1=NC=CC=C1"),
+    ("pc", "O=C([O-])C1=NC=CC=C1"),
+    ("H2pPDA", "O=C(O)CC1=CC=C(CC(O)=O)C=C1"),
+    ("HoPyBz", "O=C(O)C(C=C1)=CC=C1C2=CC=CN=C2"),
+    ("HpPyBz", "O=C(O)C(C=C1)=CC=C1C2=CC=NC=C2"),
+    ("H2adp", "OC(CCCCC(O)=O)=O"),
+))
+
+AUTO = "auto"
+FORMULA = "formula"
+SMILES = "smiles"
+COMPOSITION = "composition"
+READINGS = (AUTO, FORMULA, SMILES, COMPOSITION)
+TITLES = {AUTO: "whichever fits", FORMULA: "a sum formula",
+          SMILES: "a SMILES", COMPOSITION: "a composition"}
+
+
+class Result(object):
+    """What `calculate` found: how it read the text, the atom counts
+    (symbol -> count, possibly fractional), the Hill formula, the molar mass
+    in g/mol - or `error` and no mass."""
+
+    def __init__(self, read=None, counts=None, error=None):
+        self.read = read
+        self.counts = dict(counts or {})
+        self.error = error
+        self.mass = None
+        self.formula = ""
+        if counts and error is None:
+            try:
+                self.mass = mass_of(self.counts)
+                self.formula = hill(self.counts)
+            except ValueError as exc:
+                self.error = str(exc)
+
+    @property
+    def ok(self):
+        return self.error is None and self.mass is not None
+
+
+def _table():
+    from rdkit import Chem
+    return Chem.GetPeriodicTable()
+
+
+def available():
+    try:
+        _table()
+    except ImportError:
+        return False
+    return True
+
+
+_SYMBOLS = []
+
+
+def _is_element(symbol):
+    """True for an element symbol - looked up in a set made once, since
+    RDKit asked about a key such as "bim" prints a C++ complaint to the
+    console."""
+    if not _SYMBOLS:
+        table = _table()
+        _SYMBOLS.append(frozenset(table.GetElementSymbol(z)
+                                  for z in range(1, 119)))
+    return symbol in _SYMBOLS[0]
+
+
+def mass_of(counts):
+    """g/mol of `counts` (symbol -> count), RDKit's atomic weights."""
+    table = _table()
+    total = 0.0
+    for symbol, count in counts.items():
+        if not _is_element(symbol):
+            raise ValueError("{} is not an element".format(symbol))
+        total += table.GetAtomicWeight(symbol) * float(count)
+    return total
+
+
+def hill(counts, decimals=3):
+    """The Hill formula: C, then H, then the rest alphabetically (all
+    alphabetically without carbon); fractional counts to `decimals`."""
+    def written(count):
+        count = round(float(count), decimals)
+        if count == int(count):
+            count = int(count)
+        return "" if count == 1 else "%g" % count
+
+    present = dict((s, c) for s, c in counts.items() if abs(c) > 1e-12)
+    if "C" in present:
+        order = ["C"] + (["H"] if "H" in present else [])
+        order += sorted(s for s in present if s not in ("C", "H"))
+    else:
+        order = sorted(present)
+    return "".join(s + written(present[s]) for s in order)
+
+
+# ---------------------------------------------------------- sum formulas
+_NUMBER = r"(?:\d+\.\d*|\.\d+|\d+)"
+_FORMULA_TOKEN = re.compile(r"([A-Z][a-z]?)(" + _NUMBER + r")?"
+                            r"|([(\[])|([)\]])(" + _NUMBER + r")?")
+_ADDUCT = re.compile(r"[*\u00b7]")
+
+
+def parse_formula(text):
+    """A sum formula as `{symbol: count}`, or ValueError. Brackets carry
+    a count after them; `*` or a middle dot starts an adduct with its own
+    leading count (`CuSO4*5H2O`). A "." is a decimal point, never an
+    adduct: `C14.2H12.6N4O2Zn`, a composition's fractional formula."""
+    text = str(text or "").strip().replace(" ", "")
+    if not text:
+        raise ValueError("nothing to read")
+    total = {}
+    for part in _ADDUCT.split(text):
+        if not part:
+            raise ValueError("an empty part after a dot")
+        lead = re.match(_NUMBER, part)
+        factor = 1.0
+        if lead and lead.end() < len(part):
+            factor = float(lead.group(0))
+            part = part[lead.end():]
+        for symbol, count in _formula_part(part).items():
+            total[symbol] = total.get(symbol, 0.0) + count * factor
+    return total
+
+
+def _formula_part(text):
+    stack = [{}]
+    pos = 0
+    for match in _FORMULA_TOKEN.finditer(text):
+        if match.start() != pos:
+            raise ValueError("cannot read {!r}".format(text[pos:]))
+        pos = match.end()
+        symbol, count, opening, closing, times = match.groups()
+        if symbol:
+            if not _is_element(symbol):
+                raise ValueError("{} is not an element".format(symbol))
+            group = stack[-1]
+            group[symbol] = group.get(symbol, 0.0) + (
+                float(count) if count else 1.0)
+        elif opening:
+            stack.append({})
+        else:
+            if len(stack) < 2:
+                raise ValueError("a bracket closed that was never opened")
+            inner = stack.pop()
+            factor = float(times) if times else 1.0
+            outer = stack[-1]
+            for key, value in inner.items():
+                outer[key] = outer.get(key, 0.0) + value * factor
+    if pos != len(text):
+        raise ValueError("cannot read {!r}".format(text[pos:]))
+    if len(stack) != 1:
+        raise ValueError("a bracket is not closed")
+    if not stack[0]:
+        raise ValueError("no elements")
+    return stack[0]
+
+
+def _repeats_bare(text):
+    """True when an element follows itself with no count between ("CC"):
+    nobody writes a sum formula like that, so such text is a SMILES."""
+    symbols = re.findall(r"[A-Z][a-z]?\d*", text)
+    return any(a == b and not re.search(r"\d", a)
+               for a, b in zip(symbols, symbols[1:]))
+
+
+# ---------------------------------------------------------------- SMILES
+def smiles_counts(text):
+    """A SMILES's atoms, hydrogens included, as `{symbol: count}`."""
+    from rdkit import Chem, RDLogger
+    RDLogger.DisableLog("rdApp.*")
+    mol = Chem.MolFromSmiles(str(text or "").strip())
+    if mol is None:
+        raise ValueError("not a SMILES")
+    counts = {}
+    for atom in Chem.AddHs(mol).GetAtoms():
+        symbol = atom.GetSymbol()
+        counts[symbol] = counts.get(symbol, 0.0) + 1.0
+    return counts
+
+
+# ----------------------------------------------------------- compositions
+# His grammar, word for word (`_TOKEN_RE` in calculate_sum_formula.py).
+_COEF = r"\d*\.\d+|\d+"
+_COMPONENT = re.compile(
+    r"\((?P<pkey>[^()]+)\)\s*(?P<pcoef>%s)?"
+    r"|(?P<bkey>[A-Za-z]+)\s*(?P<bcoef>%s)?"
+    r"|(?P<sep>[+\u00b7*\s])" % (_COEF, _COEF))
+
+
+def parse_composition(text):
+    """`[(key, coefficient), ...]`, or ValueError."""
+    text = str(text or "").strip()
+    found = []
+    pos = 0
+    for match in _COMPONENT.finditer(text):
+        if match.start() != pos:
+            raise ValueError("cannot read {!r}".format(text[pos:match.start()]))
+        pos = match.end()
+        if match.group("sep") is not None:
+            continue
+        if match.group("pkey") is not None:
+            key, coef = match.group("pkey").strip(), match.group("pcoef")
+        else:
+            key, coef = match.group("bkey"), match.group("bcoef")
+        found.append((key, float(coef) if coef is not None else 1.0))
+    if pos != len(text):
+        raise ValueError("cannot read {!r}".format(text[pos:]))
+    if not found:
+        raise ValueError("no components")
+    return found
+
+
+def component_counts(key, blocks=None):
+    """One component's atoms: a building block, else a sum formula, else
+    a SMILES written in the brackets."""
+    blocks = BUILDING_BLOCKS if blocks is None else blocks
+    if key in blocks:
+        return smiles_counts(blocks[key])
+    try:
+        return parse_formula(key)
+    except ValueError:
+        pass
+    try:
+        return smiles_counts(key)
+    except ValueError:
+        raise ValueError("{} is no building block, formula or SMILES"
+                         .format(key))
+
+
+def composition_counts(text, blocks=None):
+    total = {}
+    for key, coef in parse_composition(text):
+        for symbol, count in component_counts(key, blocks).items():
+            total[symbol] = total.get(symbol, 0.0) + count * coef
+    return total
+
+
+def _uses_blocks(text, blocks):
+    """True when a composition names a building block that is not simply
+    an element too (Zn and Co are both: "ZnO" is a sum formula)."""
+    try:
+        return any(key in blocks and not _is_element(key)
+                   for key, _c in parse_composition(text))
+    except ValueError:
+        return False
+
+
+# ------------------------------------------------------------ calculating
+def calculate(text, reading=AUTO, blocks=None):
+    """`text` as a `Result`: read as asked, or - AUTO - as the first that
+    fits of a composition with a known building block, a sum formula (not
+    one with an element twice in a row, "CC", which is a SMILES), a SMILES,
+    and a composition of formulas and SMILES."""
+    text = str(text or "").strip()
+    blocks = BUILDING_BLOCKS if blocks is None else blocks
+    if not text:
+        return Result(error="Type a formula, a SMILES or a composition.")
+    if not available():
+        return Result(error="RDKit is not installed: pip install rdkit")
+    tries = {
+        FORMULA: lambda: parse_formula(text),
+        SMILES: lambda: smiles_counts(text),
+        COMPOSITION: lambda: composition_counts(text, blocks),
+    }
+    if reading != AUTO:
+        try:
+            return Result(reading, tries[reading]())
+        except ValueError as exc:
+            return Result(reading, error="Not {}: {}".format(
+                TITLES[reading], exc))
+    errors = []
+    if _uses_blocks(text, blocks):
+        try:
+            return Result(COMPOSITION, tries[COMPOSITION]())
+        except ValueError as exc:
+            errors.append(str(exc))
+    # A formula and a SMILES may both read ("CO", "CCO"): then an element
+    # twice in a row with no count ("CC") says SMILES, else the formula.
+    found = {}
+    for kind in (FORMULA, SMILES):
+        try:
+            found[kind] = tries[kind]()
+        except ValueError as exc:
+            errors.append(str(exc))
+    if FORMULA in found and SMILES in found:
+        kind = SMILES if _repeats_bare(text) else FORMULA
+        return Result(kind, found[kind])
+    for kind in (FORMULA, SMILES):
+        if kind in found:
+            return Result(kind, found[kind])
+    try:
+        return Result(COMPOSITION, tries[COMPOSITION]())
+    except ValueError as exc:
+        errors.append(str(exc))
+    return Result(error="Not a formula, a SMILES or a composition "
+                        "({}).".format(errors[0] if errors else "?"))

dscpanel/core/numbers.py

@@ -0,0 +1,208 @@
+"""How a number is WRITTEN: the format strings of the house style.
+
+A format is Python's own percent format for ONE number - `%.2f`, `%+.1f`,
+`%.0f` - because that is what a Python user already writes, and a second
+mini-language would be one more thing to learn. `{:.2f}` and a bare `.2f`
+are taken too and mean the same.
+
+Two decisions, both on the side of the number being honest:
+
+* **A format is the number, and at most a UNIT.** `%.0f degF` asks for
+  the value IN Fahrenheit: the unit is a conversion, done by
+  `core/labels.py`, never a relabelling. Any other text is refused - words
+  belong in the label - and so is a unit the program does not know.
+* **`%.3g` means three SIGNIFICANT FIGURES, written out.** Python's `%g`
+  drops trailing zeros (1.50 becomes "1.5", which claims less than was
+  measured) and switches to exponent notation at 1000 ("1.23e+03" on a
+  figure). Here `%.Ng` rounds to N significant figures and writes them all,
+  in fixed notation: 13.2, 1.50, 0.0523, 141, 1230. That is what a default
+  of "3 significant figures" for enthalpies needs: a small enthalpy keeps
+  its digits instead of vanishing behind a fixed number of decimals.
+
+UI-free: plain strings and floats.
+"""
+
+import ast
+import math
+import re
+
+#: One conversion, and nothing else around it.
+_SPEC = re.compile(r"^%([-+ 0#]*)(\d*)(?:\.(\d+))?([fFeEgGd])$")
+#: The number part at the start of a format, in any of the three spellings,
+#: and whatever follows it (a unit, or nothing).
+_LEAD = re.compile(r"^(%[-+ 0#]*\d*(?:\.\d+)?[fFeEgGd]"
+                   r"|\{:[-+ 0#]*\d*(?:\.\d+)?[fFeEgGd]\}"
+                   r"|[-+ 0#]*\d*(?:\.\d+)?[fFeEgGd](?![A-Za-z]))(.*)$")
+
+#: The built-in formats, by what the number is.
+TEMPERATURE = "%.0f"        # an onset, an endset, a Tg: whole degrees
+VALUE = "%.3g"              # an enthalpy, a step: three significant figures
+OFFSET = "%+.1f"            # the template's add_yoffset_markers
+MASS = "%.0f"               # a mass at a temperature: "99 %"
+
+
+def normalise(spec, unit_of=None):
+    """`spec` as a canonical format - `%.2f`, or `%.2f K` with a unit - or
+    None if it is not one.
+
+    Accepts `%.2f`, `{:.2f}` and `.2f`. A unit after the number is kept only
+    when `unit_of` (a function: text -> canonical unit, or None) knows it;
+    without `unit_of`, a format may not carry one (an axis's numbers sit on
+    its ticks, so their unit is the axis's). Anything else is refused.
+    """
+    if spec is None:
+        return None
+    text = str(spec).strip()
+    match = _LEAD.match(text)
+    if not match:
+        return None
+    number, rest = match.group(1), match.group(2).strip()
+    if number.startswith("{:"):
+        number = "%" + number[2:-1]
+    elif not number.startswith("%"):
+        number = "%" + number
+    if not _SPEC.match(number):
+        return None
+    if not rest:
+        return number
+    unit = unit_of(rest) if unit_of is not None else None
+    return "{} {}".format(number, unit) if unit else None
+
+
+def _any_unit(text):
+    return str(text).strip() or None
+
+
+def split(spec):
+    """`(number format, unit or None)` of a canonical format."""
+    if not spec:
+        return None, None
+    parts = str(spec).split(" ", 1)
+    return parts[0], (parts[1] if len(parts) > 1 else None)
+
+
+def is_valid(spec, unit_of=None):
+    return normalise(spec, unit_of) is not None
+
+
+def write(value, spec, fallback=VALUE):
+    """`value` written with `spec` (or `fallback` when `spec` is no format).
+
+    Never raises: a paint call is the last place for an exception, and a
+    format that does not parse falls back rather than blanking the figure.
+    """
+    if value is None:
+        return "?"
+    try:
+        value = float(value)
+    except (TypeError, ValueError):
+        return "?"
+    if value != value or abs(value) == float("inf"):
+        return "?"
+    # Only the NUMBER is written here; a unit in the format is the
+    # caller's to convert to (`core/labels.py`).
+    spec = (split(normalise(spec, _any_unit))[0]
+            or split(normalise(fallback, _any_unit))[0] or VALUE)
+    flags, width, precision, kind = _SPEC.match(spec).groups()
+    if kind in "gG":
+        digits = int(precision) if precision not in (None, "") else 6
+        text = significant(value, max(1, digits))
+        if "+" in flags and value >= 0:
+            text = "+" + text
+        elif " " in flags and value >= 0:
+            text = " " + text
+    elif kind == "d":
+        text = ("%" + flags + width + "d") % int(round(value))
+    else:
+        text = spec % value
+    return _no_negative_zero(text)
+
+
+def significant(value, digits):
+    """`value` rounded to `digits` significant figures, in fixed notation,
+    with every one of those figures written (trailing zeros kept)."""
+    if value == 0:
+        return "0" if digits <= 1 else "0." + "0" * (digits - 1)
+    exponent = int(math.floor(math.log10(abs(value))))
+    rounded = round(value, digits - 1 - exponent)
+    if rounded != 0:
+        # 9.996 to three figures is 10.0: the rounding moved the exponent.
+        exponent = int(math.floor(math.log10(abs(rounded))))
+    decimals = max(0, digits - 1 - exponent)
+    return "%.*f" % (decimals, rounded)
+
+
+def _no_negative_zero(text):
+    """"-0" and "-0.0" are zero: a sign on a rounded zero is noise."""
+    stripped = text.strip()
+    if stripped.startswith("-") and not any(c in "123456789"
+                                            for c in stripped):
+        return text.replace("-", "", 1)
+    return text
+
+
+# ------------------------------------------------------------- typed sums
+#: What a typed sum may hold: numbers, the four operations, brackets. A
+#: comma is a decimal point, as everywhere a number is typed here.
+_SUM_CHARACTERS = re.compile(r"^[0-9.,+\-*/() 	]*$")
+
+
+def evaluate(text):
+    """A typed number or simple sum as a float: "255-20", "3*(1,5+2)",
+    "-4". None if it is not one (or divides by zero).
+
+    Only + - * / and brackets; walked from Python's parse tree, never `eval`.
+    """
+    text = str(text or "").strip()
+    if not text or not _SUM_CHARACTERS.match(text):
+        return None
+    try:
+        tree = ast.parse(text.replace(",", "."), mode="eval")
+        value = _sum_of(tree.body)
+    except (SyntaxError, ValueError, ZeroDivisionError, OverflowError,
+            RecursionError):
+        return None
+    if value is None or not math.isfinite(value):
+        return None
+    return float(value)
+
+
+def values(text):
+    """Several typed numbers, as floats - `[]` for none, None when any is
+    not a number. Separated by ";", ", " or a space before the next number:
+    a comma with no space is a decimal point ("261,5"). Each may be a sum
+    (`evaluate`)."""
+    parts = [part for part in re.split(r"\s*;\s*|,\s+|\s+(?=[-+]?\d)",
+                                       str(text or "").strip())
+             if part.strip()]
+    out = []
+    for part in parts:
+        value = evaluate(part)
+        if value is None:
+            return None
+        out.append(value)
+    return out
+
+
+def is_sum(text):
+    """True if `text` holds an operation, not just a number: "255-20" does,
+    "-4" and "1,5" do not."""
+    body = str(text or "").strip().lstrip("+-")
+    return any(c in body for c in "+-*/()")
+
+
+_OPERATIONS = {ast.Add: lambda a, b: a + b, ast.Sub: lambda a, b: a - b,
+               ast.Mult: lambda a, b: a * b, ast.Div: lambda a, b: a / b}
+
+
+def _sum_of(node):
+    if isinstance(node, ast.Constant) and type(node.value) in (int, float):
+        return float(node.value)
+    if isinstance(node, ast.UnaryOp) and isinstance(node.op,
+                                                    (ast.USub, ast.UAdd)):
+        value = _sum_of(node.operand)
+        return -value if isinstance(node.op, ast.USub) else value
+    if isinstance(node, ast.BinOp) and type(node.op) in _OPERATIONS:
+        return _OPERATIONS[type(node.op)](_sum_of(node.left),
+                                          _sum_of(node.right))
+    raise ValueError("not a sum")