# KRA33-PRISMX UAM Vertiport Simulation

A discrete-event simulation platform for Urban Air Mobility (UAM) vertiport networks — models eVTOL dispatch, charging, and KPI collection, with a Streamlit dashboard, an MCP server for AI-assisted analysis, and a genetic-algorithm optimizer for vertiport network layout.

## Components

| File | Role |
|---|---|
| `uam_engine.py` | Core simulation engine — `DataLoader`, `eVTOL`, `Vertiport`, `UAMSim`, dispatch policies, KPI collection. Pure logic, no GUI. |
| `uam_web_app.py` | Streamlit dashboard for running simulations and visualizing results (maps, charts). |
| `uam_mcp_analyst.py` | MCP server exposing the simulator as tools for Claude Desktop ("Strategic Operations Analyst" — run simulations, analyze KPIs, what-if studies). |
| `uam_worker.py` | Detached background process for long-running simulation/sensitivity jobs, spawned by the MCP server. |
| `uam_lausa.py` | LAUSA — Latent-factor Analysis of Urban Suitability & Attractiveness, a pre-simulation site-selection module for scoring candidate vertiport locations. |
| `uam_app.py` | Single packaged entry point (dispatches to dashboard / `--mcp-server` / `--worker` modes) used when building the standalone executable. |
| `C_HGA/` | C++ hybrid genetic algorithm for vertiport network optimization. |

## Requirements

- Python 3.12
- `gurobipy` (requires a Gurobi license for problem sizes beyond the trial limit)
- A C++ compiler (for building `C_HGA/uam_hybrid_ga.cpp`, Windows/MinGW `Makefile` included)

```bash
pip install -r requirements.txt
```

## Running

**Dashboard (dev):**
```bash
streamlit run uam_web_app.py
```

**MCP server** (for Claude Desktop):
```bash
python uam_mcp_analyst.py
```

Add it to Claude Desktop's MCP config (`claude_desktop_config.json` — accessible via Claude Desktop → Settings → Developer → Edit Config), then restart Claude Desktop.

*Running from source (requires Python + dependencies installed):*
```json
{
  "mcpServers": {
    "uam-analyst": {
      "command": "python",
      "args": ["<absolute-path-to>/uam_mcp_analyst.py"]
    }
  }
}
```
Replace `<absolute-path-to>` with the full path to `uam_mcp_analyst.py` on your machine.

*Running the packaged `.exe` (no Python needed — see [Building the standalone executable](#building-the-standalone-executable)):*
```json
{
  "mcpServers": {
    "uam-analyst": {
      "command": "<absolute-path-to>/UAMSimulator.exe",
      "args": ["--mcp-server"]
    }
  }
}
```
Replace `<absolute-path-to>` with the full path to `UAMSimulator.exe` (e.g. `dist/UAMSimulator/UAMSimulator.exe` after building, or wherever you extracted the release zip).

**Packaged entry point** (same three modes, used by the built `.exe`):
```bash
python uam_app.py                                   # dashboard
python uam_app.py --mcp-server                       # MCP server
python uam_app.py --worker <task_type> <token> <json> # background job
```

## Building the standalone executable

```bash
pyinstaller UAMSimulator.spec
```
Output goes to `dist/UAMSimulator/`. The built app is distributed via [GitHub Releases](../../releases) rather than committed to the repo.

## Data

Sample datasets live in `sample_data/` (demand data, vertiport info, LAUSA site-scoring geojson). `simulation_config.json` holds default simulation parameters.