molbuilder 1.0.0__py3-none-any.whl

molbuilder/process/purification.py

@@ -0,0 +1,285 @@
+"""Purification strategy recommendation for synthesis products.
+
+Selects one or more :class:`PurificationStep` instances based on the reaction
+type, product characteristics, and production scale.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum, auto
+from typing import List
+
+from molbuilder.reactions.reaction_types import ReactionCategory, ReactionTemplate
+
+
+# =====================================================================
+#  Enums and data classes
+# =====================================================================
+
+class PurificationMethod(Enum):
+    DISTILLATION = auto()
+    RECRYSTALLIZATION = auto()
+    COLUMN_CHROMATOGRAPHY = auto()
+    FLASH_CHROMATOGRAPHY = auto()
+    EXTRACTION = auto()
+    FILTRATION = auto()
+    PRECIPITATION = auto()
+    SUBLIMATION = auto()
+
+
+@dataclass
+class PurificationStep:
+    """A single purification operation with expected performance."""
+
+    method: PurificationMethod
+    description: str
+    estimated_recovery: float   # percent (0-100)
+    estimated_purity: float     # percent (0-100)
+    scale_appropriate: bool
+    notes: str
+
+
+# =====================================================================
+#  Internal helpers
+# =====================================================================
+
+# Categories whose products are typically liquids at room temperature
+_LIQUID_PRODUCT_CATEGORIES = {
+    ReactionCategory.ELIMINATION,
+    ReactionCategory.RADICAL,
+}
+
+# Categories whose products are typically solids
+_SOLID_PRODUCT_CATEGORIES = {
+    ReactionCategory.COUPLING,
+    ReactionCategory.PROTECTION,
+    ReactionCategory.CARBONYL,
+    ReactionCategory.PERICYCLIC,
+}
+
+# Categories that often produce complex mixtures requiring chromatography
+_COMPLEX_MIXTURE_CATEGORIES = {
+    ReactionCategory.REARRANGEMENT,
+    ReactionCategory.RADICAL,
+    ReactionCategory.MISC,
+}
+
+
+def _chromatography_appropriate(scale_kg: float) -> bool:
+    """Chromatography is generally impractical above ~5 kg scale."""
+    return scale_kg <= 5.0
+
+
+def _extraction_step(scale_kg: float) -> PurificationStep:
+    return PurificationStep(
+        method=PurificationMethod.EXTRACTION,
+        description=(
+            "Liquid-liquid extraction with aqueous wash (saturated NaHCO3, "
+            "then brine) to remove polar impurities and inorganic salts."
+        ),
+        estimated_recovery=92.0,
+        estimated_purity=70.0,
+        scale_appropriate=True,
+        notes="Use separating funnel (lab) or mixer-settler (plant).",
+    )
+
+
+def _distillation_step(scale_kg: float) -> PurificationStep:
+    return PurificationStep(
+        method=PurificationMethod.DISTILLATION,
+        description=(
+            "Simple or fractional distillation under reduced pressure "
+            "if product bp is below 200 degC.  Use short-path distillation "
+            "for heat-sensitive materials."
+        ),
+        estimated_recovery=85.0,
+        estimated_purity=95.0,
+        scale_appropriate=True,
+        notes=(
+            "Highly scalable.  Ensure delta-bp between product and "
+            "impurities is >15 degC for simple distillation."
+        ),
+    )
+
+
+def _recrystallization_step(scale_kg: float) -> PurificationStep:
+    return PurificationStep(
+        method=PurificationMethod.RECRYSTALLIZATION,
+        description=(
+            "Dissolve crude in minimum hot solvent (e.g. ethanol, ethyl "
+            "acetate, or toluene), filter hot, cool slowly to crystallise.  "
+            "Collect crystals by vacuum filtration."
+        ),
+        estimated_recovery=75.0,
+        estimated_purity=97.0,
+        scale_appropriate=True,
+        notes="Solvent screening recommended.  May need 2 crops to maximise yield.",
+    )
+
+
+def _flash_chromatography_step(scale_kg: float) -> PurificationStep:
+    return PurificationStep(
+        method=PurificationMethod.FLASH_CHROMATOGRAPHY,
+        description=(
+            "Flash column chromatography on silica gel (40-63 um) with "
+            "gradient elution (e.g. hexanes/ethyl acetate)."
+        ),
+        estimated_recovery=80.0,
+        estimated_purity=95.0,
+        scale_appropriate=_chromatography_appropriate(scale_kg),
+        notes=(
+            "Practical up to ~5 kg.  Above that, consider preparative HPLC "
+            "or alternative purification strategies."
+        ),
+    )
+
+
+def _column_chromatography_step(scale_kg: float) -> PurificationStep:
+    return PurificationStep(
+        method=PurificationMethod.COLUMN_CHROMATOGRAPHY,
+        description=(
+            "Gravity column chromatography on silica gel.  Suitable when "
+            "flash equipment is unavailable; slower but gentler."
+        ),
+        estimated_recovery=75.0,
+        estimated_purity=93.0,
+        scale_appropriate=_chromatography_appropriate(scale_kg),
+        notes="Load ratio: ~30:1 silica-to-crude by weight.",
+    )
+
+
+def _filtration_step(scale_kg: float) -> PurificationStep:
+    return PurificationStep(
+        method=PurificationMethod.FILTRATION,
+        description=(
+            "Vacuum filtration through Celite or sintered-glass funnel "
+            "to remove catalyst residues and insoluble by-products."
+        ),
+        estimated_recovery=95.0,
+        estimated_purity=60.0,
+        scale_appropriate=True,
+        notes="Often the first purification step for heterogeneous reactions.",
+    )
+
+
+def _precipitation_step(scale_kg: float) -> PurificationStep:
+    return PurificationStep(
+        method=PurificationMethod.PRECIPITATION,
+        description=(
+            "Add anti-solvent (water, hexanes, or diethyl ether) to "
+            "precipitate product from solution.  Collect by filtration."
+        ),
+        estimated_recovery=80.0,
+        estimated_purity=88.0,
+        scale_appropriate=True,
+        notes="Works best when product is much less soluble than impurities in the anti-solvent.",
+    )
+
+
+def _sublimation_step(scale_kg: float) -> PurificationStep:
+    return PurificationStep(
+        method=PurificationMethod.SUBLIMATION,
+        description=(
+            "Vacuum sublimation at reduced pressure.  Best for low-MW "
+            "solids with high vapour pressure (e.g. naphthalene, ferrocene)."
+        ),
+        estimated_recovery=70.0,
+        estimated_purity=99.0,
+        scale_appropriate=scale_kg <= 1.0,
+        notes="Limited throughput; primarily a lab-scale technique.",
+    )
+
+
+# =====================================================================
+#  Public API
+# =====================================================================
+
+def recommend_purification(
+    template: ReactionTemplate,
+    scale_kg: float,
+) -> list[PurificationStep]:
+    """Return an ordered list of purification steps for *template* at *scale_kg*.
+
+    Strategy
+    --------
+    * Liquid products -> extraction then distillation
+    * Solid products  -> extraction then recrystallization
+    * Complex mixtures -> extraction + chromatography (small scale) or
+      extraction + precipitation + recrystallization (large scale)
+    * Catalytic reactions always start with filtration
+    * Large scale avoids chromatography
+    """
+    if not hasattr(template, 'category'):
+        raise TypeError(
+            f"template must have a 'category' attribute, "
+            f"got {type(template).__name__}"
+        )
+
+    steps: list[PurificationStep] = []
+    cat = template.category
+    has_catalyst = len(template.catalysts) > 0
+
+    # --- Step 0: Filtration for catalytic reactions ---
+    if has_catalyst:
+        steps.append(_filtration_step(scale_kg))
+
+    # --- Liquid products ---
+    if cat in _LIQUID_PRODUCT_CATEGORIES:
+        steps.append(_extraction_step(scale_kg))
+        steps.append(_distillation_step(scale_kg))
+        return steps
+
+    # --- Complex mixtures ---
+    if cat in _COMPLEX_MIXTURE_CATEGORIES:
+        steps.append(_extraction_step(scale_kg))
+        if _chromatography_appropriate(scale_kg):
+            steps.append(_flash_chromatography_step(scale_kg))
+        else:
+            steps.append(_precipitation_step(scale_kg))
+            steps.append(_recrystallization_step(scale_kg))
+        return steps
+
+    # --- Solid products ---
+    if cat in _SOLID_PRODUCT_CATEGORIES:
+        steps.append(_extraction_step(scale_kg))
+        steps.append(_recrystallization_step(scale_kg))
+        return steps
+
+    # --- Oxidation / Reduction: often aqueous workup + extraction ---
+    if cat in {ReactionCategory.OXIDATION, ReactionCategory.REDUCTION}:
+        steps.append(_extraction_step(scale_kg))
+        if _chromatography_appropriate(scale_kg) and scale_kg < 0.5:
+            steps.append(_flash_chromatography_step(scale_kg))
+        else:
+            steps.append(_distillation_step(scale_kg))
+        return steps
+
+    # --- Substitution / Addition: general workflow ---
+    if cat in {ReactionCategory.SUBSTITUTION, ReactionCategory.ADDITION}:
+        steps.append(_extraction_step(scale_kg))
+        if _chromatography_appropriate(scale_kg) and scale_kg < 1.0:
+            steps.append(_flash_chromatography_step(scale_kg))
+        else:
+            steps.append(_distillation_step(scale_kg))
+        return steps
+
+    # --- Deprotection ---
+    if cat == ReactionCategory.DEPROTECTION:
+        steps.append(_extraction_step(scale_kg))
+        steps.append(_precipitation_step(scale_kg))
+        return steps
+
+    # --- Polymerization ---
+    if cat == ReactionCategory.POLYMERIZATION:
+        steps.append(_precipitation_step(scale_kg))
+        steps.append(_filtration_step(scale_kg))
+        return steps
+
+    # --- Default fallback ---
+    steps.append(_extraction_step(scale_kg))
+    if _chromatography_appropriate(scale_kg):
+        steps.append(_flash_chromatography_step(scale_kg))
+    else:
+        steps.append(_recrystallization_step(scale_kg))
+    return steps

molbuilder/process/reactor.py

@@ -0,0 +1,297 @@
+"""Reactor selection and specification for process engineering.
+
+Maps reaction characteristics (exothermicity, phase, scale) to an appropriate
+reactor type and provides a fully populated :class:`ReactorSpec` dataclass.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum, auto
+from typing import Optional
+
+from molbuilder.reactions.reaction_types import ReactionCategory, ReactionTemplate
+from molbuilder.reactions.reagent_data import normalize_reagent_name
+
+
+# =====================================================================
+#  Enums
+# =====================================================================
+
+class ReactorType(Enum):
+    BATCH = auto()
+    SEMI_BATCH = auto()
+    CSTR = auto()          # Continuous stirred-tank reactor
+    PFR = auto()           # Plug flow reactor
+    MICROREACTOR = auto()
+    FIXED_BED = auto()
+
+
+# =====================================================================
+#  Reactor specification
+# =====================================================================
+
+@dataclass
+class ReactorSpec:
+    """Complete specification of a process reactor."""
+
+    reactor_type: ReactorType
+    volume_L: float
+    temperature_C: float
+    pressure_atm: float
+    residence_time_min: float
+    mixing_type: str        # "mechanical", "static", "none"
+    heat_transfer: str      # "jacketed", "coil", "adiabatic"
+    material: str           # "glass", "stainless steel", "hastelloy"
+    estimated_cost_usd: float
+    notes: str
+
+
+# =====================================================================
+#  Internal helpers
+# =====================================================================
+
+# Categories that are typically highly exothermic or fast
+_EXOTHERMIC_CATEGORIES = {
+    ReactionCategory.ADDITION,
+    ReactionCategory.RADICAL,
+    ReactionCategory.POLYMERIZATION,
+}
+
+# Categories that are often multiphase (solid catalyst, heterogeneous)
+_MULTIPHASE_CATEGORIES = {
+    ReactionCategory.COUPLING,
+    ReactionCategory.REDUCTION,
+}
+
+# Categories commonly run under inert or pressurised conditions
+_HIGH_PRESSURE_CATEGORIES = {
+    ReactionCategory.REDUCTION,
+    ReactionCategory.POLYMERIZATION,
+}
+
+
+def _mean_temp(template: ReactionTemplate) -> float:
+    """Return the midpoint of the template temperature range."""
+    lo, hi = template.temperature_range
+    return (lo + hi) / 2.0
+
+
+def _is_cryogenic(template: ReactionTemplate) -> bool:
+    return _mean_temp(template) < -20.0
+
+
+def _is_high_temp(template: ReactionTemplate) -> bool:
+    return _mean_temp(template) > 150.0
+
+
+def _select_material(template: ReactionTemplate) -> str:
+    """Choose vessel material based on temperature and corrosive reagents."""
+    corrosive_keywords = {"hcl", "h2so4", "hno3", "hf", "tfa", "socl2", "ticl4"}
+    reagent_keys = {normalize_reagent_name(r) for r in template.reagents}
+    if reagent_keys & corrosive_keywords:
+        return "hastelloy"
+    if _is_high_temp(template):
+        return "stainless steel"
+    return "glass"
+
+
+def _estimate_reactor_cost(reactor_type: ReactorType, volume_L: float) -> float:
+    """Rough capital cost estimate in USD.
+
+    Based on typical 2024 equipment pricing for chemical process vessels.
+    """
+    base_costs = {
+        ReactorType.BATCH: 8_000,
+        ReactorType.SEMI_BATCH: 12_000,
+        ReactorType.CSTR: 25_000,
+        ReactorType.PFR: 30_000,
+        ReactorType.MICROREACTOR: 50_000,
+        ReactorType.FIXED_BED: 35_000,
+    }
+    base = base_costs.get(reactor_type, 10_000)
+    # Scale by volume using the six-tenths rule (cost ~ volume^0.6)
+    reference_volume = 100.0  # litres
+    if volume_L <= 0:
+        volume_L = 1.0
+    scale_factor = (volume_L / reference_volume) ** 0.6
+    return round(base * max(scale_factor, 0.3), -2)
+
+
+def _volume_for_scale(scale_kg: float, concentration_factor: float = 5.0) -> float:
+    """Estimate vessel volume in litres.
+
+    Assumes ~5 L of solvent+reagent per kg of product (tuneable via
+    *concentration_factor*) and a 75 % fill level.
+    """
+    raw = scale_kg * concentration_factor
+    return round(raw / 0.75, 1)
+
+
+# =====================================================================
+#  Public API
+# =====================================================================
+
+def select_reactor(
+    template: ReactionTemplate,
+    scale_kg: float,
+) -> ReactorSpec:
+    """Select an appropriate reactor for *template* at *scale_kg*.
+
+    Decision tree
+    -------------
+    1. Fast / exothermic at small scale  -> MICROREACTOR
+    2. Fast / exothermic at large scale  -> CSTR with jacketed cooling
+    3. Slow multiphase or catalytic       -> BATCH (small) or FIXED_BED (large)
+    4. High-volume commodity (>500 kg)    -> PFR
+    5. Moderate scale, needs controlled   -> SEMI_BATCH
+       addition
+    6. Default                            -> BATCH
+    """
+    if not hasattr(template, 'temperature_range'):
+        raise TypeError(
+            f"template must have a 'temperature_range' attribute, "
+            f"got {type(template).__name__}"
+        )
+
+    mean_t = _mean_temp(template)
+    volume = _volume_for_scale(scale_kg)
+    material = _select_material(template)
+
+    is_exothermic = template.category in _EXOTHERMIC_CATEGORIES
+    is_multiphase = template.category in _MULTIPHASE_CATEGORIES
+    has_catalyst = len(template.catalysts) > 0
+
+    # --- 1. Fast exothermic, small scale -> microreactor ---
+    if is_exothermic and scale_kg < 1.0:
+        rt = ReactorType.MICROREACTOR
+        vol = max(0.05, scale_kg * 0.5)
+        return ReactorSpec(
+            reactor_type=rt,
+            volume_L=vol,
+            temperature_C=mean_t,
+            pressure_atm=1.0 if mean_t < 100 else 2.0,
+            residence_time_min=2.0,
+            mixing_type="static",
+            heat_transfer="coil",
+            material="stainless steel",
+            estimated_cost_usd=_estimate_reactor_cost(rt, vol),
+            notes=(
+                "Microreactor recommended for fast exothermic reaction at "
+                "sub-kilogram scale.  Excellent heat removal and mixing."
+            ),
+        )
+
+    # --- 2. Fast exothermic, large scale -> CSTR ---
+    if is_exothermic and scale_kg >= 1.0:
+        rt = ReactorType.CSTR
+        return ReactorSpec(
+            reactor_type=rt,
+            volume_L=volume,
+            temperature_C=mean_t,
+            pressure_atm=1.0 if mean_t < 100 else 3.0,
+            residence_time_min=30.0,
+            mixing_type="mechanical",
+            heat_transfer="jacketed",
+            material=material,
+            estimated_cost_usd=_estimate_reactor_cost(rt, volume),
+            notes=(
+                "CSTR selected for exothermic reaction at production scale.  "
+                "Jacket cooling essential; consider cascade of 2-3 CSTRs for "
+                "improved conversion."
+            ),
+        )
+
+    # --- 3. Multiphase / catalytic ---
+    if is_multiphase or has_catalyst:
+        if scale_kg > 100.0 and has_catalyst:
+            rt = ReactorType.FIXED_BED
+            return ReactorSpec(
+                reactor_type=rt,
+                volume_L=volume,
+                temperature_C=mean_t,
+                pressure_atm=3.0,
+                residence_time_min=15.0,
+                mixing_type="none",
+                heat_transfer="coil",
+                material=material,
+                estimated_cost_usd=_estimate_reactor_cost(rt, volume),
+                notes=(
+                    "Fixed-bed reactor for heterogeneous catalytic process "
+                    "at >100 kg scale.  Catalyst lifetime and regeneration "
+                    "strategy must be defined."
+                ),
+            )
+        rt = ReactorType.BATCH
+        return ReactorSpec(
+            reactor_type=rt,
+            volume_L=volume,
+            temperature_C=mean_t,
+            pressure_atm=1.0,
+            residence_time_min=120.0,
+            mixing_type="mechanical",
+            heat_transfer="jacketed",
+            material=material,
+            estimated_cost_usd=_estimate_reactor_cost(rt, volume),
+            notes=(
+                "Batch reactor for multiphase or catalytic reaction.  "
+                "Ensure adequate agitation for mass transfer."
+            ),
+        )
+
+    # --- 4. High-volume commodity -> PFR ---
+    if scale_kg > 500.0:
+        rt = ReactorType.PFR
+        return ReactorSpec(
+            reactor_type=rt,
+            volume_L=volume,
+            temperature_C=mean_t,
+            pressure_atm=5.0,
+            residence_time_min=20.0,
+            mixing_type="static",
+            heat_transfer="coil",
+            material="stainless steel",
+            estimated_cost_usd=_estimate_reactor_cost(rt, volume),
+            notes=(
+                "Plug-flow reactor for high-volume continuous production.  "
+                "Back-mixing minimised; good for high conversion targets."
+            ),
+        )
+
+    # --- 5. Controlled addition needed -> semi-batch ---
+    needs_slow_addition = (
+        template.category in {ReactionCategory.CARBONYL, ReactionCategory.SUBSTITUTION}
+        and scale_kg > 10.0
+    )
+    if needs_slow_addition:
+        rt = ReactorType.SEMI_BATCH
+        return ReactorSpec(
+            reactor_type=rt,
+            volume_L=volume,
+            temperature_C=mean_t,
+            pressure_atm=1.0,
+            residence_time_min=90.0,
+            mixing_type="mechanical",
+            heat_transfer="jacketed",
+            material=material,
+            estimated_cost_usd=_estimate_reactor_cost(rt, volume),
+            notes=(
+                "Semi-batch reactor allows controlled reagent addition to "
+                "manage selectivity and heat release."
+            ),
+        )
+
+    # --- 6. Default -> batch ---
+    rt = ReactorType.BATCH
+    return ReactorSpec(
+        reactor_type=rt,
+        volume_L=volume,
+        temperature_C=mean_t,
+        pressure_atm=1.0,
+        residence_time_min=60.0,
+        mixing_type="mechanical",
+        heat_transfer="jacketed" if volume > 20 else "adiabatic",
+        material=material,
+        estimated_cost_usd=_estimate_reactor_cost(rt, volume),
+        notes="Standard batch reactor; suitable for most laboratory and pilot-scale work.",
+    )