molbuilder 1.0.0__py3-none-any.whl

molbuilder/core/__init__.py

@@ -0,0 +1,6 @@
+"""Core data and utilities for molecular modeling."""
+from molbuilder.core.constants import *
+from molbuilder.core.elements import ELEMENTS, SYMBOL_TO_Z, from_symbol, from_name
+from molbuilder.core.element_properties import electronegativity, covalent_radius_pm
+from molbuilder.core.geometry import normalize, rotation_matrix, place_atom_zmatrix
+from molbuilder.core.bond_data import bond_length, SP3_ANGLE, SP2_ANGLE, SP_ANGLE

molbuilder/core/bond_data.py

@@ -0,0 +1,170 @@
+"""
+Bond reference data: standard bond lengths, dissociation energies,
+torsion barrier parameters.
+
+Consolidated from molecular_conformations.py (STANDARD_BOND_LENGTHS,
+TORSION_BARRIERS) and covalent_bonds.py (BDE_TABLE).
+"""
+
+from molbuilder.core.element_properties import estimated_bond_length_angstrom
+
+# ===================================================================
+# Standard bond lengths in Angstroms (experimental averages)
+# ===================================================================
+# Keys: (symbol_a, symbol_b, order) with symbols in alphabetical order.
+
+STANDARD_BOND_LENGTHS: dict[tuple[str, str, int], float] = {
+    ("C", "C", 1): 1.54,
+    ("C", "C", 2): 1.34,
+    ("C", "C", 3): 1.20,
+    ("C", "H", 1): 1.09,
+    ("C", "O", 1): 1.43,
+    ("C", "O", 2): 1.23,
+    ("C", "N", 1): 1.47,
+    ("C", "N", 2): 1.29,
+    ("C", "N", 3): 1.16,
+    ("C", "F", 1): 1.35,
+    ("C", "Cl", 1): 1.77,
+    ("Br", "C", 1): 1.94,
+    ("C", "I", 1): 2.14,
+    ("C", "S", 1): 1.82,
+    ("H", "O", 1): 0.96,
+    ("H", "N", 1): 1.01,
+    ("H", "S", 1): 1.34,
+    ("F", "F", 1): 1.42,
+    ("Cl", "Cl", 1): 1.99,
+    ("Br", "Br", 1): 2.28,
+    ("H", "H", 1): 0.74,
+    ("S", "S", 1): 2.05,
+    ("N", "O", 1): 1.36,
+    ("N", "O", 2): 1.21,
+    ("O", "P", 1): 1.63,
+    ("O", "P", 2): 1.48,
+    ("H", "P", 1): 1.44,
+}
+
+# Standard bond angles in degrees
+SP3_ANGLE = 109.47   # tetrahedral
+SP2_ANGLE = 120.0    # trigonal planar
+SP_ANGLE = 180.0     # linear
+
+
+# ===================================================================
+# Bond dissociation energies (kJ/mol)
+# ===================================================================
+# Sources: CRC Handbook, Darwent (NSRDS-NBS 31), Kerr & Stocker.
+# Keys: (symbol_a, symbol_b, bond_order) alphabetical order.
+
+BDE_TABLE: dict[tuple[str, str, int], float] = {
+    # Single bonds
+    ("H", "H", 1):  436,
+    ("C", "H", 1):  413,
+    ("C", "C", 1):  348,
+    ("C", "N", 1):  293,
+    ("C", "O", 1):  358,
+    ("C", "F", 1):  485,
+    ("C", "Cl", 1): 328,
+    ("C", "Br", 1): 276,
+    ("C", "I", 1):  240,
+    ("C", "S", 1):  272,
+    ("N", "H", 1):  391,
+    ("N", "N", 1):  163,
+    ("N", "O", 1):  201,
+    ("O", "H", 1):  463,
+    ("O", "O", 1):  146,
+    ("F", "F", 1):  155,
+    ("F", "H", 1):  567,
+    ("Cl", "Cl", 1): 242,
+    ("Cl", "H", 1): 431,
+    ("Br", "Br", 1): 193,
+    ("Br", "H", 1): 366,
+    ("H", "I", 1):  297,
+    ("I", "I", 1):  151,
+    ("H", "S", 1):  363,
+    ("S", "S", 1):  266,
+    ("P", "H", 1):  322,
+    ("O", "Si", 1): 452,
+    ("H", "Si", 1): 318,
+    # Double bonds
+    ("C", "C", 2):  614,
+    ("C", "N", 2):  615,
+    ("C", "O", 2):  799,
+    ("N", "N", 2):  418,
+    ("O", "O", 2):  498,
+    ("N", "O", 2):  607,
+    ("C", "S", 2):  577,
+    ("S", "O", 2):  522,
+    # Additional single bonds (P2-DATA-2)
+    ("C", "P", 1):  264,   # Luo 2007
+    ("C", "Si", 1): 318,   # CRC Handbook
+    ("N", "S", 1):  272,   # Benson estimates
+    ("Cl", "N", 1): 200,   # chloramine / N-Cl
+    ("F", "O", 1):  190,   # OF2
+    ("O", "S", 1):  265,   # dimethyl sulfoxide (single)
+    ("F", "S", 1):  327,   # SF6 type
+    ("N", "P", 1):  230,   # P-N amine
+    ("F", "Si", 1): 565,   # SiF4
+    # Triple bonds
+    ("C", "C", 3):  839,
+    ("C", "N", 3):  891,
+    ("N", "N", 3):  941,
+    ("C", "O", 3):  1072,
+}
+
+
+# ===================================================================
+# Torsion barrier parameters (kJ/mol) -- OPLS-AA
+# ===================================================================
+
+TORSION_BARRIERS: dict[str, dict[str, float]] = {
+    # sp3-sp3 torsions (alkanes)
+    "H_sp3_sp3_H": {"V1": 0.0,  "V2": 0.0,   "V3": 1.39},
+    "C_sp3_sp3_C": {"V1": 2.73, "V2": -0.53,  "V3": 0.84},
+    "C_sp3_sp3_H": {"V1": 0.0,  "V2": 0.0,    "V3": 0.76},
+    "H_sp3_sp3_C": {"V1": 0.0,  "V2": 0.0,    "V3": 0.76},
+    # sp2-sp3 torsions (P2-DATA-3, OPLS-AA Jorgensen et al. JACS 1996)
+    "C_sp2_sp3_C": {"V1": 0.0,  "V2": 0.0,    "V3": 0.50},
+    "C_sp2_sp3_H": {"V1": 0.0,  "V2": 0.0,    "V3": 0.50},
+    "H_sp2_sp3_C": {"V1": 0.0,  "V2": 0.0,    "V3": 0.50},
+    "H_sp2_sp3_H": {"V1": 0.0,  "V2": 0.0,    "V3": 0.50},
+    "H_sp3_sp2_C": {"V1": 0.0,  "V2": 0.0,    "V3": 0.50},
+    "C_sp3_sp2_C": {"V1": 0.0,  "V2": 0.0,    "V3": 0.50},
+    "C_sp3_sp2_H": {"V1": 0.0,  "V2": 0.0,    "V3": 0.50},
+    # sp2-sp2 torsions (conjugated systems)
+    "C_sp2_sp2_C": {"V1": 0.0,  "V2": 12.0,   "V3": 0.0},
+    "C_sp2_sp2_H": {"V1": 0.0,  "V2": 12.0,   "V3": 0.0},
+    "H_sp2_sp2_C": {"V1": 0.0,  "V2": 12.0,   "V3": 0.0},
+    "H_sp2_sp2_H": {"V1": 0.0,  "V2": 12.0,   "V3": 0.0},
+    "default":     {"V1": 0.0,  "V2": 0.0,    "V3": 1.00},
+}
+
+
+# ===================================================================
+# Electronegativity thresholds for bond polarity
+# ===================================================================
+
+NONPOLAR_THRESHOLD = 0.4
+POLAR_COVALENT_MAX = 1.7
+
+
+# ===================================================================
+# Lookup functions
+# ===================================================================
+
+def bond_length(sym_a: str, sym_b: str, order: int = 1) -> float:
+    """Look up standard bond length in Angstroms.
+
+    Checks STANDARD_BOND_LENGTHS first, falls back to
+    element_properties covalent-radii estimate.
+    """
+    a, b = sorted([sym_a, sym_b])
+    key = (a, b, order)
+    if key in STANDARD_BOND_LENGTHS:
+        return STANDARD_BOND_LENGTHS[key]
+    return estimated_bond_length_angstrom(sym_a, sym_b, order)
+
+
+def bde_lookup(sym_a: str, sym_b: str, order: int = 1) -> float | None:
+    """Look up mean bond dissociation energy in kJ/mol, or None."""
+    a, b = sorted([sym_a, sym_b])
+    return BDE_TABLE.get((a, b, order))

molbuilder/core/constants.py

@@ -0,0 +1,51 @@
+"""
+Physical constants (SI units) used throughout molbuilder.
+
+Consolidated from bohr_model.py, quantum_wavefunctions.py, and
+atomic_particle_physical_laws.py.
+"""
+
+import math
+
+# ---------------------------------------------------------------------------
+# Fundamental constants
+# ---------------------------------------------------------------------------
+BOHR_RADIUS_M = 5.29177210903e-11          # metres
+BOHR_RADIUS_PM = 52.9177210903             # picometres
+PLANCK_CONSTANT = 6.62607015e-34           # J s
+HBAR = PLANCK_CONSTANT / (2 * math.pi)    # reduced Planck constant (J s)
+SPEED_OF_LIGHT = 2.99792458e8             # m/s
+ELECTRON_CHARGE = 1.602176634e-19         # C
+ELECTRON_MASS = 9.1093837015e-31          # kg
+COULOMB_CONSTANT = 8.9875517873681764e9   # N m^2 / C^2
+VACUUM_PERMITTIVITY = 8.8541878128e-12    # F/m
+
+# ---------------------------------------------------------------------------
+# Unit conversions
+# ---------------------------------------------------------------------------
+EV_TO_JOULES = 1.602176634e-19
+RYDBERG_ENERGY_EV = 13.605693122994       # eV
+DEBYE_PER_E_ANGSTROM = 4.8032            # 1 e*A = 4.8032 D
+
+# ---------------------------------------------------------------------------
+# Fine structure constant
+# ---------------------------------------------------------------------------
+FINE_STRUCTURE_ALPHA = (
+    ELECTRON_CHARGE**2
+    / (4 * math.pi * VACUUM_PERMITTIVITY * HBAR * SPEED_OF_LIGHT)
+)
+
+# ---------------------------------------------------------------------------
+# Shell capacity
+# ---------------------------------------------------------------------------
+MAX_ELECTRONS_PER_SHELL = [2 * n**2 for n in range(1, 8)]  # shells 1-7
+
+
+# ---------------------------------------------------------------------------
+# Electrostatics
+# ---------------------------------------------------------------------------
+def coulombs_law(q1: float, q2: float, r: float) -> float:
+    """Coulomb force between two charges q1, q2 (Coulombs) separated by r (metres)."""
+    if r <= 0:
+        raise ValueError("Distance must be positive")
+    return COULOMB_CONSTANT * (abs(q1) * abs(q2)) / r**2

molbuilder/core/element_properties.py

@@ -0,0 +1,183 @@
+"""
+Chemical properties of elements: electronegativity, covalent radii,
+CPK colours, octet targets, period/group information.
+
+Migrated from element_data.py.
+"""
+
+import warnings
+
+from molbuilder.core.elements import SYMBOL_TO_Z
+
+# ---------------------------------------------------------------------------
+# Pauling electronegativity  (symbol -> float or None)
+# ---------------------------------------------------------------------------
+PAULING_ELECTRONEGATIVITY: dict[str, float | None] = {
+    "H":  2.20, "He": None,
+    "Li": 0.98, "Be": 1.57, "B":  2.04, "C":  2.55, "N":  3.04,
+    "O":  3.44, "F":  3.98, "Ne": None,
+    "Na": 0.93, "Mg": 1.31, "Al": 1.61, "Si": 1.90, "P":  2.19,
+    "S":  2.58, "Cl": 3.16, "Ar": None,
+    "K":  0.82, "Ca": 1.00, "Sc": 1.36, "Ti": 1.54, "V":  1.63,
+    "Cr": 1.66, "Mn": 1.55, "Fe": 1.83, "Co": 1.88, "Ni": 1.91,
+    "Cu": 1.90, "Zn": 1.65, "Ga": 1.81, "Ge": 2.01, "As": 2.18,
+    "Se": 2.55, "Br": 2.96, "Kr": 3.00,
+    "Rb": 0.82, "Sr": 0.95, "Y":  1.22, "Zr": 1.33, "Nb": 1.60,
+    "Mo": 2.16, "Tc": 1.90, "Ru": 2.20, "Rh": 2.28, "Pd": 2.20,
+    "Ag": 1.93, "Cd": 1.69, "In": 1.78, "Sn": 1.96, "Sb": 2.05,
+    "Te": 2.10, "I":  2.66, "Xe": 2.60,
+    "Cs": 0.79, "Ba": 0.89, "La": 1.10, "Ce": 1.12, "Pr": 1.13,
+    "Nd": 1.14, "Pm": 1.13, "Sm": 1.17, "Eu": 1.20, "Gd": 1.20,
+    "Tb": 1.10, "Dy": 1.22, "Ho": 1.23, "Er": 1.24, "Tm": 1.25,
+    "Yb": 1.10, "Lu": 1.27, "Hf": 1.30, "Ta": 1.50, "W":  2.36,
+    "Re": 1.90, "Os": 2.20, "Ir": 2.20, "Pt": 2.28, "Au": 2.54,
+    "Hg": 2.00, "Tl": 1.62, "Pb": 1.87, "Bi": 2.02, "Po": 2.00,
+    "At": 2.20, "Rn": 2.20,
+    "Fr": 0.70, "Ra": 0.90, "Ac": 1.10, "Th": 1.30, "Pa": 1.50,
+    "U":  1.38, "Np": 1.36, "Pu": 1.28, "Am": 1.30, "Cm": 1.30,
+    "Bk": 1.30, "Cf": 1.30, "Es": 1.30, "Fm": 1.30, "Md": 1.30,
+    "No": 1.30, "Lr": 1.30,
+    "Rf": None, "Db": None, "Sg": None, "Bh": None, "Hs": None,
+    "Mt": None, "Ds": None, "Rg": None, "Cn": None, "Nh": None,
+    "Fl": None, "Mc": None, "Lv": None, "Ts": None, "Og": None,
+}
+
+# ---------------------------------------------------------------------------
+# Single-bond covalent radii in picometres (Cordero et al. 2008)
+# ---------------------------------------------------------------------------
+COVALENT_RADII_PM: dict[str, float] = {
+    "H":  31,  "He": 28,
+    "Li": 128, "Be": 96,  "B":  84,  "C":  76,  "N":  71,
+    "O":  66,  "F":  57,  "Ne": 58,
+    "Na": 166, "Mg": 141, "Al": 121, "Si": 111, "P":  107,
+    "S":  105, "Cl": 102, "Ar": 106,
+    "K":  203, "Ca": 176, "Sc": 170, "Ti": 160, "V":  153,
+    "Cr": 139, "Mn": 139, "Fe": 132, "Co": 126, "Ni": 124,
+    "Cu": 132, "Zn": 122, "Ga": 122, "Ge": 120, "As": 119,
+    "Se": 120, "Br": 120, "Kr": 116,
+    "Rb": 220, "Sr": 195, "Y":  190, "Zr": 175, "Nb": 164,
+    "Mo": 154, "Tc": 147, "Ru": 146, "Rh": 142, "Pd": 139,
+    "Ag": 145, "Cd": 144, "In": 142, "Sn": 139, "Sb": 139,
+    "Te": 138, "I":  139, "Xe": 140,
+    "Cs": 244, "Ba": 215, "La": 207, "Ce": 204, "Pr": 203,
+    "Nd": 201, "Pm": 199, "Sm": 198, "Eu": 198, "Gd": 196,
+    "Tb": 194, "Dy": 192, "Ho": 192, "Er": 189, "Tm": 190,
+    "Yb": 187, "Lu": 187, "Hf": 175, "Ta": 170, "W":  162,
+    "Re": 151, "Os": 144, "Ir": 141, "Pt": 136, "Au": 136,
+    "Hg": 132, "Tl": 145, "Pb": 146, "Bi": 148, "Po": 140,
+    "At": 150, "Rn": 150,
+    "Fr": 260, "Ra": 221, "Ac": 215, "Th": 206, "Pa": 200,
+    "U":  196, "Np": 190, "Pu": 187, "Am": 180, "Cm": 169,
+    # Elements 97-118 (Pyykko & Atsumi 2009, estimated for superheavy)
+    "Bk": 168, "Cf": 168, "Es": 165, "Fm": 167, "Md": 173,
+    "No": 176, "Lr": 161, "Rf": 157, "Db": 149, "Sg": 143,
+    "Bh": 141, "Hs": 134, "Mt": 129, "Ds": 128, "Rg": 121,
+    "Cn": 122, "Nh": 136, "Fl": 143, "Mc": 162, "Lv": 175,
+    "Ts": 165, "Og": 157,
+}
+
+# ---------------------------------------------------------------------------
+# CPK colours (hex strings)
+# ---------------------------------------------------------------------------
+CPK_COLORS: dict[str, str] = {
+    "H":  "#FFFFFF",  "He": "#D9FFFF",
+    "Li": "#CC80FF",  "Be": "#C2FF00",  "B":  "#FFB5B5",  "C":  "#909090",
+    "N":  "#3050F8",  "O":  "#FF0D0D",  "F":  "#90E050",  "Ne": "#B3E3F5",
+    "Na": "#AB5CF2",  "Mg": "#8AFF00",  "Al": "#BFA6A6",  "Si": "#F0C8A0",
+    "P":  "#FF8000",  "S":  "#FFFF30",  "Cl": "#1FF01F",  "Ar": "#80D1E3",
+    "K":  "#8F40D4",  "Ca": "#3DFF00",  "Sc": "#E6E6E6",  "Ti": "#BFC2C7",
+    "V":  "#A6A6AB",  "Cr": "#8A99C7",  "Mn": "#9C7AC7",  "Fe": "#E06633",
+    "Co": "#F090A0",  "Ni": "#50D050",  "Cu": "#C88033",  "Zn": "#7D80B0",
+    "Ga": "#C28F8F",  "Ge": "#668F8F",  "As": "#BD80E3",  "Se": "#FFA100",
+    "Br": "#A62929",  "Kr": "#5CB8D1",
+    "Rb": "#702EB0",  "Sr": "#00FF00",  "Y":  "#94FFFF",  "Zr": "#94E0E0",
+    "Nb": "#73C2C9",  "Mo": "#54B5B5",  "Tc": "#3B9E9E",  "Ru": "#248F8F",
+    "Rh": "#0A7D8C",  "Pd": "#006985",  "Ag": "#C0C0C0",  "Cd": "#FFD98F",
+    "In": "#A67573",  "Sn": "#668080",  "Sb": "#9E63B5",  "Te": "#D47A00",
+    "I":  "#940094",  "Xe": "#429EB0",
+    "default": "#FF69B4",
+}
+
+# ---------------------------------------------------------------------------
+# Target electron counts (Lewis structure octet rules)
+# ---------------------------------------------------------------------------
+TARGET_ELECTRONS: dict[str, int] = {
+    "H": 2, "He": 2, "Li": 2, "Be": 4, "B": 6,
+}
+
+
+# ===================================================================
+# Helper functions
+# ===================================================================
+
+def electronegativity(symbol: str) -> float:
+    """Pauling electronegativity.  Returns 0.0 for elements without a value."""
+    val = PAULING_ELECTRONEGATIVITY.get(symbol)
+    return 0.0 if val is None else val
+
+
+def covalent_radius_pm(symbol: str) -> float:
+    """Single-bond covalent radius in picometres.  Fallback: 150 pm."""
+    val = COVALENT_RADII_PM.get(symbol)
+    if val is None:
+        warnings.warn(
+            f"No covalent radius data for '{symbol}'; using 150 pm fallback",
+            stacklevel=2,
+        )
+        return 150.0
+    return val
+
+
+def estimated_bond_length_pm(symbol_a: str, symbol_b: str,
+                              bond_order: int = 1) -> float:
+    """Estimate bond length in picometres from covalent radii.
+
+    Single bond:  r(A) + r(B)
+    Double bond:  ~0.87 * single
+    Triple bond:  ~0.78 * single
+    """
+    single = covalent_radius_pm(symbol_a) + covalent_radius_pm(symbol_b)
+    if bond_order == 2:
+        return single * 0.87
+    elif bond_order == 3:
+        return single * 0.78
+    return single
+
+
+def estimated_bond_length_angstrom(symbol_a: str, symbol_b: str,
+                                    bond_order: int = 1) -> float:
+    """Estimate bond length in Angstroms (pm / 100)."""
+    return estimated_bond_length_pm(symbol_a, symbol_b, bond_order) / 100.0
+
+
+def cpk_color(symbol: str) -> str:
+    """CPK hex colour for an element, with fallback."""
+    return CPK_COLORS.get(symbol, CPK_COLORS["default"])
+
+
+def target_electrons(symbol: str) -> int:
+    """Target electron count for octet/duet rule."""
+    return TARGET_ELECTRONS.get(symbol, 8)
+
+
+def period(symbol: str) -> int:
+    """Period (row) of an element in the periodic table."""
+    z = SYMBOL_TO_Z.get(symbol, 0)
+    if z <= 2:
+        return 1
+    if z <= 10:
+        return 2
+    if z <= 18:
+        return 3
+    if z <= 36:
+        return 4
+    if z <= 54:
+        return 5
+    if z <= 86:
+        return 6
+    return 7
+
+
+def can_expand_octet(symbol: str) -> bool:
+    """Whether an element can have an expanded octet (period 3+)."""
+    return period(symbol) >= 3

molbuilder/core/elements.py

@@ -0,0 +1,181 @@
+"""
+Periodic table element data: symbols, names, atomic weights.
+
+Migrated from bohr_model.py -- the canonical element registry for molbuilder.
+"""
+
+# ---------------------------------------------------------------------------
+# Element data  (atomic_number -> (symbol, name, standard_atomic_weight))
+# ---------------------------------------------------------------------------
+ELEMENTS: dict[int, tuple[str, str, float]] = {
+    1:  ("H",  "Hydrogen",      1.008),
+    2:  ("He", "Helium",        4.003),
+    3:  ("Li", "Lithium",       6.941),
+    4:  ("Be", "Beryllium",     9.012),
+    5:  ("B",  "Boron",        10.811),
+    6:  ("C",  "Carbon",       12.011),
+    7:  ("N",  "Nitrogen",     14.007),
+    8:  ("O",  "Oxygen",       15.999),
+    9:  ("F",  "Fluorine",     18.998),
+    10: ("Ne", "Neon",         20.180),
+    11: ("Na", "Sodium",       22.990),
+    12: ("Mg", "Magnesium",    24.305),
+    13: ("Al", "Aluminium",    26.982),
+    14: ("Si", "Silicon",      28.086),
+    15: ("P",  "Phosphorus",   30.974),
+    16: ("S",  "Sulfur",       32.065),
+    17: ("Cl", "Chlorine",     35.453),
+    18: ("Ar", "Argon",        39.948),
+    19: ("K",  "Potassium",    39.098),
+    20: ("Ca", "Calcium",      40.078),
+    21: ("Sc", "Scandium",     44.956),
+    22: ("Ti", "Titanium",     47.867),
+    23: ("V",  "Vanadium",     50.942),
+    24: ("Cr", "Chromium",     51.996),
+    25: ("Mn", "Manganese",    54.938),
+    26: ("Fe", "Iron",         55.845),
+    27: ("Co", "Cobalt",       58.933),
+    28: ("Ni", "Nickel",       58.693),
+    29: ("Cu", "Copper",       63.546),
+    30: ("Zn", "Zinc",         65.380),
+    31: ("Ga", "Gallium",      69.723),
+    32: ("Ge", "Germanium",    72.630),
+    33: ("As", "Arsenic",      74.922),
+    34: ("Se", "Selenium",     78.971),
+    35: ("Br", "Bromine",      79.904),
+    36: ("Kr", "Krypton",      83.798),
+    37: ("Rb", "Rubidium",     85.468),
+    38: ("Sr", "Strontium",    87.620),
+    39: ("Y",  "Yttrium",      88.906),
+    40: ("Zr", "Zirconium",    91.224),
+    41: ("Nb", "Niobium",      92.906),
+    42: ("Mo", "Molybdenum",   95.950),
+    43: ("Tc", "Technetium",   98.000),
+    44: ("Ru", "Ruthenium",   101.070),
+    45: ("Rh", "Rhodium",     102.906),
+    46: ("Pd", "Palladium",   106.420),
+    47: ("Ag", "Silver",      107.868),
+    48: ("Cd", "Cadmium",     112.414),
+    49: ("In", "Indium",      114.818),
+    50: ("Sn", "Tin",         118.710),
+    51: ("Sb", "Antimony",    121.760),
+    52: ("Te", "Tellurium",   127.600),
+    53: ("I",  "Iodine",      126.904),
+    54: ("Xe", "Xenon",       131.293),
+    55: ("Cs", "Caesium",     132.905),
+    56: ("Ba", "Barium",      137.327),
+    57: ("La", "Lanthanum",   138.905),
+    58: ("Ce", "Cerium",      140.116),
+    59: ("Pr", "Praseodymium",140.908),
+    60: ("Nd", "Neodymium",   144.242),
+    61: ("Pm", "Promethium",  145.000),
+    62: ("Sm", "Samarium",    150.360),
+    63: ("Eu", "Europium",    151.964),
+    64: ("Gd", "Gadolinium",  157.250),
+    65: ("Tb", "Terbium",     158.925),
+    66: ("Dy", "Dysprosium",  162.500),
+    67: ("Ho", "Holmium",     164.930),
+    68: ("Er", "Erbium",      167.259),
+    69: ("Tm", "Thulium",     168.934),
+    70: ("Yb", "Ytterbium",   173.045),
+    71: ("Lu", "Lutetium",    174.967),
+    72: ("Hf", "Hafnium",     178.490),
+    73: ("Ta", "Tantalum",    180.948),
+    74: ("W",  "Tungsten",    183.840),
+    75: ("Re", "Rhenium",     186.207),
+    76: ("Os", "Osmium",      190.230),
+    77: ("Ir", "Iridium",     192.217),
+    78: ("Pt", "Platinum",    195.084),
+    79: ("Au", "Gold",        196.967),
+    80: ("Hg", "Mercury",     200.592),
+    81: ("Tl", "Thallium",    204.383),
+    82: ("Pb", "Lead",        207.200),
+    83: ("Bi", "Bismuth",     208.980),
+    84: ("Po", "Polonium",    209.000),
+    85: ("At", "Astatine",    210.000),
+    86: ("Rn", "Radon",       222.000),
+    87: ("Fr", "Francium",    223.000),
+    88: ("Ra", "Radium",      226.000),
+    89: ("Ac", "Actinium",    227.000),
+    90: ("Th", "Thorium",     232.038),
+    91: ("Pa", "Protactinium",231.036),
+    92: ("U",  "Uranium",     238.029),
+    93: ("Np", "Neptunium",   237.000),
+    94: ("Pu", "Plutonium",   244.000),
+    95: ("Am", "Americium",   243.000),
+    96: ("Cm", "Curium",      247.000),
+    97: ("Bk", "Berkelium",   247.000),
+    98: ("Cf", "Californium", 251.000),
+    99: ("Es", "Einsteinium", 252.000),
+    100:("Fm", "Fermium",     257.000),
+    101:("Md", "Mendelevium", 258.000),
+    102:("No", "Nobelium",    259.000),
+    103:("Lr", "Lawrencium",  266.000),
+    104:("Rf", "Rutherfordium",267.000),
+    105:("Db", "Dubnium",     268.000),
+    106:("Sg", "Seaborgium",  269.000),
+    107:("Bh", "Bohrium",     270.000),
+    108:("Hs", "Hassium",     277.000),
+    109:("Mt", "Meitnerium",  278.000),
+    110:("Ds", "Darmstadtium",281.000),
+    111:("Rg", "Roentgenium", 282.000),
+    112:("Cn", "Copernicium", 285.000),
+    113:("Nh", "Nihonium",    286.000),
+    114:("Fl", "Flerovium",   289.000),
+    115:("Mc", "Moscovium",   290.000),
+    116:("Lv", "Livermorium", 293.000),
+    117:("Ts", "Tennessine",  294.000),
+    118:("Og", "Oganesson",   294.000),
+}
+
+# Reverse lookup: symbol -> atomic number
+SYMBOL_TO_Z: dict[str, int] = {v[0]: k for k, v in ELEMENTS.items()}
+
+# Reverse lookup: lowercase name -> atomic number  (O(1) name lookup)
+_NAME_TO_Z: dict[str, int] = {v[1].lower(): k for k, v in ELEMENTS.items()}
+
+# Noble gas core atomic numbers (for shorthand notation)
+NOBLE_GASES: dict[int, str] = {
+    2: "He", 10: "Ne", 18: "Ar",
+    36: "Kr", 54: "Xe", 86: "Rn",
+    118: "Og",
+}
+
+
+# ---------------------------------------------------------------------------
+# Convenience lookups
+# ---------------------------------------------------------------------------
+
+def from_symbol(symbol: str) -> tuple[int, str, str, float]:
+    """Look up element by symbol.  Returns (Z, symbol, name, weight)."""
+    sym = symbol.strip()
+    if len(sym) > 1:
+        sym = sym[0].upper() + sym[1:].lower()
+    else:
+        sym = sym.upper()
+    z = SYMBOL_TO_Z.get(sym)
+    if z is None:
+        raise ValueError(f"Unknown element symbol: {symbol}")
+    s, name, weight = ELEMENTS[z]
+    return z, s, name, weight
+
+
+def from_name(name: str) -> tuple[int, str, str, float]:
+    """Look up element by name.  Returns (Z, symbol, name, weight).
+
+    Uses a pre-built reverse mapping for O(1) lookup instead of linear scan.
+    """
+    name_lower = name.strip().lower()
+    z = _NAME_TO_Z.get(name_lower)
+    if z is None:
+        raise ValueError(f"Unknown element name: {name}")
+    sym, elem_name, weight = ELEMENTS[z]
+    return z, sym, elem_name, weight
+
+
+def atomic_weight(symbol: str) -> float:
+    """Standard atomic weight for an element symbol."""
+    z = SYMBOL_TO_Z.get(symbol)
+    if z is None:
+        raise ValueError(f"Unknown element: {symbol}")
+    return ELEMENTS[z][2]