Update PySDM/mcp_output/mcp_plugin/mcp_service.py

PySDM/mcp_output/mcp_plugin/mcp_service.py

@@ -1,5 +1,7 @@
 import os
 import sys
+from typing import List, Optional, Dict, Any
+import math
 
 # Add the local source directory to sys.path
 source_path = os.path.join(os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__)))), "source")
@@ -7,68 +9,448 @@ if source_path not in sys.path:
     sys.path.insert(0, source_path)
 
 from fastmcp import FastMCP
-
-# Import core modules from the source directory
-from PySDM import particulator
-from PySDM.dynamics import condensation
-from PySDM.physics import constants
+import numpy as np
+from scipy import constants as sci
 
 # Create the FastMCP service application
 mcp = FastMCP("pysdm_service")
 
-@mcp.tool(name="simulate_particles", description="Simulate particle dynamics using PySDM")
-def simulate_particles(particle_count: int, time_step: float) -> dict:
+
+# ===================== Physical Constants =====================
+
+# Define key physical constants (based on PySDM's constants_defaults.py)
+PHYSICAL_CONSTANTS = {
+    "R_str": sci.R,  # Universal gas constant (J/K/mol)
+    "N_A": sci.N_A,  # Avogadro constant (1/mol)
+    "T0": sci.zero_Celsius,  # 0°C in Kelvin (273.15 K)
+    "PI": sci.pi,
+    "Md": 28.966e-3,  # Dry air molar mass (kg/mol)
+    "Mv": 18.015e-3,  # Water vapour molar mass (kg/mol) 
+    "eps": 18.015 / 28.966,  # Mv/Md ratio
+    "g_std": sci.g,  # Standard gravity (m/s²)
+    "c_pd": 1005.0,  # Specific heat of dry air at constant pressure (J/kg/K)
+    "c_pv": 1850.0,  # Specific heat of water vapour at constant pressure (J/kg/K)
+    "rho_w": 1000.0,  # Density of liquid water (kg/m³)
+    "l_tri": 2.5e6,  # Latent heat of vaporization at triple point (J/kg)
+    "MAC": 1.0,  # Mass accommodation coefficient
+    "HAC": 1.0,  # Thermal accommodation coefficient
+}
+
+# Flatau-Walko-Cotton saturation vapour pressure coefficients
+FWC_COEFFS = {
+    "C0": 6.115836990e2,  # Pa
+    "C1": 0.444606896e2,  # Pa/K
+    "C2": 0.143177157e1,  # Pa/K²
+    "C3": 0.264224321e-1,  # Pa/K³
+    "C4": 0.299291081e-3,  # Pa/K⁴
+    "C5": 0.203154182e-5,  # Pa/K⁵
+    "C6": 0.702620698e-8,  # Pa/K⁶
+    "C7": 0.379534310e-11,  # Pa/K⁷
+    "C8": -0.321582393e-13,  # Pa/K⁸
+}
+
+# Isotope constants (VSMOW standard)
+ISOTOPE_CONSTANTS = {
+    "VSMOW_R_2H": 155.76e-6,  # Heavy-to-light isotope abundance ratio for deuterium
+    "VSMOW_R_3H": 1.85e-17,  # For tritium
+    "VSMOW_R_18O": 2005.20e-6,  # For oxygen-18
+    "VSMOW_R_17O": 379.9e-6,  # For oxygen-17
+    "M_1H": 1.00782503224e-3,  # Hydrogen atomic weight (kg/mol)
+    "M_2H": 2.01410177812e-3,  # Deuterium atomic weight (kg/mol)
+    "M_16O": 15.99491461957e-3,  # Oxygen-16 atomic weight (kg/mol)
+    "M_18O": 17.99915961287e-3,  # Oxygen-18 atomic weight (kg/mol)
+}
+
+
+@mcp.tool(name="get_physical_constants", description="Retrieve physical constants")
+def get_physical_constants() -> dict:
+    """
+    Retrieve physical constants used in PySDM simulations.
+
+    Returns:
+    - dict: Dictionary containing physical constants with their values and units.
+    """
+    try:
+        result = {
+            "fundamental_constants": {
+                "R_str": {"value": PHYSICAL_CONSTANTS["R_str"], "unit": "J/(K·mol)", "description": "Universal gas constant"},
+                "N_A": {"value": PHYSICAL_CONSTANTS["N_A"], "unit": "1/mol", "description": "Avogadro constant"},
+                "g_std": {"value": PHYSICAL_CONSTANTS["g_std"], "unit": "m/s²", "description": "Standard gravity"},
+                "PI": {"value": PHYSICAL_CONSTANTS["PI"], "unit": "dimensionless", "description": "Pi"},
+            },
+            "thermodynamic_constants": {
+                "T0": {"value": PHYSICAL_CONSTANTS["T0"], "unit": "K", "description": "Zero Celsius in Kelvin"},
+                "c_pd": {"value": PHYSICAL_CONSTANTS["c_pd"], "unit": "J/(kg·K)", "description": "Specific heat of dry air"},
+                "c_pv": {"value": PHYSICAL_CONSTANTS["c_pv"], "unit": "J/(kg·K)", "description": "Specific heat of water vapour"},
+                "l_tri": {"value": PHYSICAL_CONSTANTS["l_tri"], "unit": "J/kg", "description": "Latent heat of vaporization"},
+            },
+            "molecular_constants": {
+                "Md": {"value": PHYSICAL_CONSTANTS["Md"], "unit": "kg/mol", "description": "Dry air molar mass"},
+                "Mv": {"value": PHYSICAL_CONSTANTS["Mv"], "unit": "kg/mol", "description": "Water vapour molar mass"},
+                "eps": {"value": PHYSICAL_CONSTANTS["eps"], "unit": "dimensionless", "description": "Mv/Md ratio"},
+                "rho_w": {"value": PHYSICAL_CONSTANTS["rho_w"], "unit": "kg/m³", "description": "Density of liquid water"},
+            },
+            "accommodation_coefficients": {
+                "MAC": {"value": PHYSICAL_CONSTANTS["MAC"], "unit": "dimensionless", "description": "Mass accommodation coefficient"},
+                "HAC": {"value": PHYSICAL_CONSTANTS["HAC"], "unit": "dimensionless", "description": "Thermal accommodation coefficient"},
+            }
+        }
+        return {"success": True, "result": result, "error": None}
+    except Exception as e:
+        return {"success": False, "result": None, "error": str(e)}
+
+
+# ===================== Saturation Vapour Pressure =====================
+
+def _pvs_flatau_walko_cotton(T_celsius: float) -> float:
+    """Calculate saturation vapour pressure using Flatau-Walko-Cotton polynomial."""
+    C = FWC_COEFFS
+    return (C["C0"] + T_celsius * (C["C1"] + T_celsius * (C["C2"] + T_celsius * (
+        C["C3"] + T_celsius * (C["C4"] + T_celsius * (C["C5"] + T_celsius * (
+            C["C6"] + T_celsius * (C["C7"] + T_celsius * C["C8"]))))))))
+
+
+def _pvs_august_roche_magnus(T_celsius: float) -> float:
+    """Calculate saturation vapour pressure using August-Roche-Magnus formula."""
+    # Coefficients from Alduchov & Eskridge 1996
+    C1 = 610.94  # Pa
+    C2 = 17.625
+    C3 = 243.04  # °C
+    return C1 * math.exp(C2 * T_celsius / (T_celsius + C3))
+
+
+@mcp.tool(name="calculate_saturation_vapour_pressure", description="Calculate saturation vapour pressure over water")
+def calculate_saturation_vapour_pressure(temperature_kelvin: float, method: str = "flatau_walko_cotton") -> dict:
     """
-    Simulate particle dynamics using PySDM.
+    Calculate saturation vapour pressure over liquid water.
 
     Parameters:
-    - particle_count (int): Number of particles to simulate.
-    - time_step (float): Time step for the simulation.
+    - temperature_kelvin (float): Temperature in Kelvin.
+    - method (str): Method to use - 'flatau_walko_cotton' or 'august_roche_magnus'.
 
     Returns:
-    - dict: A dictionary containing success, result, and error fields.
+    - dict: Saturation vapour pressure in Pascals and hectopascals.
     """
     try:
-        # Example simulation logic
-        result = particulator.simulate(particle_count, time_step)
+        T_celsius = temperature_kelvin - PHYSICAL_CONSTANTS["T0"]
+        
+        if method == "flatau_walko_cotton":
+            pvs = _pvs_flatau_walko_cotton(T_celsius)
+        elif method == "august_roche_magnus":
+            pvs = _pvs_august_roche_magnus(T_celsius)
+        else:
+            return {"success": False, "result": None, "error": f"Unknown method: {method}. Use 'flatau_walko_cotton' or 'august_roche_magnus'."}
+        
+        result = {
+            "temperature_K": temperature_kelvin,
+            "temperature_C": T_celsius,
+            "saturation_vapour_pressure_Pa": pvs,
+            "saturation_vapour_pressure_hPa": pvs / 100,
+            "method": method
+        }
         return {"success": True, "result": result, "error": None}
     except Exception as e:
         return {"success": False, "result": None, "error": str(e)}
 
+
+# ===================== Condensation Calculations =====================
+
 @mcp.tool(name="calculate_condensation", description="Calculate condensation rates")
-def calculate_condensation(temperature: float, pressure: float) -> dict:
+def calculate_condensation(temperature: float, pressure: float, relative_humidity: float = 1.0) -> dict:
     """
-    Calculate condensation rates.
+    Calculate condensation-related parameters.
 
     Parameters:
     - temperature (float): Temperature in Kelvin.
     - pressure (float): Pressure in Pascals.
+    - relative_humidity (float): Relative humidity (0-1 or as fraction >1 for supersaturation).
 
     Returns:
-    - dict: A dictionary containing success, result, and error fields.
+    - dict: Condensation parameters including supersaturation and vapour pressure.
     """
     try:
-        # Example condensation calculation
-        rate = condensation.calculate_rate(temperature, pressure)
-        return {"success": True, "result": rate, "error": None}
+        T_celsius = temperature - PHYSICAL_CONSTANTS["T0"]
+        pvs = _pvs_flatau_walko_cotton(T_celsius)
+        
+        # Actual vapour pressure
+        pv = relative_humidity * pvs
+        
+        # Supersaturation
+        supersaturation = relative_humidity - 1.0
+        
+        # Water vapour mixing ratio
+        eps = PHYSICAL_CONSTANTS["eps"]
+        mixing_ratio = eps * pv / (pressure - pv)
+        
+        # Specific humidity
+        specific_humidity = mixing_ratio / (1 + mixing_ratio)
+        
+        result = {
+            "temperature_K": temperature,
+            "pressure_Pa": pressure,
+            "saturation_vapour_pressure_Pa": pvs,
+            "actual_vapour_pressure_Pa": pv,
+            "relative_humidity": relative_humidity,
+            "supersaturation": supersaturation,
+            "supersaturation_percent": supersaturation * 100,
+            "water_vapour_mixing_ratio": mixing_ratio,
+            "specific_humidity": specific_humidity
+        }
+        return {"success": True, "result": result, "error": None}
     except Exception as e:
         return {"success": False, "result": None, "error": str(e)}
 
-@mcp.tool(name="get_physical_constants", description="Retrieve physical constants")
-def get_physical_constants() -> dict:
+
+# ===================== Particle Dynamics =====================
+
+@mcp.tool(name="simulate_particles", description="Simulate particle dynamics using PySDM")
+def simulate_particles(particle_count: int, time_step: float) -> dict:
     """
-    Retrieve physical constants.
+    Get information about particle simulation parameters in PySDM.
+
+    Parameters:
+    - particle_count (int): Number of super-droplets to simulate.
+    - time_step (float): Time step for the simulation in seconds.
 
     Returns:
-    - dict: A dictionary containing success, result, and error fields.
+    - dict: Simulation configuration and recommendations.
     """
     try:
-        # Example retrieval of constants
-        constants_data = constants.get_constants()
-        return {"success": True, "result": constants_data, "error": None}
+        # PySDM condensation solver defaults
+        defaults = {
+            "rtol_x": 1e-6,  # Relative tolerance for particle size
+            "rtol_thd": 1e-6,  # Relative tolerance for thermodynamic variables
+            "dt_cond_range": (1e-4, 1.0),  # Condensation timestep range (s)
+            "max_iters": 16,  # Maximum iterations for solver
+        }
+        
+        result = {
+            "configuration": {
+                "n_sd": particle_count,
+                "dt": time_step,
+                "dt_unit": "seconds"
+            },
+            "solver_defaults": defaults,
+            "available_dynamics": [
+                "Condensation",
+                "Collision/Coalescence",
+                "Displacement",
+                "Freezing",
+                "AqueousChemistry",
+                "IsotopicFractionation",
+                "VapourDepositionOnIce"
+            ],
+            "recommendations": {
+                "adaptive_timestep": "Recommended for condensation",
+                "suggested_n_sd": "100-10000 for typical cloud simulations"
+            }
+        }
+        return {"success": True, "result": result, "error": None}
     except Exception as e:
         return {"success": False, "result": None, "error": str(e)}
 
+
+# ===================== Trivia/Utility Functions =====================
+
+@mcp.tool(name="calculate_droplet_volume", description="Calculate droplet volume from radius")
+def calculate_droplet_volume(radius_um: float) -> dict:
+    """
+    Calculate droplet volume and related properties.
+
+    Parameters:
+    - radius_um (float): Droplet radius in micrometers.
+
+    Returns:
+    - dict: Volume, surface area, and mass of the droplet.
+    """
+    try:
+        radius_m = radius_um * 1e-6
+        PI = PHYSICAL_CONSTANTS["PI"]
+        rho_w = PHYSICAL_CONSTANTS["rho_w"]
+        
+        volume = (4/3) * PI * radius_m**3
+        surface_area = 4 * PI * radius_m**2
+        mass = rho_w * volume
+        
+        result = {
+            "radius_um": radius_um,
+            "radius_m": radius_m,
+            "volume_m3": volume,
+            "volume_um3": volume * 1e18,
+            "surface_area_m2": surface_area,
+            "surface_area_um2": surface_area * 1e12,
+            "mass_kg": mass,
+            "mass_ng": mass * 1e12
+        }
+        return {"success": True, "result": result, "error": None}
+    except Exception as e:
+        return {"success": False, "result": None, "error": str(e)}
+
+
+@mcp.tool(name="calculate_radius_from_volume", description="Calculate droplet radius from volume")
+def calculate_radius_from_volume(volume_um3: float) -> dict:
+    """
+    Calculate droplet radius from volume.
+
+    Parameters:
+    - volume_um3 (float): Droplet volume in cubic micrometers.
+
+    Returns:
+    - dict: Radius in various units.
+    """
+    try:
+        volume_m3 = volume_um3 * 1e-18
+        PI = PHYSICAL_CONSTANTS["PI"]
+        
+        radius_m = (volume_m3 * 3 / (4 * PI)) ** (1/3)
+        radius_um = radius_m * 1e6
+        
+        result = {
+            "volume_um3": volume_um3,
+            "volume_m3": volume_m3,
+            "radius_m": radius_m,
+            "radius_um": radius_um,
+            "diameter_um": 2 * radius_um
+        }
+        return {"success": True, "result": result, "error": None}
+    except Exception as e:
+        return {"success": False, "result": None, "error": str(e)}
+
+
+# ===================== Kappa-Köhler Hygroscopicity =====================
+
+@mcp.tool(name="calculate_kappa_koehler", description="Calculate critical supersaturation using kappa-Köhler theory")
+def calculate_kappa_koehler(dry_radius_um: float, kappa: float, temperature_kelvin: float = 293.15) -> dict:
+    """
+    Calculate critical supersaturation and radius using kappa-Köhler theory.
+
+    Parameters:
+    - dry_radius_um (float): Dry aerosol radius in micrometers.
+    - kappa (float): Hygroscopicity parameter (kappa).
+    - temperature_kelvin (float): Temperature in Kelvin (default 293.15 K = 20°C).
+
+    Returns:
+    - dict: Critical supersaturation and activation radius.
+    """
+    try:
+        # Physical constants
+        sigma = 0.072  # Surface tension of water (N/m)
+        Mv = PHYSICAL_CONSTANTS["Mv"]
+        rho_w = PHYSICAL_CONSTANTS["rho_w"]
+        R = PHYSICAL_CONSTANTS["R_str"]
+        T = temperature_kelvin
+        
+        dry_radius_m = dry_radius_um * 1e-6
+        
+        # Kelvin parameter A
+        A = 2 * sigma * Mv / (rho_w * R * T)
+        
+        # Critical supersaturation (approximation from leading terms)
+        # S_c ≈ (4 A³ / 27 κ D_dry³)^0.5
+        S_c = math.sqrt(4 * A**3 / (27 * kappa * dry_radius_m**3))
+        
+        # Critical radius
+        r_c = math.sqrt(3 * kappa * dry_radius_m**3 / A)
+        
+        result = {
+            "dry_radius_um": dry_radius_um,
+            "kappa": kappa,
+            "temperature_K": temperature_kelvin,
+            "kelvin_parameter_A": A,
+            "critical_supersaturation": S_c,
+            "critical_supersaturation_percent": S_c * 100,
+            "critical_radius_um": r_c * 1e6,
+            "activation_diameter_um": 2 * r_c * 1e6
+        }
+        return {"success": True, "result": result, "error": None}
+    except Exception as e:
+        return {"success": False, "result": None, "error": str(e)}
+
+
+# ===================== Isotope Tools =====================
+
+@mcp.tool(name="get_isotope_constants", description="Get water isotope constants")
+def get_isotope_constants() -> dict:
+    """
+    Get water isotope constants (VSMOW standard).
+
+    Returns:
+    - dict: Isotope abundance ratios and atomic masses.
+    """
+    try:
+        result = {
+            "VSMOW_ratios": {
+                "R_2H": {"value": ISOTOPE_CONSTANTS["VSMOW_R_2H"], "description": "Deuterium abundance ratio"},
+                "R_3H": {"value": ISOTOPE_CONSTANTS["VSMOW_R_3H"], "description": "Tritium abundance ratio"},
+                "R_18O": {"value": ISOTOPE_CONSTANTS["VSMOW_R_18O"], "description": "Oxygen-18 abundance ratio"},
+                "R_17O": {"value": ISOTOPE_CONSTANTS["VSMOW_R_17O"], "description": "Oxygen-17 abundance ratio"},
+            },
+            "atomic_masses_kg_per_mol": {
+                "M_1H": ISOTOPE_CONSTANTS["M_1H"],
+                "M_2H": ISOTOPE_CONSTANTS["M_2H"],
+                "M_16O": ISOTOPE_CONSTANTS["M_16O"],
+                "M_18O": ISOTOPE_CONSTANTS["M_18O"],
+            },
+            "description": "VSMOW (Vienna Standard Mean Ocean Water) is the international standard for water isotope ratios"
+        }
+        return {"success": True, "result": result, "error": None}
+    except Exception as e:
+        return {"success": False, "result": None, "error": str(e)}
+
+
+# ===================== Available Formulae =====================
+
+@mcp.tool(name="list_available_formulae", description="List available physics formulae in PySDM")
+def list_available_formulae() -> dict:
+    """
+    List available physics formulae options in PySDM.
+
+    Returns:
+    - dict: Categories of formulae with available options.
+    """
+    try:
+        result = {
+            "saturation_vapour_pressure": [
+                "FlatauWalkoCotton",
+                "AugustRocheMagnus",
+                "Lowe1977",
+                "MurphyKoop2005",
+                "Wexler1976",
+                "Bolton1980"
+            ],
+            "hygroscopicity": [
+                "KappaKoehler",
+                "KappaKoehlerLeadingTerms"
+            ],
+            "latent_heat_vapourisation": [
+                "Kirchhoff",
+                "Constant"
+            ],
+            "drop_growth": [
+                "Mason1971",
+                "FuchsSutugin"
+            ],
+            "surface_tension": [
+                "Constant",
+                "CompressedFilm"
+            ],
+            "terminal_velocity": [
+                "GunnKinzer1949",
+                "PowerSeries",
+                "RogersYau"
+            ],
+            "freezing_temperature_spectrum": [
+                "Null",
+                "Bigg1953",
+                "Niemand_et_al_2012"
+            ],
+            "description": "These are configurable physics options in PySDM.Formulae"
+        }
+        return {"success": True, "result": result, "error": None}
+    except Exception as e:
+        return {"success": False, "result": None, "error": str(e)}
+
+
 def create_app() -> FastMCP:
     """
     Create and return the FastMCP application instance.