autostorage 0.0.7__tar.gz

autostorage-0.0.7/PKG-INFO

@@ -0,0 +1,10 @@
+Metadata-Version: 2.3
+Name: autostorage
+Version: 0.0.7
+Author: Andreas V. Copan
+Author-email: Andreas V. Copan <avcopan@uga.edu>
+Requires-Dist: automol==0.0.10
+Requires-Dist: pint>=0.25.2
+Requires-Dist: qcdata>=0.17.0
+Requires-Dist: sqlmodel>=0.0.31
+Requires-Python: >=3.12

autostorage-0.0.7/pyproject.toml

@@ -0,0 +1,101 @@
+[project]
+name = "autostorage"
+version = "0.0.7"
+authors = [{name = "Andreas V. Copan", email = "avcopan@uga.edu"}]
+requires-python = ">= 3.12"
+dependencies = [
+    "automol==0.0.10",
+    "pint>=0.25.2",
+    "qcdata>=0.17.0",
+    "sqlmodel>=0.0.31",
+]
+
+[build-system]
+build-backend = "uv_build"
+requires = ["uv_build"]
+
+# UV build configurations
+[tool.uv.build-backend]
+module-name = "autostorage"
+
+# Ruff configurations
+[tool.ruff]
+exclude = [
+    "docs",
+    "**/*.ipynb",
+]
+
+[tool.ruff.lint]
+select = ["ALL"]
+ignore = [
+    "COM812",   # missing trailing comma (handled by format)
+    "RUF022",   # `__all__` is not sorted
+    "TID252",   # relative import
+    "D203",     # confict: incorrect blank line before class (uses D211 instead)
+    "D213",     # conflict: multi-line summary second line (uses D212 instead)
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**.py" = ["S101"]
+
+[tool.ruff.lint.pydocstyle]
+convention = "numpy"
+
+# Ty configurations
+[tool.ty.environment]
+python = ".pixi/envs/dev/bin/python"
+
+[tool.ty.src]
+include = [
+    "src",
+    "tests",
+]
+
+# Import-linter configurations
+[tool.importlinter]
+root_package = "autostorage"
+exclude_type_checking_imports = true
+
+[[tool.importlinter.contracts]]
+name = "AutoStore Layering"
+type = "layers"
+layers = [
+    "autostorage.database",
+    "autostorage.models",
+    "autostorage.calcn",
+]
+
+[[tool.importlinter.contracts]]
+name = "AutoStore Models Layering"
+type = "layers"
+layers = [
+    "autostorage.models.listeners",
+    "autostorage.models.reaction",
+    "autostorage.models.stationary",
+    "autostorage.models.data",
+    "autostorage.models.calculation",
+    "autostorage.models.geometry",
+    "autostorage.models.links",
+]
+
+
+# Pytest configurations
+[tool.pytest.ini_options]
+testpaths = ["tests", "src"]
+addopts = [
+    "--doctest-modules",
+    "--cov=autostorage",
+    "--cov-report=term-missing",
+    "--cov-report=html",
+]
+doctest_optionflags = "NORMALIZE_WHITESPACE"
+
+# Pytest-cov configurations
+[tool.coverage.run]
+branch = true
+source = ["autostorage"]
+
+[tool.coverage.report]
+show_missing = true
+skip_covered = true
+fail_under = 80

autostorage-0.0.7/src/autostorage/__init__.py

@@ -0,0 +1,36 @@
+"""Interface for database storage."""
+
+__version__ = "0.0.7"
+
+from . import models
+from .calcn import Calculation
+from .database import Database
+from .models import (
+    CalculationGeometryLink,
+    CalculationRow,
+    EnergyRow,
+    GeometryRow,
+    StageRow,
+    StationaryPointRow,
+    StationaryStageLink,
+    StepRow,
+)  # import core Row objects
+from .types import Role
+from .utils import verify_single_iteration
+
+__all__ = [
+    "models",
+    "qc",
+    "CalculationGeometryLink",
+    "Calculation",
+    "Database",
+    "CalculationRow",
+    "EnergyRow",
+    "GeometryRow",
+    "StageRow",
+    "StationaryPointRow",
+    "StationaryStageLink",
+    "StepRow",
+    "Role",
+    "verify_single_iteration",
+]

autostorage-0.0.7/src/autostorage/calcn/__init__.py

@@ -0,0 +1,18 @@
+"""Calculation data."""
+
+from .core import Calculation, project, projected_hash
+from .registry import HashRegistry, calculation_hash, hash_registry
+from .util import CalculationDict, KeywordDict, hash_from_dict, project_keywords
+
+__all__ = [
+    "Calculation",
+    "project",
+    "projected_hash",
+    "HashRegistry",
+    "calculation_hash",
+    "hash_registry",
+    "CalculationDict",
+    "KeywordDict",
+    "hash_from_dict",
+    "project_keywords",
+]

autostorage-0.0.7/src/autostorage/calcn/core.py

@@ -0,0 +1,107 @@
+"""Calculation metadata."""
+
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+from .util import CalculationDict, hash_from_dict, project_keywords
+
+
+class Calculation(BaseModel):
+    """Calculation input parameters and metadata.
+
+    Attributes
+    ----------
+    # - Program Input -------
+    program
+        Quantum chemistry program used (psi4, ORCA, ...)
+    program_keywords
+        (Optional) Quantum chemistry program keywords.
+    super_program
+        (Optional) Geometry optimizer program (geomeTRIC, ...).
+    super_keywords
+        (Optional) Geometry optimizer keywords.
+    cmdline_args
+        (Optional) Command line arguments.
+    input
+        (Optional) Input file. [ PLACEHOLDER ]
+    files
+        (Optional) Additional input files. [ PLACEHOLDER ]
+    # - Methods -------------
+    calc_type
+        Calculation type (energy, optimization, ...)
+    method
+        Computational method (B3LYP, MP2, ...)
+    basis
+        (Optional) Basis set.
+    """
+
+    # - Program Input -------
+    program: str
+    program_keywords: dict[str, Any] = Field(default_factory=dict)
+    super_program: str | None = Field(default=None)
+    super_keywords: dict[str, Any] = Field(default_factory=dict)
+    cmdline_args: list[str] = Field(default_factory=list)
+
+    # - Methods -------------
+    calc_type: str | None = Field(default=None)
+    method: str
+    basis: str | None = Field(default=None)
+
+
+def projected_hash(calc: Calculation, template: Calculation | CalculationDict) -> str:
+    """
+    Project calculation onto template and generate hash.
+
+    Parameters
+    ----------
+    calc
+        Calculation metadata.
+    template
+        Calculation metadata template.
+
+    Returns
+    -------
+        Hash string.
+    """
+    calc_dct = project(calc, template)
+    return hash_from_dict(calc_dct)
+
+
+def project(
+    calc: Calculation, template: Calculation | CalculationDict
+) -> CalculationDict:
+    """
+    Project calculation onto template.
+
+    Parameters
+    ----------
+    calc
+        Calculation metadata.
+    template
+        Calculation metadata template.
+
+    Returns
+    -------
+        Projected calculation dictionary.
+    """
+    # Dump template to dictionary
+    template_dct = (
+        template.model_dump(exclude_unset=True)
+        if isinstance(template, Calculation)
+        else template
+    )
+    # Work on a deep copy to avoid accidental modifications
+    calc_copy = calc.model_copy(deep=True)
+    # Project program_keywords if 'keywords' is in the template
+    if "program_keywords" in template_dct:
+        calc_copy.program_keywords = project_keywords(
+            calc_copy.program_keywords,
+            template=template_dct.get("program_keywords", {}),
+        )
+    if "super_keywords" in template_dct:
+        calc_copy.super_keywords = project_keywords(
+            calc_copy.super_keywords, template=template_dct.get("super_keywords", {})
+        )
+    # Include fields from template
+    return calc_copy.model_dump(exclude_none=True, include=set(template_dct.keys()))

autostorage-0.0.7/src/autostorage/calcn/registry.py

@@ -0,0 +1,113 @@
+"""Calculation hash registry."""
+
+from collections.abc import Callable
+
+from .core import Calculation, projected_hash
+from .util import hash_from_dict
+
+HashFunc = Callable[[Calculation], str]
+
+
+class HashRegistry:
+    """Hash registry."""
+
+    def __init__(self) -> None:
+        """Initialize hash registry."""
+        self._registry: dict[str, HashFunc] = {}
+
+    def register(self, name: str) -> Callable[[HashFunc], HashFunc]:
+        """Register function in hash registry (decorator)."""
+
+        def decorator(func: HashFunc) -> HashFunc:
+            if name in self._registry:
+                msg = f"Hash '{name}' is already registered"
+                raise ValueError(msg)
+            self._registry[name] = func
+            return func
+
+        return decorator
+
+    def get(self, name: str) -> HashFunc:
+        """Get registered hash by name."""
+        try:
+            return self._registry[name]
+        except KeyError as err:
+            msg = f"Unknown hash type '{name}'. Available: {sorted(self._registry)}"
+            raise KeyError(msg) from err
+
+    def available(self) -> tuple[str, ...]:
+        """Get registered hash names."""
+        return tuple(self._registry)
+
+
+hash_registry = HashRegistry()
+
+
+@hash_registry.register("full")
+def hash_full(calc: Calculation) -> str:
+    """
+    Generate maximal hash for calculation.
+
+    Parameters
+    ----------
+    calc
+        Calculation metadata.
+
+    Returns
+    -------
+        Hash string.
+    """
+    input_fields = {
+        "program",
+        "program_keywords",
+        "super_program",
+        "super_keywords",
+        "cmdline_args",
+        "calc_type",
+        "method",
+        "basis",
+    }
+    calc_dct = calc.model_dump(include=input_fields)
+    return hash_from_dict(calc_dct)
+
+
+@hash_registry.register("minimal")
+def hash_minimal(calc: Calculation) -> str:
+    """
+    Generate minimal hash for calculation.
+
+    Parameters
+    ----------
+    calc
+        Calculation metadata.
+
+    Returns
+    -------
+        Hash string.
+    """
+    template = {
+        "program": "PROGRAM",
+        "method": "METHOD",
+        "basis": "BASIS",
+    }
+    return projected_hash(calc, template)
+
+
+def calculation_hash(calc: Calculation, name: str = "minimal") -> str:
+    """
+    Hash calculation metadata using named hash from registry.
+
+    Parameters
+    ----------
+    calc
+        Calculation metadata.
+    name
+        Hash registry name, e.g. "full" or "minimal". Use
+        `hash_registry.available()` to get list of available names.
+
+    Returns
+    -------
+        Hash string.
+    """
+    func = hash_registry.get(name)
+    return func(calc)

autostorage-0.0.7/src/autostorage/calcn/util.py

@@ -0,0 +1,67 @@
+"""Calculation data utilities."""
+
+import hashlib
+import json
+from typing import Any, Union
+
+KeywordDict = dict[str, Union[str, "KeywordDict", None]]
+CalculationDict = dict[str, Any]
+
+
+def hash_from_dict(calc_dct: CalculationDict) -> str:
+    """
+    Generate hash from calculation dictionary.
+
+    Parameters
+    ----------
+    calc_dct
+        Calculation dictionary.
+
+    Returns
+    -------
+        Hash string.
+    """
+    calc_json = json.dumps(
+        calc_dct, sort_keys=True, ensure_ascii=True, separators=(",", ":")
+    ).encode("utf-8")
+    return hashlib.sha256(calc_json).hexdigest()
+
+
+def project_keywords(keywords: KeywordDict, template: object) -> KeywordDict:
+    """
+    Project keywords dictionary onto template.
+
+    Parameters
+    ----------
+    keywords
+        Keywords dictionary.
+    template
+        Keywords dictionary template.
+
+    Returns
+    -------
+        Projected keywords dictionary.
+
+    Raises
+    ------
+    TypeError
+        If keywords template is not a dictionary.
+    TypeError
+        If keywords template keys are not strings.
+    """
+    if not isinstance(template, dict):
+        msg = "Keywords template must be a dictionary."
+        raise TypeError(msg)
+
+    projected_dict: dict[str, object] = {}
+    for key, val in template.items():
+        if not isinstance(key, str):
+            msg = "Keywords template keys must be strings."
+            raise TypeError(msg)
+
+        if key in keywords:
+            if isinstance(val, dict) and isinstance(keywords[key], dict):
+                projected_dict[key] = project_keywords(keywords[key], val)
+            else:
+                projected_dict[key] = keywords[key]
+    return projected_dict

autostorage-0.0.7/src/autostorage/database.py

@@ -0,0 +1,200 @@
+"""Database connection."""
+
+from collections.abc import Iterator
+from pathlib import Path
+
+from sqlalchemy.orm import selectinload
+from sqlmodel import Session, SQLModel, create_engine, select
+
+from .models import *  # noqa: F403
+from .types import SQLModelT
+from .utils import row_to_dict
+
+
+class Database:
+    """
+    Database connection manager.
+
+    Attributes
+    ----------
+    path
+        Path to SQLite database file.
+    engine
+        SQLAlchemy engine instance.
+    """
+
+    def __init__(self, path: str | Path, *, echo: bool = False) -> None:
+        """
+        Initialize database connection manager.
+
+        Parameters
+        ----------
+        path
+            Path to the SQLite database file.
+        echo, optional
+            If True, SQL statements will be logged to the standard output.
+            If False, no logging is performed.
+        """
+        self.path = Path(path)
+        self.engine = create_engine(f"sqlite:///{self.path}", echo=echo)
+        SQLModel.metadata.create_all(self.engine)
+
+    def session(self) -> Session:
+        """Create a new database session."""
+        return Session(self.engine)
+
+    def add(
+        self,
+        row: SQLModelT,
+        *,
+        eager_load: bool = False,
+    ) -> SQLModelT:
+        """
+        Add row to database.
+
+        Parameters
+        ----------
+        row
+            Instance of a database model class.
+        eager_load
+            If True, fully eager loads sqlmodel relationships with model return.
+
+        Returns
+        -------
+        Updated row instance.
+
+        Raises
+        ------
+        SQLAlchemyError
+            Database row failed to write.
+        """
+        with self.session() as session:
+            session.add(row)
+            session.commit()
+            session.refresh(row)
+
+            if eager_load:  # Add eager loading for all relationships
+                model = type(row)
+                statement = select(model)
+                for rel_name in model.__sqlmodel_relationships__:
+                    statement = statement.options(
+                        selectinload(getattr(model, rel_name))
+                    )
+                matches = session.exec(statement).first()
+                if not matches:
+                    msg = f"{row = } did not add to database."
+                    raise RuntimeError(msg)
+                return matches
+
+            return row
+
+    def delete(self, row: SQLModelT) -> None:
+        """
+        Delete a row from the database.
+
+        Parameters
+        ----------
+        row
+            Instance of a database model class.
+        """
+        with self.session() as session:
+            session.delete(row)
+            session.commit()
+
+    def find(
+        self,
+        row: SQLModelT,
+        *,
+        eager_load: bool = False,
+        exclude_defaults: bool = True,
+        exclude_id: bool = False,
+    ) -> Iterator[SQLModelT]:
+        """
+        Find matching rows in database.
+
+        If no matches, adds and yields row instance.
+
+        Parameters
+        ----------
+        row
+            Instance of a database model class.
+        session
+            (Optional) Instance of an active session.
+        eager_load
+            If True, fully eager loads sqlmodel relationships with model return.
+        exclude_defaults
+            If True, exclude default values from model dump.
+        exclude_id
+            If True, exclude id field from model dump (if applicable).
+
+        Yields
+        ------
+            Instance of a database "model".
+        """
+        data = row_to_dict(
+            row, exclude_defaults=exclude_defaults, exclude_id=exclude_id
+        )
+        with self.session() as session:
+            model = type(row)
+            statement = select(model)
+
+            for k, v in data.items():
+                statement = statement.where(getattr(model, k) == v)
+
+            if eager_load:  # Add eager loading for all relationships
+                for rel_name in model.__sqlmodel_relationships__:
+                    statement = statement.options(
+                        selectinload(getattr(model, rel_name))
+                    )
+
+        yield from session.exec(statement)
+
+    def find_or_add(
+        self,
+        row: SQLModelT,
+        *,
+        eager_load: bool = False,
+        exclude_defaults: bool = True,
+        exclude_id: bool = False,
+    ) -> Iterator[SQLModelT]:
+        """
+        Find matching rows in database.
+
+        If no matches, adds and yields row instance.
+
+        Parameters
+        ----------
+        row
+            Instance of a database model class.
+        eager_load
+            If True, fully eager loads sqlmodel relationships with model return.
+        exclude_defaults
+            If True, exclude default values from model dump.
+        exclude_id
+            If True, exclude id field from model dump (if applicable).
+
+        Yields
+        ------
+            Instance of a database "model".
+        """
+        # Flag to avoid loading the whole iterator into memory.
+        found_any = False
+
+        for matching_row in self.find(
+            row,
+            eager_load=eager_load,
+            exclude_defaults=exclude_defaults,
+            exclude_id=exclude_id,
+        ):
+            found_any = True
+            yield matching_row
+
+        if not found_any:
+            yield self.add(row=row)
+
+    def close(self) -> None:
+        """Close the database connection.
+
+        Seems to be needed only for testing with in-memory databases.
+        """
+        self.engine.dispose()

autostorage-0.0.7/src/autostorage/models/__init__.py

@@ -0,0 +1,45 @@
+"""SQLModel row definitions.
+
+Layers to avoid circular imports at load time:
+    links
+  → geometry
+  → calculation
+  → data
+  → stationary
+  → reaction
+  → listeners
+"""
+
+from . import listeners  # 1st registers @event.listens_for  # noqa: F401
+from .calculation import CalculationHashRow, CalculationRow, ProvenanceRow
+from .data import EnergyRow
+from .geometry import GeometryRow
+from .links import (
+    CalculationGeometryLink,
+    StationaryIdentityLink,
+    StationaryStageLink,
+)
+from .reaction import StageRow, StepRow
+from .stationary import IdentityRow, MetricRow, StationaryPointRow
+
+__all__ = [
+    # links
+    "CalculationGeometryLink",
+    "StationaryIdentityLink",
+    "StationaryStageLink",
+    # geometry
+    "GeometryRow",
+    # calculation
+    "CalculationRow",
+    "ProvenanceRow",
+    "CalculationHashRow",
+    # data
+    "EnergyRow",
+    # stationary
+    "StationaryPointRow",
+    "IdentityRow",
+    "MetricRow",
+    # reaction
+    "StageRow",
+    "StepRow",
+]