stjames 0.0.43__py3-none-any.whl → 0.0.45__py3-none-any.whl

stjames/workflows/conformer_search.py

@@ -0,0 +1,345 @@
+"""Conformer Search Workflow."""
+
+from abc import ABC
+from typing import Self, Sequence, TypeVar
+
+from pydantic import BaseModel, Field, field_validator, model_validator
+
+from ..base import LowercaseStrEnum
+from ..constraint import Constraint
+from ..method import Method, XTBMethod
+from ..mode import Mode
+from ..types import UUID
+from .multistage_opt import MultiStageOptMixin
+from .workflow import Workflow
+
+_sentinel = object()
+
+_T = TypeVar("_T")
+_U = TypeVar("_U")
+
+
+def check_sentinel(value: _T, default: _U) -> _T | _U:
+    """Return value unless _sentinel, then return default."""
+    return default if value is _sentinel else value
+
+
+class ScreeningSettings(BaseModel):
+    """
+    Settings for determing unique and useful conformers.
+
+    :param energy_threshhold: maximum relative energy for screening
+    :param rotational_constants_threshhold: maximum difference in rotational constants for screening
+    :param rmsd: cartesian RMSD for screening
+    :param max_confs: maximum number of conformers to keep
+    """
+
+    energy_threshhold: float | None = None  # kcal/mol
+    rotational_constants_threshhold: float | None = 0.02
+    rmsd: float | None = 0.25
+    max_confs: int | None = None
+
+
+class ConformerGenSettings(BaseModel):
+    """
+    Conformer generation settings.
+
+    Conformers are generated and an initial screening is performed to remove duplicates and high-energy conformers.
+
+    :param mode: Mode for calculations
+    :param conf_opt_method: method for the optimization
+    :param screening: post-generation screening settings
+    :param constraints: constraints for conformer generation
+    :param nci: add a constraining potential for non-covalent interactions
+    :param max_confs: maximum number of conformers to keep
+    """
+
+    mode: Mode = Mode.RAPID
+    conf_opt_method: XTBMethod = Method.GFN_FF
+    screening: ScreeningSettings | None = None
+    constraints: Sequence[Constraint] = tuple()
+    nci: bool = False
+    max_confs: int | None = None
+
+    def __str__(self) -> str:
+        """Return a string representation of the ConformerGenSettings."""
+        return repr(self)
+
+    def __repr__(self) -> str:
+        """Return a string representation of the ConformerGenSettings."""
+        return f"<{type(self).__name__} {self.mode.name}>"
+
+
+class ETKDGSettings(ConformerGenSettings):
+    """
+    Settings for ETKDG conformer generation.
+
+    Inherited:
+    :param mode: Mode for calculations
+    :param screening: post-generation screening settings
+    :param constraints: constraints for conformer generation
+    :param nci: add a constraining potential for non-covalent interactions (not supported in ETKDG)
+    :param conf_opt_method: method for the optimization
+
+    New:
+    :param num_initial_confs: number of initial conformers to generate
+    :param num_confs_considered: number of conformers to consider for optimization
+    :param num_confs_taken: number of final conformers to take
+    :param max_mmff_energy: MMFF energy cutoff
+    :param max_mmff_iterations: MMFF optimization iterations
+    :param max_confs: maximum number of conformers to keep
+    """
+
+    num_initial_confs: int = 300
+    num_confs_considered: int = 100
+    max_mmff_iterations: int = 500
+    max_mmff_energy: float | None = 30
+
+    @field_validator("constraints")
+    def check_constraints(cls, constraints: Sequence[Constraint]) -> Sequence[Constraint]:
+        if constraints:
+            raise ValueError("ETKDG does not support constraints")
+
+        return tuple(constraints)
+
+    @field_validator("nci")
+    def check_nci(cls, nci: bool) -> bool:
+        if nci:
+            raise ValueError("ETKDG does not support NCI")
+
+        return nci
+
+    @model_validator(mode="after")
+    def validate_and_build(self) -> Self:
+        match self.mode:
+            case Mode.MANUAL:
+                pass
+            case Mode.RECKLESS:
+                self.num_initial_confs = 200
+                self.num_confs_considered = 50
+                self.max_confs = 20 if self.max_confs is _sentinel else self.max_confs
+                self.max_mmff_energy = 20
+            case Mode.RAPID:
+                self.max_confs = 50 if self.max_confs is _sentinel else self.max_confs
+                self.conf_opt_method = Method.GFN0_XTB
+            case _:
+                raise NotImplementedError(f"Unsupported mode: {self.mode}")
+
+        return self
+
+
+class iMTDSpeeds(LowercaseStrEnum):
+    MEGAQUICK = "megaquick"
+    SUPERQUICK = "superquick"
+    QUICK = "quick"
+    NORMAL = "normal"
+    EXTENSIVE = "extensive"
+
+
+class iMTDSettings(ConformerGenSettings, ABC):
+    """
+    Settings for iMTD style conformer generation.
+
+    RECKLESS:
+        - GFN-FF//MTD(GFN-FF)
+        - Megaquick
+            - No GC
+            - No rotamer metadynamics
+            - Energy window = 5.0
+            - Run scaling factor = 0.5
+            - 6 MTD runs
+    RAPID:
+        - GFN0//MTD(GFN-FF)
+        - Superquick
+            - No GC
+            - No rotamer metadynamics
+            - Energy window = 5.0
+            - Run scaling factor = 0.5
+            - 6 MTD runs
+    CAREFUL:
+        - GFN2//MTD(GFN-FF)
+        - Quick
+            - GC (for iMTD-GC)
+            - Rotamer metadynamics (for iMTD-GC)
+            - Energy window = 5.0
+            - Run scaling factor = 0.5
+            - 6 MTD runs
+    METICULOUS:
+        - GFN2//MTD(GFN2)
+        - "Normal"
+            - GC (for iMTD-GC)
+            - Rotamer metadynamics (for iMTD-GC)
+            - Energy window = 6.0
+            - Run scaling factor = 1
+            - 14 MTD runs (2 with extreme values)
+
+
+    See https://github.com/crest-lab/crest/blob/5ca82feb2ec4df30a0129db957163c934f085952/src/choose_settings.f90#L202
+    and https://github.com/crest-lab/crest/blob/5ca82feb2ec4df30a0129db957163c934f085952/src/confparse.f90#L825
+    for how quick, superquick, and megaquick are defined.
+
+    Additional notes:
+        Extensive mode
+        - GC
+        - Rotamer metadynamics
+        - Energy window = 8.0
+        - Run scaling factor = 2
+        - 14 MTD runs (2 with extreme values)
+
+        --NCI may switch things to QUICK?
+
+    Inherited:
+    :param mode: Mode for calculations
+    :param conf_opt_method: method for the optimization
+    :param screening: post-generation screening settings (not used)
+    :param constraints: constraints to add
+    :param nci: add an ellipsoide potential around the input structure
+
+    New:
+    :param mtd_method: method for the metadynamics
+    :param speed: speed of the calculations (CREST specific setting)
+    :param reopt: re-optimize conformers (corrects for the lack of rotamer metadynamics and GC)
+    :param free_energy_weights: calculate frequencies and re-weight based on free energies
+    """
+
+    mtd_method: XTBMethod = Method.GFN_FF
+    mtd_runtype: str = "imtd-gc"
+
+    speed: iMTDSpeeds = iMTDSpeeds.QUICK
+    reopt: bool = _sentinel  # type: ignore [assignment]
+    free_energy_weights: bool = False
+
+    @model_validator(mode="after")
+    def validate_and_build_imtdgc_settings(self) -> Self:
+        match self.mode:
+            case Mode.MANUAL:
+                if self.reopt is _sentinel:
+                    raise ValueError("Must specify reopt with MANUAL mode")
+            case Mode.RECKLESS:  # GFN-FF//MTD(GFN-FF)
+                self.max_confs = 20 if self.max_confs is _sentinel else self.max_confs
+                self.speed = iMTDSpeeds.MEGAQUICK
+                self.reopt = check_sentinel(self.reopt, True)
+            case Mode.RAPID:  # GFN0//MTD(GFN-FF)
+                self.max_confs = 50 if self.max_confs is _sentinel else self.max_confs
+                self.speed = iMTDSpeeds.SUPERQUICK
+                self.conf_opt_method = Method.GFN0_XTB
+                self.reopt = check_sentinel(self.reopt, True)
+            case Mode.CAREFUL:  # GFN2//MTD(GFN-FF)
+                self.speed = iMTDSpeeds.QUICK
+                self.conf_opt_method = Method.GFN2_XTB
+                self.reopt = check_sentinel(self.reopt, False)
+            case Mode.METICULOUS:  # GFN2//MTD(GFN2)
+                self.speed = iMTDSpeeds.NORMAL
+                self.mtd_method = Method.GFN2_XTB
+                self.conf_opt_method = Method.GFN2_XTB
+                self.reopt = check_sentinel(self.reopt, False)
+            # case Mode.EXTREME: # GFN2//MTD(GFN2)
+            #     self.mtd_method = Method.GFN2_XTB
+            #     self.conf_opt_method = Method.GFN2_XTB
+            #     self.speed = iMTDSpeeds.EXTENSIVE
+            #     self.reopt = check_sentinel(self.reopt, False)
+            case _:
+                raise NotImplementedError(f"Unsupported mode: {self.mode}")
+
+        return self
+
+
+class iMTDGCSettings(iMTDSettings):
+    run_type: str = "imtdgc"
+
+
+class iMTDsMTDSettings(iMTDSettings):
+    run_type: str = "imtd-smtd"
+
+
+class ConformerGenMixin(BaseModel):
+    """
+    Mixin for workflows that need conformer generation.
+
+    :param conf_gen_mode: Mode for calculations
+    :param conf_gen_settings: settings for conformer generation
+    """
+
+    conf_gen_mode: Mode = Mode.RAPID
+    conf_gen_settings: ConformerGenSettings = _sentinel  # type: ignore [assignment]
+    constraints: Sequence[Constraint] = tuple()
+
+    @model_validator(mode="after")
+    def validate_and_build_conf_gen_settings(self) -> Self:
+        """Validate and build the ConformerGenSettings."""
+        if self.conf_gen_settings is not _sentinel and self.conf_gen_mode != Mode.MANUAL:
+            raise ValueError("Cannot specify conf_gen_settings with non-MANUAL mode")
+
+        match self.conf_gen_mode:
+            case Mode.MANUAL:
+                if self.conf_gen_settings is _sentinel:
+                    raise ValueError("Must specify conf_gen_settings with MANUAL mode")
+
+            case Mode.RECKLESS | Mode.RAPID:
+                # ETKDGSettings will error if constraints added
+                self.conf_gen_settings = ETKDGSettings(mode=self.conf_gen_mode, constraints=self.constraints)
+            case Mode.CAREFUL | Mode.METICULOUS:
+                self.conf_gen_settings = iMTDSettings(mode=self.conf_gen_mode, constraints=self.constraints)
+
+            case _:
+                raise NotImplementedError(f"Unsupported mode: {self.conf_gen_mode}")
+
+        return self
+
+
+class ConformerSearchMixin(ConformerGenMixin, MultiStageOptMixin):
+    """
+    Mixin for workflows that need conformer search—a combination of conformer generation and optimization.
+
+    Inherited:
+    :param conf_gen_mode: Mode for conformer generation
+    :param mso_mode: Mode for MultiStageOptSettings
+    :param conf_gen_settings: settings for conformer generation
+    :param multistage_opt_settings: set by mso_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)
+    :param constraints: constraints to add (diamond inheritance, works as expected)
+    :param transition_state: whether this is a transition state
+
+    Overridden:
+    :param frequencies: whether to calculate frequencies (turned off)
+    """
+
+    frequencies: bool = False
+
+    def __str__(self) -> str:
+        """Return a string representation of the ConformerSearch workflow."""
+        return repr(self)
+
+    def __repr__(self) -> str:
+        """Return a string representation of the ConformerSearch workflow."""
+        return f"<{type(self).__name__} {self.conf_gen_mode.name} {self.mso_mode.name}>"
+
+
+class ConformerSearchWorkflow(ConformerSearchMixin, Workflow):
+    """
+    ConformerSearch Workflow.
+
+    Inherited:
+    :param initial_molecule: Molecule of interest
+    :param conf_gen_mode: Mode for calculations
+    :param conf_gen_settings: settings for conformer generation
+    :param mso_mode: Mode for MultiStageOptSettings
+    :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)
+    :param constraints: constraints to add
+    :param transition_state: whether this is a transition state
+    :param frequencies: whether to calculate frequencies (turned off)
+
+    Ignored:
+    :param mode: Mode to use (not used)
+
+    New:
+    :param conformer_uuids: list of UUIDs of the Molecules generated
+    :param energies: energies of the molecules
+    """
+
+    # Results
+    conformer_uuids: list[list[UUID | None]] = Field(default_factory=list)
+    energies: list[float] = Field(default_factory=list)

stjames/workflows/electronic_properties.py

@@ -0,0 +1,86 @@
+from pydantic import NonNegativeFloat, NonNegativeInt
+
+from ..base import Base
+from ..settings import Settings
+from ..types import UUID, FloatPerAtom, Matrix3x3, Vector3D
+from .workflow import Workflow
+
+
+class PropertyCubePoint(Base):
+    x: float
+    y: float
+    z: float
+    val: float
+
+
+class PropertyCube(Base):
+    """
+    Represents a "cubefile" of some property.
+    """
+
+    cube_data: list[PropertyCubePoint]
+
+
+class MolecularOrbitalCube(PropertyCube):
+    """
+    Inherits `cube_data`.
+    """
+
+    occupation: NonNegativeInt
+    energy: float
+
+
+class ElectronicPropertiesWorkflow(Workflow):
+    """
+    Workflow for computing electronic properties!
+
+    Inherited
+    :param initial_molecule: molecule of interest
+
+    Config settings:
+    :param settings: the level of theory to use
+    :param compute_density_cube: whether or not to compute the density on a cube
+    :param compute_electrostatic_potential_cube: whether or not to compute the electrostatic potential on a cube
+    :param compute_num_occupied_orbitals: how many occupied orbitals to save
+    :param compute_num_virtual_orbitals: how many virtual orbitals to save
+
+    Populated while running:
+    :param calculation: the UUID of the calculation
+    :param dipole: the dipole moment
+    :param quadrupole: the quadrupole moment
+    :param mulliken_charges: the Mulliken charges
+    :param lowdin_charges: the Lowdin charges
+    :param wiberg_bond_orders: the Wiberg bond orders (`atom1`, `atom2`, `order`)
+    :param mayer_bond_orders: the Mayer bond orders (`atom1`, `atom2`, `order`)
+    :param density_cube: the electron density, as a cube
+    :param electrostatic_potential_cube: the electrostatic potential, as a cube
+    :param molecular_orbitals_alpha: for open-shell species (UHF/ROHF), a dict containing the alpha MOs
+        (The key is the absolute orbital index.)
+    :param molecular_orbitals_beta: for open-shell species (UHF/ROHF), a dict containing the beta MOs
+        (The key is the absolute orbital index.)
+    :param molecular_orbitals: for closed-shell species (RHF), a dict containing the MOs
+        (The key is the absolute orbital index.)
+    """
+
+    settings: Settings
+    compute_density_cube: bool = True
+    compute_electrostatic_potential_cube: bool = True
+    compute_num_occupied_orbitals: NonNegativeInt = 1
+    compute_num_virtual_orbitals: NonNegativeInt = 1
+
+    calculation: UUID | None = None
+
+    dipole: Vector3D | None = None
+    quadrupole: Matrix3x3 | None = None
+
+    mulliken_charges: FloatPerAtom | None = None
+    lowdin_charges: FloatPerAtom | None = None
+
+    wiberg_bond_orders: list[tuple[NonNegativeInt, NonNegativeInt, NonNegativeFloat]] = []
+    mayer_bond_orders: list[tuple[NonNegativeInt, NonNegativeInt, NonNegativeFloat]] = []
+
+    density_cube: PropertyCube | None = None
+    electrostatic_potential_cube: PropertyCube | None = None
+    molecular_orbitals_alpha: dict[NonNegativeInt, MolecularOrbitalCube] = {}
+    molecular_orbitals_beta: dict[NonNegativeInt, MolecularOrbitalCube] = {}
+    molecular_orbitals: dict[NonNegativeInt, MolecularOrbitalCube] = {}

stjames/workflows/molecular_dynamics.py

@@ -9,6 +9,11 @@ from ..types import UUID
 from .workflow import Workflow
 
 
+class MolecularDynamicsInitialization(LowercaseStrEnum):
+    RANDOM = "random"
+    QUASICLASSICAL = "quasiclassical"
+
+
 class ThermodynamicEnsemble(LowercaseStrEnum):
     NPT = "npt"
     NVT = "nvt"
@@ -18,22 +23,24 @@ class ThermodynamicEnsemble(LowercaseStrEnum):
 class Frame(Base):
     index: int  # what number frame this is within the MD simulation
 
-    uuid: UUID | None = None  # UUID of molecule
+    calculation_uuid: UUID | None = None  # UUID of calculation
 
     pressure: float
     temperature: float
+    volume: float
     energy: float
 
 
 class MolecularDynamicsSettings(Base):
     ensemble: ThermodynamicEnsemble = ThermodynamicEnsemble.NVT
+    initialization: MolecularDynamicsInitialization = MolecularDynamicsInitialization.RANDOM
 
     timestep: PositiveFloat = 1.0  # fs
     num_steps: PositiveInt = 500
 
     confining_constraint: SphericalHarmonicConstraint | None = None
 
-    temperature: PositiveFloat | None = 300  # K
+    temperature: PositiveFloat = 300  # K
     pressure: PositiveFloat | None = None  # atm
 
     langevin_thermostat_timescale: PositiveFloat = 100  # fs
@@ -46,7 +53,7 @@ class MolecularDynamicsSettings(Base):
         """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):
+        elif 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
 
@@ -56,5 +63,7 @@ class MolecularDynamicsWorkflow(Workflow):
     calc_settings: Settings
     calc_engine: str | None = None
 
+    save_interval: PositiveInt = 10
+
     # uuids of scan points
     frames: list[Frame] = []

stjames/workflows/multistage_opt.py

@@ -22,19 +22,19 @@ class MultiStageOptSettings(BaseModel):
     RAPID *default
         r²SCAN-3c//GFN2-xTB with GFN0-xTB pre-opt (off by default)
     CAREFUL
-        wB97X-3c//B97-3c with GFN2-xTB pre-opt
+        wB97X-3c//r²SCAN-3c with GFN2-xTB pre-opt
     METICULOUS
-        wB97M-D3BJ/def2-TZVPPD//wB97X-3c//B97-3c with GFN2-xTB pre-opt
+        wB97M-D3BJ/def2-TZVPPD//wB97X-3c//r²SCAN-3c with GFN2-xTB pre-opt
 
     Notes:
-    - No solvent in pre-opt
+    - No solvent in any optimizations when using Modes
     - If solvent: xTB singlepoints use CPCMX, xTB optimizations use ALBP, all else use CPCM
     - Allows a single point to be called with no optimization
 
     :param mode: Mode for settings
     :param optimization_settings: list of opt settings to apply successively
     :param singlepoint_settings: final single point settings
-    :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)
     :param constraints: constraints for optimization
     :param transition_state: whether this is a transition state
@@ -44,7 +44,7 @@ class MultiStageOptSettings(BaseModel):
     >>> msos
     <MultiStageOptSettings RAPID>
     >>> msos.level_of_theory
-    'r2scan_3c/cpcm(water)//gfn2_xtb/alpb(water)'
+    'r2scan_3c/cpcm(water)//gfn2_xtb'
     """
 
     mode: Mode
@@ -78,7 +78,7 @@ class MultiStageOptSettings(BaseModel):
 
         >>> msos = MultiStageOptSettings(mode=Mode.RAPID, solvent="hexane")
         >>> msos.level_of_theory
-        'r2scan_3c/cpcm(hexane)//gfn2_xtb/alpb(hexane)'
+        'r2scan_3c/cpcm(hexane)//gfn2_xtb'
         """
         methods = [self.singlepoint_settings] if self.singlepoint_settings else []
         methods += reversed(self.optimization_settings)
@@ -148,14 +148,14 @@ class MultiStageOptSettings(BaseModel):
         match mode:
             case Mode.RECKLESS:
                 self.xtb_preopt = False
-                self.optimization_settings = [opt(Method.GFN_FF, solvent=self.solvent, freq=self.frequencies)]
+                self.optimization_settings = [opt(Method.GFN_FF, freq=self.frequencies)]
                 self.singlepoint_settings = sp(Method.GFN2_XTB, solvent=self.solvent)
 
             case Mode.RAPID:
                 self.xtb_preopt = bool(self.xtb_preopt)
                 self.optimization_settings = [
                     *gfn0_pre_opt * self.xtb_preopt,
-                    opt(Method.GFN2_XTB, solvent=self.solvent, freq=self.frequencies),
+                    opt(Method.GFN2_XTB, freq=self.frequencies),
                 ]
                 self.singlepoint_settings = sp(Method.R2SCAN3C, solvent=self.solvent)
 
@@ -163,7 +163,7 @@ class MultiStageOptSettings(BaseModel):
                 self.xtb_preopt = (self.xtb_preopt is None) or self.xtb_preopt
                 self.optimization_settings = [
                     *gfn2_pre_opt * self.xtb_preopt,
-                    opt(Method.B973C, solvent=self.solvent, freq=self.frequencies),
+                    opt(Method.R2SCAN3C, freq=self.frequencies),
                 ]
                 self.singlepoint_settings = sp(Method.WB97X3C, solvent=self.solvent)
 
@@ -171,8 +171,8 @@ class MultiStageOptSettings(BaseModel):
                 self.xtb_preopt = (self.xtb_preopt is None) or self.xtb_preopt
                 self.optimization_settings = [
                     *gfn2_pre_opt * self.xtb_preopt,
-                    opt(Method.B973C, solvent=self.solvent),
-                    opt(Method.WB97X3C, solvent=self.solvent, freq=self.frequencies),
+                    opt(Method.R2SCAN3C),
+                    opt(Method.WB97X3C, freq=self.frequencies),
                 ]
                 self.singlepoint_settings = sp(Method.WB97MD3BJ, "def2-TZVPPD", solvent=self.solvent)
 
@@ -191,7 +191,7 @@ class MultiStageOptWorkflow(Workflow, MultiStageOptSettings):
     :param mode: Mode for workflow
     :param optimization_settings: list of opt settings to apply successively
     :param singlepoint_settings: final single point settings
-    :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)
     :param constraints: constraints for optimization
     :param transition_state: whether this is a transition state
@@ -206,12 +206,18 @@ class MultiStageOptWorkflow(Workflow, MultiStageOptSettings):
     >>> msow
     <MultiStageOptWorkflow RAPID>
     >>> msow.level_of_theory
-    'r2scan_3c/cpcm(water)//gfn2_xtb/alpb(water)'
+    'r2scan_3c/cpcm(water)//gfn2_xtb'
     """
 
     # Populated while running the workflow
     calculations: list[UUID | None] = Field(default_factory=list)
 
+    def __repr__(self) -> str:
+        if self.mode != Mode.MANUAL:
+            return f"<{type(self).__name__} {self.mode.name}>"
+
+        return f"<{type(self).__name__} {self.level_of_theory}>"
+
 
 # the id of a mutable object may change, thus using object()
 _sentinel_msos = object()
@@ -222,7 +228,7 @@ class MultiStageOptMixin(BaseModel):
     Mixin for workflows that use MultiStageOptSettings.
     """
 
-    mso_mode: Mode
+    mso_mode: Mode = Mode.AUTO
     # Need to use a sentinel object to make both mypy and pydantic happy
     multistage_opt_settings: MultiStageOptSettings = _sentinel_msos  # type: ignore [assignment]
     solvent: Solvent | None = None
@@ -259,3 +265,74 @@ class MultiStageOptMixin(BaseModel):
                 )
 
         return self
+
+
+def build_mso_settings(
+    sp_method: Method,
+    sp_basis_set: str | None,
+    opt_methods: list[Method],
+    opt_basis_sets: list[str | None],
+    mode: Mode = Mode.MANUAL,
+    solvent: Solvent | None = None,
+    use_solvent_for_opt: bool = False,
+    constraints: list[Constraint] | None = None,
+    transition_state: bool = False,
+    frequencies: bool = True,
+) -> MultiStageOptSettings:
+    """
+    Helper function to construct multi-stage opt settings objects manually.
+
+    There's no xTB pre-optimization here - add that yourself!
+
+    :param optimization_settings: list of opt settings to apply successively
+    :param singlepoint_settings: final single point settings
+    :param mode: Mode for settings, defaults to `MANUAL`
+    :param solvent: solvent to use
+    :param use_solvent_for_opt: whether to conduct opts with solvent
+    :param constraints: constraints for optimization
+    :param transition_state: whether this is a transition state
+    :param frequencies: whether to calculate frequencies
+    :returns: the final multistage opt settings
+    """
+    if constraints is None:
+        constraints = []
+
+    opt_settings = OptimizationSettings(constraints=constraints, transition_state=transition_state)
+
+    OPT = [Task.OPTIMIZE if not transition_state else Task.OPTIMIZE_TS]
+
+    def opt(method: Method, basis_set: str | None = None, solvent: Solvent | None = None, freq: bool = False) -> Settings:
+        """Generates optimization settings."""
+        model = "alpb" if method in XTB_METHODS else "cpcm"
+
+        return Settings(
+            method=method,
+            basis_set=basis_set,
+            tasks=OPT + [Task.FREQUENCIES] * freq,
+            solvent_settings=SolventSettings(solvent=solvent, model=model) if (solvent and use_solvent_for_opt) else None,
+            opt_settings=opt_settings,
+        )
+
+    def sp(method: Method, basis_set: str | None = None, solvent: Solvent | None = None) -> Settings:
+        """Generate singlepoint settings."""
+        model = "cpcmx" if method in XTB_METHODS else "cpcm"
+
+        return Settings(
+            method=method,
+            basis_set=basis_set,
+            tasks=[Task.ENERGY],
+            solvent_settings=SolventSettings(solvent=solvent, model=model) if solvent else None,
+        )
+
+    return MultiStageOptSettings(
+        mode=mode,
+        optimization_settings=[
+            opt(method=method, basis_set=basis_set, solvent=solvent, freq=frequencies) for method, basis_set in zip(opt_methods, opt_basis_sets, strict=True)
+        ],
+        singlepoint_settings=sp(method=sp_method, basis_set=sp_basis_set, solvent=solvent),
+        solvent=solvent,
+        xtb_preopt=False,
+        constraints=constraints,
+        transition_state=transition_state,
+        frequencies=frequencies,
+    )