stjames 0.0.39__py3-none-any.whl → 0.0.41__py3-none-any.whl

stjames/settings.py

@@ -5,7 +5,7 @@ import pydantic
 from .base import Base, UniqueList
 from .basis_set import BasisSet
 from .correction import Correction
-from .method import Method
+from .method import METHODS_WITH_CORRECTION, PREPACKAGED_METHODS, Method
 from .mode import Mode
 from .opt_settings import OptimizationSettings
 from .scf_settings import SCFSettings
@@ -13,26 +13,7 @@ from .solvent import SolventSettings
 from .task import Task
 from .thermochem_settings import ThermochemistrySettings
 
-PREPACKAGED_METHODS = [
-    Method.HF3C,
-    Method.B973C,
-    Method.R2SCAN3C,
-    Method.AIMNET2_WB97MD3,
-    Method.GFN2_XTB,
-    Method.GFN1_XTB,
-    Method.GFN0_XTB,
-    Method.GFN_FF,
-]
-
-METHODS_WITH_CORRECTION = [
-    Method.WB97XD3,
-    Method.WB97XV,
-    Method.WB97MV,
-    Method.WB97MD3BJ,
-    Method.DSDBLYPD3BJ,
-]
-
-T = TypeVar("T")
+_T = TypeVar("_T")
 
 
 class Settings(Base):
@@ -51,7 +32,8 @@ class Settings(Base):
     thermochem_settings: ThermochemistrySettings = ThermochemistrySettings()
 
     # mypy has this dead wrong (https://docs.pydantic.dev/2.0/usage/computed_fields/)
-    @pydantic.computed_field  # type: ignore[misc]
+    # Python 3.12 narrows the reason for the ignore to prop-decorator
+    @pydantic.computed_field  # type: ignore[misc, prop-decorator, unused-ignore]
     @property
     def level_of_theory(self) -> str:
         corrections = list(filter(lambda x: x not in (None, ""), self.corrections))
@@ -81,11 +63,15 @@ class Settings(Base):
         if self.method == Method.HF3C:
             self.basis_set = BasisSet(name="minix")
         elif self.method == Method.B973C:
-            self.basis_set = BasisSet(name="mTZVP")
+            self.basis_set = BasisSet(name="def2-mTZVP")
+        elif self.method == Method.R2SCAN3C:
+            self.basis_set = BasisSet(name="def2-mTZVPP")
+        elif self.method == Method.WB97X3C:
+            self.basis_set = BasisSet(name="vDZP")
 
     @pydantic.field_validator("basis_set", mode="before")
     @classmethod
-    def parse_basis_set(cls, v: Any) -> BasisSet | dict | None:
+    def parse_basis_set(cls, v: Any) -> BasisSet | dict[str, Any] | None:
         """Turn a string into a ``BasisSet`` object. (This is a little crude.)"""
         if isinstance(v, BasisSet):
             return None if v.name is None else v
@@ -103,9 +89,9 @@ class Settings(Base):
 
     @pydantic.field_validator("corrections", mode="before")
     @classmethod
-    def remove_empty_string(cls, v: list[T]) -> list[T]:
+    def remove_empty_string(cls, v: list[_T]) -> list[_T]:
         """Remove empty string values."""
-        return [c for c in v if c]
+        return [c for c in v if c] if v is not None else v
 
 
 def _assign_settings_by_mode(settings: Settings) -> None:
@@ -198,25 +184,26 @@ def _assign_settings_by_mode(settings: Settings) -> None:
 
     # cf. DLFIND manual, and https://www.cup.uni-muenchen.de/ch/compchem/geom/basic.html
     # and the discussion at https://geometric.readthedocs.io/en/latest/how-it-works.html
+    # in periodic systems, "normal" is 0.05 eV/Å ~= 2e-3 Hartree/Å, and "careful" is 0.01 ~= 4e-4
     if mode == Mode.RECKLESS:
-        opt_settings.energy_threshold = 1e-5
-        opt_settings.max_gradient_threshold = 4.5e-3
-        opt_settings.rms_gradient_threshold = 3e-3
-    elif (mode == Mode.RAPID) or (mode == Mode.CAREFUL and has_constraints):
+        opt_settings.energy_threshold = 2e-5
+        opt_settings.max_gradient_threshold = 7e-3
+        opt_settings.rms_gradient_threshold = 6e-3
+    elif mode == Mode.RAPID or (mode == Mode.CAREFUL and has_constraints):
         opt_settings.energy_threshold = 5e-5
-        opt_settings.max_gradient_threshold = 2.5e-3
-        opt_settings.rms_gradient_threshold = 1.7e-3
-    elif mode == Mode.CAREFUL or (mode == mode.METICULOUS and has_constraints):
+        opt_settings.max_gradient_threshold = 5e-3
+        opt_settings.rms_gradient_threshold = 3.5e-3
+    elif mode == Mode.CAREFUL or (mode == Mode.METICULOUS and has_constraints):
         opt_settings.energy_threshold = 1e-6
-        opt_settings.max_gradient_threshold = 4.5e-4
-        opt_settings.rms_gradient_threshold = 3e-4
+        opt_settings.max_gradient_threshold = 9e-4
+        opt_settings.rms_gradient_threshold = 6e-4
     elif mode == Mode.METICULOUS:
         opt_settings.energy_threshold = 1e-6
-        opt_settings.max_gradient_threshold = 1.5e-5
-        opt_settings.rms_gradient_threshold = 1e-5
+        opt_settings.max_gradient_threshold = 3e-5
+        opt_settings.rms_gradient_threshold = 2e-5
     elif mode == Mode.DEBUG:
         opt_settings.energy_threshold = 1e-6
-        opt_settings.max_gradient_threshold = 2e-6
-        opt_settings.rms_gradient_threshold = 1e-6
+        opt_settings.max_gradient_threshold = 4e-6
+        opt_settings.rms_gradient_threshold = 2e-6
     else:
         raise ValueError(f"Unknown mode ``{mode.value}``!")

stjames/solvent.py

@@ -35,6 +35,8 @@ class SolventModel(LowercaseStrEnum):
     CPCM = "cpcm"
     ALPB = "alpb"
     COSMO = "cosmo"
+    GBSA = "gbsa"
+    CPCMX = "cpcmx"
 
 
 class SolventSettings(Base):

stjames/task.py

@@ -11,3 +11,4 @@ class Task(LowercaseStrEnum):
     DIPOLE = "dipole"
     HESSIAN = "hessian"
     FREQUENCIES = "frequencies"
+    STRESS = "stress"

stjames/types.py

@@ -0,0 +1,8 @@
+from typing import TypeAlias
+
+UUID: TypeAlias = str
+
+Vector3D: TypeAlias = tuple[float, float, float]
+Vector3DPerAtom: TypeAlias = list[Vector3D]
+
+Matrix3x3: TypeAlias = tuple[Vector3D, Vector3D, Vector3D]

stjames/workflows/__init__.py

@@ -1,7 +1,13 @@
+from .admet import *
+from .basic_calculation import *
+from .bde import *
 from .conformer import *
 from .descriptors import *
 from .fukui import *
+from .molecular_dynamics import *
+from .multistage_opt import *
 from .pka import *
 from .redox_potential import *
 from .scan import *
+from .spin_states import *
 from .tautomer import *

stjames/workflows/admet.py

@@ -0,0 +1,7 @@
+from typing import Optional
+
+from .workflow import Workflow
+
+
+class ADMETWorkflow(Workflow):
+    properties: Optional[dict[str, float | int]] = None

stjames/workflows/basic_calculation.py

@@ -0,0 +1,9 @@
+from ..settings import Settings
+from ..types import UUID
+from .workflow import Workflow
+
+
+class BasicCalculationWorkflow(Workflow):
+    settings: Settings
+    engine: str
+    calculation_uuid: UUID | None = None

stjames/workflows/bde.py

@@ -0,0 +1,269 @@
+"""Bond Dissociation Energy (BDE) workflow."""
+
+import itertools
+from typing import Any, Iterable, Self, TypeVar
+
+from pydantic import BaseModel, Field, PositiveInt, ValidationInfo, field_validator, model_validator
+
+from ..mode import Mode
+from ..molecule import Molecule
+from ..types import UUID
+from .multistage_opt import MultiStageOptMixin
+from .workflow import Workflow
+
+# the id of a mutable object may change, thus using object()
+_sentinel_mso_mode = object()
+_T = TypeVar("_T")
+
+
+class BDE(BaseModel):
+    """
+    Bond Dissociation Energy (BDE) result.
+
+    energy => (E_{fragment1} + E_{fragment2}) - E_{starting molecule}
+
+    :param fragment_idxs: indices of the atoms in the fragment that was dissociated (1-indexed)
+    :param energy: BDE in kcal/mol
+    :param fragment_energies: energy of fragments
+    :param calculations_uuids: calculation UUIDs
+    """
+
+    fragment_idxs: tuple[PositiveInt, ...]
+    energy: float | None
+    fragment_energies: tuple[float | None, float | None]
+    calculation_uuids: tuple[list[UUID | None], list[UUID | None]]
+
+    def __str__(self) -> str:
+        return repr(self)
+
+    def __repr__(self) -> str:
+        """
+        Return a string representation of the BDE result.
+
+        >>> BDE(fragment_idxs=(1, 2), energy=1.0, fragment_energies=(4, 2), calculation_uuids=([], []))
+        <BDE (1, 2)  1.00>
+        """
+        energy = "None" if self.energy is None else f"{self.energy:>5.2f}"
+
+        return f"<{type(self).__name__} {self.fragment_idxs} {energy}>"
+
+
+class BDEWorkflow(Workflow, MultiStageOptMixin):
+    """
+    Bond Dissociation Energy (BDE) workflow.
+
+    Uses the modes from MultiStageOptSettings to compute BDEs.
+
+    Inherited:
+    :param initial_molecule: Molecule of interest
+    :param multistage_opt_settings: set by mode unless mode=MANUAL (ignores additional settings if set)
+    :param solvent: solvent to use
+    :param xtb_preopt: pre-optimize with xtb (sets based on mode when None)
+
+    Overridden:
+    :param mso_mode: Mode for MultiStageOptSettings
+    :param frequencies: whether to calculate frequencies
+
+    Turned off:
+    :param constraints: constraints to add (not supported)
+    :param transition_state: whether this is a transition state (not supported)
+
+    New:
+    :param mode: Mode for workflow
+    :param optimize_fragments: whether to optimize the fragments, or just the starting molecule (default depends on mode)
+    :param atoms: atoms to dissociate (1-indexed)
+    :param fragment_indices: fragments to dissociate (all fields feed into this, 1-indexed)
+    :param all_CH: dissociate all C–H bonds
+    :param all_CX: dissociate all C–X bonds (X ∈ {F, Cl, Br, I, At, Ts})
+    :param optimization_calculation_uuids: UUIDs of initial optimization calculations
+    :param optimization_energy: energy of optimized initial molecule
+    :param bdes: BDE results
+    """
+
+    mode: Mode
+    mso_mode: Mode = _sentinel_mso_mode  # type: ignore [assignment]
+    frequencies: bool = False
+    optimize_fragments: bool = None  # type: ignore [assignment]
+
+    atoms: tuple[PositiveInt, ...] = Field(default_factory=tuple)
+    fragment_indices: tuple[tuple[PositiveInt, ...], ...] = Field(default_factory=tuple)
+
+    all_CH: bool = False
+    all_CX: bool = False
+
+    # Results
+    optimization_calculation_uuids: list[UUID | None] | None = None
+    optimization_energy: float | None = None
+    bdes: list[BDE] = Field(default_factory=list)
+
+    def __str__(self) -> str:
+        r"""
+        Return a string representation of the BDE workflow.
+
+        >>> print(BDEWorkflow(initial_molecule=Molecule.from_xyz("H 0 0 0\nF 0 0 1"), mode=Mode.METICULOUS, atoms=[1, 2]))
+        BDEWorkflow METICULOUS
+        (1,)
+        (2,)
+        """
+        return f"{type(self).__name__} {self.mode.name}\n" + "\n".join(map(str, self.fragment_indices))
+
+    def __repr__(self) -> str:
+        """
+        Return a string representation of the BDE workflow.
+
+        >>> BDEWorkflow(initial_molecule=Molecule.from_xyz("He 0 0 0"), mode=Mode.METICULOUS, atoms=[])
+        <BDEWorkflow METICULOUS>
+        """
+        return f"<{type(self).__name__} {self.mode.name}>"
+
+    @property
+    def energies(self) -> tuple[float | None, ...]:
+        return tuple(bde.energy for bde in self.bdes)
+
+    @field_validator("constraints", "transition_state")
+    @classmethod
+    def turned_off(cls, value: _T, info: ValidationInfo) -> _T:
+        if value:
+            raise ValueError(f"{info.field_name} not supported in BDE workflows.")
+
+        return value
+
+    @field_validator("mode")
+    @classmethod
+    def set_mode_auto(cls, mode: Mode) -> Mode:
+        if mode == Mode.AUTO:
+            return Mode.RAPID
+
+        return mode
+
+    @field_validator("initial_molecule", mode="before")
+    @classmethod
+    def no_charge_or_spin(cls, mol: Molecule) -> Molecule:
+        """Ensure the molecule has no charge or spin."""
+        if mol.charge != 0 or mol.multiplicity != 1:
+            raise ValueError("Charge and spin partitioning undefined for BDE, only neutral singlet molecules supported.")
+
+        return mol
+
+    @model_validator(mode="before")
+    @classmethod
+    def set_mso_mode(cls, values: dict[str, Any]) -> dict[str, Any]:
+        """Set the MultiStageOptSettings mode to match current BDE mode."""
+        values["mso_mode"] = values["mode"]
+        return values
+
+    @model_validator(mode="after")
+    def validate_and_build(self) -> Self:
+        """Validate atomic numbers and build the atoms field."""
+        self.atoms = tuple(self.atoms)
+        self.fragment_indices = tuple(map(tuple, self.fragment_indices))
+
+        match self.mode:
+            case Mode.RECKLESS | Mode.RAPID:
+                # Default off
+                self.optimize_fragments = self.optimize_fragments or False
+            case Mode.CAREFUL | Mode.METICULOUS:
+                # Default on
+                self.optimize_fragments = self.optimize_fragments or self.optimize_fragments is None
+            case _:
+                raise NotImplementedError(f"{self.mode} not implemented.")
+
+        for atom in self.atoms:
+            if atom > len(self.initial_molecule):
+                raise ValueError(f"{atom=} is out of range.")
+        for fragment_idxs in self.fragment_indices:
+            if any(a > len(self.initial_molecule) for a in fragment_idxs):
+                raise ValueError(f"{fragment_idxs=} contains atoms that are out of range.")
+
+        if self.all_CH:
+            self.atoms = self.atoms + tuple(H for _C, H in find_CH_bonds(self.initial_molecule))
+        if self.all_CX:
+            self.atoms = self.atoms + tuple(X for _C, X in find_CX_bonds(self.initial_molecule))
+
+        # Combine atoms and fragments, remove duplicates, and sort
+        self.fragment_indices = self.fragment_indices + tuple((a,) for a in self.atoms)
+        assert isinstance(self.fragment_indices, tuple)
+        self.fragment_indices = tuple(sorted(set(self.fragment_indices)))
+
+        return self
+
+
+def atomic_number_indices(molecule: Molecule, atomic_numbers: set[PositiveInt] | PositiveInt) -> tuple[PositiveInt, ...]:
+    r"""
+    Return the indices of the atoms with the given atomic numbers.
+
+    :param molecule: Molecule of interest
+    :param atomic_numbers: atomic number(s) of interest
+
+    >>> H2O = Molecule.from_xyz("H 0 0 0\nO 0 0 1\nH 0 1 1")
+    >>> atomic_number_indices(H2O, 1)
+    (1, 3)
+    >>> atomic_number_indices(H2O, {8, 1})
+    (1, 2, 3)
+    >>> atomic_number_indices(H2O, {6, 9})
+    ()
+    """
+    if isinstance(atomic_numbers, int):
+        return tuple(i for i, an in enumerate(molecule.atomic_numbers, start=1) if an == atomic_numbers)
+    return tuple(i for i, an in enumerate(molecule.atomic_numbers, start=1) if an in atomic_numbers)
+
+
+def find_CH_bonds(molecule: Molecule, distance_max: float = 1.2) -> Iterable[tuple[PositiveInt, PositiveInt]]:
+    r"""
+    Find all C–H bonds in the molecule.
+
+    :param molecule: Molecule of interest
+    :param distance_max: distance max for bond
+
+    >>> H2O = Molecule.from_xyz("H 0 0 0\nO 0 0 1\nH 0 1 1")
+    >>> CH4 = Molecule.from_xyz("C 0 0 0\nH 0 0 1\nH 0 1 0\nH 1 0 0\nH 0 0 -1")
+    >>> ethane = Molecule.from_xyz("C -1 0 0\nC 1 0 0\nH -1 0 1\nH -1 0 -1\nH -1 1 0\nH 1 0 1\nH 1 0 -1\nH 1 1 0")
+    >>> list(find_CH_bonds(H2O))
+    []
+    >>> list(find_CH_bonds(CH4))
+    [(1, 2), (1, 3), (1, 4), (1, 5)]
+    >>> list(find_CH_bonds(ethane))
+    [(1, 3), (1, 4), (1, 5), (2, 6), (2, 7), (2, 8)]
+    """
+    yield from find_AB_bonds(molecule, 6, 1, distance_max)
+
+
+def find_CX_bonds(molecule: Molecule) -> Iterable[tuple[PositiveInt, PositiveInt]]:
+    r"""
+    Find all C–X bonds in the molecule.
+
+    :param molecule: Molecule of interest
+    :param distance_max: distance max for bond
+
+    >>> HCF = Molecule.from_xyz("H 0 0 0\nC 0 0 1\nF 0 1 1")
+    >>> list(find_CX_bonds(HCF))
+    [(2, 3)]
+    """
+    halogens = {9: 2.0, 17: 2.2, 35: 2.5, 53: 2.8, 85: 3.0, 117: 4.0}
+    yield from itertools.chain.from_iterable(find_AB_bonds(molecule, 6, x, distance) for x, distance in halogens.items())
+
+
+def find_AB_bonds(molecule: Molecule, a: int, b: int, distance_max: float) -> Iterable[tuple[PositiveInt, PositiveInt]]:
+    r"""
+    Find all A–B bonds in the molecule.
+
+    :param molecule: Molecule of interest
+    :param a: atomic number of atom A
+    :param b: atomic number of atom B
+    :param distance_max: distance max for bond
+
+    >>> H2O = Molecule.from_xyz("H 0 0 0\nO 0 0 1\nH 0 1 1")
+    >>> list(find_AB_bonds(H2O, 8, 1, 1.1))
+    [(2, 1), (2, 3)]
+    """
+
+    def close(idxs: tuple[PositiveInt, PositiveInt]) -> bool:
+        return molecule.distance(*idxs) < distance_max
+
+    yield from filter(
+        close,
+        itertools.product(
+            atomic_number_indices(molecule, a),
+            atomic_number_indices(molecule, b),
+        ),
+    )

stjames/workflows/conformer.py

@@ -13,6 +13,7 @@ class ConformerSettings(Base):
     num_confs_taken: int = 50
     rmsd_cutoff: float = 0.1
 
+    transition_state: bool = False
     final_method: Method = Method.AIMNET2_WB97MD3
     solvent: Optional[Solvent] = Solvent.WATER
     max_energy: float = 5

stjames/workflows/descriptors.py

@@ -1,3 +1,4 @@
+from ..types import UUID
 from .workflow import Workflow
 
 Descriptors = dict[str, dict[str, float] | tuple[float | None, ...] | float]
@@ -5,6 +6,6 @@ Descriptors = dict[str, dict[str, float] | tuple[float | None, ...] | float]
 
 class DescriptorsWorkflow(Workflow):
     # uuid of optimization
-    optimization: str | None = None
+    optimization: UUID | None = None
 
     descriptors: Descriptors | None = None

stjames/workflows/fukui.py

@@ -1,13 +1,12 @@
-from typing import Optional
-
+from ..types import UUID
 from .workflow import Workflow
 
 
 class FukuiIndexWorkflow(Workflow):
     # uuid of optimization
-    optimization: Optional[str] = None
+    optimization: UUID | None = None
 
-    global_electrophilicity_index: Optional[float] = None
-    fukui_positive: Optional[list[float]] = None
-    fukui_negative: Optional[list[float]] = None
-    fukui_zero: Optional[list[float]] = None
+    global_electrophilicity_index: float | None = None
+    fukui_positive: list[float] | None = None
+    fukui_negative: list[float] | None = None
+    fukui_zero: list[float] | None = None

stjames/workflows/molecular_dynamics.py

@@ -0,0 +1,60 @@
+from typing import Self
+
+from pydantic import PositiveFloat, PositiveInt, model_validator
+
+from ..base import Base, LowercaseStrEnum
+from ..constraint import PairwiseHarmonicConstraint, SphericalHarmonicConstraint
+from ..settings import Settings
+from ..types import UUID
+from .workflow import Workflow
+
+
+class ThermodynamicEnsemble(LowercaseStrEnum):
+    NPT = "npt"
+    NVT = "nvt"
+    NVE = "nve"
+
+
+class Frame(Base):
+    index: int  # what number frame this is within the MD simulation
+
+    uuid: UUID | None = None  # UUID of molecule
+
+    pressure: float
+    temperature: float
+    energy: float
+
+
+class MolecularDynamicsSettings(Base):
+    ensemble: ThermodynamicEnsemble = ThermodynamicEnsemble.NVT
+
+    timestep: PositiveFloat = 1.0  # fs
+    num_steps: PositiveInt = 500
+
+    confining_constraint: SphericalHarmonicConstraint | None = None
+
+    temperature: PositiveFloat | None = 300  # K
+    pressure: PositiveFloat | None = None  # atm
+
+    langevin_thermostat_timescale: PositiveFloat = 100  # fs
+    berendsen_barostat_timescale: PositiveFloat = 1000  # fs
+
+    constraints: list[PairwiseHarmonicConstraint] = []
+
+    @model_validator(mode="after")
+    def validate_ensemble_settings(self) -> Self:
+        """Check that NVT ensemble always has temperature defined, and that NPT has temp and pressure defined."""
+        if self.ensemble == ThermodynamicEnsemble.NVT and self.temperature is None:
+            raise ValueError("NVT ensemble must have a temperature defined")
+        if self.ensemble == ThermodynamicEnsemble.NPT and (self.temperature is None or self.pressure is None):
+            raise ValueError("NPT ensemble must have both temperature and pressure defined")
+        return self
+
+
+class MolecularDynamicsWorkflow(Workflow):
+    settings: MolecularDynamicsSettings
+    calc_settings: Settings
+    calc_engine: str | None = None
+
+    # uuids of scan points
+    frames: list[Frame] = []