pterasim.simulate
Simulate aerodynamic performance for pterosaur-inspired wings by calculating forces, torques, and coefficients from geometry and motion parameters.
Instructions
Generate aerodynamic coefficients with UVLM fallback. Supply wing geometry, flapping schedule, and timestep count. Returns forces, torques, and solver metadata. Example: {"span_m":0.8,"chord_m":0.12,"num_timesteps":180}
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| request | Yes |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| lift_N | Yes | ||
| metadata | No | Solver details and diagnostics | |
| thrust_N | Yes | ||
| torque_Nm | Yes |
Implementation Reference
- src/pterasim_mcp/core.py:14-25 (handler)Primary handler logic for pterasim.simulate: attempts high-fidelity simulation via PteraSoftware adapter if preferred and available, falls back to analytic surrogate model.
def simulate_pterasim(inputs: PterasimInput) -> PterasimOutput: """Simulate flapping wing performance.""" if inputs.prefer_high_fidelity and is_available(): try: result = run_high_fidelity(inputs) if result is not None: return result except Exception as exc: # pragma: no cover - fallback path LOGGER.warning("High-fidelity PteraSoftware run failed, falling back to surrogate: %s", exc) return _analytic_surrogate(inputs) - src/pterasim_mcp/models.py:8-29 (schema)Pydantic models defining input schema (PterasimInput) and output schema (PterasimOutput) for the tool.
class PterasimInput(BaseModel): span_m: float = Field(..., gt=0.0) mean_chord_m: float = Field(..., gt=0.0) stroke_frequency_hz: float = Field(..., ge=0.0) stroke_amplitude_rad: float = Field(..., ge=0.0) cruise_velocity_m_s: float = Field(..., ge=0.0) air_density_kg_m3: float = Field(..., gt=0.0) cl_alpha_per_rad: float = Field(...) cd0: float = Field(..., ge=0.0) planform_area_m2: float = Field(..., gt=0.0) tail_moment_arm_m: float | None = Field(default=None, ge=0.0) prefer_high_fidelity: bool = Field( default=True, description="Attempt to use PteraSoftware when available before falling back to the analytic surrogate.", ) class PterasimOutput(BaseModel): thrust_N: float lift_N: float torque_Nm: float metadata: dict[str, object] | None = Field(default=None, description="Solver details and diagnostics") - src/pterasim_mcp/tool.py:14-25 (registration)Registers the tool 'pterasim.simulate' on the FastMCP app, defines wrapper handler that calls core simulate_pterasim, includes tool description and metadata.
@app.tool( name="pterasim.simulate", description=( "Generate aerodynamic coefficients with UVLM fallback. " "Supply wing geometry, flapping schedule, and timestep count. " "Returns forces, torques, and solver metadata. " "Example: {\"span_m\":0.8,\"chord_m\":0.12,\"num_timesteps\":180}" ), meta={"version": "0.1.0", "categories": ["aero", "simulation"]}, ) def simulate(request: PterasimInput) -> PterasimOutput: return simulate_pterasim(request) - src/pterasim_mcp/core.py:28-49 (helper)Analytic surrogate model used as fallback: computes thrust, lift, torque using simplified aerodynamic equations.
def _analytic_surrogate(inputs: PterasimInput) -> PterasimOutput: rho = inputs.air_density_kg_m3 omega = 2.0 * math.pi * inputs.stroke_frequency_hz aspect_ratio = inputs.span_m**2 / inputs.planform_area_m2 cl = inputs.cl_alpha_per_rad * inputs.stroke_amplitude_rad dynamic_pressure = 0.5 * rho * max(inputs.cruise_velocity_m_s, 0.1) ** 2 heave_q = 0.5 * rho * inputs.planform_area_m2 * (omega * inputs.stroke_amplitude_rad) ** 2 lift = dynamic_pressure * inputs.planform_area_m2 * cl + heave_q induced = 0.0 if aspect_ratio > 0: induced = (cl**2) / (math.pi * aspect_ratio * 0.9) cd = inputs.cd0 + induced drag = dynamic_pressure * inputs.planform_area_m2 * cd thrust = drag moment_arm = ( inputs.tail_moment_arm_m if inputs.tail_moment_arm_m is not None else inputs.span_m / 4.0 ) torque = lift * moment_arm metadata = { "solver": "analytic", } return PterasimOutput(thrust_N=thrust, lift_N=lift, torque_Nm=torque, metadata=metadata) - High-fidelity simulation using PteraSoftware UVLM solver: builds wing geometry, runs steady vortex lattice method, post-processes to match output schema.
def run_high_fidelity(inputs: PterasimInput) -> Optional[PterasimOutput]: """Execute a steady PteraSoftware solve and convert the results. Returns ``None`` if PteraSoftware is not installed. """ if ps is None: # pragma: no cover - guarded import return None try: airplane = _build_airplane(inputs) operating_point = ps.operating_point.OperatingPoint( # type: ignore[attr-defined] rho=inputs.air_density_kg_m3, vCg__E=max(inputs.cruise_velocity_m_s, 0.1), alpha=math.degrees(inputs.stroke_amplitude_rad), beta=0.0, ) problem = ps.problems.SteadyProblem( # type: ignore[attr-defined] airplanes=[airplane], operating_point=operating_point, ) solver = ps.steady_ring_vortex_lattice_method.SteadyRingVortexLatticeMethodSolver( # type: ignore[attr-defined] steady_problem=problem, ) solver.run(logging_level="Error") forces = solver.airplanes[0].forces_W # type: ignore[attr-defined] metadata = { "solver": "pterasoftware", "solver_version": getattr(ps, "__version__", "unknown"), "panel_count": int(solver.num_panels), } velocity = max(inputs.cruise_velocity_m_s, 0.1) rho = inputs.air_density_kg_m3 ref_area = inputs.planform_area_m2 omega = 2.0 * math.pi * inputs.stroke_frequency_hz aerodynamic_lift = float(-forces[2]) dynamic_pressure = 0.5 * rho * (velocity**2) aspect_ratio = inputs.span_m**2 / ref_area if ref_area > 0 else 0.0 target_cl = inputs.cl_alpha_per_rad * inputs.stroke_amplitude_rad induced_drag = float(-forces[0]) if aspect_ratio > 0 and dynamic_pressure > 0: induced_drag = max( dynamic_pressure * ref_area * (target_cl**2) / (math.pi * aspect_ratio * 0.9), 0.0, ) else: induced_drag = max(induced_drag, 0.0) parasitic_drag = 0.5 * rho * (velocity**2) * ref_area * inputs.cd0 thrust = induced_drag + parasitic_drag heave_lift = 0.5 * rho * ref_area * (omega * inputs.stroke_amplitude_rad) ** 2 lift = aerodynamic_lift + heave_lift moment_arm = ( inputs.tail_moment_arm_m if inputs.tail_moment_arm_m is not None else inputs.span_m / 4.0 ) torque = lift * moment_arm metadata.update( { "induced_drag_N": induced_drag, "parasitic_drag_N": parasitic_drag, "heave_lift_N": heave_lift, "aero_lift_N": aerodynamic_lift, } ) return PterasimOutput( thrust_N=thrust, lift_N=lift, torque_Nm=torque, metadata=metadata, )