hashmol3d 0.5.0__py3-none-any.whl

hashmol3d/__init__.py

@@ -0,0 +1,32 @@
+"""HashMol3D: deterministic 3D molecular geometry hashing."""
+
+from .core import (
+    DESCRIPTOR_VERSION,
+    HashMol3DResult,
+    generate_hashmol3d,
+    hash_molecule,
+)
+from .io import read_xyz
+from .version import __version__
+
+
+def hash_xyz(path, **kwargs) -> HashMol3DResult:
+    """Read an XYZ file and hash its geometry.
+
+    Convenience wrapper combining :func:`read_xyz` and
+    :func:`hash_molecule`. Any keyword arguments are forwarded to
+    :func:`hash_molecule`.
+    """
+    atomic_nums, coords = read_xyz(path)
+    return hash_molecule(atomic_nums, coords, **kwargs)
+
+
+__all__ = [
+    "DESCRIPTOR_VERSION",
+    "HashMol3DResult",
+    "__version__",
+    "generate_hashmol3d",
+    "hash_molecule",
+    "hash_xyz",
+    "read_xyz",
+]

hashmol3d/cli.py

@@ -0,0 +1,109 @@
+"""Command-line interface for HashMol3D."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from typing import Sequence
+
+from .core import hash_molecule
+from .io import read_xyz
+from .version import __version__
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="hashmol3d",
+        description=(
+            "Deterministic 3D molecular geometry hash. "
+            "Reads an XYZ file and prints the HashMol3D identifier."
+        ),
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"hashmol3d {__version__}",
+    )
+    parser.add_argument("file", help="Path to a molecular geometry file (.xyz)")
+    parser.add_argument(
+        "-p",
+        "--precision",
+        type=float,
+        default=1e-4,
+        metavar="Å",
+        help="Distance precision in angstroms (default: 1e-4)",
+    )
+    parser.add_argument(
+        "-c",
+        "--charge",
+        type=int,
+        default=0,
+        help="Total formal charge (default: 0)",
+    )
+    parser.add_argument(
+        "-m",
+        "--multiplicity",
+        type=int,
+        default=None,
+        help="Spin multiplicity (default: inferred from electron count)",
+    )
+    parser.add_argument(
+        "-l",
+        "--length",
+        type=int,
+        default=None,
+        help="Number of hex characters in the geometry hash, 1-64 "
+        "(default: auto-scaled as clip(N, 16, 64))",
+    )
+    parser.add_argument(
+        "-v",
+        "--verbose",
+        action="store_true",
+        help="Also print the canonical descriptor and metadata",
+    )
+    return parser
+
+
+def cli(argv: Sequence[str] | None = None) -> int:
+    """Run the HashMol3D CLI.
+
+    Returns the process exit code. ``argv`` may be passed for testing;
+    if omitted, ``sys.argv[1:]`` is used.
+    """
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+
+    try:
+        atomic_nums, coords = read_xyz(args.file)
+        result = hash_molecule(
+            atomic_nums,
+            coords,
+            precision=args.precision,
+            charge=args.charge,
+            multiplicity=args.multiplicity,
+            length=args.length,
+        )
+    except FileNotFoundError as err:
+        print(f"hashmol3d: {err}", file=sys.stderr)
+        return 1
+    except (ValueError, OSError) as err:
+        print(f"hashmol3d: {err}", file=sys.stderr)
+        return 1
+
+    if args.verbose:
+        print(f"identifier:    {result.hash_str}")
+        print(f"formula:       {result.formula}")
+        print(f"geometry_hash: {result.geometry_hash}")
+        print(f"descriptor:    {result.descriptor}")
+        print(f"version:       {result.version}")
+        print(f"precision:     {result.precision}")
+        print(f"charge:        {result.charge}")
+        print(f"multiplicity:  {result.multiplicity}")
+    else:
+        print(result.hash_str)
+    return 0
+
+
+def main() -> None:
+    """Entry point used by the ``hashmol3d`` console script."""
+    sys.exit(cli())

hashmol3d/core.py

@@ -0,0 +1,293 @@
+"""
+HashMol3D core: a deterministic identifier for 3D molecular conformers.
+
+The identifier has the form::
+
+    <Hill formula><state tag>-<geometry hash>
+
+For example, ``H2Oq0m1-a1b28135...`` for neutral singlet water.
+
+The trailing hexadecimal hash is invariant under exactly the operations
+that leave the non-relativistic molecular Hamiltonian's eigenvalues
+unchanged:
+
+  * rigid translation of the coordinates
+  * rigid rotation of the coordinates
+  * permutation (relabeling) of atom indices
+  * spatial inversion / reflection (parity)
+
+It depends on atomic numbers, pairwise distances (rounded to a user
+specified precision), and the descriptor version. Total charge and
+spin multiplicity are encoded in the readable prefix, not inside the
+hash, so changing charge or multiplicity only changes the prefix.
+
+The implementation has no RDKit dependency; it uses only NumPy and the
+Python standard library.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import warnings
+from collections import Counter
+from dataclasses import dataclass
+
+import numpy as np
+
+from .periodic_table import get_symbol
+
+__all__ = [
+    "DESCRIPTOR_VERSION",
+    "HashMol3DResult",
+    "generate_hashmol3d",
+    "hash_molecule",
+]
+
+
+# The descriptor version is part of the hashed payload. Bump it whenever
+# the descriptor format changes in a way that would alter hashes.
+DESCRIPTOR_VERSION = "4-GEOM-SHA256"
+
+# Auto-scaled hash length. The number of distinguishable conformers grows
+# (roughly) exponentially with N, so log2 of it grows linearly with N;
+# growing the hash length linearly with N keeps birthday-collision risk
+# constant. 16 hex chars (64 bits) is the floor for very small molecules;
+# SHA-256 caps us at 64 hex chars (256 bits).
+_MIN_LENGTH = 16
+_MAX_LENGTH = 64
+
+
+@dataclass(frozen=True)
+class HashMol3DResult:
+    """The result of hashing a molecular geometry."""
+
+    hash_str: str
+    formula: str
+    geometry_hash: str
+    version: str
+    precision: float
+    charge: int
+    multiplicity: int
+    descriptor: str
+
+    def __str__(self) -> str:
+        return self.hash_str
+
+
+def _precision_to_decimals(precision: float) -> int:
+    """Number of decimal places implied by a distance precision in Å."""
+    if not np.isfinite(precision) or precision <= 0:
+        raise ValueError(f"precision must be a positive finite number, got {precision!r}")
+    return int(max(0, round(-np.log10(precision))))
+
+
+def _infer_multiplicity(atomic_nums: np.ndarray, charge: int, multiplicity: int | None) -> int:
+    """Use the caller-supplied multiplicity, or infer one from electron count."""
+    if multiplicity is not None:
+        m = int(multiplicity)
+        if m < 1:
+            raise ValueError(f"multiplicity must be >= 1, got {m}")
+        return m
+    electrons = int(np.sum(atomic_nums)) - int(charge)
+    return 1 if electrons % 2 == 0 else 2
+
+
+def _hill_formula(atomic_nums: np.ndarray) -> str:
+    """Render the molecular formula in Hill order.
+
+    Carbon first (if present), then hydrogen (if present), then the
+    remaining elements alphabetically by symbol. A count of 1 is
+    omitted (e.g. ``H2O``, ``CHBrClF``).
+    """
+    counts: Counter = Counter(int(z) for z in atomic_nums)
+
+    ordered: list[tuple[str, int]] = []
+    if 6 in counts:
+        ordered.append(("C", counts.pop(6)))
+        if 1 in counts:
+            ordered.append(("H", counts.pop(1)))
+    rest = sorted(((get_symbol(z), n) for z, n in counts.items()), key=lambda x: x[0])
+    ordered.extend(rest)
+
+    return "".join(sym if n == 1 else f"{sym}{n}" for sym, n in ordered)
+
+
+def _state_tag(charge: int, multiplicity: int) -> str:
+    """Render the readable charge/multiplicity suffix, e.g. ``q1m2``.
+
+    Positive and zero charges are written without a sign (``q0``, ``q1``);
+    only negative charges carry a leading ``-`` (``q-1``).
+    """
+    return f"q{charge}m{multiplicity}"
+
+
+def _auto_length(n_atoms: int) -> int:
+    """Default hash length in hex chars, scaling linearly with N."""
+    return max(_MIN_LENGTH, min(_MAX_LENGTH, n_atoms))
+
+
+def _pair_signature(
+    atomic_nums: np.ndarray, coords: np.ndarray, decimals: int
+) -> tuple[tuple[int, ...], list[tuple[int, int, float]]]:
+    """Build the permutation-invariant fingerprint of the geometry.
+
+    Returns ``(z_sorted, pairs)`` where ``z_sorted`` is a sorted tuple of
+    atomic numbers and ``pairs`` is a sorted list of
+    ``(Z_min, Z_max, rounded_distance)`` triples over every unordered pair
+    of atoms. Both objects are invariant under any relabeling of atoms
+    (multisets) and under any rigid motion or reflection (functions only
+    of Z and pairwise distances).
+    """
+    n = atomic_nums.shape[0]
+    z_sorted = tuple(sorted(int(z) for z in atomic_nums))
+
+    if n < 2:
+        return z_sorted, []
+
+    diff = coords[:, None, :] - coords[None, :, :]
+    dmat = np.linalg.norm(diff, axis=-1)
+    iu, ju = np.triu_indices(n, k=1)
+    dvals = np.round(dmat[iu, ju], decimals=decimals)
+
+    z_i = atomic_nums[iu].astype(int)
+    z_j = atomic_nums[ju].astype(int)
+    za = np.minimum(z_i, z_j)
+    zb = np.maximum(z_i, z_j)
+
+    pairs = [(int(a), int(b), float(d)) for a, b, d in zip(za, zb, dvals)]
+    pairs.sort()
+    return z_sorted, pairs
+
+
+def _format_descriptor(
+    version: str,
+    precision: float,
+    decimals: int,
+    z_sorted: tuple[int, ...],
+    pairs: list[tuple[int, int, float]],
+) -> str:
+    """Render the canonical descriptor string that is fed to SHA-256.
+
+    Charge and multiplicity are *not* included: they are part of the
+    readable prefix of the final identifier, not of the hashed payload.
+    """
+    prec_str = f"{precision:.1e}"
+    z_part = ",".join(str(z) for z in z_sorted)
+    fmt = f"{{:.{decimals}f}}"
+    d_part = ",".join(f"{a}-{b}:{fmt.format(d)}" for a, b, d in pairs)
+    return "|".join(
+        [
+            "V:" + version,
+            "P:" + prec_str,
+            "Z:" + z_part,
+            "D:" + d_part,
+        ]
+    )
+
+
+def hash_molecule(
+    atomic_nums,
+    coords,
+    *,
+    precision: float = 1e-4,
+    charge: int = 0,
+    multiplicity: int | None = None,
+    length: int | None = None,
+) -> HashMol3DResult:
+    """Compute the HashMol3D identifier for a 3D molecular geometry.
+
+    The identifier has the form ``<Hill formula><state tag>-<geom hash>``,
+    e.g. ``H2Oq0m1-a1b28135...``. Charge and multiplicity appear in the
+    readable prefix; only the geometry contributes to the hash.
+
+    Args:
+        atomic_nums: integer array-like of atomic numbers, shape ``(N,)``.
+        coords: float array-like of Cartesian coordinates in Å, shape
+            ``(N, 3)``.
+        precision: distance precision in Å (default ``1e-4``).
+        charge: total formal charge (default ``0``).
+        multiplicity: spin multiplicity (``1`` = singlet, ``2`` = doublet,
+            ...). If ``None``, inferred as singlet/doublet from the
+            electron count.
+        length: number of hex characters retained from the SHA-256 digest.
+            Must be in ``[1, 64]``. If ``None`` (default), scales with the
+            number of atoms as ``clip(N, 16, 64)`` so collision risk stays
+            roughly constant as molecules grow.
+
+    Returns:
+        :class:`HashMol3DResult`.
+    """
+    atomic_nums = np.asarray(atomic_nums, dtype=int).reshape(-1)
+    coords = np.asarray(coords, dtype=float)
+
+    if atomic_nums.size == 0:
+        raise ValueError("molecule must contain at least one atom")
+    if coords.ndim != 2 or coords.shape[1] != 3:
+        raise ValueError(f"coords must have shape (N, 3); got {coords.shape}")
+    if coords.shape[0] != atomic_nums.size:
+        raise ValueError(
+            f"atomic_nums has {atomic_nums.size} entries but coords has {coords.shape[0]} rows"
+        )
+    if not np.all(atomic_nums > 0):
+        raise ValueError("atomic numbers must be positive integers")
+    if not np.all(np.isfinite(coords)):
+        raise ValueError("coords contain non-finite values")
+
+    if length is None:
+        length = _auto_length(int(atomic_nums.size))
+    elif not isinstance(length, int) or not (1 <= length <= 64):
+        raise ValueError("length must be an int in [1, 64]")
+
+    charge = int(charge)
+    decimals = _precision_to_decimals(precision)
+    used_mult = _infer_multiplicity(atomic_nums, charge, multiplicity)
+
+    z_sorted, pairs = _pair_signature(atomic_nums, coords, decimals)
+    descriptor = _format_descriptor(DESCRIPTOR_VERSION, precision, decimals, z_sorted, pairs)
+    digest = hashlib.sha256(descriptor.encode("utf-8")).hexdigest()[:length]
+
+    formula = _hill_formula(atomic_nums)
+    identifier = f"{formula}{_state_tag(charge, used_mult)}-{digest}"
+
+    return HashMol3DResult(
+        hash_str=identifier,
+        formula=formula,
+        geometry_hash=digest,
+        version=DESCRIPTOR_VERSION,
+        precision=precision,
+        charge=charge,
+        multiplicity=used_mult,
+        descriptor=descriptor,
+    )
+
+
+def generate_hashmol3d(
+    atomic_nums,
+    coords,
+    precision: float = 1e-4,
+    charge: int = 0,
+    multiplicity: int | None = None,
+    hash_length: int = 32,
+) -> HashMol3DResult:
+    """Deprecated alias for :func:`hash_molecule`.
+
+    .. deprecated:: 0.4.0
+        Use :func:`hash_molecule` instead. The ``hash_length`` keyword is
+        renamed to ``length`` in the new function. Note that as of 0.5.0
+        the returned ``hash_str`` is the full readable identifier
+        (``<formula><state>-<hash>``), not just the hex digest.
+    """
+    warnings.warn(
+        "generate_hashmol3d() is deprecated; use hash_molecule() instead "
+        "(the hash_length kwarg is now called length).",
+        DeprecationWarning,
+        stacklevel=2,
+    )
+    return hash_molecule(
+        atomic_nums,
+        coords,
+        precision=precision,
+        charge=charge,
+        multiplicity=multiplicity,
+        length=hash_length,
+    )

hashmol3d/io.py

@@ -0,0 +1,80 @@
+"""File I/O helpers for HashMol3D."""
+
+from __future__ import annotations
+
+import numpy as np
+
+from .periodic_table import get_atomic_num
+
+__all__ = ["read_xyz"]
+
+
+def read_xyz(path: str) -> tuple[np.ndarray, np.ndarray]:
+    """Read a standard XYZ file.
+
+    The first line must contain the atom count; the second line is a
+    free-form comment; subsequent lines contain ``symbol x y z`` (or
+    ``Z x y z``).
+
+    Args:
+        path: Path to the XYZ file.
+
+    Returns:
+        ``(atomic_nums, coords)`` as NumPy arrays.
+
+    Raises:
+        ValueError: if the file is malformed (bad atom count, missing or
+            extra atom lines, unknown element symbol, non-numeric coords).
+    """
+    with open(path) as f:
+        lines = f.readlines()
+
+    if len(lines) < 2:
+        raise ValueError("XYZ file is too short (need at least 2 header lines)")
+
+    try:
+        n_declared = int(lines[0].strip())
+    except ValueError as err:
+        raise ValueError(
+            f"first line of an XYZ file must be the atom count; got {lines[0].strip()!r}"
+        ) from err
+    if n_declared <= 0:
+        raise ValueError(f"XYZ atom count must be positive, got {n_declared}")
+
+    z_list = []
+    coords_list = []
+    for raw in lines[2:]:
+        line = raw.strip()
+        if not line:
+            continue
+        parts = line.split()
+        if len(parts) < 4:
+            raise ValueError(f"malformed XYZ atom line: {line!r}")
+
+        sym = parts[0]
+        if sym.lstrip("-").isdigit():
+            z = int(sym)
+            if z <= 0 or z > 118:
+                raise ValueError(f"atomic number out of range: {z}")
+        else:
+            z = get_atomic_num(sym)
+            if z == 0:
+                raise ValueError(f"unknown element symbol: {sym!r}")
+
+        try:
+            xyz = [float(parts[1]), float(parts[2]), float(parts[3])]
+        except ValueError as err:
+            raise ValueError(f"malformed coordinates in XYZ line: {line!r}") from err
+
+        z_list.append(z)
+        coords_list.append(xyz)
+        if len(z_list) == n_declared:
+            break
+
+    if len(z_list) != n_declared:
+        raise ValueError(
+            f"XYZ header declares {n_declared} atoms but only "
+            f"{len(z_list)} valid atom lines were found"
+        )
+
+    return np.array(z_list, dtype=int), np.array(coords_list, dtype=float)

hashmol3d/periodic_table.py

@@ -0,0 +1,169 @@
+"""Periodic table data and utilities for atomic number lookup.
+
+Element symbols are stored in their canonical mixed-case form
+(``"H"``, ``"He"``, ``"Co"``, ...) so that ``Co`` (cobalt) and ``CO``
+(carbon + oxygen, which is not a single element) can be told apart.
+
+``get_atomic_num`` accepts any case (``"co"``, ``"CO"``, ``"Co"``) and
+normalizes to the canonical capitalization before lookup.
+"""
+
+from typing import Dict
+
+# Symbol -> atomic number, using canonical capitalization.
+PTABLE: Dict[str, int] = {
+    "H": 1,
+    "He": 2,
+    "Li": 3,
+    "Be": 4,
+    "B": 5,
+    "C": 6,
+    "N": 7,
+    "O": 8,
+    "F": 9,
+    "Ne": 10,
+    "Na": 11,
+    "Mg": 12,
+    "Al": 13,
+    "Si": 14,
+    "P": 15,
+    "S": 16,
+    "Cl": 17,
+    "Ar": 18,
+    "K": 19,
+    "Ca": 20,
+    "Sc": 21,
+    "Ti": 22,
+    "V": 23,
+    "Cr": 24,
+    "Mn": 25,
+    "Fe": 26,
+    "Co": 27,
+    "Ni": 28,
+    "Cu": 29,
+    "Zn": 30,
+    "Ga": 31,
+    "Ge": 32,
+    "As": 33,
+    "Se": 34,
+    "Br": 35,
+    "Kr": 36,
+    "Rb": 37,
+    "Sr": 38,
+    "Y": 39,
+    "Zr": 40,
+    "Nb": 41,
+    "Mo": 42,
+    "Tc": 43,
+    "Ru": 44,
+    "Rh": 45,
+    "Pd": 46,
+    "Ag": 47,
+    "Cd": 48,
+    "In": 49,
+    "Sn": 50,
+    "Sb": 51,
+    "Te": 52,
+    "I": 53,
+    "Xe": 54,
+    "Cs": 55,
+    "Ba": 56,
+    "La": 57,
+    "Ce": 58,
+    "Pr": 59,
+    "Nd": 60,
+    "Pm": 61,
+    "Sm": 62,
+    "Eu": 63,
+    "Gd": 64,
+    "Tb": 65,
+    "Dy": 66,
+    "Ho": 67,
+    "Er": 68,
+    "Tm": 69,
+    "Yb": 70,
+    "Lu": 71,
+    "Hf": 72,
+    "Ta": 73,
+    "W": 74,
+    "Re": 75,
+    "Os": 76,
+    "Ir": 77,
+    "Pt": 78,
+    "Au": 79,
+    "Hg": 80,
+    "Tl": 81,
+    "Pb": 82,
+    "Bi": 83,
+    "Po": 84,
+    "At": 85,
+    "Rn": 86,
+    "Fr": 87,
+    "Ra": 88,
+    "Ac": 89,
+    "Th": 90,
+    "Pa": 91,
+    "U": 92,
+    "Np": 93,
+    "Pu": 94,
+    "Am": 95,
+    "Cm": 96,
+    "Bk": 97,
+    "Cf": 98,
+    "Es": 99,
+    "Fm": 100,
+    "Md": 101,
+    "No": 102,
+    "Lr": 103,
+    "Rf": 104,
+    "Db": 105,
+    "Sg": 106,
+    "Bh": 107,
+    "Hs": 108,
+    "Mt": 109,
+    "Ds": 110,
+    "Rg": 111,
+    "Cn": 112,
+    "Nh": 113,
+    "Fl": 114,
+    "Mc": 115,
+    "Lv": 116,
+    "Ts": 117,
+    "Og": 118,
+}
+
+
+# Atomic number -> canonical symbol (inverse of PTABLE).
+SYMBOL_BY_Z: Dict[int, str] = {z: s for s, z in PTABLE.items()}
+
+
+def get_symbol(atomic_num: int) -> str:
+    """Get the canonical element symbol for an atomic number.
+
+    Raises:
+        KeyError: if ``atomic_num`` is not in ``[1, 118]``.
+    """
+    return SYMBOL_BY_Z[int(atomic_num)]
+
+
+def _canonicalize_symbol(symbol: str) -> str:
+    """Normalize an element symbol to canonical capitalization."""
+    s = symbol.strip()
+    if not s:
+        return s
+    if len(s) == 1:
+        return s.upper()
+    return s[0].upper() + s[1:].lower()
+
+
+def get_atomic_num(symbol: str) -> int:
+    """
+    Get atomic number from element symbol.
+
+    Args:
+        symbol: Element symbol; capitalization is normalized.
+
+    Returns:
+        Atomic number, or 0 if the symbol is not recognized.
+    """
+    return PTABLE.get(_canonicalize_symbol(symbol), 0)

hashmol3d/version.py

@@ -0,0 +1,3 @@
+"""Version information for HashMol3D."""
+
+__version__ = "0.5.0"

hashmol3d-0.5.0.dist-info/METADATA

@@ -0,0 +1,152 @@
+Metadata-Version: 2.4
+Name: hashmol3d
+Version: 0.5.0
+Summary: Deterministic 3D molecular geometry hashing standard
+Author: Murat Keçeli
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Dynamic: license-file
+
+# HashMol3D
+
+**HashMol3D** is a standard, deterministic 3D molecular geometry identifier
+for computational chemistry, machine learning, and HPC workflows.
+
+It produces a **readable** identifier of the form
+
+    <Hill formula><state tag>-<geometry hash>
+
+e.g. `H2Oq0m1-68936c504bf5fa3b` for neutral singlet water. The trailing
+geometry hash is **rotation-, translation-, permutation-, and
+parity-invariant** (matching the invariances of the eigenvalues of the
+non-relativistic molecular Hamiltonian), and depends on:
+
+- atomic numbers
+- pairwise distances rounded to a user-specified precision
+- a descriptor version tag
+
+Charge and spin multiplicity live in the readable prefix, **not** in
+the hash, so two states of the same geometry share the same hex tail
+and can be grouped by suffix matching:
+
+```text
+H2Oq0m1-68936c504bf5fa3b     # neutral singlet water
+H2Oq1m2-68936c504bf5fa3b     # water cation, same geometry → same hex tail
+```
+
+The hash length auto-scales with the number of atoms (`clip(N, 16, 64)`
+hex chars) so collision risk stays roughly constant as molecules grow;
+pass `length=` to pin a fixed value.
+
+It deliberately does **not** distinguish enantiomers (which share their
+Hamiltonian eigenvalues). The reference implementation depends only on
+NumPy.
+
+HashMol3D IDs are **stable across machines**, **reproducible**, and ideal for:
+- workflow deduplication  
+- caching  
+- large QC datasets  
+- MD conformer tracking  
+- ML potential datasets  
+- LLM scientific agents  
+
+## Install
+
+### Using pip
+
+```bash
+pip install hashmol3d
+```
+
+### Using uv
+
+```bash
+# Install from PyPI
+uv pip install hashmol3d
+```
+
+### Install from source
+
+```bash
+# Clone the repository
+git clone https://github.com/yourusername/HashMol3D.git
+cd HashMol3D
+
+# Create and activate a virtual environment (recommended)
+# Using uv:
+uv venv
+source .venv/bin/activate  # On Windows: .venv\Scripts\activate
+
+# Or using standard Python:
+python -m venv .venv
+source .venv/bin/activate  # On Windows: .venv\Scripts\activate
+
+# Install the package in editable mode
+uv pip install -e .  # Or: pip install -e .
+```
+
+## Usage (CLI)
+
+```bash
+$ hashmol3d water.xyz
+H2Oq0m1-68936c504bf5fa3b
+
+# Cation with explicit multiplicity — only the prefix changes.
+$ hashmol3d -c 1 -m 2 water.xyz
+H2Oq1m2-68936c504bf5fa3b
+
+# Pin a fixed hash length and a coarser precision.
+$ hashmol3d -p 1e-3 -l 32 benzene.xyz
+
+# Verbose: also print formula, geometry hash, descriptor, and metadata.
+$ hashmol3d -v water.xyz
+
+# Show the package version.
+$ hashmol3d --version
+```
+
+Short flags: `-p/--precision`, `-c/--charge`, `-m/--multiplicity`,
+`-l/--length`, `-v/--verbose`. Errors on missing or malformed input go
+to stderr with exit code 1 (no Python traceback).
+
+## Usage (Python)
+
+```python
+import numpy as np
+from hashmol3d import hash_molecule
+
+atomic_nums = np.array([8, 1, 1])
+coords = np.array([
+    [ 0.0000, 0.0000, 0.0],
+    [ 0.7572, 0.5860, 0.0],
+    [-0.7572, 0.5860, 0.0],
+])
+res = hash_molecule(atomic_nums, coords)
+print(res.hash_str)        # H2Oq0m1-68936c504bf5fa3b
+print(res.formula)         # H2O
+print(res.geometry_hash)   # 68936c504bf5fa3b
+print(res.charge, res.multiplicity)  # 0 1
+```
+
+All optional arguments are keyword-only: `precision`, `charge`,
+`multiplicity`, `length`.
+
+Or read straight from a file:
+
+```python
+from hashmol3d import hash_xyz
+
+print(hash_xyz("water.xyz").hash_str)        # H2Oq0m1-68936c504bf5fa3b
+print(hash_xyz("water.xyz", charge=1, multiplicity=2).hash_str)
+# H2Oq1m2-68936c504bf5fa3b
+```
+
+See [`docs/`](docs/) for the full
+[specification](docs/specification.md),
+[API reference](docs/api_reference.md), and
+[CLI guide](docs/cli_usage.md).
+

hashmol3d-0.5.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+hashmol3d/__init__.py,sha256=p7-ZEIqORy-Ag48OH7I_q5yLN2avJLmB_hISa7l-tMc,746
+hashmol3d/cli.py,sha256=sHBz5ehATwvrv7x-iJACh6tX1Y4pMGjFagjGfR6bXPE,3021
+hashmol3d/core.py,sha256=Ni0sWPBPw9IOGh_EZSiqo5DuppN9BFwQ-IZ3bMny6nc,9852
+hashmol3d/io.py,sha256=HtN0EuDBQADqNGQxqxanZ6Old2BvV2_j3mpHlOBybO4,2349
+hashmol3d/periodic_table.py,sha256=7K8fZ-6m-oVzIcrDxaOfGhx5bT19qc_9tgZ3wDU06MM,3066
+hashmol3d/version.py,sha256=vjyKlU95LK1slAc40jPFhbpCONJ-peuFyEHdOGuTbYA,64
+hashmol3d-0.5.0.dist-info/licenses/LICENSE,sha256=KYkSY4pbu9rhIRi9_q7SuwZcRrrKUqV6iiSUNKyujiU,23
+hashmol3d-0.5.0.dist-info/METADATA,sha256=i7Ff13vFq8WfKpuhDKCuStMMaAEzWPHFHg10L7q7aaA,3982
+hashmol3d-0.5.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+hashmol3d-0.5.0.dist-info/entry_points.txt,sha256=j1uNhM8Nqdk1TAN1fS9oDSMUrw6weW83_18BqMwr_9w,49
+hashmol3d-0.5.0.dist-info/top_level.txt,sha256=tTvyNJglebM26-3e-0bBBMF-GuXdkKTEa0grZX6UF6I,10
+hashmol3d-0.5.0.dist-info/RECORD,,

hashmol3d-0.5.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

hashmol3d-0.5.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+hashmol3d = hashmol3d.cli:main

hashmol3d-0.5.0.dist-info/licenses/LICENSE

@@ -0,0 +1,3 @@
+MIT License
+
+Copyright.

hashmol3d-0.5.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+hashmol3d