{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "e750cf22-3ebc-4e03-bbd4-ea190aaf4ca2",
   "metadata": {
    "jp-MarkdownHeadingCollapsed": true
   },
   "source": [
    "# Object Configurators in mom6_forge\n",
    "\n",
    "## Set up a custom regional CESM-MOM6 domain using object configurators\n",
    "\n",
    "These object configurators include:\n",
    "\n",
    "1. A horizontal grid creator (Grid Creator)\n",
    "2. A topography editor (Topo Editor)\n",
    "3. A vertical grid creator (VGrid Creator)\n",
    "\n",
    "This notebook demonstrates how to use these object configurators to streamline regional CESM-MOM6 domain generation."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d0d70586-e8f9-421a-a9b3-b9ea922329d8",
   "metadata": {},
   "source": [
    "## SECTION 1: Using the Grid Creator"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "1bcfa877-c711-4802-8e59-a4b6513032c5",
   "metadata": {},
   "source": [
    "We begin by defining a regional MOM6 domain. To do so, we first generate a horizontal grid."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "id": "c54b08a3-0c12-4f63-a686-f7ceba206fe9",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "The autoreload extension is already loaded. To reload it, use:\n",
      "  %reload_ext autoreload\n"
     ]
    }
   ],
   "source": [
    "%load_ext autoreload\n",
    "%autoreload 2"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "aac156c3-cb67-4513-831d-edf44eb9d35a",
   "metadata": {},
   "source": [
    "We instantiate a `Grid` with the necessary parameters, including resolution, xstart, lenx, ystart, leny, and name."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "id": "6f3d8331-1d17-4f6d-9145-3ebe1db8b0e3",
   "metadata": {},
   "outputs": [],
   "source": [
    "from mom6_forge.grid import Grid\n",
    "%matplotlib ipympl\n",
    "grid = Grid(\n",
    "  resolution = 0.01,\n",
    "  xstart = 281.0,\n",
    "  lenx = 5.0,\n",
    "  ystart = 35.0,\n",
    "  leny = 5.0,\n",
    "  name = \"EastCoast\",\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8be7debd-77ed-4db1-b029-736e405df186",
   "metadata": {},
   "source": [
    "Once we have instantiated a `Grid` object, we are now ready to use the Grid Creator."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "9b484951-54a9-4dc3-9d05-4d95e02c84e8",
   "metadata": {},
   "source": [
    "## 1. Launching the Grid Creator\n",
    "\n",
    "First, import and launch the Grid Creator in a notebook cell:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "id": "d96dc0fb-0138-4727-a2a6-cdae762a7376",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "application/vnd.jupyter.widget-view+json": {
       "model_id": "bd712d20c9e34606bc8355b8eb64f3bf",
       "version_major": 2,
       "version_minor": 0
      },
      "text/plain": [
       "GridCreator(children=(VBox(children=(VBox(children=(HTML(value='<h3>Grid Creator</h3>'), FloatSlider(value=0.0…"
      ]
     },
     "execution_count": 4,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "from mom6_forge.grid_creator import GridCreator\n",
    "Grid_Creator = GridCreator(grid)\n",
    "Grid_Creator"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "1eea8f99-587e-42cb-9d22-f9d8b65913cb",
   "metadata": {},
   "source": [
    "## 2. Grid Parameter Controls\n",
    "\n",
    "On the left panel, you’ll find sliders for:\n",
    "\n",
    "- **Resolution**: Set the grid cell size (degrees).\n",
    "- **xstart**: Longitude of the lower-left grid corner.\n",
    "- **lenx**: Length of the grid in the x (longitude) direction (degrees).\n",
    "- **ystart**: Latitude of the lower-left grid corner.\n",
    "- **leny**: Length of the grid in the y (latitude) direction (degrees).\n",
    "\n",
    "Adjust these sliders to change the grid geometry. The map on the right updates automatically.\n",
    "\n",
    "---\n",
    "\n",
    "## 3. Resetting the Grid\n",
    "\n",
    "If you want to revert to the original grid parameters, click the **Reset** button.\n",
    "\n",
    "---\n",
    "\n",
    "## 4. Saving and Loading Grids\n",
    "\n",
    "### Saving\n",
    "\n",
    "- Enter a **Name** and a **Message** describing your grid.\n",
    "- Click **Save Grid** to save your current grid to the library.\n",
    "\n",
    "### Loading\n",
    "\n",
    "- Use the **Grids** dropdown to select a previously saved grid.\n",
    "- Click **Load Grid** to load it into the creator.\n",
    "\n",
    "---\n",
    "\n",
    "## 5. Grid Library\n",
    "\n",
    "- The **Grids** dropdown lists all saved grids.\n",
    "- The details panel shows information about the selected grid (name, date, resolution, size).\n",
    "\n",
    "---\n",
    "\n",
    "## 6. Map Features\n",
    "\n",
    "- The map displays your grid overlaid on coastlines and land.\n",
    "- A scale bar is shown for reference.\n",
    "- You can use the toolbar to pan, zoom, and save the map image.\n",
    "\n",
    "---\n",
    "\n",
    "## Tips\n",
    "\n",
    "- Make sure to save your grid before switching to another one.\n",
    "- Use descriptive names and messages for easy identification.\n",
    "- All grids are saved in the `Grids` folder under your repository root.\n",
    "- Note that by rerunning the cell, the Grid Creator reverts back to the original, instantiated Grid in the cell above.\n",
    "- When you are happy with the `Grid` you have created, make sure to save it! What is shown in the Grid Creator can be used to instantiate a `Topo` object by doing: `grid = Grid_Creator.grid`."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d9f4a945-1ee5-4a2e-a5f4-a8b53d992a9c",
   "metadata": {},
   "source": [
    "## SECTION 2: Using the Topo Editor"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "1ecb95cc-94cf-485e-a1e9-655d7dd69e84",
   "metadata": {},
   "source": [
    "Now that we have created a `Grid`, we can now instantiate a `Topo` object."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "id": "2e5e8392-38ff-47e9-bdef-d72ec4a82599",
   "metadata": {},
   "outputs": [],
   "source": [
    "from mom6_forge.topo import Topo\n",
    "\n",
    "topo = Topo(\n",
    "    grid = Grid_Creator.grid,\n",
    "    min_depth = 0,\n",
    ")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "id": "892683a2-55e3-4752-9fba-980a15fda2dc",
   "metadata": {},
   "outputs": [],
   "source": [
    "topo.set_spoon(2000,200)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "978ea27c-f81d-40ae-b1c9-e4b4c577989a",
   "metadata": {},
   "source": [
    "Once we have instantiated the `Topo` object and run the set step, we can use the Topo Editor."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "917ce86e-9d50-4cbd-9092-fe93b0ba40fc",
   "metadata": {},
   "source": [
    "The **Topo Editor** is a powerful interactive tool for editing, managing, and version-controlling ocean model topography files. This guide will walk you through all major features and workflows."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "2272b61d-441d-4efd-afda-c1760d95b412",
   "metadata": {},
   "source": [
    "## 1. Launching the Topo Editor\n",
    "\n",
    "First, import and launch the Topo Editor in a notebook cell:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "id": "0bbe0329-b200-474c-98d4-dbfaaef5d3cf",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "application/vnd.jupyter.widget-view+json": {
       "model_id": "7ff31e4070e4400a86890a2b7f68ab55",
       "version_major": 2,
       "version_minor": 0
      },
      "text/plain": [
       "TopoEditor(children=(VBox(children=(HTML(value='<h2>Topo Editor</h2>'), VBox(children=(VBox(children=(HTML(val…"
      ]
     },
     "execution_count": 7,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "from mom6_forge.topo_editor import TopoEditor\n",
    "Topo_Editor = TopoEditor(topo)\n",
    "Topo_Editor"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "19117a7e-97cc-40b8-80c7-67366676aa1e",
   "metadata": {},
   "source": [
    "## 2. Interface Overview\n",
    "\n",
    "The Topo Editor interface consists of two main panels:\n",
    "\n",
    "- **Left Panel:** Control panel for editing, history, snapshots, and version control.\n",
    "- **Right Panel:** Interactive map displaying the topography.\n",
    "\n",
    "---\n",
    "\n",
    "## 3. Display Controls\n",
    "\n",
    "- **Display Mode:**  \n",
    "  Use the `Field` toggle to switch between:\n",
    "  - `depth`: Shows the bathymetry (depth values).\n",
    "  - `mask`: Shows the land/ocean mask.\n",
    "  - `basinmask`: Shows basin labels.\n",
    "\n",
    "- **Min Depth:**  \n",
    "  Adjust the minimum allowed depth for the domain.\n",
    "\n",
    "---\n",
    "\n",
    "## 4. Editing Topography\n",
    "\n",
    "### Selecting and Editing Cells\n",
    "\n",
    "- **Select a Cell:**  \n",
    "  Double-click on a cell in the map to select it. The selected cell will be highlighted, and its coordinates and depth will appear in the control panel.\n",
    "\n",
    "- **Edit Depth:**  \n",
    "  Enter a new value in the `Depth (m)` field to change the depth of the selected cell.\n",
    "\n",
    "### Basin Operations\n",
    "\n",
    "- **Erase Disconnected Basins:**  \n",
    "  Removes all basins not connected to the selected cell.\n",
    "\n",
    "- **Erase Selected Basin:**  \n",
    "  Removes the entire basin associated with the selected cell.\n",
    "\n",
    "---\n",
    "\n",
    "## 5. Undo, Redo, and Reset\n",
    "\n",
    "- **Undo:**  \n",
    "  Reverts the last edit.\n",
    "\n",
    "- **Redo:**  \n",
    "  Re-applies an undone edit.\n",
    "\n",
    "- **Reset:**  \n",
    "  Restores the topography to its original state.\n",
    "\n",
    "---\n",
    "\n",
    "## 6. Git Version Control\n",
    "\n",
    "The Topo Editor supports git-based version control for collaborative workflows.\n",
    "\n",
    "### Tag\n",
    "\n",
    "- **Save Tage:**  \n",
    "  Applies the git tag function and saves the tagged topo to your topo folder\n",
    "\n",
    "\n",
    "- **Branch Management:**\n",
    "  - Create a new branch: Enter a name and click `Create Branch`. (Will not be automatically checked out)\n",
    "  - Checkout a branch: Select from the dropdown and click `Checkout`.\n",
    "\n",
    "---\n",
    "\n",
    "## 8. Tips and Best Practices\n",
    "\n",
    "- **Autosave:**  \n",
    "  The editor autosaves your working state (because it commits). If you close and reopen, your latest work will be restored\n",
    "\n",
    "- **Tags:**  \n",
    "  Take tags frequently to save topos you like! \n",
    "\n",
    "- **Version Control:**  \n",
    "  Use branches to experiment with different edits\n",
    "\n",
    "- **Navigation:**  \n",
    "  Use the map toolbar to zoom, pan, and save images.\n",
    "\n",
    "- **Cell/Basin Editing:**  \n",
    "  Use the basin tools to clean up disconnected or unwanted basins for realistic bathymetry.\n",
    "\n",
    "---\n",
    "\n",
    "## 9. Example Workflow\n",
    "\n",
    "1. **Load a Topo file and grid.**\n",
    "2. **Switch to `depth` mode and inspect the bathymetry.**\n",
    "3. **Double-click a cell to select and edit its depth.**\n",
    "4. **Use basin tools to clean up the domain.**\n",
    "5. **Take a tag with a descriptive name**\n",
    "6. **Create a new branch to try a different editing approach.**\n",
    "7. **Switch between branches as needed.**\n",
    "8. **Undo/redo edits if you make a mistake.**\n",
    "\n",
    "---\n",
    "\n",
    "## 10. Troubleshooting\n",
    "\n",
    "- If you encounter errors loading or saving, check that your file paths and permissions are correct.\n",
    "- If git operations fail, ensure your repository is properly initialized and you have the necessary permissions."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "60275b4e-f15b-4c9e-8601-3516b7348828",
   "metadata": {},
   "source": [
    "## SECTION 3: Using the VGrid Creator"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "07d127e1-0850-4191-aa6f-a3f99a207656",
   "metadata": {},
   "source": [
    "Now that we have created a `Topo`, we can now instantiate a `VGrid` object. Note that we use the maximum depth from the Topo Editor to set the depth of the `VGrid` – this is not strictly necessary."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "id": "145c758d-f474-4218-aba6-8546ee2fc384",
   "metadata": {},
   "outputs": [],
   "source": [
    "from mom6_forge.vgrid import VGrid\n",
    "\n",
    "vgrid = VGrid.hyperbolic(\n",
    "    nk = 50,\n",
    "    depth = Topo_Editor.topo.max_depth,\n",
    "    ratio=5.0,\n",
    "    name=\"EastCoast\"\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c806b505-7a09-4d5d-b85b-2c0f2dc4e2b1",
   "metadata": {},
   "source": [
    "## 1. Launching the VGrid Creator\n",
    "\n",
    "First, import and launch the VGrid Creator in a notebook cell:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "id": "4996d949-541e-4e4f-8503-55db87d092fb",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "application/vnd.jupyter.widget-view+json": {
       "model_id": "c56bea93be7a4020801ab1f831983ccc",
       "version_major": 2,
       "version_minor": 0
      },
      "text/plain": [
       "VGridCreator(children=(VBox(children=(VBox(children=(HTML(value='<h3>Vertical Grid Creator</h3>'), ToggleButto…"
      ]
     },
     "execution_count": 9,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "from mom6_forge.vgrid_creator import VGridCreator\n",
    "VGrid_Creator = VGridCreator(vgrid=vgrid, topo=Topo_Editor.topo) # Setting topo is optional!\n",
    "VGrid_Creator"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "94dbddf3-cb40-407d-b79f-a4e9cc8d56c0",
   "metadata": {},
   "source": [
    "## 2. Interface Overview\n",
    "\n",
    "The VGrid Creator interface consists of:\n",
    "\n",
    "- **Left Panel:** Controls for editing vertical grid parameters and managing saved grids.\n",
    "- **Right Panel:** A plot showing the vertical grid layers.\n",
    "\n",
    "---\n",
    "\n",
    "## 3. Editing Vertical Grid Parameters\n",
    "\n",
    "- **Type:**  \n",
    "  Choose between `Uniform` (equal layer thickness) and `Hyperbolic` (thickness increases with depth).\n",
    "\n",
    "- **Levels:**  \n",
    "  Set the number of vertical layers (`nk`).\n",
    "\n",
    "- **Depth (m):**  \n",
    "  Set the total depth of the grid.\n",
    "\n",
    "- **Top/Bottom Ratio:**  \n",
    "  For `Hyperbolic` grids, adjust the ratio of the bottom layer thickness to the top layer thickness.  \n",
    "  *Tip: Hover or adjust the slider to see a help message.*\n",
    "\n",
    "- **Warning:**  \n",
    "  If the total depth is less than the maximum depth of your topography, a warning will appear.\n",
    "\n",
    "- **Reset:**  \n",
    "  Click to revert to the initial grid parameters.\n",
    "\n",
    "---\n",
    "\n",
    "## 4. Plot Panel\n",
    "\n",
    "- The right panel shows a plot of the vertical grid layers.\n",
    "- Each horizontal line represents a layer interface.\n",
    "- The plot updates automatically as you adjust parameters.\n",
    "\n",
    "---\n",
    "\n",
    "## 5. Saving and Loading VGrids\n",
    "\n",
    "### Saving\n",
    "\n",
    "- Enter a **Name** and a **Message** describing your vertical grid.\n",
    "- Click **Save VGrid** to save your current grid to the library (`VGrids` folder).\n",
    "\n",
    "### Loading\n",
    "\n",
    "- Use the **VGrids** dropdown to select a previously saved grid.\n",
    "- Click **Load VGrid** to load it into the creator.\n",
    "\n",
    "---\n",
    "\n",
    "## 6. VGrid Library\n",
    "\n",
    "- The **VGrids** dropdown lists all saved vertical grids.\n",
    "- The details panel shows information about the selected grid (name, date, depth, number of layers).\n",
    "\n",
    "---\n",
    "\n",
    "## 7. Tips and Best Practices\n",
    "\n",
    "- **Choose the right type:**  \n",
    "  Use `Uniform` for simple cases, `Hyperbolic` for higher resolution near the surface or bottom.\n",
    "\n",
    "- **Match depth to topo:**  \n",
    "  Ensure your vertical grid depth is at least as deep as your topography’s maximum depth.\n",
    "\n",
    "- **Save often:**  \n",
    "  Save grids with descriptive names and messages for easy identification and reproducibility.\n",
    "\n",
    "- **Reset if needed:**  \n",
    "  Use the reset button to quickly revert to your starting configuration."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "25211af5-c2a9-463e-9556-fec8a8665a74",
   "metadata": {},
   "source": [
    "## You have now generated a regional CESM-MOM6 domain! "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "b3e7e8fa-eba9-4438-b45a-0a8fa233611a",
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python [conda env:mom6_forge]",
   "language": "python",
   "name": "conda-env-mom6_forge-py"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.11.15"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}