{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "9414b5c6-69f6-4caa-b776-a51999830609",
   "metadata": {},
   "source": [
    "# How-to: Convert a `timml` model to `timflow`\n",
    "Conversion of a `timml` model to a `timflow` model only requires a few minor changes. "
   ]
  },
  {
   "cell_type": "markdown",
   "id": "bb3ee149-cb66-4eeb-97d3-c3acd9ed8c2a",
   "metadata": {},
   "source": [
    "## The `import` statement\n",
    "The `timflow.steady` model is essentially the same as `timml`. \n",
    "So all that is required is to change the import statement. \n",
    "For example, if your model imports `timml` as\n",
    "\n",
    "```import timml```\n",
    "\n",
    "and you don't want to make any other changes to your model, then replace the import statement by\n",
    "\n",
    "```from timflow import steady as timml```\n",
    "\n",
    "or, if you like that better\n",
    "\n",
    "```import timflow.steady as timml```\n",
    "\n",
    "If you used a different name in your original model, then make sure to use the same name in the `timflow` model. So if your import statement was\n",
    "\n",
    "```import timml as tml```\n",
    "\n",
    "then replace it by\n",
    "\n",
    "```import timflow.steady as tml```\n",
    "\n",
    "Note: The docs of `timflow` use the three-letter abbreviation `tfs` (for **t**im**f**low **s**teady) for the steady model."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "3809e6e4-2ae7-4dd1-8b2f-990b33ff2f72",
   "metadata": {},
   "source": [
    "## Combining two or more plot statements on the same graph"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a7a1d702-6c53-463d-99aa-3479d270e7a2",
   "metadata": {},
   "source": [
    "All plotting commands in `timflow` are gathered in the `plots` submodule. Each plotting command optionally takes an axis as input. If no axis is provided, then a new plot is created. Each plotting command returns the axis to which is plots. When you issue multiple plotting commands in a row, for example to first plot contours and then on the same graph plot tracelines, then make sure that the axis created by the contouring command is passed to the tracelines command. For example, consider the following model of a well in uniform flow"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "64bbd190-d675-49d3-90cb-b4041afe39c4",
   "metadata": {},
   "outputs": [],
   "source": [
    "import timflow.steady as tfs"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "e68eefdc-e6da-40f7-a429-13f87ad47c8a",
   "metadata": {},
   "outputs": [],
   "source": [
    "ml = tfs.ModelMaq(kaq=10, z=[10, 0])\n",
    "rf = tfs.Constant(ml, xr=-1000, yr=0, hr=41)\n",
    "uf = tfs.Uflow(ml, slope=0.001, angle=0)\n",
    "w = tfs.Well(ml, xw=-400, yw=0, Qw=50.0, rw=0.2)\n",
    "ml.solve()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d96eec9c-59c7-4e6c-a57b-9dd8e693f44b",
   "metadata": {},
   "source": [
    "A contour plot is created and the returned axis is stored in the variable `ax0`. Then a traceline is computed and added to the same graph by supplying the `ax=ax0` as input. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "6008eb35-aa0c-4604-bd23-e4d56cd5e730",
   "metadata": {},
   "outputs": [],
   "source": [
    "ax0 = ml.plots.contour(win=[-1000, 100, -500, 500], ngr=50, levels=10, labels=False)\n",
    "ml.plots.tracelines(\n",
    "    xstart=[-800], ystart=[-200], zstart=[1], hstepmax=20, color=\"C1\", ax=ax0\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "76ba3423-c23f-41ee-92d6-d25f5f867b82",
   "metadata": {},
   "source": [
    "Note that two separate graphs are created when the `ax=ax0` input is omitted. You won't even see much on the second graph, as no window is provided (like the `win=[-1000, 100, -500, 500]` specification for the contours). The window is set by default to a very large area if no `ax` is provided and no `win`. "
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c00eb393-d11b-450a-acab-32192e688745",
   "metadata": {},
   "source": [
    "The same procedure holds for combining other plots. For example combining two contour plots, or a contour plot plus a capture zone. Note that the `plotcapzone` function has moved to the `plots` module. All three can be combined as follows"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "5ca0804c-eb07-4703-98f9-bb0569cd5d39",
   "metadata": {},
   "outputs": [],
   "source": [
    "ax0 = ml.plots.contour(win=[-1000, 100, -500, 500], ngr=50, levels=10, labels=False)\n",
    "ml.plots.plotcapzone(\n",
    "    well=w, nt=10, zstart=[1], hstepmax=20, tmax=10 * 365, color=\"C1\", ax=ax0\n",
    ")\n",
    "ml.plots.contour(win=[-1000, 100, -500, 500], ngr=50, levels=[40], color=\"k\", ax=ax0);"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "4ee57d7d-84f0-4a45-9d0a-7279ddf55304",
   "metadata": {},
   "source": [
    "### Renaming of elements\n",
    "\n",
    "If you had not updated your `timml` model recently, you may not have noticed that some\n",
    "old element names have been replaced by newer more descriptive ones. This was done in\n",
    "version 6.8.0. The old ones still work, but you will get a deprecation warning. These\n",
    "are the changes:\n",
    "\n",
    "#### Line-sinks\n",
    "* `HeadLineSink` -> `River`\n",
    "* `HeadLineSinkString` -> `RiverString`\n",
    "* `LineSinkDitch` -> `Ditch`\n",
    "* `LineSinkDitchString` -> `DitchString`\n",
    "\n",
    "#### Line-doublets\n",
    "* `ImpLineDoublet` -> `ImpermeableWall`\n",
    "* `ImpLineDoubletString` -> `ImpermeableWallString`\n",
    "* `LeakyLineDoublet` -> `LeakyWall`\n",
    "* `LeakyLineDoubletString` -> `LeakyWallString`\n",
    "\n",
    "#### Xsection elements\n",
    "* `HeadLineSink1D` -> `River1D`\n",
    "* `ImpLineDoublet1D` -> `ImpermeableWall1D`\n",
    "* `LeakyLineDoublet1D` -> `LeakyWall1D`"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8dec8e12-366e-43c1-bb09-83d979a49b44",
   "metadata": {},
   "source": [
    "### New elements\n",
    "In `timml` release 6.8.0 and before, a bunch of new elements were introduced that may be worth checking out:\n",
    "* `WellString`: A string of wells for which the total discharge is given. The discharge is distributed over the wells such that the head inside the wells is the same for all wells. This element is intended for wells connected by a manifold and a single pump. \n",
    "* `TargetHeadWell`: A well for which a target head is specified at a target location. The discharge is computed to meet the specified head at the target location.\n",
    "* `TargetHeadWellString`: Like a string of wells, but now the total dicharge is computed such that the specified head is met at the the target location.\n",
    "* `RadialCollectorWell`: A radial collector well with an arbitrary number of arms. The total discharge of the radial collector well is specified and is distributed across the arms such that the head is uniform and equal along all arms. \n",
    "* `BuildingPitMaq`: A special inhomogeneity element to simulate sheet piles around a building pit. For use in a `ModelMaq` model. \n",
    "* `BuildingPit3D`: A special inhomogeneity element to simulate sheet piles around a building pit. For use in a `Model3D` model. "
   ]
  }
 ],
 "metadata": {
  "language_info": {
   "name": "python"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}