⚡ V.A.L.K.Y.R.I.E.

Validated Aerospace Logic & Kinetic Yield Reasoning Intelligence Engine

Know if your drone can fly the mission before you build it.

Mission Lab • Quick Start • MCP • Military Checks • Validation • Docs • Roadmap

🎯 The Problem

Most small-scale UAVs fly by accident.

The typical development process:

1. Sketch on paper 📝

2. Jump straight into CAD 🖥️

3. Pick a motor from static thrust tables ⚡

4. Cross fingers and maiden flight 🤞

In hobbyist prototyping, trial-and-error is acceptable. In defense tech, autonomous systems, and physical AI platforms, skipping first-principles aerospace engineering destroys payload capacity, endurance margins, and program timelines before a single rib is cut.

VALKYRIE sizes a small electric fixed-wing aircraft from its mission (payload, endurance, range, field, altitude, weather), and says plainly when the mission is impossible.

Who It's For

• Defense & tactical UAS teams: check a CONOPS against physics before a program commits: DoD UAS Group, wind penetration and hot-and-high field performance come out of every sizing run

• UAV builders: RC, FPV and fixed-wing people who want to know the battery and wing size before the maiden flight

• Aerospace students: textbook conceptual sizing (Raymer, Anderson, Mattingly) as readable, tested, validated Python

• Agent builders: an MCP server, so an LLM can answer "is this mission physically possible?" with physics instead of a guess

Related MCP server: lucad

🛰️ Mission Lab

pip install -e .
valkyrie-lab            # opens http://127.0.0.1:8765

Drag a slider and the aircraft is re-sized, re-simulated and re-plotted: an animated mission profile with live telemetry, battery state of charge and power over time, the constraint diagram with the design point, energy by segment, energy vs wind direction, the DoD UAS Group and every engineering check. Same engine as the library and MCP server.

🏗️ System Architecture

1. Mission input & interfaces: payload, endurance and/or range (one-way or round_trip), field elevation, cruise altitude, temperature (hot-and-high), wind (max_wind_speed_ms), and stall speed cap (max_stall_speed_ms); driven from Python, Mission Lab (valkyrie-lab), or an LLM over MCP (valkyrie-mcp).

2. Physics, sizing & simulation engine: USSA-1976 geopotential atmosphere, parabolic drag polar ($C_D = C_{D0} + k C_L^2$), constraint analysis ($T/W$ vs. $W/S$ with stall/landing cap), wind-optimal battery energy budget (climb + transit out + loiter + transit back, UIUC-validated $\eta_p = 0.70$), iterative weight closure with runaway guards, and a 1 s time-stepping MissionSimulator with 0–360° vector wind.

3. Validated design point & military checks: weight, wing area, thrust, battery mass, DoD UAS Group (1–5), wind-penetration and structural/Reynolds checks, plus sourced COTS component lookup — or feasible: false with the physical reason the mission can't be flown.

How each step works, with equations and sources: docs/theory.md.

🚀 Quick Start

git clone https://github.com/madhavmadupu/valkyrie-mcp.git
cd valkyrie-mcp
python -m venv venv && source venv/bin/activate   # Windows: venv\Scripts\activate
pip install -e .

from valkyrie import MissionRequirements, ConstraintAnalyzer

mission = MissionRequirements(
    payload_mass_kg=0.91,        # 2.0 lb EO/IR camera
    endurance_hours=0.75,        # 45 minutes on station
    takeoff_distance_m=76,       # 250 ft grass field
    cruise_altitude_m=300,       # low-altitude surveillance
)
design = ConstraintAnalyzer(mission).solve()

print(f"Gross weight:  {design.gross_weight_kg:.2f} kg")
print(f"Wing area:     {design.wing_area_m2:.3f} m²")
print(f"Thrust:        {design.required_thrust_n:.2f} N")
print(f"Battery:       {design.battery_mass_kg:.3f} kg")

Gross weight:  2.31 kg
Wing area:     0.183 m²
Thrust:        6.18 N
Battery:       0.243 kg

Impossible missions fail loudly instead of returning a fantasy aircraft:

MissionRequirements(payload_mass_kg=10, endurance_hours=10, takeoff_distance_m=50, cruise_altitude_m=5000)
# ConvergenceError: Sum of fractions exceeds 1.0: We/W0=0.500, BMF=1.793.

All mission inputs, outputs and a full walkthrough: docs/getting-started.md.

🤖 Use it from Claude (MCP)

pip install -e .
claude mcp add valkyrie -- valkyrie-mcp       # Claude Code

Claude Desktop (claude_desktop_config.json):

{ "mcpServers": { "valkyrie": { "command": "valkyrie-mcp" } } }

Then ask: "Can a fixed-wing drone carry a 2 lb camera for 45 minutes and take off in 250 ft?" or "Same mission from a 6,000 ft strip at 45 °C in 15 m/s wind: what DoD group, and does it still work?"

Works with mcp 1.x and 2.x.

🪖 Military Operating Checks

from valkyrie.analysis import DesignValidator

mission = MissionRequirements(
    payload_mass_kg=0.91, endurance_hours=0.75, takeoff_distance_m=76,
    field_elevation_m=1800, cruise_altitude_m=2100,   # high-altitude strip
    temperature_celsius=45, max_wind_speed_ms=15,      # hot day, gusty
)
design = ConstraintAnalyzer(mission).solve()
validator = DesignValidator(mission, design)
validator.validate_all()
print(validator.uas_group(), validator.summary())      # 1, wind_penetration_marginal warning

Details and thresholds: docs/theory.md § Military operating checks.

🔬 Validation

Tests prove the code is self-consistent; validation checks it against outside evidence. Full report with figures: docs/validation.md (regenerated by validation/run_validation.py).

Validation changed the model: propeller efficiency dropped from 0.80 to 0.70 after the UIUC data, climb energy was added after the simulator exposed it, and the parts database was rebuilt from manufacturer pages. On real Albatross flights the defaults under-predict cruise power by a median 18%, which is in line with avionics and payload drawing from the same battery. The datasets are in validation/data/, every row traceable to a public log, a datasheet or a Wikipedia revision. Still missing: a flight log of a weighed aircraft (CONTRIBUTING.md).

📖 Documentation

🗺️ Roadmap

✅ Done (v0.1.x)

• Constraint analysis (T/W vs W/S) with stall/landing-limited wing loading

• Battery energy budget: climb, transit (one-way and out-and-back, with wind), loiter

• Military operating checks: DoD UAS Group, wind penetration, hot-and-high

• Time-stepping mission simulator

• Validation suite against USSA-1976, Skywalker X8, UIUC propeller data, AeroSandbox

• MCP server (size_uav, find_components)

• Mission Lab: interactive sizing, simulation and plots in the browser (valkyrie-lab)

🎯 Next (v0.2.0)

• End-to-end validation against a real flight log

• Empty-weight model that scales with size and wing area (replaces the fixed 50% fraction)

• Battery reserve, Peukert effect, payload + avionics power draw

• Motor power sizing (P = T·V/η) wired to the component database

• Max dash speed sizing, so the DoD group and wind checks use dash speed, not cruise

• Plotted constraint diagram generated from the solver

• Hybrid / ICE propulsion (Group 2–3 aircraft); currently rejected with a clear error

Vision: No one should have to maiden-fly an aircraft to find out whether its mission was possible.

🤝 Contributing

We welcome contributions from aerospace engineers, defense tech developers, and autonomy researchers. The most valuable one right now is a flight log (mass, wing area, battery energy used, airspeed, wind) to validate endurance end to end.

See CONTRIBUTING.md.

📜 Citation

@software{valkyrie_mcp,
  author = {Madupu, Madhav},
  title = {VALKYRIE: Validated Aerospace Logic \& Kinetic Yield Reasoning Intelligence Engine},
  year = {2026},
  url = {https://github.com/madhavmadupu/valkyrie-mcp},
  note = {Physics-aware mission intelligence for autonomous systems}
}

🌟 From the Author

"I've watched defense tech startups waste months building UAVs that couldn't meet their stated endurance requirements. I've seen military operators request missions that violated basic aerodynamics. Intelligence platforms fuse data brilliantly but can't answer: 'Is this even possible?'

VALKYRIE enforces the laws of physics before you commit resources. No more accidental flight."

— Madhav Madupu, Aerospace Systems Engineer

⚖️ License

Apache License 2.0 - See LICENSE for details.

🔗 Links

• Documentation: madhavmadupu.github.io/valkyrie-mcp

• Issues/Features: GitHub Issues

• Author: Madhav Madupu | LinkedIn | madhav.madupu@gmail.com

⚡ Built for engineers who refuse to let aircraft fly by accident. ⚡

⭐ Star this repo if VALKYRIE saves you from an impossible UAV design!