{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "3f28abc3",
   "metadata": {},
   "source": [
    "## Update a 2D Delft3D FM model: mesh refinements"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a2553c7d",
   "metadata": {},
   "source": [
    "Once you have a **Delft3D FM** model, you may want to update your model in order to use a new data map, change a parameter value, add structures or cross-sections data, use different boundary data, create and run different scenarios etc.\n",
    "\n",
    "With HydroMT, you can easily read your model and update one or several components of your model using the **update** function of the command line interface (CLI). Here are the steps and some examples on how to **refine the mesh 2D grid** for an existing 1D2D model.\n",
    "\n",
    "All lines in this notebook which starts with ! are executed from the command line. Within the notebook environment the logging messages are shown after completion. You can also copy these lines and paste them in your shell to get more feedback."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d897fbcc",
   "metadata": {},
   "source": [
    "### Model setup configuration"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "285bff3c",
   "metadata": {},
   "source": [
    "Updating a bedlevel or infiltration capacity map is an easy step with the command line but sometimes, for example with forcing or grid refinement, you need to update several things at the same time. This is possible by preparing a **configuration file** that includes every methods and settings that you want to do during your update.\n",
    "\n",
    "The configuration-file contains the model setup configuration and determines which methods are updated and in which sequence and sets optional arguments for each method. This configuration is passed to HydroMT using `-i <path_to_configuration_file>`.\n",
    "\n",
    "Each section, before indent, (e.g. setup_mesh2d_refine) corresponds with a model method which are explained in the [docs (model methods)](https://deltares.github.io/hydromt_delft3dfm/latest/user_guide/dflowfm_model_setup.html).\n",
    "\n",
    "Let's open the example configuration file **dflowfm_update_mesh2d_refine.yml** from the model repository [examples folder] and have a look at the settings."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "033f24ab",
   "metadata": {},
   "outputs": [],
   "source": [
    "fn_yml = \"dflowfm_update_mesh2d_refine.yml\"\n",
    "with open(fn_yml, \"r\") as f:\n",
    "    txt = f.read()\n",
    "print(txt)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "100f6165",
   "metadata": {},
   "source": [
    "Here we can see that to fully refine the 2D grid, we will run two methods:\n",
    "\n",
    "- [global](https://deltares.github.io/hydromt_delft3dfm/latest/_generated/hydromt_delft3dfm.DFlowFMModel.html#hydromt_delft3dfm.DFlowFMModel): our model to update is defined in the projected CRS WGS84 EPSG 3857. Unfortunately Delft3D FM do not allow yet to store the model CRS information, and the CRS of the model to update needs to be passed to HydroMT again.\n",
    "\n",
    "Then the model updating ``steps`` are:\n",
    "\n",
    "- [setup_mesh2d_refine](https://deltares.github.io/hydromt_delft3dfm/latest/_generated/hydromt_delft3dfm.DFlowFMModel.setup_mesh2d_refine.html): we will refine our 2D mesh within the polygons defined in the file *data/refine.geojson* with 2 steps or iterations.\n",
    "- [setup_link1d2d](https://deltares.github.io/hydromt_delft3dfm/latest/_generated/hydromt_delft3dfm.DFlowFMModel.setup_link1d2d.html): in the model we would like to update, 1D elements are present. Because we will udpate the 2D mesh with our refinements, we need to update and re-create the 1D2D links so that they match the newly refined 2D grid.\n",
    "\n",
    "You can find more information on the different methods and their options in the [docs (model methods)](https://deltares.github.io/hydromt_delft3dfm/latest/user_guide/dflowfm_model_setup.html).\n",
    "\n",
    "> **NOTE**: to provide data to HydroMT, you can either provide a data catalog entry, a direct path to a file (provided reading that file is straightforward and no pre-processing is required) or for python users. We use a direct path in `setup_mesh2d_refine` for the refine polygon. \n",
    "\n",
    "> **NOTE**: Refinment of the 2D grid leads to a new grid definition. There fore the `setup_link1d2d` is called again."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d3a9c2d7",
   "metadata": {},
   "source": [
    "### HydroMT CLI update interface"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "84c580a3",
   "metadata": {},
   "source": [
    "Using the **HydroMT build** API, we can update one or several components of an already existing Delft3D FM model. Let's get an overview of the available options:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "f9253e01",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Print the options available from the update command\n",
    "!hydromt update --help"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ee4d250d",
   "metadata": {},
   "source": [
    "### Update a 1D2D Delft3D FM model to refine the 2D mesh"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "dd69c94d",
   "metadata": {},
   "outputs": [],
   "source": [
    "# NOTE: copy this line (without !) to your shell for more direct feedback\n",
    "!hydromt update dflowfm dflowfm_piave -o ./build/dflowfm_mesh2d_refine -i dflowfm_update_mesh2d_refine.yml -v"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "90b9ec42",
   "metadata": {},
   "source": [
    "The example above means the following: run **hydromt** with:\n",
    "\n",
    "- `update dflowfm`: i.e. update a dflowfm model\n",
    "- `dflowfm_piave`: original model folder\n",
    "- `-o ./build/dflowfm_mesh2d_refine`: output updated model folder\n",
    "- `-i dflowfm_update_mesh2d_refine.yml`: setup configuration file containing the components to update and their different options\n",
    "- `v`: give some extra verbosity (1 * v) to display feedback on screen. Now info messages are provided.\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c2f94675",
   "metadata": {},
   "source": [
    "### Model comparison"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "1fff56c3",
   "metadata": {},
   "source": [
    "From the information above, you can see that the mesh2d was refined and now contains 828 faces after refinement compared to 460 beforehand and that the 1D2D links have been regenerated.\n",
    "\n",
    "Using the script from the [plot example](https://deltares.github.io/hydromt_delft3dfm/latest/_examples/plot_dflowfm_mesh.html), we can compare the 2D mesh before and after the refinements."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "1c08be85",
   "metadata": {},
   "source": [
    "First, let's load some packages. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "65691e5f",
   "metadata": {},
   "outputs": [],
   "source": [
    "import geopandas as gpd\n",
    "import matplotlib.pyplot as plt"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "4da9d10a",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Load both models with hydromt\n",
    "from hydromt_delft3dfm import DFlowFMModel\n",
    "\n",
    "mod0 = DFlowFMModel(root=\"dflowfm_piave\", mode=\"r\")\n",
    "mod1 = DFlowFMModel(root=\"build/dflowfm_mesh2d_refine\", mode=\"r\")\n",
    "\n",
    "# read dflowfm mesh; extract the 2d grid part\n",
    "mesh2d_0 = mod0.mesh.mesh_grids[\"mesh2d\"]\n",
    "mesh2d_1 = mod1.mesh.mesh_grids[\"mesh2d\"]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "a3ddd47c",
   "metadata": {},
   "outputs": [],
   "source": [
    "# read the polygon file we used for the refinement\n",
    "polygons = gpd.read_file(\"data/refine.geojson\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "e53070e4",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Make 2 side-by-side plots to plot each mesh\n",
    "zoom_level = 10\n",
    "fig = plt.figure(figsize=(12, 6))\n",
    "axs = fig.subplots(1, 2)\n",
    "\n",
    "axs[0].set_title(\"Original mesh\")\n",
    "axs[1].set_title(\"Refined mesh\")\n",
    "\n",
    "# Plot the original mesh\n",
    "mesh2d_0.plot(ax=axs[0], facecolor=\"none\", edgecolor=\"k\")\n",
    "polygons.to_crs(mod0.crs).plot(ax=axs[0], facecolor=\"r\", edgecolor=\"r\")\n",
    "\n",
    "# Plot the refined mesh\n",
    "mesh2d_1.plot(ax=axs[1], facecolor=\"none\", edgecolor=\"k\")\n",
    "polygons.to_crs(mod0.crs).plot(ax=axs[1], facecolor=\"none\", edgecolor=\"r\")\n"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "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.12.13"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}