{
  "cells": [
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "# PCSWMM AI SDK \u2014 Quickstart v0.1\n",
        "\n",
        "This notebook uses PCSWMM's injected `pcpy` object through a reusable,\n",
        "read-only SDK.\n",
        "\n",
        "**Open a PCSWMM project before running the cells below.**"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## 1. Load the SDK"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {},
      "outputs": [],
      "source": [
        "import os\n",
        "import sys\n",
        "from pathlib import Path\n",
        "\n",
        "# This notebook is stored in: <SDK folder>/examples/\n",
        "SDK_ROOT = Path.cwd().parent\n",
        "if str(SDK_ROOT) not in sys.path:\n",
        "    sys.path.insert(0, str(SDK_ROOT))\n",
        "\n",
        "from pcswmm_ai import PCSWMMClient\n",
        "\n",
        "client = PCSWMMClient(pcpy)\n",
        "client.health()"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## 2. Active project summary"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {},
      "outputs": [],
      "source": [
        "import pandas as pd\n",
        "\n",
        "project_df = pd.DataFrame(\n",
        "    list(client.project.summary().items()),\n",
        "    columns=[\"Property\", \"Value\"],\n",
        ")\n",
        "display(project_df)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## 3. SWMM collection inventory"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {},
      "outputs": [],
      "source": [
        "collection_df = pd.DataFrame(client.collections.summary())\n",
        "display(collection_df)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## 4. List collection keys"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {},
      "outputs": [],
      "source": [
        "for collection_name in [\"Scenarios\", \"Nodes\", \"Links\", \"Subcatchments\"]:\n",
        "    print(\"\\n\", collection_name)\n",
        "    print(client.collections.keys(collection_name))"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## 5. Map layers"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {},
      "outputs": [],
      "source": [
        "layer_names = client.layers.names()\n",
        "display(pd.DataFrame({\"Layer\": layer_names}))"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## 6. Read a layer as records"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {},
      "outputs": [],
      "source": [
        "layer_name = \"Subcatchments\"\n",
        "\n",
        "if layer_name in layer_names:\n",
        "    records = client.layers.records(layer_name)\n",
        "    display(pd.DataFrame(records))\n",
        "else:\n",
        "    print(f\"{layer_name} is unavailable in the active project.\")"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## 7. Basic deterministic QA/QC"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {},
      "outputs": [],
      "source": [
        "if \"Subcatchments\" in layer_names:\n",
        "    duplicates = client.qaqc.duplicate_names(\"Subcatchments\")\n",
        "    print(\"Duplicate subcatchment names:\", duplicates)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## 8. Run the active model"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {},
      "outputs": [],
      "source": [
        "# Uncomment only when ready to run the model.\n",
        "# run_result = client.simulation.run()\n",
        "# display(pd.DataFrame([run_result]))"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## 9. Retrieve a PCSWMM time series"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {},
      "outputs": [],
      "source": [
        "# Modify these four values to match the active model and result file.\n",
        "OBJECT_GROUP = \"Links\"\n",
        "RESULT_VARIABLE = \"Flow\"\n",
        "UNITS = \"CMS\"\n",
        "OBJECT_NAME = \"C_out\"\n",
        "\n",
        "# Uncomment after the model has been run and a graph file is available.\n",
        "# records = client.results.timeseries(\n",
        "#     OBJECT_GROUP,\n",
        "#     RESULT_VARIABLE,\n",
        "#     UNITS,\n",
        "#     OBJECT_NAME,\n",
        "# )\n",
        "# display(pd.DataFrame(records).head())\n",
        "# client.results.summarize(records)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Verification targets\n",
        "\n",
        "The first test is successful when:\n",
        "\n",
        "- `client.health()` shows the PCSWMM runtime type;\n",
        "- the active project metadata appears;\n",
        "- collection counts match the PCSWMM model;\n",
        "- map layers are listed;\n",
        "- subcatchment records appear as a DataFrame.\n",
        "\n",
        "The simulation and time-series cells are intentionally commented to prevent\n",
        "unintended model execution."
      ]
    }
  ],
  "metadata": {
    "kernelspec": {
      "display_name": "Python 3 (ipykernel)",
      "language": "python",
      "name": "python3"
    },
    "language_info": {
      "name": "python",
      "version": "3.10"
    }
  },
  "nbformat": 4,
  "nbformat_minor": 5
}