PyPI - approximate - Versions diffs - 0.1.0__py3-none-any.whl - Mend

approximate 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (25) hide show

approximate/Data/fixed_ox_states.csv +42 -0
approximate/Data/variable_ox_states_srps.csv +171 -0
approximate/__init__.py +31 -0
approximate/capacity.py +169 -0
approximate/core.py +976 -0
approximate/feature_engineering/__init__.py +21 -0
approximate/feature_engineering/base.py +68 -0
approximate/feature_engineering/electronegativity_features.py +175 -0
approximate/feature_engineering/element_properties.py +150 -0
approximate/feature_engineering/element_property_features.py +48 -0
approximate/feature_engineering/feature_extractor.py +119 -0
approximate/feature_engineering/ionic_radius_features.py +49 -0
approximate/feature_engineering/layered_ox_features.py +98 -0
approximate/feature_engineering/magnetic_moment_features.py +122 -0
approximate/feature_engineering/registry.py +15 -0
approximate/feature_engineering/stats_expander.py +38 -0
approximate/feature_engineering/utils.py +112 -0
approximate/feature_engineering/valence_features.py +100 -0
approximate/plotting.py +113 -0
approximate/sweep.py +111 -0
approximate-0.1.0.dist-info/METADATA +202 -0
approximate-0.1.0.dist-info/RECORD +25 -0
approximate-0.1.0.dist-info/WHEEL +5 -0
approximate-0.1.0.dist-info/licenses/LICENSE +21 -0
approximate-0.1.0.dist-info/top_level.txt +1 -0

approximate/Data/fixed_ox_states.csv ADDED Viewed

@@ -0,0 +1,42 @@
+Element,Ox State
+H,1
+Li,1
+Na,1
+K,1
+Rb,1
+Cs,1
+Fr,1
+Be,2
+Mg,2
+Ca,2
+Sr,2
+Ba,2
+Ra,2
+Y,3
+La,3
+Gd,3
+Lu,3
+Ac,3
+Th,4
+Lr,3
+Zr,4
+Hf,4
+Zn,2
+Cd,2
+Hg,2
+B,3
+Al,3
+Ga,3
+O,-2
+Po,4
+F,-1
+Cl,-1
+Br,-1
+I,-1
+At,-1
+T,2
+D,3
+Er,3
+In,3
+Ho,3
+P,5

approximate/Data/variable_ox_states_srps.csv ADDED Viewed

@@ -0,0 +1,171 @@
+Element,Ox,Red,SRP (V)
+Sc,3,2,-2.3
+Sc,3,0,-2.09
+Sc,2,0,-2
+Ti,2,0,-1.63
+Ti,3,0,-1.37
+Ti,3,2,-0.37
+Ti,4,3,0.10
+Ce,3,0,-2.336
+Ce,4,3,1.71
+Pr,3,0,-2.353
+Nd,3,2,-2.7
+Nd,3,0,-2.323
+Nd,2,0,-2.1
+Pm,3,2,-2.6
+Pm,3,0,-2.3
+Pm,2,0,-2.2
+Eu,2,0,-2.812
+Eu,3,0,-1.991
+Eu,3,2,-0.35
+Tb,3,0,-2.28
+Dy,3,2,-2.6
+Dy,3,0,-2.295
+Dy,2,0,-2.2
+Tm,2,0,-2.4
+Tm,3,0,-2.319
+Tm,3,2,-2.2
+Yb,2,0,-2.76
+Yb,3,0,-2.19
+Yb,3,2,-1.05
+Pa,4,3,-1.9
+Pa,4,0,-1.49
+Pa,3,0,-1.34
+U,3,0,-1.642
+U,4,3,-0.577
+Np,3,0,-1.768
+Np,4,3,0.157
+Pu,3,2,-2.8
+Pu,3,0,-1.978
+Pu,2,0,-1.6
+Pu,4,3,1.006
+Am,3,2,-2.3
+Am,3,0,-2.048
+Am,2,0,-1.9
+Cm,3,0,-2.04
+Bk,3,2,-2.8
+Bk,3,0,-1.98
+Bk,2,0,-1.6
+Bk,4,3,1.67
+Cf,2,0,-2.12
+Cf,3,0,-1.94
+Cf,3,2,-1.6
+Es,2,0,-2.23
+Es,3,0,-1.91
+Es,3,2,-1.3
+Fm,2,0,-2.3
+Fm,3,0,-1.89
+Fm,3,2,-1.1
+Md,2,0,-2.4
+Md,3,0,-1.65
+Md,3,2,-0.1
+No,2,0,-2.5
+No,3,0,-1.2
+No,3,2,1.4
+V,2,0,-1.13
+V,3,2,-0.26
+V,4,3,0.337
+V,5,4,1.001
+Nb,3,0,-0.733
+Nb,5,0,-0.69
+Nb,5,3,-0.646
+Ta,5,0,-0.752
+Ta,3,0,-0.6
+Cr,2,0,-0.89
+Cr,3,0,-0.74
+Cr,3,2,-0.42
+Cr,6,3,1.36
+Mo,4,0,-0.152
+Mo,6,0,0.082
+Mo,6,4,0.2
+W,4,0,-1.54
+W,6,0,-0.091
+W,6,4,0.01
+Mn,2,0,-1.182
+Mn,4,3,0.98
+Mn,3,2,1.56
+Mn,7,4,2.09
+Tc,4,0,0.272
+Tc,7,0,0.427
+Tc,7,4,0.738
+Re,4,0,0.276
+Re,7,0,0.376
+Re,7,4,0.51
+Fe,2,0,-0.44
+Fe,3,2,0.771
+Ru,4,3,0.58
+Ru,3,0,0.6
+Ru,8,4,1.4
+Os,4,0,0.65
+Os,8,0,0.838
+Os,8,4,0.964
+Co,2,0,-0.282
+Co,3,0,0.003
+Co,4,3,1.42
+Co,3,2,1.92
+Ir,4,3,0.4
+Ir,4,0,0.73
+Ir,3,0,0.84
+Ni,2,0,-0.236
+Ni,4,0,0.055
+Ni,3,2,1.753
+Ni,4,3,2.05
+Pd,2,0,0.915
+Pd,4,2,1.27
+Pt,4,0,0.92
+Pt,4,2,1.01
+Pt,2,0,1.18
+Cu,2,1,0.161
+Cu,2,0,0.339
+Cu,1,0,0.518
+Ag,1,0,0.7993
+Ag,2,1,1.98
+Au,3,1,1.41
+Au,3,0,1.52
+Au,1,0,1.69
+Sm,2,0,-2.68
+Sm,3,0,-2.304
+Sm,3,2,-1.55
+Tl,1,0,-0.336
+Tl,3,0,0.741
+Tl,3,1,1.28
+C,4,2,-0.07
+C,4,0,0.2073
+C,2,0,0.5184
+Si,4,0,-0.931
+Si,0,-4,-0.147
+Ge,4,2,-2.07
+Ge,4,0,-0.104
+Ge,2,0,0.11
+Sn,2,0,-0.141
+Sn,4,0,-0.117
+Sn,4,2,-0.094
+Pb,2,0,-0.126
+Pb,4,0,1.23
+Pb,4,2,1.458
+Bi,3,0,0.308
+Bi,5,3,2
+S,0,-2,0.144
+S,6,4,0.158
+S,6,0,0.333
+S,4,0,0.458
+Te,0,-2,-0.46
+Te,4,0,0.529
+Te,6,4,0.84
+P,3,0,-0.402
+P,5,0,-0.377
+P,5,3,-0.3
+P,0,-3,-0.088
+Sb,3,0,0.231
+Sb,5,3,0.54
+As,3,0,0.234
+As,5,3,0.566
+N,0,-3,-3.334
+N,3,-3,-1.887
+N,3,0,1.447
+Rh,3,0,0.76
+Rh,4,0,0.83
+Rh,4,3,1.3
+Se,0,-2,-0.114
+Se,4,0,0.739
+Se,6,4,1.094

approximate/__init__.py ADDED Viewed

@@ -0,0 +1,31 @@
+"""ApprOxiMate: composition-only mixed oxidation state estimation.
+    from approximate import charge_balance
+    r = charge_balance("Fe3O4")
+"""
+from .capacity import CapacityResult, capacity, molar_mass
+from .sweep import SweepResult, alkali_sweep
+from .core import (
+    BalanceResult,
+    ElementState,
+    charge_balance,
+    final_charge,
+    oxidation_states,
+    parse_formula,
+)
+__version__ = "0.1.0"
+__all__ = [
+    "charge_balance",
+    "oxidation_states",
+    "final_charge",
+    "parse_formula",
+    "capacity",
+    "molar_mass",
+    "CapacityResult",
+    "alkali_sweep",
+    "SweepResult",
+    "BalanceResult",
+    "ElementState",
+]

approximate/capacity.py ADDED Viewed

@@ -0,0 +1,169 @@
+"""Theoretical and charge-balance-adjusted capacity.
+Pure Python (only depends on approximate.core), so it also runs in the
+browser via Pyodide for the ApprOxiMate website.
+    >>> from approximate import capacity
+    >>> c = capacity("NaFe0.5Co0.5O2")
+    >>> round(c.q_theoretical, 1), round(c.q_adjusted, 1)
+    (238.5, 119.2)
+Assumptions:
+    * one electron transferred per alkali ion removed;
+    * molar mass is that of the starting (fully alkali-loaded) formula.
+"""
+from dataclasses import asdict, dataclass
+from .core import charge_balance, parse_formula
+#: Faraday constant in C/mol (exact, 2019 SI redefinition).
+FARADAY = 96485.33212
+ALKALI_METALS = ("Li", "Na", "K", "Rb", "Cs")
+# Standard atomic weights (g/mol): IUPAC/CIAAW 2013 values with the 2015
+# ytterbium revision, as distributed by the mendeleev package.
+#   J. Meija et al., "Atomic weights of the elements 2013 (IUPAC Technical
+#   Report)", Pure Appl. Chem. 88, 265-291 (2016). doi:10.1515/pac-2015-0305
+#   CIAAW, "Standard atomic weight of ytterbium revised", Chem. Int. 37(5-6),
+#   26 (2015). doi:10.1515/ci-2015-0512
+# Values are kept identical to mendeleev (checked in tests/test_capacity.py) so
+# that capacities agree with the feature engineering, which uses mendeleev.
+ATOMIC_MASS = {
+    "H": 1.008, "He": 4.002602, "Li": 6.94, "Be": 9.0121831, "B": 10.81, "C": 12.011,
+    "N": 14.007, "O": 15.999, "F": 18.998403163, "Ne": 20.1797, "Na": 22.98976928,
+    "Mg": 24.305, "Al": 26.9815385, "Si": 28.085, "P": 30.973761998, "S": 32.06, "Cl": 35.45,
+    "Ar": 39.948, "K": 39.0983, "Ca": 40.078, "Sc": 44.955908, "Ti": 47.867, "V": 50.9415,
+    "Cr": 51.9961, "Mn": 54.938044, "Fe": 55.845, "Co": 58.933194, "Ni": 58.6934,
+    "Cu": 63.546, "Zn": 65.38, "Ga": 69.723, "Ge": 72.63, "As": 74.921595, "Se": 78.971,
+    "Br": 79.904, "Kr": 83.798, "Rb": 85.4678, "Sr": 87.62, "Y": 88.90584, "Zr": 91.224,
+    "Nb": 92.90637, "Mo": 95.95, "Tc": 97.90721, "Ru": 101.07, "Rh": 102.9055, "Pd": 106.42,
+    "Ag": 107.8682, "Cd": 112.414, "In": 114.818, "Sn": 118.71, "Sb": 121.76, "Te": 127.6,
+    "I": 126.90447, "Xe": 131.293, "Cs": 132.90545196, "Ba": 137.327, "La": 138.90547,
+    "Ce": 140.116, "Pr": 140.90766, "Nd": 144.242, "Pm": 144.91276, "Sm": 150.36,
+    "Eu": 151.964, "Gd": 157.25, "Tb": 158.92535, "Dy": 162.5, "Ho": 164.93033,
+    "Er": 167.259, "Tm": 168.93422, "Yb": 173.045, "Lu": 174.9668, "Hf": 178.49,
+    "Ta": 180.94788, "W": 183.84, "Re": 186.207, "Os": 190.23, "Ir": 192.217, "Pt": 195.084,
+    "Au": 196.966569, "Hg": 200.592, "Tl": 204.38, "Pb": 207.2, "Bi": 208.9804, "Po": 209.0,
+    "At": 210.0, "Rn": 222.0, "Fr": 223.0, "Ra": 226.0, "Ac": 227.0, "Th": 232.0377,
+    "Pa": 231.03588, "U": 238.02891, "Np": 237.0, "Pu": 244.0, "Am": 243.0, "Cm": 247.0,
+    "Bk": 247.0, "Cf": 251.0, "Es": 252.0, "Fm": 257.0, "Md": 258.0, "No": 259.0,
+    "Lr": 262.0, "Rf": 267.0, "Db": 268.0, "Sg": 271.0, "Bh": 274.0, "Hs": 269.0,
+    "Mt": 276.0, "Ds": 281.0, "Rg": 281.0, "Cn": 285.0, "Nh": 286.0, "Fl": 289.0,
+    "Mc": 288.0, "Lv": 293.0, "Ts": 294.0, "Og": 294.0,
+}
+@dataclass(frozen=True)
+class CapacityResult:
+    """Result of capacity().
+    Attributes:
+        alkali: the alkali metal being removed.
+        full: alkali per formula unit in the starting formula.
+        removable: alkali that can be removed before the formula can no
+            longer be charge balanced.
+        remaining: alkali left at that limit (full - removable).
+        molar_mass: molar mass of the starting formula, g/mol.
+        q_theoretical: capacity if all alkali is removed, mAh/g.
+        q_adjusted: capacity limited by charge balance, mAh/g.
+    """
+    alkali: str
+    full: float
+    removable: float
+    remaining: float
+    molar_mass: float
+    q_theoretical: float
+    q_adjusted: float
+    @property
+    def per_alkali(self) -> float:
+        """mAh/g per formula unit of alkali removed."""
+        return self.q_theoretical / self.full
+    def to_dict(self) -> dict:
+        return asdict(self)
+def _as_parsed(formula):
+    if isinstance(formula, dict):
+        return dict(formula)
+    parsed = parse_formula(str(formula).strip())
+    if not parsed:
+        raise ValueError(f"Could not parse formula {formula!r} (unknown element?)")
+    return parsed
+def molar_mass(formula) -> float:
+    """Molar mass in g/mol of a formula string or {element: amount} dict."""
+    parsed = _as_parsed(formula)
+    missing = [el for el in parsed if el not in ATOMIC_MASS]
+    if missing:
+        raise ValueError(f"No atomic mass for {', '.join(missing)}")
+    return sum(ATOMIC_MASS[el] * q for el, q in parsed.items())
+def _pick_alkali(parsed):
+    present = [el for el in ALKALI_METALS if parsed.get(el, 0) > 0]
+    if len(present) != 1:
+        found = ", ".join(present) if present else "none"
+        raise ValueError(f"Specify alkali= (alkali metals found: {found})")
+    return present[0]
+def capacity(formula, alkali=None, interval=0.01, tol=1e-6, faraday=FARADAY):
+    """Theoretical vs charge-balance-adjusted capacity (mAh/g).
+    Steps the alkali amount down from its full value in `interval` steps and
+    stops at the first composition that is no longer charge neutral
+    (|final charge| > tol). The last neutral composition sets how much
+    alkali is removable.
+        Q_theoretical = full      * F / (3.6 * M)
+        Q_adjusted    = removable * F / (3.6 * M)
+    Args:
+        formula: formula string or {element: amount} dict.
+        alkali: alkali metal to remove. If None, the single alkali metal
+            in the formula is used.
+        interval: step size in alkali per formula unit (paper: 0.01).
+        tol: charge tolerance for "still balanced".
+        faraday: Faraday constant, C/mol.
+    Raises:
+        ValueError: unparsable formula, unknown element, or alkali not present.
+    """
+    parsed = _as_parsed(formula)
+    if alkali is None:
+        alkali = _pick_alkali(parsed)
+    full = parsed.get(alkali, 0)
+    if not full or full <= 0:
+        raise ValueError(f"{alkali} not found in formula")
+    mass = molar_mass(parsed)
+    n_steps = max(1, int(round(full / interval)))
+    step = -full / n_steps
+    last_ok = full
+    for k in range(n_steps + 1):
+        # same values as np.linspace(full, 0, n_steps + 1), endpoint exactly 0
+        remaining = 0.0 if k == n_steps else full + k * step
+        try:
+            r = charge_balance({**parsed, alkali: remaining})
+            charge = r.final_charge if r is not None else float("nan")
+        except Exception:
+            charge = float("nan")
+        if charge != charge or abs(charge) > tol:  # NaN or unbalanced
+            break
+        last_ok = remaining
+    per_unit = faraday / (3.6 * mass)
+    removable = full - last_ok
+    return CapacityResult(
+        alkali=alkali,
+        full=float(full),
+        removable=removable,
+        remaining=last_ok,
+        molar_mass=mass,
+        q_theoretical=full * per_unit,
+        q_adjusted=removable * per_unit,
+    )