hashmol3d 0.5.0__tar.gz

hashmol3d-0.5.0/LICENSE

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

hashmol3d-0.5.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,139 @@
+# 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/pyproject.toml

@@ -0,0 +1,42 @@
+[project]
+name = "hashmol3d"
+version = "0.5.0"
+description = "Deterministic 3D molecular geometry hashing standard"
+authors = [{name = "Murat Keçeli"}]
+readme = "README.md"
+requires-python = ">=3.8"
+dependencies = ["numpy"]
+
+[project.optional-dependencies]
+test = ["pytest"]
+
+[project.scripts]
+hashmol3d = "hashmol3d.cli:main"
+
+[build-system]
+requires = ["setuptools>=61", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+norecursedirs = ["gemini", "xyz", ".venv", ".git", "build", "dist"]
+
+[tool.mypy]
+ignore_missing_imports = true
+
+[tool.ruff]
+line-length = 100
+target-version = "py38"
+extend-exclude = ["gemini", "xyz", "build", "dist"]
+
+[tool.ruff.lint]
+# Pyflakes (F), pycodestyle errors+warnings (E, W), isort (I),
+# pyupgrade (UP), bugbear (B).
+select = ["E", "W", "F", "I", "UP", "B"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/*" = ["E501"]  # tolerate long lines in test fixtures

hashmol3d-0.5.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

hashmol3d-0.5.0/src/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-0.5.0/src/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())