novomd 1.2.0__py3-none-any.whl

novomd/__about__.py

@@ -0,0 +1,3 @@
+"""Single source of truth for the package version."""
+
+__version__ = "1.2.0"

novomd/__init__.py

@@ -0,0 +1,42 @@
+"""NovoMD: a local-first molecular property calculator.
+
+Compute molecular descriptors on your own hardware, no server and no API key::
+
+    from novomd import calculate_properties
+    props = calculate_properties("CCO")
+    print(props["molecular_weight"])
+
+The same core powers the optional REST service (``pip install novomd[server]``).
+"""
+
+from __future__ import annotations
+
+from .__about__ import __version__
+from .batch import MAX_BATCH_SIZE, calculate_properties_batch
+from .conversion import get_atom_type, pdb_to_omd
+from .core import (
+    RDKIT_AVAILABLE,
+    calculate_all_molecular_properties,
+    calculate_partial_charges,
+    calculate_properties,
+    extract_coordinates_from_pdb,
+    smiles_to_pdb,
+)
+from .exceptions import InvalidSMILESError, NovoMDError, RDKitNotAvailableError
+
+__all__ = [
+    "__version__",
+    "RDKIT_AVAILABLE",
+    "calculate_properties",
+    "calculate_properties_batch",
+    "MAX_BATCH_SIZE",
+    "calculate_all_molecular_properties",
+    "calculate_partial_charges",
+    "extract_coordinates_from_pdb",
+    "smiles_to_pdb",
+    "get_atom_type",
+    "pdb_to_omd",
+    "NovoMDError",
+    "InvalidSMILESError",
+    "RDKitNotAvailableError",
+]

novomd/batch.py

@@ -0,0 +1,56 @@
+"""Batch molecular property calculation with per-item error isolation.
+
+Process a list of SMILES in one call. A single malformed or un-embeddable
+molecule never fails the whole batch: each item returns its own status, so a
+1,000-molecule run with a few bad entries still returns every good result.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional, Sequence
+
+from .core import calculate_properties
+
+# Default ceiling on how many molecules one call will process. The REST service
+# enforces the same cap so a single request cannot tie up the worker.
+MAX_BATCH_SIZE = 1000
+
+
+def calculate_properties_batch(
+    smiles_list: Sequence[str],
+    *,
+    add_hydrogens: bool = True,
+    optimize_3d: bool = True,
+    max_batch_size: Optional[int] = MAX_BATCH_SIZE,
+) -> List[Dict[str, Any]]:
+    """Compute descriptors for many SMILES, isolating per-item failures.
+
+    Args:
+        smiles_list: SMILES strings to process.
+        add_hydrogens: Add explicit hydrogens before embedding (default True).
+        optimize_3d: Run UFF geometry optimization on each conformer (default True).
+        max_batch_size: Reject inputs larger than this. Pass ``None`` to disable
+            the check (the caller is then responsible for bounding the work).
+
+    Returns:
+        One result dict per input, in order. Each is either
+        ``{"smiles": ..., "status": "ok", "properties": {...}}`` or
+        ``{"smiles": ..., "status": "error", "error": "<message>"}``.
+
+    Raises:
+        ValueError: The input is larger than ``max_batch_size``.
+    """
+    if max_batch_size is not None and len(smiles_list) > max_batch_size:
+        raise ValueError(f"Batch size {len(smiles_list)} exceeds the maximum of {max_batch_size}.")
+
+    results: List[Dict[str, Any]] = []
+    for smiles in smiles_list:
+        try:
+            properties = calculate_properties(
+                smiles, add_hydrogens=add_hydrogens, optimize_3d=optimize_3d
+            )
+            results.append({"smiles": smiles, "status": "ok", "properties": properties})
+        except Exception as exc:  # noqa: BLE001 - one bad molecule must not kill the batch
+            results.append({"smiles": smiles, "status": "error", "error": str(exc)})
+
+    return results

novomd/cli.py

@@ -0,0 +1,157 @@
+"""Command-line entry point for NovoMD.
+
+- ``novomd props "<smiles>"`` computes descriptors for one molecule.
+- ``novomd batch <file.smi> --out results.csv`` processes many at once.
+"""
+
+from __future__ import annotations
+
+import argparse
+import csv
+import json
+import sys
+from typing import Any, Dict, List, Optional
+
+from .__about__ import __version__
+from .exceptions import NovoMDError
+
+# Property fields that are per-atom lists; omitted from flat CSV output.
+_LIST_FIELDS = {"coords_x", "coords_y", "coords_z", "atom_types", "bonds"}
+
+
+def _cmd_props(args: argparse.Namespace) -> int:
+    from .core import calculate_properties
+
+    try:
+        result = calculate_properties(
+            args.smiles,
+            add_hydrogens=not args.no_hydrogens,
+            optimize_3d=not args.no_optimize,
+        )
+    except NovoMDError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+
+    indent = None if args.compact else 2
+    print(json.dumps(result, indent=indent))
+    return 0
+
+
+def _read_smiles_file(path: str) -> List[str]:
+    """Read a .smi file: one SMILES per line; the first whitespace-separated
+    token is taken as the SMILES. Blank lines and ``#`` comments are skipped."""
+    molecules: List[str] = []
+    with open(path, "r", encoding="utf-8") as handle:
+        for line in handle:
+            stripped = line.strip()
+            if not stripped or stripped.startswith("#"):
+                continue
+            molecules.append(stripped.split()[0])
+    return molecules
+
+
+def _flatten_for_csv(results: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
+    rows: List[Dict[str, Any]] = []
+    for item in results:
+        row: Dict[str, Any] = {
+            "smiles": item["smiles"],
+            "status": item["status"],
+            "error": item.get("error", ""),
+        }
+        for key, value in item.get("properties", {}).items():
+            if key not in _LIST_FIELDS:
+                row[key] = value
+        rows.append(row)
+    return rows
+
+
+def _cmd_batch(args: argparse.Namespace) -> int:
+    from .batch import calculate_properties_batch
+
+    try:
+        molecules = _read_smiles_file(args.input)
+    except OSError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+
+    if not molecules:
+        print(f"error: no SMILES found in {args.input}", file=sys.stderr)
+        return 1
+
+    results = calculate_properties_batch(
+        molecules,
+        add_hydrogens=not args.no_hydrogens,
+        optimize_3d=not args.no_optimize,
+    )
+    succeeded = sum(1 for r in results if r["status"] == "ok")
+    print(
+        f"processed {len(results)} molecules: {succeeded} ok, {len(results) - succeeded} failed",
+        file=sys.stderr,
+    )
+
+    if args.out:
+        if args.out.lower().endswith((".csv", ".tsv")):
+            rows = _flatten_for_csv(results)
+            fieldnames: List[str] = []
+            for row in rows:
+                for key in row:
+                    if key not in fieldnames:
+                        fieldnames.append(key)
+            delimiter = "\t" if args.out.lower().endswith(".tsv") else ","
+            with open(args.out, "w", encoding="utf-8", newline="") as handle:
+                writer = csv.DictWriter(handle, fieldnames=fieldnames, delimiter=delimiter)
+                writer.writeheader()
+                writer.writerows(rows)
+        else:
+            with open(args.out, "w", encoding="utf-8") as handle:
+                json.dump(results, handle, indent=2)
+        print(f"wrote {args.out}", file=sys.stderr)
+    else:
+        print(json.dumps(results, indent=2))
+
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="novomd",
+        description="Local-first molecular property calculator.",
+    )
+    parser.add_argument("--version", action="version", version=f"novomd {__version__}")
+
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    props = subparsers.add_parser("props", help="Compute descriptors for one SMILES string.")
+    props.add_argument("smiles", help="SMILES string, e.g. 'CCO'")
+    props.add_argument("--no-hydrogens", action="store_true", help="Do not add explicit hydrogens.")
+    props.add_argument("--no-optimize", action="store_true", help="Skip 3D geometry optimization.")
+    props.add_argument(
+        "--compact", action="store_true", help="Emit single-line JSON instead of indented."
+    )
+    props.set_defaults(func=_cmd_props)
+
+    batch = subparsers.add_parser(
+        "batch", help="Compute descriptors for many SMILES from a .smi file."
+    )
+    batch.add_argument("input", help="Path to a .smi file (one SMILES per line).")
+    batch.add_argument(
+        "--out",
+        help="Write results to this file (.csv/.tsv for a table, otherwise JSON). "
+        "Without --out, JSON is printed to stdout.",
+    )
+    batch.add_argument("--no-hydrogens", action="store_true", help="Do not add explicit hydrogens.")
+    batch.add_argument("--no-optimize", action="store_true", help="Skip 3D geometry optimization.")
+    batch.set_defaults(func=_cmd_batch)
+
+    return parser
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    exit_code: int = args.func(args)
+    return exit_code
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())

novomd/conversion.py

@@ -0,0 +1,132 @@
+"""PDB to OpenMD (.omd) format conversion.
+
+Framework-free helpers for turning a PDB block into an OpenMD input file and
+mapping elements onto force-field atom types. Used by both the library and the
+REST service.
+"""
+
+from __future__ import annotations
+
+
+def get_atom_type(element: str, force_field: str) -> str:
+    """Map an element symbol to a force-field atom type."""
+
+    force_field_mappings = {
+        "AMBER": {
+            "H": "HC",
+            "C": "CT",
+            "N": "N",
+            "O": "O",
+            "S": "S",
+            "P": "P",
+            "F": "F",
+            "Cl": "Cl",
+            "Br": "Br",
+        },
+        "CHARMM": {
+            "H": "HGA1",
+            "C": "CG321",
+            "N": "NG321",
+            "O": "OG311",
+            "S": "SG311",
+            "P": "PG1",
+            "F": "FGA1",
+            "Cl": "CLGA1",
+            "Br": "BRGA1",
+        },
+        "OPLS": {
+            "H": "opls_140",
+            "C": "opls_135",
+            "N": "opls_238",
+            "O": "opls_236",
+            "S": "opls_200",
+            "P": "opls_393",
+            "F": "opls_164",
+            "Cl": "opls_151",
+            "Br": "opls_156",
+        },
+    }
+
+    mapping = force_field_mappings.get(force_field, force_field_mappings["AMBER"])
+    return mapping.get(element, element)
+
+
+def pdb_to_omd(pdb_content: str, force_field: str, box_size: float, charge_method: str) -> str:
+    """Convert a PDB block to OpenMD (.omd) format."""
+
+    # Parse PDB content to extract atoms
+    atoms = []
+    for line in pdb_content.split("\n"):
+        if line.startswith("ATOM") or line.startswith("HETATM"):
+            atom_info = {
+                "index": int(line[6:11].strip()),
+                "name": line[12:16].strip(),
+                "resname": line[17:20].strip(),
+                "x": float(line[30:38].strip()),
+                "y": float(line[38:46].strip()),
+                "z": float(line[46:54].strip()),
+                "element": line[76:78].strip() if len(line) > 76 else "C",
+            }
+            atoms.append(atom_info)
+
+    if not atoms:
+        raise ValueError("No atoms found in PDB content")
+
+    # Generate OpenMD format content
+    omd_content = """<OpenMD version=2>
+  <MetaData>
+    <molecule id="0">
+      <name>Converted_Molecule</name>"""
+
+    # Add atom definitions
+    for atom in atoms:
+        # Assign atom type based on element and force field
+        atom_type = get_atom_type(str(atom["element"]), force_field)
+        omd_content += f"""
+      <atom id="{atom['index']}">
+        <type>{atom_type}</type>
+        <position x="{atom['x']}" y="{atom['y']}" z="{atom['z']}"/>
+      </atom>"""
+
+    omd_content += f"""
+    </molecule>
+
+    <forceField>{force_field}</forceField>
+    <ensemble>NVT</ensemble>
+    <target_temp>300</target_temp>
+    <target_pressure>1</target_pressure>
+  </MetaData>
+
+  <Snapshot>
+    <FrameData>
+      <Time>0</Time>
+      <Hmat>
+        <Hxx>{box_size}</Hxx>
+        <Hxy>0</Hxy>
+        <Hxz>0</Hxz>
+        <Hyx>0</Hyx>
+        <Hyy>{box_size}</Hyy>
+        <Hyz>0</Hyz>
+        <Hzx>0</Hzx>
+        <Hzy>0</Hzy>
+        <Hzz>{box_size}</Hzz>
+      </Hmat>
+    </FrameData>
+
+    <StuntDoubles>"""
+
+    # Add positions for each atom
+    for atom in atoms:
+        atom_index: int = atom["index"]  # type: ignore[assignment]
+        omd_content += f"""
+      <StuntDouble index="{atom_index - 1}">
+        <position x="{atom['x']}" y="{atom['y']}" z="{atom['z']}"/>
+        <velocity x="0" y="0" z="0"/>
+      </StuntDouble>"""
+
+    omd_content += """
+    </StuntDoubles>
+  </Snapshot>
+</OpenMD>"""
+
+    return omd_content

novomd/core.py

@@ -0,0 +1,289 @@
+"""Framework-free molecular property calculation core.
+
+Everything in this module runs locally with no network calls and no web
+framework. If RDKit is installed, :func:`calculate_properties` turns a SMILES
+string into a full descriptor dictionary on your own hardware.
+
+The numerical routines here are the same ones the REST service uses; the
+service imports from this module rather than redefining them.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Tuple
+
+import numpy as np
+from scipy.spatial.distance import cdist
+
+from .exceptions import InvalidSMILESError, RDKitNotAvailableError
+
+try:
+    from rdkit import Chem
+    from rdkit.Chem import AllChem, Descriptors
+
+    RDKIT_AVAILABLE = True
+except ImportError:  # pragma: no cover - exercised only without RDKit
+    RDKIT_AVAILABLE = False
+
+
+def _require_rdkit() -> None:
+    if not RDKIT_AVAILABLE:
+        raise RDKitNotAvailableError(
+            "RDKit is required for this operation but is not installed. "
+            "Install it with: pip install novomd"
+        )
+
+
+def smiles_to_pdb(smiles: str, optimize_3d: bool = True, add_hydrogens: bool = True) -> str:
+    """Convert a SMILES string to a 3D PDB block using RDKit."""
+    _require_rdkit()
+
+    mol = Chem.MolFromSmiles(smiles)
+    if mol is None:
+        raise InvalidSMILESError(f"Invalid SMILES string: {smiles!r}")
+
+    if add_hydrogens:
+        mol = Chem.AddHs(mol)
+
+    AllChem.EmbedMolecule(mol, randomSeed=42)
+
+    if optimize_3d:
+        AllChem.UFFOptimizeMolecule(mol, maxIters=200)
+
+    pdb_block = Chem.MolToPDBBlock(mol)
+    return str(pdb_block) if pdb_block else ""
+
+
+def calculate_partial_charges(pdb_content: str, method: str = "gasteiger") -> Dict[int, float]:
+    """Estimate per-atom partial charges from PDB content.
+
+    Simplified electronegativity-based model; outcome-level descriptor only.
+    """
+    charges: Dict[int, float] = {}
+    atom_index = 0
+
+    for line in pdb_content.split("\n"):
+        if line.startswith("ATOM") or line.startswith("HETATM"):
+            element = line[76:78].strip() if len(line) > 76 else "C"
+
+            electronegativities = {
+                "H": 2.20,
+                "C": 2.55,
+                "N": 3.04,
+                "O": 3.44,
+                "F": 3.98,
+                "S": 2.58,
+                "Cl": 3.16,
+                "Br": 2.96,
+            }
+
+            en = electronegativities.get(element, 2.5)
+            charge = (en - 2.5) * 0.1
+
+            charges[atom_index] = round(charge, 4)
+            atom_index += 1
+
+    return charges
+
+
+def extract_coordinates_from_pdb(pdb_content: str) -> Tuple[np.ndarray, List[str]]:
+    """Extract 3D coordinates and element symbols from PDB content."""
+    coords: List[List[float]] = []
+    atoms: List[str] = []
+
+    for line in pdb_content.split("\n"):
+        if line.startswith("ATOM") or line.startswith("HETATM"):
+            try:
+                x = float(line[30:38].strip())
+                y = float(line[38:46].strip())
+                z = float(line[46:54].strip())
+                element = line[76:78].strip() if len(line) > 76 else "C"
+
+                coords.append([x, y, z])
+                atoms.append(element)
+            except (ValueError, IndexError):
+                continue
+
+    return np.array(coords), atoms
+
+
+def calculate_all_molecular_properties(
+    coords: np.ndarray, atoms: List[str], mol: Any, pdb_content: str
+) -> Dict[str, Any]:
+    """Calculate the full descriptor set from 3D coordinates.
+
+    Returns geometry, energy estimate, electrostatic, surface/volume, atom-count
+    and 3D-visualization descriptors. Returns an empty dict for empty input.
+    """
+
+    if len(coords) == 0:
+        return {}
+
+    # Center of mass
+    center = np.mean(coords, axis=0)
+    centered_coords = coords - center
+
+    # === GEOMETRY PROPERTIES (7) ===
+
+    # Radius of gyration
+    rgyr = np.sqrt(np.mean(np.sum(centered_coords**2, axis=1)))
+
+    # Maximum distance (span)
+    distances = cdist(coords, coords)
+    max_dist = np.max(distances)
+
+    # Inertia tensor for shape analysis (I is the conventional physics symbol)
+    I = np.zeros((3, 3))  # noqa: E741
+    for coord in centered_coords:
+        I[0, 0] += coord[1] ** 2 + coord[2] ** 2
+        I[1, 1] += coord[0] ** 2 + coord[2] ** 2
+        I[2, 2] += coord[0] ** 2 + coord[1] ** 2
+        I[0, 1] -= coord[0] * coord[1]
+        I[0, 2] -= coord[0] * coord[2]
+        I[1, 2] -= coord[1] * coord[2]
+    I[1, 0] = I[0, 1]
+    I[2, 0] = I[0, 2]
+    I[2, 1] = I[1, 2]
+
+    # Principal moments of inertia
+    eigenvalues = np.sort(np.linalg.eigvals(I).real)
+    pmi1, pmi2, pmi3 = eigenvalues
+
+    # Shape descriptors
+    asphericity = pmi3 - 0.5 * (pmi1 + pmi2)
+    eccentricity = (pmi3 - pmi1) / pmi3 if pmi3 > 0 else 0
+    inertia_shape_factor = pmi1 / pmi3 if pmi3 > 0 else 0
+
+    # === SURFACE/VOLUME PROPERTIES (4) ===
+
+    num_atoms = len(atoms)
+    num_heavy = sum(1 for a in atoms if a not in ["H", "h"])
+
+    # Estimate molecular volume and surface area
+    hull_volume = num_atoms * 15.0  # ų per atom
+    hull_area = num_atoms * 30.0  # Ų per atom
+    globularity = (
+        min(1.0, (36 * np.pi * hull_volume**2) ** (1 / 3) / hull_area) if hull_area > 0 else 0
+    )
+    surface_to_volume = hull_area / hull_volume if hull_volume > 0 else 0
+
+    # === ENERGY PROPERTIES (6) ===
+    # These are estimates - real MD would provide actual values
+
+    # Bond detection
+    bonds = []
+    for i in range(len(coords)):
+        for j in range(i + 1, len(coords)):
+            if distances[i, j] < 1.6:  # Typical bond length
+                bonds.append([int(i), int(j)])
+
+    conformer_energy = -10.0 * num_atoms
+    vdw_energy = -0.5 * len(bonds)
+    electrostatic_energy = -0.1 * num_atoms
+    torsion_strain = 0.1 * max(0, len(bonds) - num_atoms + 1)
+    angle_strain = 0.05 * num_atoms
+    optimization_delta = abs(conformer_energy) * 0.1
+
+    # === ELECTROSTATIC PROPERTIES (6) ===
+
+    dipole_moment = np.linalg.norm(center) * 0.1
+    total_charge = 0.0  # Neutral
+
+    # Calculate partial charges
+    charges = calculate_partial_charges(pdb_content, "gasteiger")
+    if charges:
+        charge_values = list(charges.values())
+        max_partial_charge = max(charge_values)
+        min_partial_charge = min(charge_values)
+        charge_span = max_partial_charge - min_partial_charge
+        total_charge = sum(charge_values)
+    else:
+        max_partial_charge = 0.5
+        min_partial_charge = -0.5
+        charge_span = 1.0
+
+    electrostatic_potential = dipole_moment * 0.1
+
+    # Return all descriptors
+    return {
+        # Geometry (7)
+        "radius_of_gyration": round(float(rgyr), 3),
+        "asphericity": round(float(asphericity), 3),
+        "eccentricity": round(float(eccentricity), 3),
+        "inertia_shape_factor": round(float(inertia_shape_factor), 3),
+        "span_r": round(float(max_dist), 3),
+        "pmi1": round(float(pmi1), 3),
+        "pmi2": round(float(pmi2), 3),
+        # Energy (6)
+        "conformer_energy": round(float(conformer_energy), 2),
+        "vdw_energy": round(float(vdw_energy), 2),
+        "electrostatic_energy": round(float(electrostatic_energy), 2),
+        "torsion_strain": round(float(torsion_strain), 2),
+        "angle_strain": round(float(angle_strain), 2),
+        "optimization_delta": round(float(optimization_delta), 2),
+        # Electrostatics (6)
+        "dipole_moment": round(float(dipole_moment), 3),
+        "total_charge": round(float(total_charge), 3),
+        "max_partial_charge": round(float(max_partial_charge), 3),
+        "min_partial_charge": round(float(min_partial_charge), 3),
+        "charge_span": round(float(charge_span), 3),
+        "electrostatic_potential": round(float(electrostatic_potential), 3),
+        # Surface/Volume (4)
+        "sasa": round(float(hull_area), 1),
+        "molecular_volume": round(float(hull_volume), 1),
+        "globularity": round(float(globularity), 3),
+        "surface_to_volume_ratio": round(float(surface_to_volume), 3),
+        # Atom counts (2)
+        "num_atoms_with_h": int(num_atoms),
+        "num_heavy_atoms": int(num_heavy),
+        # Visualization (5+)
+        "coords_x": [round(float(c[0]), 4) for c in coords],
+        "coords_y": [round(float(c[1]), 4) for c in coords],
+        "coords_z": [round(float(c[2]), 4) for c in coords],
+        "atom_types": atoms,
+        "bonds": bonds,
+    }
+
+
+def calculate_properties(
+    smiles: str, *, add_hydrogens: bool = True, optimize_3d: bool = True
+) -> Dict[str, Any]:
+    """Compute the full molecular descriptor set for a SMILES string, locally.
+
+    Parses the SMILES, embeds a 3D conformer, and returns a flat dictionary of
+    identity metadata (molecular weight, atom/bond counts) plus the geometry,
+    energy, electrostatic, surface/volume and visualization descriptors. No
+    network access, no API key, no server.
+
+    Args:
+        smiles: The molecule as a SMILES string (e.g. ``"CCO"``).
+        add_hydrogens: Add explicit hydrogens before embedding (default True).
+        optimize_3d: Run UFF geometry optimization on the conformer (default True).
+
+    Returns:
+        A descriptor dictionary keyed by property name.
+
+    Raises:
+        RDKitNotAvailableError: RDKit is not installed.
+        InvalidSMILESError: The SMILES string could not be parsed.
+    """
+    _require_rdkit()
+
+    mol = Chem.MolFromSmiles(smiles)
+    if mol is None:
+        raise InvalidSMILESError(f"Invalid SMILES string: {smiles!r}")
+
+    if add_hydrogens:
+        mol = Chem.AddHs(mol)
+
+    pdb_content = smiles_to_pdb(smiles, optimize_3d=optimize_3d, add_hydrogens=add_hydrogens)
+    coords, atoms = extract_coordinates_from_pdb(pdb_content)
+    properties = calculate_all_molecular_properties(coords, atoms, mol, pdb_content)
+
+    return {
+        "smiles": smiles,
+        "num_atoms": mol.GetNumAtoms(),
+        "num_bonds": mol.GetNumBonds(),
+        "molecular_weight": round(Descriptors.MolWt(mol), 2),
+        **properties,
+    }

novomd/exceptions.py

@@ -0,0 +1,20 @@
+"""Exception types raised by the NovoMD core.
+
+These are plain Python exceptions with no web-framework coupling, so the core
+can be imported and used as a library without FastAPI installed. The REST
+service translates them into HTTP responses at the endpoint boundary.
+"""
+
+from __future__ import annotations
+
+
+class NovoMDError(Exception):
+    """Base class for all NovoMD errors."""
+
+
+class InvalidSMILESError(NovoMDError, ValueError):
+    """Raised when a SMILES string cannot be parsed into a molecule."""
+
+
+class RDKitNotAvailableError(NovoMDError, RuntimeError):
+    """Raised when an operation needs RDKit but it is not installed."""

novomd-1.2.0.dist-info/METADATA

@@ -0,0 +1,311 @@
+Metadata-Version: 2.4
+Name: novomd
+Version: 1.2.0
+Summary: Local-first molecular property calculator. Compute descriptors from SMILES with no server and no API key.
+Author: NovoMCP
+License: MIT
+Project-URL: Homepage, https://github.com/realariharrison/NovoMD
+Project-URL: Documentation, https://github.com/realariharrison/NovoMD#readme
+Project-URL: Repository, https://github.com/realariharrison/NovoMD.git
+Project-URL: Issues, https://github.com/realariharrison/NovoMD/issues
+Keywords: molecular-dynamics,computational-chemistry,cheminformatics,molecular-descriptors,smiles,openmd,rdkit,local-first
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Chemistry
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Classifier: Framework :: FastAPI
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy<2.0.0,>=1.24.0
+Requires-Dist: scipy>=1.11.0
+Requires-Dist: rdkit>=2023.3.1
+Provides-Extra: server
+Requires-Dist: fastapi>=0.104.0; extra == "server"
+Requires-Dist: uvicorn[standard]>=0.24.0; extra == "server"
+Requires-Dist: pydantic>=2.5.0; extra == "server"
+Requires-Dist: pydantic-settings>=2.1.0; extra == "server"
+Requires-Dist: python-dotenv>=1.0.0; extra == "server"
+Requires-Dist: slowapi>=0.1.9; extra == "server"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.4.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Requires-Dist: httpx>=0.25.0; extra == "dev"
+Requires-Dist: flake8>=6.1.0; extra == "dev"
+Requires-Dist: black>=23.9.0; extra == "dev"
+Requires-Dist: isort>=5.12.0; extra == "dev"
+Requires-Dist: mypy>=1.5.0; extra == "dev"
+Requires-Dist: bandit>=1.7.0; extra == "dev"
+Requires-Dist: safety>=2.3.0; extra == "dev"
+Requires-Dist: pre-commit>=3.4.0; extra == "dev"
+Dynamic: license-file
+
+<div align="center">
+
+<img src="docs/novomd-card.png" alt="NovoMD: local-first molecular property calculation" width="820" />
+
+# NovoMD
+
+**local-first molecular property calculation**
+
+[![CI](https://github.com/realariharrison/NovoMD/actions/workflows/ci.yml/badge.svg)](https://github.com/realariharrison/NovoMD/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-B8704B.svg)](LICENSE)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-2D2A26.svg)](https://www.python.org/downloads/)
+
+</div>
+
+NovoMD turns a SMILES string into a set of molecular descriptors. It runs on your own machine, with no account and no API key. Install it as a Python library, call it from the command line, or run it as a REST service.
+
+## What it is, and what it is not
+
+NovoMD computes 32+ outcome-level descriptors from a 3D conformer: geometry, an energy estimate, electrostatics, surface and volume, atom counts, and the coordinates for visualization. The calculation is local and deterministic.
+
+It does not run full molecular dynamics trajectories, docking, binding affinity, or ADMET. The scope is deliberate. For that work, see [Beyond property calculation](#beyond-property-calculation) below.
+
+## Quick start
+
+### Python library
+
+The shortest path. No server, no key.
+
+```bash
+pip install novomd
+```
+
+```python
+from novomd import calculate_properties
+
+props = calculate_properties("CCO")
+print(props["molecular_weight"])     # 46.07
+print(props["radius_of_gyration"])
+```
+
+Process a list in one call. A bad SMILES does not stop the batch; each item carries its own status.
+
+```python
+from novomd import calculate_properties_batch
+
+results = calculate_properties_batch(["CCO", "CC(=O)O", "NOT_VALID"])
+for item in results:
+    if item["status"] == "ok":
+        print(item["smiles"], item["properties"]["molecular_weight"])
+    else:
+        print(item["smiles"], "->", item["error"])
+```
+
+RDKit, NumPy, and SciPy install automatically. Everything runs on your hardware.
+
+### Command line
+
+```bash
+novomd props "CCO"
+novomd props "CC(=O)OC1=CC=CC=C1C(=O)O" --compact
+novomd batch molecules.smi --out results.csv
+```
+
+`batch` reads a `.smi` file (one SMILES per line) and writes a CSV, TSV, or JSON table.
+
+### From an AI assistant (MCP)
+
+NovoMD exposes a [Model Context Protocol](https://modelcontextprotocol.io/) endpoint, so assistants like Claude can query molecular properties directly.
+
+**Endpoint:** `https://quantnexusai-novomd.hf.space/gradio_api/mcp/sse`
+
+Add it as a custom connector in Claude (Settings, then Integrations), or point any MCP-compatible client at the same URL. Then ask:
+
+- "Calculate the molecular properties of aspirin (CC(=O)OC1=CC=CC=C1C(=O)O)."
+- "What is the dipole moment of caffeine?"
+
+The endpoint works with Claude (web and desktop), Cursor, Continue.dev, and any client that speaks the [MCP specification](https://modelcontextprotocol.io/).
+
+### REST service (Docker)
+
+For networked or containerized use, run the same core behind FastAPI.
+
+```bash
+# pre-built image
+docker run -d -p 8010:8010 \
+  -e NOVOMD_API_KEY="your-secure-api-key" \
+  --name novomd \
+  ghcr.io/realariharrison/novomd:latest
+
+curl http://localhost:8010/health
+```
+
+Or from source:
+
+```bash
+pip install "novomd[server]"
+uvicorn main:app --host 0.0.0.0 --port 8010
+```
+
+## What you get
+
+32+ descriptors, calculated from an embedded 3D structure:
+
+- **Geometry** (7): radius of gyration, asphericity, eccentricity, inertia shape factor, span, principal moments of inertia
+- **Energy** (6): conformer energy, van der Waals, electrostatic, torsion strain, angle strain, optimization delta
+- **Electrostatics** (6): dipole moment, total charge, max and min partial charge, charge span, electrostatic potential
+- **Surface and volume** (4): SASA, molecular volume, globularity, surface-to-volume ratio
+- **Atom counts** (2): total atoms, heavy atoms
+- **Visualization** (5+): full atomic coordinates, atom types, bond connectivity
+
+Energy values are estimates from the conformer, not from a force-field simulation. The descriptors are derived from real 3D coordinates, not mocked.
+
+## Library reference
+
+```python
+from novomd import calculate_properties, calculate_properties_batch
+
+# one molecule -> descriptor dict
+calculate_properties("CCO", add_hydrogens=True, optimize_3d=True)
+
+# many molecules -> list of {smiles, status, properties | error}
+calculate_properties_batch(["CCO", "C"], max_batch_size=1000)
+```
+
+Both raise `InvalidSMILESError` for unparseable input and `RDKitNotAvailableError` if RDKit is missing. The batch function isolates per-item failures instead of raising.
+
+## REST API
+
+All endpoints except `/health` require an API key in the `X-API-Key` header.
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/health` | GET | Health check (no auth) |
+| `/status` | GET | Service status and capabilities |
+| `/smiles-to-omd` | POST | Convert SMILES to OpenMD with 32+ properties |
+| `/batch` | POST | Calculate properties for many SMILES in one call |
+| `/atom2md` | POST | Convert PDB to OpenMD format |
+| `/force-fields` | GET | List available force fields |
+| `/force-field-types/{ff}` | GET | Atom types for a force field |
+
+```bash
+curl -X POST http://localhost:8010/batch \
+  -H "Content-Type: application/json" \
+  -H "X-API-Key: your-api-key" \
+  -d '{"molecules": ["CCO", "CC(=O)O", "NOT_VALID"]}'
+```
+
+```json
+{
+  "count": 3,
+  "succeeded": 2,
+  "failed": 1,
+  "results": [
+    {"smiles": "CCO", "status": "ok", "properties": {"molecular_weight": 46.07, "...": "..."}},
+    {"smiles": "CC(=O)O", "status": "ok", "properties": {"...": "..."}},
+    {"smiles": "NOT_VALID", "status": "error", "error": "Invalid SMILES string: 'NOT_VALID'"}
+  ]
+}
+```
+
+Batches are capped at 1,000 molecules per request and share the service rate limit.
+
+### Notebooks
+
+| Notebook | Topic |
+|----------|-------|
+| [01_getting_started.ipynb](examples/01_getting_started.ipynb) | Basic usage and conversion |
+| [02_molecular_properties.ipynb](examples/02_molecular_properties.ipynb) | Property analysis with pandas and matplotlib |
+| [03_visualization.ipynb](examples/03_visualization.ipynb) | 3D visualization with plotly and py3Dmol |
+| [04_batch_processing.ipynb](examples/04_batch_processing.ipynb) | One-call batch, library and endpoint |
+
+## Beyond property calculation
+
+NovoMD computes molecular descriptors locally. It does not run full MD trajectories, docking, ADMET, or compliance.
+
+For those, the same team builds NovoMCP, a computational engine for AI-native discovery: 122M enriched compounds, docking and FEP pipelines, ADMET and compliance scoring, and an immutable audit trail on every step. NovoMD is open and always will be. NovoMCP is the production layer for work that outgrows it.
+
+Learn more: [novomcp.com](https://novomcp.com)
+
+## Force fields
+
+`AMBER14`, `AMBER99SB`, `CHARMM36`, `OPLS-AA/M`, `GROMOS 54A7`. Property values are conformer-derived and force-field-independent; the force field affects only the OpenMD output.
+
+## Configuration
+
+Set these in a `.env` file or as environment variables (REST service only).
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `NOVOMD_API_KEY` | API authentication key (required) | - |
+| `PORT` | Server port | 8010 |
+| `HOST` | Server host | 0.0.0.0 |
+| `LOG_LEVEL` | DEBUG, INFO, WARNING, ERROR | INFO |
+| `CORS_ORIGINS` | Comma-separated origins, or "*" for all | localhost:3000,localhost:8080 |
+| `RATE_LIMIT` | e.g. "100/minute", "1000/hour" | 100/minute |
+
+## Development
+
+```bash
+pip install -e ".[dev,server]"   # core + server + dev tools
+pre-commit install
+
+pytest tests/ -v
+pytest tests/ --cov=novomd --cov=main --cov-report=term-missing
+
+black . && isort . && flake8 .
+mypy novomd main.py auth.py config.py
+bandit -r . -x ./tests
+```
+
+```
+NovoMD/
+├── novomd/              # importable library (framework-free core)
+│   ├── core.py          # property calculation
+│   ├── batch.py         # batch with per-item error isolation
+│   ├── conversion.py    # PDB to OpenMD
+│   ├── cli.py           # `novomd` command
+│   └── exceptions.py
+├── main.py              # FastAPI service (imports the core)
+├── config.py            # configuration
+├── auth.py              # API-key authentication
+├── tests/               # unit + integration tests
+├── examples/            # Jupyter notebooks
+└── .github/workflows/   # CI and PyPI publish
+```
+
+## Security
+
+NovoMD runs locally by default; no molecular data leaves your machine. For the REST service, use a strong `NOVOMD_API_KEY`, deploy behind TLS, and restrict `CORS_ORIGINS`. To report a vulnerability, see [SECURITY.md](SECURITY.md).
+
+## Contributing
+
+Contributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+- **Issues**: [GitHub Issues](https://github.com/realariharrison/NovoMD/issues)
+- **Discussions**: [GitHub Discussions](https://github.com/realariharrison/NovoMD/discussions)
+
+## License
+
+MIT. See [LICENSE](LICENSE).
+
+Built with [FastAPI](https://fastapi.tiangolo.com/) and [RDKit](https://www.rdkit.org/).
+
+## Citation
+
+```bibtex
+@software{novomd2025,
+  title = {NovoMD: Local-First Molecular Property Calculation},
+  author = {NovoMCP},
+  year = {2025},
+  url = {https://github.com/realariharrison/NovoMD}
+}
+```
+
+---
+
+<div align="center">
+
+Built by the NovoMCP team
+
+</div>

novomd-1.2.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+novomd/__about__.py,sha256=Wec8Imu4VTzXc_61Gus-tyToJZaRGWtgUupGymMEtR8,77
+novomd/__init__.py,sha256=Uy4esheEsjAyw9B2ZG4S2a9bwzX-4WUWM9QUFwOQ-xo,1188
+novomd/batch.py,sha256=OFt9X9HXE3FusO2cRkrj0hjO8aW-a6BJC-bcLpHQ4P8,2255
+novomd/cli.py,sha256=WJx7_CZgHjDqKRjFEw4EmAsqLkCN_160-4O3Yrqu7vY,5371
+novomd/conversion.py,sha256=k8R2035Vwi1Dsmq-ohFbRn6XWEBK-POYmmI33o1-fsk,3634
+novomd/core.py,sha256=i52f3F9yo_IEhv27DSLWJUCsRD923_AiNt6kjTiqW-Y,9995
+novomd/exceptions.py,sha256=G4klJsZ0OANnRx1WFldmhBxpfjRxh9GPM9fxZHI5D84,641
+novomd-1.2.0.dist-info/licenses/LICENSE,sha256=LIuaWTSa_1KTax1i2aAlZLPGJTD6GhqvvWfyUHTW0Bo,1070
+novomd-1.2.0.dist-info/METADATA,sha256=PYryS4Eo9UJ3XzKENha5C99Kflz-eM6sowfHylNtChY,11658
+novomd-1.2.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+novomd-1.2.0.dist-info/entry_points.txt,sha256=jlSgQig2R_tvCK-KZDUww4hZIv1927VSbY6OSoRi8oY,43
+novomd-1.2.0.dist-info/top_level.txt,sha256=RsP5EuTC6UYgf9TegjXZdYmvNdMKEwXS92L648zCW5A,7
+novomd-1.2.0.dist-info/RECORD,,

novomd-1.2.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
+

novomd-1.2.0.dist-info/entry_points.txt

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

novomd-1.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 QuantNexus AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

novomd-1.2.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+novomd