stjames 0.0.43__tar.gz → 0.0.45__tar.gz

{stjames-0.0.43/stjames.egg-info → stjames-0.0.45}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: stjames
-Version: 0.0.43
+Version: 0.0.45
 Summary: standardized JSON atom/molecule encoding scheme
 Author-email: Corin Wagen <corin@rowansci.com>
 Project-URL: Homepage, https://github.com/rowansci/stjames

{stjames-0.0.43 → stjames-0.0.45}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "stjames"
-version = "0.0.43"
+version = "0.0.45"
 description = "standardized JSON atom/molecule encoding scheme"
 readme = "README.md"
 requires-python = ">=3.11"

stjames-0.0.45/stjames/constraint.py

@@ -0,0 +1,70 @@
+from typing import Optional, Self
+
+from pydantic import PositiveFloat, PositiveInt, model_validator
+
+from .base import Base, LowercaseStrEnum
+
+
+class ConstraintType(LowercaseStrEnum):
+    """Different sorts of constraints."""
+
+    BOND = "bond"
+    ANGLE = "angle"
+    DIHEDRAL = "dihedral"
+
+
+class Constraint(Base):
+    """
+    Represents a single (absolute) constraint.
+
+    :param constraint_type: which type
+    :param atoms: the atoms in question
+    :param value: the value to constrain this to, leaving this blank sets the current value
+    """
+
+    constraint_type: ConstraintType
+    atoms: list[PositiveInt]  # 1-indexed
+    value: Optional[float] = None
+
+    @model_validator(mode="after")
+    def check_atom_list_length(self) -> Self:
+        match self.constraint_type:
+            case ConstraintType.BOND:
+                if len(self.atoms) != 2:
+                    raise ValueError("Bond constraint needs two atom indices!")
+            case ConstraintType.ANGLE:
+                if len(self.atoms) != 3:
+                    raise ValueError("Angle constraint needs three atom indices!")
+            case ConstraintType.DIHEDRAL:
+                if len(self.atoms) != 4:
+                    raise ValueError("Dihedral constraint needs four atom indices!")
+            case _:
+                raise ValueError("Unknown constraint_type!")
+
+        return self
+
+
+class PairwiseHarmonicConstraint(Base):
+    """
+    Represents a harmonic constraint, with a characteristic spring constant.
+
+    :param atoms: whch atoms to apply to
+    :param force_constant: the strength of the attraction, in kcal/mol/Å
+    :param equilibrium: the distance at which force is zero
+    """
+
+    atoms: tuple[PositiveInt, PositiveInt]  # 1-indexed
+    force_constant: PositiveFloat  # kcal/mol / Å**2
+    equilibrium: PositiveFloat  # Å
+
+
+class SphericalHarmonicConstraint(Base):
+    """
+    Represents a spherical harmonic constraint to keep a system near the origin.
+
+    :param confining radius: the confining radius, in Å
+    :param force_constant: the strength of the confinement, in kcal/mol/Å
+    """
+
+    confining_radius: PositiveFloat
+    force_constant: PositiveFloat = 10  # kcal/mol / Å**2

{stjames-0.0.43 → stjames-0.0.45}/stjames/correction.py

@@ -10,5 +10,8 @@ class Correction(LowercaseStrEnum):
     # Grimme's D3 dispersion correction, *without* Becke–Johnson damping
     D3 = "d3"
 
+    # Grimme's D4 dispersion correction
+    D4 = "d4"
+
     # Grimme's geometric counterpoise correction
     GCP = "gcp"

stjames-0.0.45/stjames/method.py

@@ -0,0 +1,60 @@
+from typing import Literal
+
+from .base import LowercaseStrEnum
+
+
+class Method(LowercaseStrEnum):
+    HARTREE_FOCK = "hf"
+    HF3C = "hf_3c"
+
+    PBE = "pbe"
+    B973C = "b97_3c"
+    B97D3BJ = "b97_d3bj"
+    R2SCAN = "r2scan"
+    R2SCAN3C = "r2scan_3c"
+    TPSS = "tpss"
+    M06L = "m06l"
+
+    PBE0 = "pbe0"
+    B3LYP = "b3lyp"
+    TPSSH = "tpssh"
+    M06 = "m06"
+    M062X = "m062x"
+
+    CAMB3LYP = "camb3lyp"
+    WB97XD3 = "wb97x_d3"
+    WB97XV = "wb97x_v"
+    WB97MV = "wb97m_v"
+    WB97MD3BJ = "wb97m_d3bj"
+    WB97X3C = "wb97x_3c"
+
+    DSDBLYPD3BJ = "dsd_blyp_d3bj"
+
+    AIMNET2_WB97MD3 = "aimnet2_wb97md3"
+    MACE_MP_0 = "mace_mp_0"
+    OCP24_S = "ocp24_s"
+    OCP24_L = "ocp24_l"
+
+    GFN_FF = "gfn_ff"
+    GFN0_XTB = "gfn0_xtb"
+    GFN1_XTB = "gfn1_xtb"
+    GFN2_XTB = "gfn2_xtb"
+
+    # this was going to be removed, but Jonathon wrote such a nice basis set test... it's off the front end.
+    BP86 = "bp86"
+
+
+NNPMethod = Literal[Method.AIMNET2_WB97MD3]
+NNP_METHODS = [Method.AIMNET2_WB97MD3]
+
+XTBMethod = Literal[Method.GFN_FF, Method.GFN0_XTB, Method.GFN1_XTB, Method.GFN2_XTB]
+XTB_METHODS = [Method.GFN_FF, Method.GFN0_XTB, Method.GFN1_XTB, Method.GFN2_XTB]
+
+CompositeMethod = Literal[Method.HF3C, Method.B973C, Method.R2SCAN3C, Method.WB97X3C]
+COMPOSITE_METHODS = [Method.HF3C, Method.B973C, Method.R2SCAN3C, Method.WB97X3C]
+
+PrepackagedMethod = XTBMethod | CompositeMethod | NNPMethod
+PREPACKAGED_METHODS = [*XTB_METHODS, *COMPOSITE_METHODS]
+
+MethodWithCorrection = Literal[Method.WB97XD3, Method.WB97XV, Method.WB97MV, Method.WB97MD3BJ, Method.DSDBLYPD3BJ]
+METHODS_WITH_CORRECTION = [Method.WB97XD3, Method.WB97XV, Method.WB97MV, Method.WB97MD3BJ, Method.DSDBLYPD3BJ, Method.B97D3BJ]

{stjames-0.0.43 → stjames-0.0.45}/stjames/molecule.py

@@ -8,7 +8,7 @@ from pydantic import NonNegativeInt, PositiveInt, ValidationError
 from .atom import Atom
 from .base import Base
 from .periodic_cell import PeriodicCell
-from .types import Matrix3x3, Vector3D, Vector3DPerAtom
+from .types import FloatPerAtom, Matrix3x3, Vector3D, Vector3DPerAtom
 
 
 class MoleculeReadError(RuntimeError):
@@ -18,10 +18,8 @@ class MoleculeReadError(RuntimeError):
 class VibrationalMode(Base):
     frequency: float  # in cm-1
     reduced_mass: float  # amu
-
-    # todo - check units here?
-    force_constant: float
-    displacements: Vector3DPerAtom
+    force_constant: float  # mDyne/Å
+    displacements: Vector3DPerAtom  # Å
 
 
 class Molecule(Base):
@@ -44,8 +42,8 @@ class Molecule(Base):
 
     velocities: Optional[Vector3DPerAtom] = None  # Å/fs
 
-    mulliken_charges: Optional[list[float]] = None
-    mulliken_spin_densities: Optional[list[float]] = None
+    mulliken_charges: FloatPerAtom | None = None
+    mulliken_spin_densities: FloatPerAtom | None = None
     dipole: Optional[Vector3D] = None  # in Debye
 
     vibrational_modes: Optional[list[VibrationalMode]] = None
@@ -55,6 +53,8 @@ class Molecule(Base):
     thermal_enthalpy_corr: Optional[float] = None
     thermal_free_energy_corr: Optional[float] = None
 
+    smiles: Optional[str] = None
+
     def __len__(self) -> int:
         return len(self.atoms)
 

stjames-0.0.45/stjames/settings.py

@@ -0,0 +1,216 @@
+from typing import Any, Optional, Self, TypeVar
+
+from pydantic import computed_field, field_validator, model_validator
+
+from .base import Base, UniqueList
+from .basis_set import BasisSet
+from .correction import Correction
+from .method import METHODS_WITH_CORRECTION, PREPACKAGED_METHODS, Method
+from .mode import Mode
+from .opt_settings import OptimizationSettings
+from .scf_settings import SCFSettings
+from .solvent import SolventSettings
+from .task import Task
+from .thermochem_settings import ThermochemistrySettings
+
+_T = TypeVar("_T")
+
+
+class Settings(Base):
+    mode: Mode = Mode.AUTO
+
+    method: Method = Method.HARTREE_FOCK
+    basis_set: Optional[BasisSet] = None
+    tasks: UniqueList[Task] = [Task.ENERGY, Task.CHARGE, Task.DIPOLE]
+    corrections: UniqueList[Correction] = []
+
+    solvent_settings: Optional[SolventSettings] = None
+
+    # scf/opt settings will be set automatically based on mode, but can be overridden manually
+    scf_settings: SCFSettings = SCFSettings()
+    opt_settings: OptimizationSettings = OptimizationSettings()
+    thermochem_settings: ThermochemistrySettings = ThermochemistrySettings()
+
+    # mypy has this dead wrong (https://docs.pydantic.dev/2.0/usage/computed_fields/)
+    # Python 3.12 narrows the reason for the ignore to prop-decorator
+    @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))
+
+        if self.method in PREPACKAGED_METHODS or self.basis_set is None:
+            method = self.method.value
+        elif self.method in METHODS_WITH_CORRECTION or len(corrections) == 0:
+            method = f"{self.method.value}/{self.basis_set.name.lower()}"
+        else:
+            method = f"{self.method.value}-{'-'.join([c.value for c in corrections])}/{self.basis_set.name.lower()}"
+
+        if self.solvent_settings is not None:
+            method += f"/{self.solvent_settings.model.value}({self.solvent_settings.solvent.value})"
+
+        return method
+
+    @field_validator("mode")
+    @classmethod
+    def set_mode_auto(cls, mode: Mode) -> Mode:
+        """Set the mode to RAPID if AUTO is selected."""
+        if mode == Mode.AUTO:
+            return Mode.RAPID
+
+        return mode
+
+    @model_validator(mode="after")
+    def validate_and_build(self) -> Self:
+        if self.mode == Mode.AUTO:
+            self.mode = Mode.RAPID
+
+        self.scf_settings = _assign_scf_settings_by_mode(self.mode, self.scf_settings)
+        self.opt_settings = _assign_opt_settings_by_mode(self.mode, self.opt_settings)
+
+        return self
+
+    def model_post_init(self, __context: Any) -> None:
+        # figure out `optimize_ts`
+        if Task.OPTIMIZE_TS in self.tasks:
+            self.tasks.pop(self.tasks.index(Task.OPTIMIZE_TS))
+            self.tasks.append(Task.OPTIMIZE)
+            self.opt_settings.transition_state = True
+
+        # composite methods have their own basis sets, so overwrite user stuff
+        if self.method == Method.HF3C:
+            self.basis_set = BasisSet(name="minix")
+        elif self.method == Method.B973C:
+            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")
+
+    @field_validator("basis_set", mode="before")
+    @classmethod
+    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
+        elif isinstance(v, dict):
+            return None if v.get("name") is None else v
+        elif isinstance(v, str):
+            if len(v):
+                return BasisSet(name=v)
+            # "" is basically None, let's be real here...
+            return None
+        elif v is None:
+            return None
+        else:
+            raise ValueError(f"invalid value ``{v}`` for ``basis_set``")
+
+    @field_validator("corrections", mode="before")
+    @classmethod
+    def remove_empty_string(cls, v: list[_T]) -> list[_T]:
+        """Remove empty string values."""
+        return [c for c in v if c] if v is not None else v
+
+
+def _assign_scf_settings_by_mode(mode: Mode, scf_settings: SCFSettings) -> SCFSettings:
+    """
+    Assign SCF settings based on the mode.
+
+    Values based off of the following sources:
+    QChem:
+        - https://manual.q-chem.com/5.2/Ch4.S3.SS2.html
+        - https://manual.q-chem.com/5.2/Ch4.S5.SS2.html
+
+    Gaussian:
+        - https://gaussian.com/integral/
+        - https://gaussian.com/overlay5/
+
+    Orca:
+        - manual 4.2.1, §9.6.1 and §9.7.3
+
+    Psi4:
+        - https://psicode.org/psi4manual/master/autodir_options_c/module__scf.html
+        - https://psicode.org/psi4manual/master/autodoc_glossary_options_c.html
+
+    TeraChem:
+        - Manual, it's easy to locate everything.
+
+    The below values are my best attempt at homogenizing various sources.
+    In general, eri_threshold should be 3 OOM lower than SCF convergence.
+    """
+    if mode == Mode.MANUAL:
+        return scf_settings
+
+    match mode:
+        case Mode.RECKLESS:
+            scf_settings.energy_threshold = 1e-5
+            scf_settings.rms_error_threshold = 1e-7
+            scf_settings.max_error_threshold = 1e-5
+            scf_settings.rebuild_frequency = 100
+            scf_settings.int_settings.eri_threshold = 1e-8
+            scf_settings.int_settings.csam_multiplier = 3.0
+            scf_settings.int_settings.pair_overlap_threshold = 1e-8
+        case Mode.RAPID | Mode.CAREFUL:
+            scf_settings.energy_threshold = 1e-6
+            scf_settings.rms_error_threshold = 1e-9
+            scf_settings.max_error_threshold = 1e-7
+            scf_settings.rebuild_frequency = 10
+            scf_settings.int_settings.eri_threshold = 1e-10
+            scf_settings.int_settings.csam_multiplier = 1.0
+            scf_settings.int_settings.pair_overlap_threshold = 1e-10
+        case Mode.METICULOUS:
+            scf_settings.energy_threshold = 1e-8
+            scf_settings.rms_error_threshold = 1e-9
+            scf_settings.max_error_threshold = 1e-7
+            scf_settings.rebuild_frequency = 5
+            scf_settings.int_settings.eri_threshold = 1e-12
+            scf_settings.int_settings.csam_multiplier = 1.0
+            scf_settings.int_settings.pair_overlap_threshold = 1e-12
+        case Mode.DEBUG:
+            scf_settings.energy_threshold = 1e-9
+            scf_settings.rms_error_threshold = 1e-10
+            scf_settings.max_error_threshold = 1e-9
+            scf_settings.rebuild_frequency = 1
+            scf_settings.int_settings.eri_threshold = 1e-14
+            scf_settings.int_settings.csam_multiplier = 1e10  # in other words, disable CSAM
+            scf_settings.int_settings.pair_overlap_threshold = 1e-14
+        case _:
+            raise ValueError(f"Unknown mode ``{mode.value}``!")
+
+    return scf_settings
+
+
+def _assign_opt_settings_by_mode(mode: Mode, opt_settings: OptimizationSettings) -> OptimizationSettings:
+    """
+    Assign optimization settings based on the mode.
+
+    Constraints lead to a lot of noise, so we need to loosen the thresholds.
+
+    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
+
+    Note: thresholds here are in units of Hartree/Å, not Hartree/Bohr as listed in many places.
+    """
+    opt_settings.energy_threshold = 1e-6
+    match mode:
+        case Mode.RECKLESS:
+            opt_settings.energy_threshold = 2e-5
+            opt_settings.max_gradient_threshold = 7e-3
+            opt_settings.rms_gradient_threshold = 6e-3
+        case Mode.RAPID:
+            opt_settings.energy_threshold = 5e-5
+            opt_settings.max_gradient_threshold = 5e-3
+            opt_settings.rms_gradient_threshold = 3.5e-3
+        case Mode.CAREFUL:
+            opt_settings.max_gradient_threshold = 9e-4
+            opt_settings.rms_gradient_threshold = 6e-4
+        case Mode.METICULOUS:
+            opt_settings.max_gradient_threshold = 3e-5
+            opt_settings.rms_gradient_threshold = 2e-5
+        case Mode.DEBUG:
+            opt_settings.max_gradient_threshold = 4e-6
+            opt_settings.rms_gradient_threshold = 2e-6
+        case _:
+            raise ValueError(f"Unknown mode ``{mode.value}``!")
+
+    return opt_settings

{stjames-0.0.43 → stjames-0.0.45}/stjames/types.py

@@ -5,4 +5,6 @@ UUID: TypeAlias = str
 Vector3D: TypeAlias = tuple[float, float, float]
 Vector3DPerAtom: TypeAlias = list[Vector3D]
 
+FloatPerAtom: TypeAlias = list[float]
+
 Matrix3x3: TypeAlias = tuple[Vector3D, Vector3D, Vector3D]

{stjames-0.0.43 → stjames-0.0.45}/stjames/workflows/__init__.py

@@ -2,6 +2,7 @@ from .admet import *
 from .basic_calculation import *
 from .bde import *
 from .conformer import *
+from .conformer_search import *
 from .descriptors import *
 from .fukui import *
 from .molecular_dynamics import *

{stjames-0.0.43 → stjames-0.0.45}/stjames/workflows/bde.py

@@ -56,8 +56,9 @@ class BDEWorkflow(Workflow, MultiStageOptMixin):
 
     Inherited:
     :param initial_molecule: Molecule of interest
+    :param mode: Mode for workflow
     :param multistage_opt_settings: set by mode unless mode=MANUAL (ignores additional settings if set)
-    :param solvent: solvent to use
+    :param solvent: solvent to use for singlepoint
     :param xtb_preopt: pre-optimize with xtb (sets based on mode when None)
 
     Overridden:
@@ -69,7 +70,6 @@ class BDEWorkflow(Workflow, MultiStageOptMixin):
     :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)
@@ -80,7 +80,6 @@ class BDEWorkflow(Workflow, MultiStageOptMixin):
     :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]
@@ -107,14 +106,9 @@ class BDEWorkflow(Workflow, MultiStageOptMixin):
         """
         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 level_of_theory(self) -> str:
+        return self.multistage_opt_settings.level_of_theory
 
     @property
     def energies(self) -> tuple[float | None, ...]:
@@ -128,22 +122,21 @@ class BDEWorkflow(Workflow, MultiStageOptMixin):
 
         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:
+    def no_charge_or_spin(cls, val: Molecule | dict[str, Any]) -> Molecule | dict[str, Any]:
         """Ensure the molecule has no charge or spin."""
+        if isinstance(val, dict):
+            mol = Molecule(**val)
+        elif isinstance(val, Molecule):
+            mol = val
+        else:
+            raise ValueError(f"{val=} is not a Molecule.")
+
         if mol.charge != 0 or mol.multiplicity != 1:
             raise ValueError("Charge and spin partitioning undefined for BDE, only neutral singlet molecules supported.")
 
-        return mol
+        return val
 
     @model_validator(mode="before")
     @classmethod
@@ -159,10 +152,10 @@ class BDEWorkflow(Workflow, MultiStageOptMixin):
         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:
+            case Mode.RECKLESS:
+                # GFN-FF doesn't support open-shell species
+                self.optimize_fragments = False
+            case Mode.RAPID | Mode.CAREFUL | Mode.METICULOUS:
                 # Default on
                 self.optimize_fragments = self.optimize_fragments or self.optimize_fragments is None
             case _: