adsorb-screen 0.1.0__tar.gz

adsorb_screen-0.1.0/PKG-INFO

@@ -0,0 +1,41 @@
+Metadata-Version: 2.4
+Name: adsorb-screen
+Version: 0.1.0
+Summary: General-purpose AdsorbML screening of molecules and radicals on catalytic surfaces with FAIRChem / UMA.
+Author-email: Raghavendra Meena <raghavendra.ip2020@gmail.com>
+License-Expression: MIT
+Keywords: catalysis,adsorption,machine-learning-potentials,fairchem,DFT,VASP,ASE
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: numpy>=1.23
+Requires-Dist: pandas>=1.5
+Requires-Dist: ase>=3.22
+Requires-Dist: fairchem-core>=2.0.0
+Requires-Dist: fairchem-data-oc>=0.1.0
+Provides-Extra: smiles
+Requires-Dist: rdkit>=2023.3.1; extra == "smiles"
+Provides-Extra: mp
+Requires-Dist: mp-api>=0.39.0; extra == "mp"
+Requires-Dist: pymatgen>=2023.10.0; extra == "mp"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: ruff>=0.3.0; extra == "dev"
+
+# adsorb-screen
+
+Automated, general-purpose **AdsorbML** configuration screening of molecules, radicals, and atoms on **any catalytic surface** using FAIRChem v2 / UMA and VASP input generation.
+
+## Key Features
+- **Any Adsorbate**: Screen built-in radicals (`CH2I2`, `CH2I`, `CH2`, `CH2OO`), any single atom (`H`, `O`, `N`, `I`, `Pt`), any molecule in the ASE G2 database (`CO`, `CO2`, `NH3`, `CH3OH`, `H2O`, `C2H4`), SMILES strings (`smiles:CC(=O)O`), or custom structure files (`.xyz`, `POSCAR`, `.sdf`).
+- **Any Catalytic Surface**: Provide your own slab (`--slab-file`), cleave any bulk crystal file (`--bulk my_oxide.cif --millers 1 1 0`), use built-in oxide presets (`alpha-quartz`, `rutile-TiO2`, `MgO`), use any ASE metal/crystal (`--bulk Pt --millers 1 1 1`), or fetch directly from the Materials Project (`--bulk mp-126 --millers 1 1 1`).
+- **Symmetry-Aware Binding Modes**: Automatically identifies symmetry-unique monodentate and bidentate binding sites and orients lone pairs/radical lobes toward the surface (`down`), pi-systems parallel to the surface (`flat`), or bidentate bridges (`pair`).
+- **Anomaly Filtering & VASP Export**: Rejects dissociated, desorbed, intercalated, or reconstructed trajectories and exports ready-to-run VASP directories (`POSCAR`, `INCAR`, `KPOINTS`, `POTCAR_ORDER`) with open-shell `MAGMOM`/`NUPDOWN` and metallic/insulator smearing.
+
+## Installation
+
+```bash
+pip install -e .
+# Optional extras for SMILES and Materials Project support:
+pip install -e ".[smiles,mp,dev]"
+huggingface-cli login
+```

adsorb_screen-0.1.0/README.md

@@ -0,0 +1,18 @@
+# adsorb-screen
+
+Automated, general-purpose **AdsorbML** configuration screening of molecules, radicals, and atoms on **any catalytic surface** using FAIRChem v2 / UMA and VASP input generation.
+
+## Key Features
+- **Any Adsorbate**: Screen built-in radicals (`CH2I2`, `CH2I`, `CH2`, `CH2OO`), any single atom (`H`, `O`, `N`, `I`, `Pt`), any molecule in the ASE G2 database (`CO`, `CO2`, `NH3`, `CH3OH`, `H2O`, `C2H4`), SMILES strings (`smiles:CC(=O)O`), or custom structure files (`.xyz`, `POSCAR`, `.sdf`).
+- **Any Catalytic Surface**: Provide your own slab (`--slab-file`), cleave any bulk crystal file (`--bulk my_oxide.cif --millers 1 1 0`), use built-in oxide presets (`alpha-quartz`, `rutile-TiO2`, `MgO`), use any ASE metal/crystal (`--bulk Pt --millers 1 1 1`), or fetch directly from the Materials Project (`--bulk mp-126 --millers 1 1 1`).
+- **Symmetry-Aware Binding Modes**: Automatically identifies symmetry-unique monodentate and bidentate binding sites and orients lone pairs/radical lobes toward the surface (`down`), pi-systems parallel to the surface (`flat`), or bidentate bridges (`pair`).
+- **Anomaly Filtering & VASP Export**: Rejects dissociated, desorbed, intercalated, or reconstructed trajectories and exports ready-to-run VASP directories (`POSCAR`, `INCAR`, `KPOINTS`, `POTCAR_ORDER`) with open-shell `MAGMOM`/`NUPDOWN` and metallic/insulator smearing.
+
+## Installation
+
+```bash
+pip install -e .
+# Optional extras for SMILES and Materials Project support:
+pip install -e ".[smiles,mp,dev]"
+huggingface-cli login
+```

adsorb_screen-0.1.0/pyproject.toml

@@ -0,0 +1,33 @@
+[build-system]
+requires = ["setuptools>=65.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "adsorb-screen"
+version = "0.1.0"
+description = "General-purpose AdsorbML screening of molecules and radicals on catalytic surfaces with FAIRChem / UMA."
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+authors = [
+    { name = "Raghavendra Meena", email = "raghavendra.ip2020@gmail.com" }
+]
+keywords = ["catalysis", "adsorption", "machine-learning-potentials", "fairchem", "DFT", "VASP", "ASE"]
+dependencies = [
+    "numpy>=1.23",
+    "pandas>=1.5",
+    "ase>=3.22",
+    "fairchem-core>=2.0.0",
+    "fairchem-data-oc>=0.1.0",
+]
+
+[project.optional-dependencies]
+smiles = ["rdkit>=2023.3.1"]
+mp = ["mp-api>=0.39.0", "pymatgen>=2023.10.0"]
+dev = ["pytest>=7.0", "ruff>=0.3.0"]
+
+[project.scripts]
+adsorb-screen = "adsorb_screen.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]

adsorb_screen-0.1.0/setup.cfg

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

adsorb_screen-0.1.0/src/adsorb_screen/__init__.py

@@ -0,0 +1,3 @@
+"""General-purpose AdsorbML screening on catalytic surfaces."""
+
+__version__ = "0.1.0"

adsorb_screen-0.1.0/src/adsorb_screen/cli.py

@@ -0,0 +1,393 @@
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+import random
+import warnings
+
+import numpy as np
+import pandas as pd
+from ase.io import write
+from fairchem.data.oc.core import Adsorbate, Slab
+from fairchem.data.oc.core.multi_adsorbate_slab_config import MultipleAdsorbateSlabConfig
+
+from .modes import binding_modes, describe_modes, orient_for_binding
+from .molecules import BUILTIN_MOLECULES, build_dimer, load_molecule
+from .relax import (
+    OPTIMIZERS,
+    find_anomalies,
+    get_calculator,
+    make_relax_job,
+    min_ads_slab_distance,
+    relax_gas_molecule,
+)
+from .slab import BUILTIN_BULKS, load_bulk_atoms, slab_from_bulk, slab_from_file
+from .vasp import INCAR_GAS, INCAR_SLAB, write_vasp_dir
+
+warnings.filterwarnings("ignore", category=UserWarning)
+
+
+def parse_args() -> argparse.Namespace:
+    p = argparse.ArgumentParser(
+        prog="adsorb-screen",
+        description="General-purpose AdsorbML screening of molecules, radicals, and atoms on any catalytic surface.",
+        formatter_class=argparse.ArgumentDefaultsHelpFormatter,
+    )
+
+    g_mol = p.add_argument_group("Adsorbates (Molecules / Radicals / Atoms)")
+    g_mol.add_argument(
+        "--molecules",
+        nargs="+",
+        default=["CH2I2"],
+        help="Built-ins, element symbols (O, H, I), ASE G2 names (CO, NH3, CH3OH), 'smiles:...', or structure files.",
+    )
+    g_mol.add_argument(
+        "--unpaired",
+        type=int,
+        default=None,
+        help="Override number of unpaired electrons for open-shell molecules.",
+    )
+    g_mol.add_argument(
+        "--no-bidentate",
+        dest="bidentate",
+        action="store_false",
+        help="Disable automatic bidentate pair binding modes.",
+    )
+    g_mol.add_argument(
+        "--include-h-modes",
+        action="store_true",
+        help="Include H atoms when generating monodentate binding modes.",
+    )
+    g_mol.add_argument(
+        "--modes",
+        nargs="+",
+        default=None,
+        help="Filter specific binding mode names (e.g., I1 C0 I1-I2).",
+    )
+    g_mol.add_argument(
+        "--atom-reference",
+        default="half_dimer",
+        choices=["half_dimer", "atom"],
+        help="Gas-phase reference for single-atom adsorbates: 1/2 E(X2) or free atom.",
+    )
+    g_mol.add_argument(
+        "--list-modes",
+        action="store_true",
+        help="Inspect generated binding modes and exit without running ML relaxations.",
+    )
+
+    g_slab = p.add_argument_group("Catalytic Surface / Slab")
+    g_slab.add_argument(
+        "--slab-file",
+        default=None,
+        help="Path to a pre-built surface slab (POSCAR, CIF, xyz).",
+    )
+    g_slab.add_argument(
+        "--bulk",
+        default="alpha-quartz",
+        help=f"Bulk crystal when --slab-file is omitted: preset ({', '.join(BUILTIN_BULKS)}), "
+             f"element/formula (Pt, Cu, Au, TiO2), MP-ID (mp-126), or bulk crystal file.",
+    )
+    g_slab.add_argument("--crystalstructure", default=None, help="ASE crystalstructure (fcc, bcc, hcp, rocksalt, etc.).")
+    g_slab.add_argument("--lattice-a", type=float, default=None, help="Custom lattice constant 'a' (A) for ASE bulk.")
+    g_slab.add_argument("--lattice-c", type=float, default=None, help="Custom lattice constant 'c' (A) for ASE bulk.")
+    g_slab.add_argument("--millers", type=int, nargs=3, default=[0, 0, 1], help="Miller indices (h k l) for bulk cleaving.")
+    g_slab.add_argument("--termination", type=int, default=None, help="Slab termination index (default: lowest broken bonds).")
+    g_slab.add_argument("--min-ab", type=float, default=8.0, help="Minimum lateral slab dimension (A) when cleaving bulk.")
+    g_slab.add_argument("--surface-depth", type=float, default=2.5, help="Top depth (A) tagged as surface for --slab-file.")
+    g_slab.add_argument("--fixed-depth", type=float, default=6.0, help="Bottom depth (A) frozen as bulk (0 = no fixed atoms).")
+    g_slab.add_argument("--metallic", action="store_true", help="Write metallic smearing (ISMEAR=1, SIGMA=0.2) in VASP INCARs.")
+
+    g_ads = p.add_argument_group("AdsorbML Sampling & Relaxation")
+    g_ads.add_argument("--num-placements", type=int, default=50, help="Number of placements per binding mode.")
+    g_ads.add_argument("--steps", type=int, default=300, help="Maximum optimizer steps per placement.")
+    g_ads.add_argument("--fmax", type=float, default=0.02, help="Force convergence criterion (eV/A).")
+    g_ads.add_argument("--optimizer", default="LBFGS", choices=list(OPTIMIZERS), help="ASE geometry optimizer.")
+    g_ads.add_argument("--desorb-dist", type=float, default=4.5, help="Max min(adsorbate-slab) distance (A) before flagging desorption.")
+    g_ads.add_argument(
+        "--placement-mode",
+        default="random_site_heuristic_placement",
+        choices=["random_site_heuristic_placement", "heuristic", "random"],
+    )
+    g_ads.add_argument(
+        "--place-on-unrelaxed-slab",
+        action="store_true",
+        help="Place adsorbates on the unrelaxed input slab instead of the ML-relaxed clean slab.",
+    )
+    g_ads.add_argument("--save-trajectories", action="store_true", help="Save .traj files for all relaxations.")
+    g_ads.add_argument("--seed", type=int, default=0, help="Random seed for reproducible placements.")
+
+    g_ml = p.add_argument_group("MLIP Model")
+    g_ml.add_argument("--model", default="uma-s-1p2p1", help="FAIRChem / UMA checkpoint name.")
+    g_ml.add_argument("--task", default="oc25", choices=["oc25", "oc20", "omat", "omol", "odac", "omc"])
+    g_ml.add_argument("--device", default=None, choices=["cpu", "cuda"])
+
+    g_out = p.add_argument_group("Output")
+    g_out.add_argument("--outdir", default="adsorbml_results", help="Root output directory.")
+    g_out.add_argument("--top-k", type=int, default=5, help="Number of top candidates to export to VASP/traj.")
+    g_out.add_argument("--no-vasp", action="store_true", help="Skip generating VASP input directories.")
+
+    return p.parse_args()
+
+
+def run_molecule(
+    name: str,
+    mol,
+    unpaired: int,
+    args: argparse.Namespace,
+    outdir: Path,
+    calc,
+    relax,
+    place_slab: Slab,
+    relaxed_slab,
+    e_slab: float,
+) -> dict | None:
+    mol_dir = outdir / name
+    mol_dir.mkdir(parents=True, exist_ok=True)
+    print(f"\n################ {name} ({mol.get_chemical_formula()}) ################")
+
+    # 1. Relax in gas phase FIRST so binding modes use relaxed bond lengths/angles
+    gas_boxed, e_gas = relax_gas_molecule(mol, calc)
+    write(str(mol_dir / f"{name}_gas_relaxed.xyz"), gas_boxed)
+    print(f"E({name}, gas) = {e_gas:.4f} eV")
+
+    mol_relaxed = gas_boxed.copy()
+    mol_relaxed.set_cell(None)
+    mol_relaxed.pbc = False
+
+    # 2. Compute symmetry-unique binding modes on the relaxed gas geometry
+    modes = binding_modes(
+        mol_relaxed, bidentate=args.bidentate, include_h=args.include_h_modes
+    )
+    if args.modes:
+        modes = {k: v for k, v in modes.items() if k in args.modes}
+    describe_modes(name, mol_relaxed, modes)
+    if not modes:
+        print(f"  No matching binding modes for {name}; skipping.")
+        return None
+
+    # 3. Determine gas-phase reference energy
+    single_atom = len(mol_relaxed) == 1
+    e_ref, ref_label, dimer = e_gas, f"{name}(g)", None
+    if single_atom:
+        sym = mol_relaxed[0].symbol
+        dimer_init = build_dimer(sym)
+        dimer, e_dimer = relax_gas_molecule(dimer_init, calc)
+        write(str(mol_dir / f"{sym}2_gas_relaxed.xyz"), dimer)
+        print(
+            f"E({sym}2, gas) = {e_dimer:.4f} eV (bond {dimer.get_distance(0, 1):.3f} A); "
+            f"1/2 E({sym}2) - E({sym}) = {e_dimer / 2 - e_gas:.3f} eV"
+        )
+        if args.atom_reference == "half_dimer":
+            e_ref, ref_label = e_dimer / 2.0, f"1/2 {sym}2(g)"
+    elif unpaired > 0:
+        print(
+            f"  NOTE: {name} is open-shell ({unpaired} unpaired e-); non-spin-polarized MLIPs "
+            f"carry extra reference uncertainty."
+        )
+    print(f"Reference for E_ads: {ref_label}")
+
+    def extra_col(r: dict) -> dict:
+        return {"E_ads_vs_free_atom_eV": r["E_ads_vs_gas"]} if single_atom and e_ref != e_gas else {}
+
+    candidates, rows = [], []
+    for mname, idx in modes.items():
+        oriented, how = orient_for_binding(mol_relaxed, idx)
+        print(f"\n=== {name} mode {mname} [{how}]: {args.num_placements} placements ===")
+        ads = Adsorbate(adsorbate_atoms=oriented, adsorbate_binding_indices=idx)
+        configs = MultipleAdsorbateSlabConfig(
+            place_slab,
+            [ads],
+            num_configurations=args.num_placements,
+            mode=args.placement_mode,
+        ).atoms_list
+
+        n_valid, kinds = 0, {}
+        for k, init in enumerate(configs):
+            res = relax(init, f"{name} {mname} #{k + 1}")
+            anomalies = find_anomalies(init, res["atoms"], relaxed_slab, args.desorb_dist)
+            res.update(
+                mode=mname,
+                E_ads=res["energy"] - e_slab - e_ref,
+                E_ads_vs_gas=res["energy"] - e_slab - e_gas,
+                anomalies=anomalies,
+                min_dist=min_ads_slab_distance(res["atoms"]),
+            )
+            rows.append(
+                {
+                    "mode": mname,
+                    "E_ads_eV": res["E_ads"],
+                    **extra_col(res),
+                    "E_adslab_eV": res["energy"],
+                    "converged": res["converged"],
+                    "min_ads_slab_dist_A": res["min_dist"],
+                    "anomalies": ",".join(anomalies) or "none",
+                }
+            )
+            for a in anomalies:
+                kinds[a] = kinds.get(a, 0) + 1
+            if not anomalies:
+                candidates.append(res)
+                n_valid += 1
+        print(f"  {n_valid} valid, {len(configs) - n_valid} rejected {kinds if kinds else ''}")
+
+    pd.DataFrame(rows).sort_values("E_ads_eV").to_csv(mol_dir / "all_placements.csv", index=False)
+    if not candidates:
+        print(f"  No valid configurations for {name}; see {mol_dir / 'all_placements.csv'}")
+        return None
+
+    candidates.sort(key=lambda c: c["E_ads"])
+    df = pd.DataFrame(
+        [
+            {
+                "mode": c["mode"],
+                "E_ads_eV": c["E_ads"],
+                **extra_col(c),
+                "E_adslab_eV": c["energy"],
+                "converged": c["converged"],
+                "min_ads_slab_dist_A": c["min_dist"],
+            }
+            for c in candidates
+        ]
+    )
+    df.index.name = "rank"
+    df.to_csv(mol_dir / "adsorption_energies.csv")
+
+    top = candidates[: args.top_k]
+    write(str(mol_dir / "top_candidates.traj"), [c["atoms"] for c in top])
+    write(str(mol_dir / "all_valid_candidates.traj"), [c["atoms"] for c in candidates])
+    for k, c in enumerate(top):
+        write(str(mol_dir / f"rank{k}_{c['mode']}.vasp"), c["atoms"], format="vasp", direct=True)
+
+    print(f"\n{name}: top configurations (E_ads = E_adslab - E_slab - E[{ref_label}]; negative = exothermic)")
+    print(df.head(args.top_k).to_string(float_format=lambda x: f"{x:.3f}"))
+
+    if not args.no_vasp:
+        write_vasp_dir(
+            gas_boxed,
+            mol_dir / "vasp" / "gas",
+            INCAR_GAS,
+            kpts=(1, 1, 1),
+            unpaired=unpaired,
+            fix_moment=True,
+        )
+        if dimer is not None:
+            write_vasp_dir(dimer, mol_dir / "vasp" / "gas_dimer", INCAR_GAS, kpts=(1, 1, 1))
+        for k, c in enumerate(top):
+            write_vasp_dir(
+                c["atoms"],
+                mol_dir / "vasp" / f"rank{k}_{c['mode']}",
+                INCAR_SLAB,
+                unpaired=unpaired,
+                metallic_slab=args.metallic,
+            )
+
+    best_per_mode = df.groupby("mode")["E_ads_eV"].min().to_dict()
+    summary = {
+        "molecule": name,
+        "formula": mol_relaxed.get_chemical_formula(),
+        "unpaired_electrons": unpaired,
+        "E_gas_eV": e_gas,
+        "E_reference_eV": e_ref,
+        "reference": ref_label,
+        "E_slab_eV": e_slab,
+        "placements": len(rows),
+        "valid": len(candidates),
+        "best_mode": top[0]["mode"],
+        "best_E_ads_eV": top[0]["E_ads"],
+        "best_per_mode_eV": best_per_mode,
+    }
+    with open(mol_dir / "summary.json", "w") as f:
+        json.dump(summary, f, indent=2)
+    return summary
+
+
+def main() -> None:
+    args = parse_args()
+    mols = [load_molecule(s, args.unpaired) for s in args.molecules]
+
+    if args.list_modes:
+        for name, mol, _ in mols:
+            modes = binding_modes(mol, bidentate=args.bidentate, include_h=args.include_h_modes)
+            if args.modes:
+                modes = {k: v for k, v in modes.items() if k in args.modes}
+            describe_modes(name, mol, modes)
+        return
+
+    random.seed(args.seed)
+    np.random.seed(args.seed)
+
+    outdir = Path(args.outdir).resolve()
+    outdir.mkdir(parents=True, exist_ok=True)
+    traj_dir = (outdir / "trajectories") if args.save_trajectories else None
+    if traj_dir is not None:
+        traj_dir.mkdir(parents=True, exist_ok=True)
+
+    print(f"Model: {args.model} | Task: {args.task} | Device: {args.device or 'auto'}")
+
+    if args.slab_file:
+        slab = slab_from_file(str(Path(args.slab_file).resolve()), args.surface_depth, args.fixed_depth)
+    else:
+        bulk_atoms = load_bulk_atoms(
+            args.bulk,
+            crystalstructure=args.crystalstructure,
+            a=args.lattice_a,
+            c=args.lattice_c,
+        )
+        slab = slab_from_bulk(
+            bulk_atoms,
+            tuple(args.millers),
+            termination=args.termination,
+            fixed_depth=args.fixed_depth,
+            min_ab=args.min_ab,
+        )
+
+    write(str(outdir / "slab_input.vasp"), slab.atoms, format="vasp", direct=True)
+
+    calc = get_calculator(args.model, args.task, args.device)
+    relax = make_relax_job(calc, args.fmax, args.steps, args.optimizer, traj_dir)
+
+    print("\nRelaxing clean slab:")
+    slab_res = relax(slab.atoms, "clean slab")
+    e_slab, relaxed_slab = slab_res["energy"], slab_res["atoms"]
+    write(str(outdir / "slab_relaxed.vasp"), relaxed_slab, format="vasp", direct=True)
+
+    if not args.no_vasp:
+        write_vasp_dir(relaxed_slab, outdir / "vasp_slab", INCAR_SLAB, metallic_slab=args.metallic)
+
+    # Default: place on the relaxed slab to avoid artificial surface_changed anomalies
+    place_slab = slab if args.place_on_unrelaxed_slab else Slab(slab_atoms=relaxed_slab.copy())
+
+    summaries = []
+    for name, mol, unpaired in mols:
+        s = run_molecule(
+            name, mol, unpaired, args, outdir, calc, relax, place_slab, relaxed_slab, e_slab
+        )
+        if s is not None:
+            summaries.append(s)
+
+    if summaries:
+        tab = pd.DataFrame(
+            [
+                {
+                    "molecule": s["molecule"],
+                    "best_mode": s["best_mode"],
+                    "E_ads_eV": s["best_E_ads_eV"],
+                    "reference": s["reference"],
+                    "valid": s["valid"],
+                    "placements": s["placements"],
+                    "unpaired_e": s["unpaired_electrons"],
+                }
+                for s in summaries
+            ]
+        )
+        tab.to_csv(outdir / "summary_all_molecules.csv", index=False)
+        print("\n================ Summary ================")
+        print(tab.to_string(index=False, float_format=lambda x: f"{x:.3f}"))
+
+    print(f"\nAll output written to: {outdir}")
+
+
+if __name__ == "__main__":
+    main()

adsorb_screen-0.1.0/src/adsorb_screen/modes.py

@@ -0,0 +1,135 @@
+from __future__ import annotations
+
+import itertools
+import numpy as np
+from ase import Atoms
+from ase.neighborlist import NeighborList, natural_cutoffs
+
+
+def safe_rotate(atoms: Atoms, v1: np.ndarray, v2: np.ndarray, center: np.ndarray) -> None:
+    """Rotate vector v1 onto v2 around center, safely handling collinear/antiparallel vectors."""
+    n1, n2 = np.linalg.norm(v1), np.linalg.norm(v2)
+    if n1 < 1e-8 or n2 < 1e-8:
+        return
+    u1, u2 = v1 / n1, v2 / n2
+    if np.allclose(u1, u2, atol=1e-6):
+        return
+    if np.allclose(u1, -u2, atol=1e-6):
+        ortho = np.array([1.0, 0.0, 0.0]) if abs(u1[0]) < 0.9 else np.array([0.0, 1.0, 0.0])
+        axis = np.cross(u1, ortho)
+        atoms.rotate(180.0, axis, center=center)
+    else:
+        atoms.rotate(u1, u2, center=center)
+
+
+def bonded_neighbors(mol: Atoms, mult: float = 1.15) -> list[list[int]]:
+    if len(mol) <= 1:
+        return [[]]
+    nl = NeighborList(natural_cutoffs(mol, mult=mult), self_interaction=False, bothways=True)
+    nl.update(mol)
+    return [list(nl.get_neighbors(i)[0]) for i in range(len(mol))]
+
+
+def atom_fingerprint(mol: Atoms, i: int, tol: float = 0.08) -> tuple:
+    """Distance-spectrum + coordination fingerprint for symmetry equivalence."""
+    d = mol.get_distances(i, range(len(mol)))
+    spectrum = tuple(
+        sorted((mol[j].symbol, round(float(d[j]) / tol)) for j in range(len(mol)) if j != i)
+    )
+    return (mol[i].symbol,) + spectrum
+
+
+def orient_for_binding(
+    mol: Atoms, atoms: list[int], flat_threshold: float = 0.5
+) -> tuple[Atoms, str]:
+    """Orient molecule so binding atom(s) face -z (toward the catalytic surface)."""
+    m = mol.copy()
+    if len(m) == 1:
+        return m, "atom"
+
+    center = m.positions[atoms].mean(axis=0)
+    if len(atoms) == 2:
+        ax = m.positions[atoms[1]] - m.positions[atoms[0]]
+        safe_rotate(m, ax, np.array([1.0, 0.0, 0.0]), center=center)
+        others = [k for k in range(len(m)) if k not in atoms]
+        if not others:
+            return m, "pair"
+        best, best_score = None, None
+        for ang in np.arange(0.0, 360.0, 2.0):
+            t = m.copy()
+            t.rotate(ang, "x", center=center)
+            dz = t.positions[others, 2] - t.positions[atoms, 2].mean()
+            score = (round(float(dz.min()), 2), float(dz.mean()))
+            if best_score is None or score > best_score:
+                best, best_score = t, score
+        return best, "pair"
+
+    nbrs = bonded_neighbors(m)
+    vec = np.zeros(3)
+    for i in atoms:
+        for j in nbrs[i]:
+            u = m.positions[j] - m.positions[i]
+            norm = np.linalg.norm(u)
+            if norm > 1e-8:
+                vec += u / norm
+
+    if np.linalg.norm(vec) > flat_threshold:
+        safe_rotate(m, -vec, np.array([0.0, 0.0, -1.0]), center=center)
+        return m, "down"
+
+    x = m.positions - m.positions.mean(axis=0)
+    normal = np.linalg.eigh(x.T @ x)[1][:, 0]
+    safe_rotate(m, normal, np.array([0.0, 0.0, 1.0]), center=center)
+    return m, "flat"
+
+
+def binding_modes(
+    mol: Atoms,
+    bidentate: bool = True,
+    include_h: bool = False,
+    pair_cutoff: float = 4.0,
+) -> dict[str, list[int]]:
+    """Find symmetry-unique monodentate and bidentate binding modes."""
+    if len(mol) == 1:
+        return {f"{mol[0].symbol}0": [0]}
+
+    candidates = [
+        i for i, a in enumerate(mol) if include_h or a.symbol != "H"
+    ]
+    if not candidates:
+        candidates = list(range(len(mol)))
+
+    modes: dict[str, list[int]] = {}
+    seen: set[tuple] = set()
+    for i in candidates:
+        fp = atom_fingerprint(mol, i)
+        if fp not in seen:
+            seen.add(fp)
+            modes[f"{mol[i].symbol}{i}"] = [i]
+
+    if bidentate and len(candidates) >= 2:
+        seen_pairs: set[tuple] = set()
+        for i, j in itertools.combinations(candidates, 2):
+            if mol.get_distance(i, j) > pair_cutoff:
+                continue
+            fp_pair = tuple(sorted([atom_fingerprint(mol, i), atom_fingerprint(mol, j)]))
+            o, _ = orient_for_binding(mol, [i, j])
+            others = [k for k in range(len(mol)) if k not in (i, j)]
+            if others and (o.positions[others, 2] - o.positions[[i, j], 2].mean()).min() < 0.3:
+                continue
+            if fp_pair not in seen_pairs:
+                seen_pairs.add(fp_pair)
+                modes[f"{mol[i].symbol}{i}-{mol[j].symbol}{j}"] = [i, j]
+
+    return modes
+
+
+def describe_modes(name: str, mol: Atoms, modes: dict[str, list[int]]) -> None:
+    print(f"\n{name} ({mol.get_chemical_formula()}): {len(modes)} binding mode(s)")
+    for mname, idx in modes.items():
+        o, how = orient_for_binding(mol, idx)
+        z = o.positions[:, 2] - o.positions[idx, 2].mean()
+        prof = ", ".join(
+            f"{s}{k}:{dz:+.2f}" for k, (s, dz) in enumerate(zip(o.get_chemical_symbols(), z))
+        )
+        print(f"  {mname:<10s} [{how:4s}]  heights rel. to binding atom(s): {prof}")

adsorb_screen-0.1.0/src/adsorb_screen/molecules.py

@@ -0,0 +1,161 @@
+from __future__ import annotations
+
+from pathlib import Path
+import numpy as np
+from ase import Atoms
+from ase.build import molecule as ase_molecule
+from ase.collections import g2
+from ase.data import chemical_symbols, covalent_radii
+from ase.io import read
+
+
+def _ch2i2() -> Atoms:
+    r_ci, r_ch = 2.14, 1.09
+    a, b = np.radians(113.0) / 2, np.radians(112.0) / 2
+    return Atoms(
+        "CI2H2",
+        positions=[
+            (0, 0, 0),
+            (r_ci * np.sin(a), 0, r_ci * np.cos(a)),
+            (-r_ci * np.sin(a), 0, r_ci * np.cos(a)),
+            (0, r_ch * np.sin(b), -r_ch * np.cos(b)),
+            (0, -r_ch * np.sin(b), -r_ch * np.cos(b)),
+        ],
+    )
+
+
+def _ch2i() -> Atoms:
+    r_ci, r_ch, t = 2.05, 1.08, np.radians(120.0)
+    return Atoms(
+        "CIH2",
+        positions=[
+            (0, 0, 0),
+            (r_ci, 0, 0),
+            (r_ch * np.cos(t), r_ch * np.sin(t), 0),
+            (r_ch * np.cos(t), -r_ch * np.sin(t), 0),
+        ],
+    )
+
+
+def _ch2() -> Atoms:
+    r, h = 1.08, np.radians(134.0) / 2
+    return Atoms(
+        "CH2",
+        positions=[
+            (0, 0, 0),
+            (r * np.sin(h), 0, r * np.cos(h)),
+            (-r * np.sin(h), 0, r * np.cos(h)),
+        ],
+    )
+
+
+def _ch2oo() -> Atoms:
+    r_co, r_oo, r_ch = 1.27, 1.35, 1.08
+    o1 = np.array([r_co, 0, 0])
+    o2 = o1 + r_oo * np.array([np.cos(np.radians(62.0)), np.sin(np.radians(62.0)), 0])
+    t = np.radians(120.0)
+    return Atoms(
+        "COOH2",
+        positions=[
+            (0, 0, 0),
+            o1,
+            o2,
+            (r_ch * np.cos(t), r_ch * np.sin(t), 0),
+            (r_ch * np.cos(t), -r_ch * np.sin(t), 0),
+        ],
+    )
+
+
+BUILTIN_MOLECULES: dict[str, tuple[callable, int]] = {
+    "CH2I2": (_ch2i2, 0),
+    "CH2I": (_ch2i, 1),
+    "CH2": (_ch2, 2),
+    "CH2OO": (_ch2oo, 0),
+}
+
+# Standard ground-state unpaired electrons for isolated atoms
+ATOM_UNPAIRED: dict[str, int] = {
+    "H": 1, "Li": 1, "B": 1, "C": 2, "N": 3, "O": 2, "F": 1,
+    "Na": 1, "Al": 1, "Si": 2, "P": 3, "S": 2, "Cl": 1,
+    "K": 1, "Br": 1, "I": 1,
+}
+
+
+def _from_smiles(smiles: str) -> Atoms:
+    try:
+        from rdkit import Chem
+        from rdkit.Chem import AllChem
+    except ImportError as exc:
+        raise SystemExit(
+            "Install rdkit (`pip install adsorb-screen[smiles]`) to build molecules from SMILES."
+        ) from exc
+
+    mol = Chem.AddHs(Chem.MolFromSmiles(smiles))
+    if mol is None:
+        raise SystemExit(f"Invalid SMILES string: '{smiles}'")
+    AllChem.EmbedMolecule(mol, AllChem.ETKDGv3())
+    AllChem.UFFOptimizeMolecule(mol)
+    conf = mol.GetConformer()
+    symbols = [a.GetSymbol() for a in mol.GetAtoms()]
+    positions = conf.GetPositions()
+    return Atoms(symbols=symbols, positions=positions)
+
+
+def load_molecule(spec: str, unpaired_override: int | None = None) -> tuple[str, Atoms, int]:
+    """Load a molecule/atom from built-ins, file path, SMILES, single element, or ASE G2."""
+    path = Path(spec)
+    if path.is_file():
+        mol = read(str(path))
+        mol.set_cell(None)
+        mol.pbc = False
+        n_unp = unpaired_override if unpaired_override is not None else 0
+        return path.stem, mol, n_unp
+
+    if spec in BUILTIN_MOLECULES:
+        builder, default_unp = BUILTIN_MOLECULES[spec]
+        n_unp = unpaired_override if unpaired_override is not None else default_unp
+        return spec, builder(), n_unp
+
+    if spec.startswith("smiles:"):
+        smiles_str = spec.split("smiles:", 1)[1]
+        mol = _from_smiles(smiles_str)
+        safe_name = "".join(c if c.isalnum() else "_" for c in smiles_str).strip("_")
+        n_unp = unpaired_override if unpaired_override is not None else 0
+        return f"smiles_{safe_name}", mol, n_unp
+
+    if spec in chemical_symbols and spec != "X":
+        mol = Atoms(spec, positions=[(0.0, 0.0, 0.0)])
+        default_unp = ATOM_UNPAIRED.get(spec, 0)
+        n_unp = unpaired_override if unpaired_override is not None else default_unp
+        return spec, mol, n_unp
+
+    if spec in g2.names:
+        mol = ase_molecule(spec)
+        mol.set_cell(None)
+        mol.pbc = False
+        inferred_unp = int(round(abs(mol.get_initial_magnetic_moments().sum())))
+        n_unp = unpaired_override if unpaired_override is not None else inferred_unp
+        return spec, mol, n_unp
+
+    raise SystemExit(
+        f"Unknown molecule '{spec}'. Supported inputs:\n"
+        f"  1. Structure file (.xyz, POSCAR, .sdf, .cif)\n"
+        f"  2. Built-in presets: {', '.join(BUILTIN_MOLECULES)}\n"
+        f"  3. Any chemical element symbol (e.g., H, O, N, I, Pt)\n"
+        f"  4. Any ASE G2 molecule name (e.g., CO, CO2, NH3, H2O, CH4, CH3OH, C2H4)\n"
+        f"  5. SMILES string prefixed with 'smiles:' (e.g., 'smiles:CCO')"
+    )
+
+
+def build_dimer(symbol: str, box: float = 20.0) -> Atoms:
+    """Build a homonuclear diatomic molecule X2 for half-dimer gas reference."""
+    z = Atoms(symbol).numbers[0]
+    r0 = 2.67 if symbol == "I" else float(2.0 * covalent_radii[z])
+    dimer = Atoms(
+        f"{symbol}2",
+        positions=[(0.0, 0.0, 0.0), (0.0, 0.0, r0)],
+        cell=[box, box, box],
+        pbc=True,
+    )
+    dimer.center()
+    return dimer

adsorb_screen-0.1.0/src/adsorb_screen/relax.py

@@ -0,0 +1,99 @@
+from __future__ import annotations
+
+from pathlib import Path
+import time
+import numpy as np
+from ase import Atoms
+from ase.optimize import BFGS, FIRE, LBFGS
+from fairchem.data.oc.utils import DetectTrajAnomaly
+
+
+OPTIMIZERS = {"LBFGS": LBFGS, "BFGS": BFGS, "FIRE": FIRE}
+
+
+def get_calculator(model: str, task: str, device: str | None = None):
+    from fairchem.core import FAIRChemCalculator, pretrained_mlip
+    predict_unit = pretrained_mlip.get_predict_unit(model, device=device)
+    return FAIRChemCalculator(predict_unit, task_name=task)
+
+
+def make_relax_job(
+    calc,
+    fmax: float = 0.02,
+    steps: int = 300,
+    optimizer_name: str = "LBFGS",
+    traj_dir: Path | None = None,
+):
+    opt_cls = OPTIMIZERS.get(optimizer_name.upper(), LBFGS)
+
+    def relax(initial_atoms: Atoms, label: str) -> dict:
+        atoms = initial_atoms.copy()
+        atoms.calc = calc
+        traj_path = None
+        if traj_dir is not None:
+            safe_label = label.replace(" #", "_").replace(" ", "_")
+            traj_path = str(traj_dir / f"{safe_label}.traj")
+        t0 = time.time()
+        opt = opt_cls(atoms, logfile=None, trajectory=traj_path)
+        converged = bool(opt.run(fmax=fmax, steps=steps))
+        energy = float(atoms.get_potential_energy())
+        atoms.calc = None
+        print(
+            f"  {label:>26s}: E = {energy:12.4f} eV, {opt.nsteps:4d} steps, "
+            f"{'converged' if converged else 'NOT converged'}, {time.time() - t0:6.1f} s",
+            flush=True,
+        )
+        return {
+            "initial": initial_atoms,
+            "atoms": atoms,
+            "energy": energy,
+            "converged": converged,
+        }
+
+    return relax
+
+
+def relax_gas_molecule(
+    mol: Atoms, calc, box: float = 20.0, fmax: float = 0.01, steps: int = 500
+) -> tuple[Atoms, float]:
+    gas = mol.copy()
+    gas.set_cell([box, box, box])
+    gas.center()
+    gas.pbc = True
+    gas.calc = calc
+    if len(gas) > 1:
+        LBFGS(gas, logfile=None).run(fmax=fmax, steps=steps)
+    e = float(gas.get_potential_energy())
+    gas.calc = None
+    # Strip cell for clean orientation processing while keeping relaxed coordinates
+    gas_no_cell = gas.copy()
+    gas_no_cell.set_cell(None)
+    gas_no_cell.pbc = False
+    return gas, e
+
+
+def min_ads_slab_distance(atoms: Atoms) -> float:
+    tags = atoms.get_tags()
+    ads = np.where(tags == 2)[0]
+    sub = np.where(tags != 2)[0]
+    if len(ads) == 0 or len(sub) == 0:
+        return 0.0
+    return float(min(atoms.get_distances(i, sub, mic=True).min() for i in ads))
+
+
+def find_anomalies(
+    initial: Atoms, final: Atoms, relaxed_slab: Atoms, desorb_dist: float
+) -> list[str]:
+    det = DetectTrajAnomaly(
+        initial, final, atoms_tag=initial.get_tags(), final_slab_atoms=relaxed_slab
+    )
+    found = []
+    if (initial.get_tags() == 2).sum() > 1 and det.is_adsorbate_dissociated():
+        found.append("dissociated")
+    if min_ads_slab_distance(final) > desorb_dist:
+        found.append("desorbed")
+    if det.has_surface_changed():
+        found.append("surface_changed")
+    if det.is_adsorbate_intercalated():
+        found.append("intercalated")
+    return found

adsorb_screen-0.1.0/src/adsorb_screen/slab.py

@@ -0,0 +1,160 @@
+from __future__ import annotations
+
+import numpy as np
+from ase import Atoms
+from ase.build import bulk as ase_bulk
+from ase.constraints import FixAtoms
+from ase.io import read
+from ase.neighborlist import NeighborList, natural_cutoffs
+from ase.spacegroup import crystal
+from fairchem.data.oc.core import Bulk, Slab
+
+
+BUILTIN_BULKS: dict[str, callable] = {
+    "alpha-quartz": lambda: crystal(
+        ["Si", "O"],
+        basis=[(0.4697, 0.0, 1 / 3), (0.4135, 0.2669, 0.2142)],
+        spacegroup=152,
+        cellpar=[4.9134, 4.9134, 5.4052, 90, 90, 120],
+    ),
+    "rutile-TiO2": lambda: crystal(
+        ["Ti", "O"],
+        basis=[(0.0, 0.0, 0.0), (0.3048, 0.3048, 0.0)],
+        spacegroup=136,
+        cellpar=[4.5937, 4.5937, 2.9587, 90, 90, 90],
+    ),
+    "MgO": lambda: ase_bulk("MgO", crystalstructure="rocksalt", a=4.212),
+}
+
+
+def load_bulk_atoms(
+    bulk_spec: str,
+    crystalstructure: str | None = None,
+    a: float | None = None,
+    c: float | None = None,
+) -> Atoms:
+    """Load bulk crystal from preset, file path, Materials Project ID, or ASE bulk."""
+    if bulk_spec in BUILTIN_BULKS:
+        return BUILTIN_BULKS[bulk_spec]()
+
+    if bulk_spec.startswith("mp-"):
+        try:
+            from mp_api.client import MPRester
+            from pymatgen.io.ase import AseAtomsAdaptor
+        except ImportError as exc:
+            raise SystemExit(
+                "Install mp-api (`pip install adsorb-screen[mp]`) to fetch Materials Project IDs."
+            ) from exc
+        with MPRester() as mpr:
+            struct = mpr.get_structure_by_material_id(bulk_spec, conventional_unit_cell=True)
+        return AseAtomsAdaptor.get_atoms(struct)
+
+    try:
+        return read(bulk_spec)
+    except Exception:
+        pass
+
+    try:
+        kwargs = {}
+        if crystalstructure:
+            kwargs["crystalstructure"] = crystalstructure
+        if a is not None:
+            kwargs["a"] = a
+        if c is not None:
+            kwargs["c"] = c
+        return ase_bulk(bulk_spec, **kwargs)
+    except Exception as exc:
+        raise SystemExit(
+            f"Could not build bulk '{bulk_spec}'. Provide a valid structure file, "
+            f"preset ({', '.join(BUILTIN_BULKS)}), ASE formula (e.g. Pt, Cu, Fe, Au, NaCl), "
+            f"or Materials Project ID (mp-XXXX)."
+        ) from exc
+
+
+def get_bulk_cn(bulk_atoms: Atoms, mult: float = 1.15) -> dict[str, int]:
+    """Dynamically determine ideal bulk coordination numbers per element."""
+    rep = bulk_atoms.repeat((2, 2, 2))
+    nl = NeighborList(natural_cutoffs(rep, mult=mult), self_interaction=False, bothways=True)
+    nl.update(rep)
+    cn_map: dict[str, int] = {}
+    for idx, atom in enumerate(rep):
+        cn = len(nl.get_neighbors(idx)[0])
+        cn_map[atom.symbol] = max(cn_map.get(atom.symbol, 0), cn)
+    return cn_map
+
+
+def broken_bonds(atoms: Atoms, bulk_cn: dict[str, int], mult: float = 1.15) -> int:
+    """Count under-coordinated bonds on surface atoms (tag == 1) for any crystal."""
+    nl = NeighborList(natural_cutoffs(atoms, mult=mult), self_interaction=False, bothways=True)
+    nl.update(atoms)
+    surf = np.where(atoms.get_tags() == 1)[0]
+    return int(
+        sum(max(bulk_cn.get(atoms[k].symbol, 0) - len(nl.get_neighbors(k)[0]), 0) for k in surf)
+    )
+
+
+def apply_fixed_depth(atoms: Atoms, fixed_depth: float) -> Atoms:
+    """Freeze atoms within fixed_depth (A) of the bottom of the slab."""
+    z = atoms.positions[:, 2]
+    thickness = float(z.max() - z.min())
+    fixed = z < (z.min() + fixed_depth) if fixed_depth > 0 else np.zeros(len(atoms), dtype=bool)
+    if fixed.all():
+        raise SystemExit(
+            f"--fixed-depth {fixed_depth} A fixes the entire slab (thickness {thickness:.2f} A)."
+        )
+    overlap = fixed & (atoms.get_tags() == 1)
+    if overlap.any():
+        print(f"  WARNING: {overlap.sum()} surface-tagged atoms are inside --fixed-depth.")
+    atoms.set_constraint(FixAtoms(mask=fixed) if fixed.any() else [])
+    free = ~fixed
+    print(
+        f"  Fixed {fixed.sum()} / {len(atoms)} atoms: bottom {fixed_depth:.2f} A of a "
+        f"{thickness:.2f} A slab (relaxing {free.sum()} atoms with z >= {z[free].min():.2f} A)"
+    )
+    return atoms
+
+
+def slab_from_bulk(
+    bulk_atoms: Atoms,
+    millers: tuple[int, int, int],
+    termination: int | None = None,
+    fixed_depth: float = 6.0,
+    min_ab: float = 8.0,
+) -> Slab:
+    """Cleave bulk crystal along Miller indices, pick lowest broken-bond termination, and tile."""
+    bulk_cn = get_bulk_cn(bulk_atoms)
+    slabs = Slab.from_bulk_get_specific_millers(
+        tuple(millers), bulk=Bulk(bulk_atoms=bulk_atoms), min_ab=min_ab
+    )
+    print(f"{len(slabs)} termination(s) for {bulk_atoms.get_chemical_formula()} {tuple(millers)}:")
+    scores = []
+    for k, s in enumerate(slabs):
+        bb = broken_bonds(s.atoms, bulk_cn)
+        scores.append(bb)
+        print(f"  [{k}] {s}  under-coordinated surface bonds: {bb}")
+    pick = termination if termination is not None else int(np.argmin(scores))
+    print(f"Selected termination [{pick}]")
+    slab = slabs[pick]
+    if fixed_depth is not None:
+        apply_fixed_depth(slab.atoms, fixed_depth)
+    return slab
+
+
+def slab_from_file(path: str, surface_depth: float, fixed_depth: float) -> Slab:
+    """Load custom slab file and tag top surface_depth A as surface (tag=1)."""
+    atoms = read(path)
+    atoms.pbc = True
+    z = atoms.positions[:, 2]
+    surf = z > (z.max() - surface_depth)
+    if surf.sum() == 0:
+        raise SystemExit("Check --surface-depth: no atoms tagged as surface.")
+    atoms.set_tags(surf.astype(int))
+    vac = float(atoms.cell.lengths()[2] - (z.max() - z.min()))
+    print(
+        f"Slab {atoms.get_chemical_formula()} from {path}: {len(atoms)} atoms, "
+        f"{surf.sum()} surface (top {surface_depth:.2f} A), ~{vac:.1f} A vacuum"
+    )
+    apply_fixed_depth(atoms, fixed_depth)
+    if vac < 12.0:
+        print("  WARNING: Vacuum is less than 12 A; periodic image interactions may occur.")
+    return Slab(slab_atoms=atoms)

adsorb_screen-0.1.0/src/adsorb_screen/vasp.py

@@ -0,0 +1,85 @@
+from __future__ import annotations
+
+from pathlib import Path
+import numpy as np
+from ase import Atoms
+from ase.io import write
+
+
+INCAR_COMMON = {
+    "PREC": "Normal",
+    "ENCUT": 400,
+    "GGA": "RP",
+    "IVDW": 11,
+    "ISPIN": 1,
+    "EDIFF": 1e-5,
+    "ISMEAR": 0,
+    "SIGMA": 0.05,
+    "LREAL": "Auto",
+    "ISYM": 0,
+    "NELM": 200,
+    "LWAVE": ".FALSE.",
+    "LCHARG": ".FALSE.",
+    "IBRION": 2,
+    "NSW": 500,
+    "ISIF": 0,
+    "EDIFFG": -0.03,
+}
+INCAR_SLAB = {"LDIPOL": ".TRUE.", "IDIPOL": 3}
+INCAR_GAS = {"LDIPOL": ".TRUE.", "IDIPOL": 4}
+
+
+def write_vasp_dir(
+    atoms: Atoms,
+    outdir: Path,
+    incar_extra: dict,
+    kpts: tuple[int, int, int] | None = None,
+    unpaired: int = 0,
+    fix_moment: bool = False,
+    metallic_slab: bool = False,
+) -> None:
+    outdir.mkdir(parents=True, exist_ok=True)
+
+    # Sort explicitly by symbol so tags stay synchronized with POSCAR atom order
+    symbols_orig = atoms.get_chemical_symbols()
+    sort_idx = np.argsort(symbols_orig, kind="mergesort")
+    sorted_atoms = atoms[sort_idx]
+
+    poscar_path = outdir / "POSCAR"
+    write(str(poscar_path), sorted_atoms, format="vasp", direct=True, sort=False)
+
+    symbols = sorted_atoms.get_chemical_symbols()
+    species = list(dict.fromkeys(symbols))
+
+    incar = {**INCAR_COMMON, **incar_extra}
+    if metallic_slab and incar_extra != INCAR_GAS:
+        incar["ISMEAR"] = 1
+        incar["SIGMA"] = 0.20
+
+    if unpaired > 0:
+        incar["ISPIN"] = 2
+        if fix_moment:
+            incar["NUPDOWN"] = unpaired
+        tags = sorted_atoms.get_tags()
+        # Assign initial spin to non-H adsorbate atoms (tag == 2) or isolated gas molecule
+        is_gas = (tags == 2).sum() == 0
+        is_mag_target = [
+            ((t == 2 or is_gas) and (s != "H" or len(sorted_atoms) == 1))
+            for t, s in zip(tags, symbols)
+        ]
+        n_mag = max(sum(is_mag_target), 1)
+        mag_val = round(max(unpaired / n_mag, 0.5), 2)
+        incar["MAGMOM"] = " ".join(f"{mag_val}" if m else "0.0" for m in is_mag_target)
+
+    with open(outdir / "INCAR", "w") as f:
+        f.write("".join(f"{k} = {v}\n" for k, v in incar.items()))
+
+    if kpts is None:
+        a, b = sorted_atoms.cell.lengths()[:2]
+        kpts = (max(1, round(40.0 / a)), max(1, round(40.0 / b)), 1)
+
+    with open(outdir / "KPOINTS", "w") as f:
+        f.write(f"Automatic\n0\nGamma\n{kpts[0]} {kpts[1]} {kpts[2]}\n0 0 0\n")
+
+    with open(outdir / "POTCAR_ORDER", "w") as f:
+        f.write(" ".join(species) + "\n")

adsorb_screen-0.1.0/src/adsorb_screen.egg-info/PKG-INFO

@@ -0,0 +1,41 @@
+Metadata-Version: 2.4
+Name: adsorb-screen
+Version: 0.1.0
+Summary: General-purpose AdsorbML screening of molecules and radicals on catalytic surfaces with FAIRChem / UMA.
+Author-email: Raghavendra Meena <raghavendra.ip2020@gmail.com>
+License-Expression: MIT
+Keywords: catalysis,adsorption,machine-learning-potentials,fairchem,DFT,VASP,ASE
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: numpy>=1.23
+Requires-Dist: pandas>=1.5
+Requires-Dist: ase>=3.22
+Requires-Dist: fairchem-core>=2.0.0
+Requires-Dist: fairchem-data-oc>=0.1.0
+Provides-Extra: smiles
+Requires-Dist: rdkit>=2023.3.1; extra == "smiles"
+Provides-Extra: mp
+Requires-Dist: mp-api>=0.39.0; extra == "mp"
+Requires-Dist: pymatgen>=2023.10.0; extra == "mp"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: ruff>=0.3.0; extra == "dev"
+
+# adsorb-screen
+
+Automated, general-purpose **AdsorbML** configuration screening of molecules, radicals, and atoms on **any catalytic surface** using FAIRChem v2 / UMA and VASP input generation.
+
+## Key Features
+- **Any Adsorbate**: Screen built-in radicals (`CH2I2`, `CH2I`, `CH2`, `CH2OO`), any single atom (`H`, `O`, `N`, `I`, `Pt`), any molecule in the ASE G2 database (`CO`, `CO2`, `NH3`, `CH3OH`, `H2O`, `C2H4`), SMILES strings (`smiles:CC(=O)O`), or custom structure files (`.xyz`, `POSCAR`, `.sdf`).
+- **Any Catalytic Surface**: Provide your own slab (`--slab-file`), cleave any bulk crystal file (`--bulk my_oxide.cif --millers 1 1 0`), use built-in oxide presets (`alpha-quartz`, `rutile-TiO2`, `MgO`), use any ASE metal/crystal (`--bulk Pt --millers 1 1 1`), or fetch directly from the Materials Project (`--bulk mp-126 --millers 1 1 1`).
+- **Symmetry-Aware Binding Modes**: Automatically identifies symmetry-unique monodentate and bidentate binding sites and orients lone pairs/radical lobes toward the surface (`down`), pi-systems parallel to the surface (`flat`), or bidentate bridges (`pair`).
+- **Anomaly Filtering & VASP Export**: Rejects dissociated, desorbed, intercalated, or reconstructed trajectories and exports ready-to-run VASP directories (`POSCAR`, `INCAR`, `KPOINTS`, `POTCAR_ORDER`) with open-shell `MAGMOM`/`NUPDOWN` and metallic/insulator smearing.
+
+## Installation
+
+```bash
+pip install -e .
+# Optional extras for SMILES and Materials Project support:
+pip install -e ".[smiles,mp,dev]"
+huggingface-cli login
+```

adsorb_screen-0.1.0/src/adsorb_screen.egg-info/SOURCES.txt

@@ -0,0 +1,16 @@
+README.md
+pyproject.toml
+src/adsorb_screen/__init__.py
+src/adsorb_screen/cli.py
+src/adsorb_screen/modes.py
+src/adsorb_screen/molecules.py
+src/adsorb_screen/relax.py
+src/adsorb_screen/slab.py
+src/adsorb_screen/vasp.py
+src/adsorb_screen.egg-info/PKG-INFO
+src/adsorb_screen.egg-info/SOURCES.txt
+src/adsorb_screen.egg-info/dependency_links.txt
+src/adsorb_screen.egg-info/entry_points.txt
+src/adsorb_screen.egg-info/requires.txt
+src/adsorb_screen.egg-info/top_level.txt
+tests/test_core.py

adsorb_screen-0.1.0/src/adsorb_screen.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

adsorb_screen-0.1.0/src/adsorb_screen.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+adsorb-screen = adsorb_screen.cli:main

adsorb_screen-0.1.0/src/adsorb_screen.egg-info/requires.txt

@@ -0,0 +1,16 @@
+numpy>=1.23
+pandas>=1.5
+ase>=3.22
+fairchem-core>=2.0.0
+fairchem-data-oc>=0.1.0
+
+[dev]
+pytest>=7.0
+ruff>=0.3.0
+
+[mp]
+mp-api>=0.39.0
+pymatgen>=2023.10.0
+
+[smiles]
+rdkit>=2023.3.1

adsorb_screen-0.1.0/src/adsorb_screen.egg-info/top_level.txt

@@ -0,0 +1 @@
+adsorb_screen

adsorb_screen-0.1.0/tests/test_core.py

@@ -0,0 +1,42 @@
+import numpy as np
+from adsorb_screen.modes import binding_modes, orient_for_binding, safe_rotate
+from adsorb_screen.molecules import load_molecule
+from adsorb_screen.slab import get_bulk_cn, load_bulk_atoms
+
+
+def test_safe_rotate_antiparallel():
+    _, mol, _ = load_molecule("CH2I2")
+    v1 = np.array([0.0, 0.0, 1.0])
+    v2 = np.array([0.0, 0.0, -1.0])
+    safe_rotate(mol, v1, v2, center=np.zeros(3))
+    assert not np.isnan(mol.positions).any()
+
+
+def test_binding_modes_ch2i2():
+    _, mol, _ = load_molecule("CH2I2")
+    modes = binding_modes(mol, bidentate=True)
+    # Expect C0 (flat), one unique I (down), and I1-I2 (bidentate pair)
+    assert len(modes) == 3
+    o_pair, how = orient_for_binding(mol, [1, 2])
+    assert how == "pair"
+    # C and H atoms must sit higher in z than the two binding I atoms
+    z_i = o_pair.positions[[1, 2], 2].mean()
+    assert (o_pair.positions[[0, 3, 4], 2] > z_i + 0.3).all()
+
+
+def test_load_any_g2_and_atom():
+    name_co, co, unp_co = load_molecule("CO")
+    assert len(co) == 2 and unp_co == 0
+
+    name_o, o_atom, unp_o = load_molecule("O")
+    assert len(o_atom) == 1 and unp_o == 2
+
+
+def test_bulk_cn_quartz_and_pt():
+    quartz = load_bulk_atoms("alpha-quartz")
+    cn_q = get_bulk_cn(quartz)
+    assert cn_q["Si"] == 4 and cn_q["O"] == 2
+
+    pt = load_bulk_atoms("Pt")
+    cn_pt = get_bulk_cn(pt)
+    assert cn_pt["Pt"] == 12