Skip to main content

qualia_mcp/tools/
sim_geomechanics.rs

1//! MCP tools for Geotechnical Soil Mechanics, Compaction, and Excavation Kinematics.
2//!
3//! Powered by `qualia-sim::geomechanics`.
4//! Designed according to `AGENTS.md` ยง0-B (<500 lines).
5
6use crate::types::{parse_tool_args, McpSystemError};
7use qualia_sim::geomechanics::{
8    critical_trench_depth_m, evaluate_excavation_pass, evaluate_soil_compaction,
9    SoilMechanicsProfile, ToolEffector, ToolKind,
10};
11use serde_json::{json, Value};
12
13fn parse_soil_profile(v: &Value) -> SoilMechanicsProfile {
14    if let Some(name) = v.get("soil_preset").and_then(Value::as_str) {
15        let base = match name.to_lowercase().as_str() {
16            "bedrock" | "rock" => SoilMechanicsProfile::bedrock(),
17            "clay" | "dense_clay" => SoilMechanicsProfile::illuvial_clay(),
18            "humic" | "root_mat" => SoilMechanicsProfile::humic_root_mat(),
19            "saprolite" | "sand" | "dry_sand" => SoilMechanicsProfile::saprolite(),
20            _ => SoilMechanicsProfile::loam(),
21        };
22        let temp = v.get("temperature_c").and_then(Value::as_f64).map(|t| t as f32);
23        let sat = v.get("saturation_ratio").and_then(Value::as_f64).map(|s| s as f32);
24        if temp.is_some() || sat.is_some() {
25            return base.with_seasonal_state(temp.unwrap_or(15.0), sat.unwrap_or(0.35));
26        }
27        return base;
28    }
29
30    SoilMechanicsProfile {
31        cohesion_kpa: v.get("cohesion_kpa").and_then(Value::as_f64).unwrap_or(10.0) as f32,
32        friction_angle_rad: v.get("friction_angle_rad").and_then(Value::as_f64).unwrap_or(0.488) as f32,
33        bulk_density_kn_m3: v.get("bulk_density_kn_m3").and_then(Value::as_f64).unwrap_or(16.5) as f32,
34        pore_water_pressure_kpa: v.get("pore_water_pressure_kpa").and_then(Value::as_f64).unwrap_or(-15.0) as f32,
35        root_tensile_reinforcement_kpa: v.get("root_tensile_reinforcement_kpa").and_then(Value::as_f64).unwrap_or(5.0) as f32,
36        soil_tool_adhesion_kpa: v.get("soil_tool_adhesion_kpa").and_then(Value::as_f64).unwrap_or(2.5) as f32,
37        bulking_factor: v.get("bulking_factor").and_then(Value::as_f64).unwrap_or(1.25) as f32,
38        angle_of_repose_rad: v.get("angle_of_repose_rad").and_then(Value::as_f64).unwrap_or(0.558) as f32,
39        unconfined_compressive_strength_kpa: v.get("unconfined_compressive_strength_kpa").and_then(Value::as_f64).unwrap_or(85.0) as f32,
40    }
41}
42
43fn parse_tool_effector(v: &Value) -> ToolEffector {
44    if let Some(kind_str) = v.get("tool_preset").and_then(Value::as_str) {
45        return match kind_str.to_lowercase().as_str() {
46            "pickaxe" => ToolEffector::pickaxe(),
47            "mini_excavator" | "excavator" => ToolEffector::mini_excavator(),
48            "fossorial_claw" | "claw" => ToolEffector::wombat_claws(),
49            "raycast" | "mouse" => ToolEffector::mouse_click(),
50            _ => ToolEffector::hand_spade(),
51        };
52    }
53
54    let kind = match v.get("kind").and_then(Value::as_str).unwrap_or("spade") {
55        "pickaxe" => ToolKind::Pickaxe,
56        "excavator" => ToolKind::ExcavatorBucket,
57        "claw" => ToolKind::FossorialClaw,
58        "raycast" => ToolKind::ObservationRay,
59        _ => ToolKind::HandSpade,
60    };
61
62    ToolEffector {
63        kind,
64        blade_width_m: v.get("blade_width_m").and_then(Value::as_f64).unwrap_or(0.18) as f32,
65        rake_angle_rad: v.get("rake_angle_rad").and_then(Value::as_f64).unwrap_or(0.785) as f32,
66        wedge_angle_rad: v.get("wedge_angle_rad").and_then(Value::as_f64).unwrap_or(0.349) as f32,
67        applied_force_n: v.get("applied_force_n").and_then(Value::as_f64).unwrap_or(650.0) as f32,
68        applied_torque_nm: v.get("applied_torque_nm").and_then(Value::as_f64).unwrap_or(95.0) as f32,
69        capacity_volume_m3: v.get("capacity_volume_m3").and_then(Value::as_f64).unwrap_or(0.0035) as f32,
70    }
71}
72
73/// `sim_evaluate_excavation_pass` tool โ€” evaluates elasto-plastic cutting resistance, failure, and volumetric bulking.
74pub fn evaluate_excavation_pass_tool(args: &[u8]) -> Result<String, McpSystemError> {
75    let v = parse_tool_args(args)?;
76    let tool = parse_tool_effector(&v);
77    let soil = parse_soil_profile(&v);
78    let depth_m = v.get("depth_m").and_then(Value::as_f64).unwrap_or(0.10) as f32;
79
80    let verdict = evaluate_excavation_pass(&tool, depth_m, &soil);
81
82    let payload = json!({
83        "severed": verdict.severed,
84        "requiredForceN": verdict.required_force_n,
85        "appliedForceN": tool.applied_force_n,
86        "marginForceN": verdict.margin_force_n,
87        "excavatedBankVolumeM3": verdict.excavated_bank_volume_m3,
88        "excavatedLooseVolumeM3": verdict.excavated_loose_volume_m3,
89        "rootMatSevered": verdict.root_mat_severed,
90        "refusalHit": verdict.refusal_hit,
91    });
92    serde_json::to_string(&payload).map_err(|_| McpSystemError::ParseError)
93}
94
95/// `sim_evaluate_soil_compaction` tool โ€” evaluates pore collapse and Kozeny-Carman permeability degradation under load.
96pub fn evaluate_soil_compaction_tool(args: &[u8]) -> Result<String, McpSystemError> {
97    let v = parse_tool_args(args)?;
98    let pressure_kpa = v.get("contact_pressure_kpa").and_then(Value::as_f64).unwrap_or(150.0) as f32;
99    let initial_porosity = v.get("initial_porosity").and_then(Value::as_f64).unwrap_or(0.45) as f32;
100    let soil = parse_soil_profile(&v);
101
102    let (final_porosity, k_multiplier) = evaluate_soil_compaction(pressure_kpa, initial_porosity, &soil);
103
104    let payload = json!({
105        "initialPorosity": initial_porosity,
106        "finalPorosity": final_porosity,
107        "porosityReduction": initial_porosity - final_porosity,
108        "hydraulicConductivityMultiplier": k_multiplier,
109        "compactionLevel": if k_multiplier < 0.3 { "severe" } else if k_multiplier < 0.7 { "moderate" } else { "mild" },
110    });
111    serde_json::to_string(&payload).map_err(|_| McpSystemError::ParseError)
112}
113
114/// `sim_critical_trench_depth` tool โ€” calculates Rankine unconfined vertical trench wall collapse threshold.
115pub fn critical_trench_depth_tool(args: &[u8]) -> Result<String, McpSystemError> {
116    let v = parse_tool_args(args)?;
117    let soil = parse_soil_profile(&v);
118    let depth_m = critical_trench_depth_m(&soil);
119
120    let payload = json!({
121        "criticalTrenchDepthMeters": depth_m,
122        "safeWorkingDepthMeters": depth_m * 0.65,
123        "soilCohesionKpa": soil.cohesion_kpa,
124        "soilFrictionAngleRad": soil.friction_angle_rad,
125    });
126    serde_json::to_string(&payload).map_err(|_| McpSystemError::ParseError)
127}
128
129pub use evaluate_excavation_pass_tool as sim_trench_excavation;
130pub use evaluate_soil_compaction_tool as sim_soil_compaction;
131pub use critical_trench_depth_tool as sim_critical_trench_depth;