{
  "cells": [
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "# PCSWMM Engineering Review Dashboard v0.3\n",
        "\n",
        "Deterministic, read-only hydrology, pond, topology, scenario, and model QA/QC.\n",
        "\n",
        "**Open a PCSWMM project before running this notebook.**"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## 1. Load the matching SDK"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {},
      "outputs": [],
      "source": [
        "import sys\n",
        "import importlib\n",
        "from pathlib import Path\n",
        "\n",
        "REQUIRED_VERSION = \"0.3.0\"\n",
        "ROOT = Path.cwd()\n",
        "\n",
        "preferred = [\n",
        "    ROOT / \"PCSWMM_Engineering_SDK_v0_3\",\n",
        "    ROOT / \"PCSWMM_Engineering_SDK_v0_3\" / \"PCSWMM_Engineering_SDK_v0_3\",\n",
        "]\n",
        "\n",
        "SDK_ROOT = next(\n",
        "    (path for path in preferred if (path / \"pcswmm_ai\").is_dir()),\n",
        "    None,\n",
        ")\n",
        "\n",
        "if SDK_ROOT is None:\n",
        "    matches = [\n",
        "        p.parent for p in ROOT.rglob(\"pcswmm_ai\")\n",
        "        if p.is_dir() and \"Engineering_SDK_v0_3\" in str(p.parent)\n",
        "    ]\n",
        "    SDK_ROOT = matches[0] if matches else None\n",
        "\n",
        "if SDK_ROOT is None:\n",
        "    raise FileNotFoundError(\"PCSWMM Engineering SDK v0.3 was not found.\")\n",
        "\n",
        "for module_name in list(sys.modules):\n",
        "    if module_name == \"pcswmm_ai\" or module_name.startswith(\"pcswmm_ai.\"):\n",
        "        del sys.modules[module_name]\n",
        "\n",
        "sys.path = [\n",
        "    p for p in sys.path\n",
        "    if \"PCSWMM_AI_SDK_v0_\" not in str(p)\n",
        "    and \"PCSWMM_Engineering_SDK_v0_3\" not in str(p)\n",
        "]\n",
        "sys.path.insert(0, str(SDK_ROOT))\n",
        "importlib.invalidate_caches()\n",
        "\n",
        "from pcswmm_ai import PCSWMMClient, __version__\n",
        "import pcswmm_ai\n",
        "\n",
        "print(\"SDK root:\", SDK_ROOT)\n",
        "print(\"SDK package:\", Path(pcswmm_ai.__file__).resolve())\n",
        "print(\"SDK version:\", __version__)\n",
        "\n",
        "if __version__ != REQUIRED_VERSION:\n",
        "    raise RuntimeError(\n",
        "        f\"Expected SDK {REQUIRED_VERSION}, loaded {__version__}\"\n",
        "    )\n",
        "\n",
        "client = PCSWMMClient(pcpy)\n",
        "client.health()"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## 2. Project and model inventory"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {},
      "outputs": [],
      "source": [
        "import pandas as pd\n",
        "from IPython.display import display, Markdown\n",
        "\n",
        "display(pd.DataFrame(\n",
        "    list(client.project.summary().items()),\n",
        "    columns=[\"Property\", \"Value\"],\n",
        "))\n",
        "display(pd.DataFrame(client.collections.summary()))"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## 3. Hydrology review"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {},
      "outputs": [],
      "source": [
        "display(Markdown(\"### Hydrology summary\"))\n",
        "display(pd.DataFrame(\n",
        "    list(client.hydrology.summary().items()),\n",
        "    columns=[\"Metric\", \"Value\"],\n",
        "))\n",
        "\n",
        "display(Markdown(\"### Hydrology findings\"))\n",
        "display(pd.DataFrame(client.hydrology.review()))"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## 4. Pond and outlet review"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {},
      "outputs": [],
      "source": [
        "display(Markdown(\"### Pond summary\"))\n",
        "display(pd.DataFrame(\n",
        "    list(client.pond.summary().items()),\n",
        "    columns=[\"Metric\", \"Value\"],\n",
        "))\n",
        "\n",
        "display(Markdown(\"### Storage records\"))\n",
        "display(pd.DataFrame(client.pond.storage_records()))\n",
        "\n",
        "display(Markdown(\"### Outlet structures\"))\n",
        "display(pd.DataFrame(client.pond.outlet_records()))\n",
        "\n",
        "display(Markdown(\"### Pond findings\"))\n",
        "display(pd.DataFrame(client.pond.review()))"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## 5. Topology review"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {},
      "outputs": [],
      "source": [
        "display(Markdown(\"### Link endpoints\"))\n",
        "display(pd.DataFrame(client.topology.link_endpoints()))\n",
        "\n",
        "display(Markdown(\"### Orphan links\"))\n",
        "display(pd.DataFrame(client.topology.orphan_links()))\n",
        "\n",
        "display(Markdown(\"### Isolated nodes\"))\n",
        "display(pd.DataFrame(client.topology.isolated_nodes()))\n",
        "\n",
        "display(Markdown(\"### Duplicate directed link pairs\"))\n",
        "display(pd.DataFrame(client.topology.duplicate_link_pairs()))"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## 6. Scenario source-file review"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {},
      "outputs": [],
      "source": [
        "display(pd.DataFrame(\n",
        "    list(client.scenarios.summary().items()),\n",
        "    columns=[\"Metric\", \"Value\"],\n",
        "))\n",
        "display(pd.DataFrame(client.scenarios.path_status()))"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## 7. Consolidated screening summary"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {},
      "outputs": [],
      "source": [
        "display(pd.DataFrame(\n",
        "    list(client.engineering.model_screening_summary().items()),\n",
        "    columns=[\"Check\", \"Finding count\"],\n",
        "))"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## 8. Build report-ready review package"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {},
      "outputs": [],
      "source": [
        "review_package = client.review_report.build()\n",
        "\n",
        "print(\"Review classification:\")\n",
        "print(review_package[\"classification\"])\n",
        "\n",
        "print(\"\\nSections:\")\n",
        "print(list(review_package.keys()))"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## 9. Export review package to JSON"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {},
      "outputs": [],
      "source": [
        "import json\n",
        "from pathlib import Path\n",
        "from datetime import datetime\n",
        "\n",
        "# Uncomment to export.\n",
        "# export_dir = Path(client.project.summary()[\"project_folder\"]) / \"PCSWMM_Engineering_Review\"\n",
        "# export_dir.mkdir(parents=True, exist_ok=True)\n",
        "# export_path = export_dir / (\n",
        "#     \"engineering_review_\"\n",
        "#     + datetime.now().strftime(\"%Y%m%d_%H%M%S\")\n",
        "#     + \".json\"\n",
        "# )\n",
        "# export_path.write_text(\n",
        "#     json.dumps(review_package, indent=2, default=str),\n",
        "#     encoding=\"utf-8\",\n",
        "# )\n",
        "# print(export_path)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## 10. Run simulation explicitly"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {},
      "outputs": [],
      "source": [
        "# Uncomment only when ready to run the active model.\n",
        "# display(pd.DataFrame([client.simulation.run()]))"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## 11. Hydraulic result examples"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {},
      "outputs": [],
      "source": [
        "# Confirm PCSWMM result labels and units before uncommenting.\n",
        "\n",
        "# Link peak flow:\n",
        "# display(pd.DataFrame(\n",
        "#     client.hydraulics.peak_link_results(\"Flow\", \"CMS\")\n",
        "# ))\n",
        "\n",
        "# Pond peak depth:\n",
        "# display(pd.DataFrame(\n",
        "#     client.hydraulics.peak_node_results(\n",
        "#         \"Depth\",\n",
        "#         \"m\",\n",
        "#         [\"pond\"],\n",
        "#     )\n",
        "# ))"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Engineering status\n",
        "\n",
        "The findings are automated screening results. They are not a substitute for\n",
        "project-specific design criteria, municipal standards, calibration review,\n",
        "or professional engineering judgment."
      ]
    }
  ],
  "metadata": {
    "kernelspec": {
      "display_name": "Python 3 (ipykernel)",
      "language": "python",
      "name": "python3"
    },
    "language_info": {
      "name": "python",
      "version": "3.10"
    }
  },
  "nbformat": 4,
  "nbformat_minor": 5
}