examples/Notebooks/flopy3_ModelCheckerExample.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# FloPy \n",
    "\n",
    "### Model checker demonstration"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "flopy is installed in /Users/jdhughes/Documents/Development/flopy_git/flopy_us/flopy\n",
      "3.7.3 (default, Mar 27 2019, 16:54:48) \n",
      "[Clang 4.0.1 (tags/RELEASE_401/final)]\n",
      "flopy version: 3.2.12\n"
     ]
    }
   ],
   "source": [
    "import os\n",
    "import sys\n",
    "\n",
    "# run installed version of flopy or add local path\n",
    "try:\n",
    "    import flopy\n",
    "except:\n",
    "    fpth = os.path.abspath(os.path.join('..', '..'))\n",
    "    sys.path.append(fpth)\n",
    "    import flopy\n",
    "\n",
    "print(sys.version)\n",
    "print('flopy version: {}'.format(flopy.__version__))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Set the working directory"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [],
   "source": [
    "path = os.path.join('..', 'data', 'mf2005_test')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Load example dataset and change the model work space"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "\n",
      "changing model workspace...\n",
      "   data\n"
     ]
    }
   ],
   "source": [
    "m = flopy.modflow.Modflow.load('test1ss.nam', model_ws=path)\n",
    "m.change_model_ws('data')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "By default, the checker performs a model-level check when a set of model files are loaded, unless load is called with `check=False`. The load check only produces screen output if load is called with `verbose=True`. Checks are also performed at the package level when an individual package is loaded\n",
    "\n",
    "#### The `check()` method\n",
    "Each model and each package has a `check()` method. The check method has three arguments:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Help on method check in module flopy.mbase:\n",
      "\n",
      "check(f=None, verbose=True, level=1) method of flopy.modflow.mf.Modflow instance\n",
      "    Check model data for common errors.\n",
      "    \n",
      "    Parameters\n",
      "    ----------\n",
      "    f : str or file handle\n",
      "        String defining file name or file handle for summary file\n",
      "        of check method output. If a string is passed a file handle\n",
      "        is created. If f is None, check method does not write\n",
      "        results to a summary file. (default is None)\n",
      "    verbose : bool\n",
      "        Boolean flag used to determine if check method results are\n",
      "        written to the screen\n",
      "    level : int\n",
      "        Check method analysis level. If level=0, summary checks are\n",
      "        performed. If level=1, full checks are performed.\n",
      "    \n",
      "    Returns\n",
      "    -------\n",
      "    None\n",
      "    \n",
      "    Examples\n",
      "    --------\n",
      "    \n",
      "    >>> import flopy\n",
      "    >>> m = flopy.modflow.Modflow.load('model.nam')\n",
      "    >>> m.check()\n",
      "\n"
     ]
    }
   ],
   "source": [
    "help(m.check)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### The check class\n",
    "\n",
    "By default, check is called at the model level without a summary output file, but with `verbose=True` and `level=1`. The check methods return an instance of the **check** class, which is housed with the flopy utilities."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "\n",
      "test1ss MODEL DATA VALIDATION SUMMARY:\n",
      "  3 Warnings:\n",
      "    1 instance of \r",
      "    OC package: action(s) defined in OC stress_period_data ignored as they are not part the stress periods defined by DIS\n",
      "    1 instance of \r",
      "    RCH package: Mean R/T ratio < checker warning threshold of 2e-08 for 1 stress periods\n",
      "    1 instance of \r",
      "    RCH package: Variable NRCHOP set to value other than 3\n",
      "\n",
      "  Checks that passed:\n",
      "    Compatible solver package\n",
      "    Unit number conflicts\n",
      "    DIS package: zero or negative thickness\n",
      "    DIS package: thin cells (less than checker threshold of 1.0)\n",
      "    DIS package: nan values in top array\n",
      "    DIS package: nan values in bottom array\n",
      "    BAS6 package: isolated cells in ibound array\n",
      "    BAS6 package: Not a number\n",
      "    LPF package: zero or negative horizontal hydraulic conductivity values\n",
      "    LPF package: zero or negative vertical hydraulic conductivity values\n",
      "    LPF package: negative horizontal anisotropy values\n",
      "    LPF package: vertical hydraulic conductivity values below checker threshold of 1e-11\n",
      "    LPF package: vertical hydraulic conductivity values above checker threshold of 100000.0\n",
      "    LPF package: horizontal hydraulic conductivity values below checker threshold of 1e-11\n",
      "    LPF package: horizontal hydraulic conductivity values above checker threshold of 100000.0\n",
      "    GHB package: BC indices valid\n",
      "    GHB package: not a number (Nan) entries\n",
      "    GHB package: BC in inactive cells\n",
      "    GHB package: BC elevation below cell bottom\n",
      "\n"
     ]
    }
   ],
   "source": [
    "chk = m.check()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Summary array\n",
    "Most of the attributes and methods in **check** are intended to be used by the ``check()`` methods. The central attribute of **check** is the summary array:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "rec.array([('Warning', 'OC', 0, 0, 0, 0.0000000e+00, '\\r    OC package: action(s) defined in OC stress_period_data ignored as they are not part the stress periods defined by DIS'),\n",
       "           ('Warning', 'RCH', 0, 0, 0, 1.1785916e-09, '\\r    RCH package: Mean R/T ratio < checker warning threshold of 2e-08 for 1 stress periods'),\n",
       "           ('Warning', 'RCH', 0, 0, 0, 1.0000000e+00, '\\r    RCH package: Variable NRCHOP set to value other than 3')],\n",
       "          dtype=[('type', 'O'), ('package', 'O'), ('k', '<i8'), ('i', '<i8'), ('j', '<i8'), ('value', '<f8'), ('desc', 'O')])"
      ]
     },
     "execution_count": 6,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "chk.summary_array"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This is a numpy record array that summarizes errors and warnings found by the checker. The package, layer-row-column location of the error, the offending value, and a description of the error are provided. In the checker, errors and warnings are loosely defined as follows:  \n",
    "#### Errors:\n",
    "\n",
    "either input that would cause MODFLOW to crash, or inputs that almost certainly mis-represent the intended conceptual model.\n",
    "\n",
    "#### Warnings:\n",
    "\n",
    "inputs that are potentially problematic, but may be intentional.\n",
    "\n",
    "each package-level check produces a **check** instance with a summary array. The model level checks combine the summary arrays from the packages into a master summary array. At the model and the package levels, the summary array is used to generate the screen output shown above. At either level, the summary array can be written to a csv file by supply a filename to the `f` argument. Specifying `level=2` prints the summary array to the screen."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Errors and/or Warnings encountered.\n",
      "Errors and/or Warnings encountered.\n",
      "\n",
      "test1ss MODEL DATA VALIDATION SUMMARY:\n",
      "  3 Warnings:\n",
      "    1 instance of \r",
      "    OC package: action(s) defined in OC stress_period_data ignored as they are not part the stress periods defined by DIS\n",
      "    1 instance of \r",
      "    RCH package: Mean R/T ratio < checker warning threshold of 2e-08 for 1 stress periods\n",
      "    1 instance of \r",
      "    RCH package: Variable NRCHOP set to value other than 3\n",
      "\n",
      "  Checks that passed:\n",
      "    Compatible solver package\n",
      "    Unit number conflicts\n",
      "    DIS package: zero or negative thickness\n",
      "    DIS package: thin cells (less than checker threshold of 1.0)\n",
      "    DIS package: nan values in top array\n",
      "    DIS package: nan values in bottom array\n",
      "    BAS6 package: isolated cells in ibound array\n",
      "    BAS6 package: Not a number\n",
      "    LPF package: zero or negative horizontal hydraulic conductivity values\n",
      "    LPF package: zero or negative vertical hydraulic conductivity values\n",
      "    LPF package: negative horizontal anisotropy values\n",
      "    LPF package: vertical hydraulic conductivity values below checker threshold of 1e-11\n",
      "    LPF package: vertical hydraulic conductivity values above checker threshold of 100000.0\n",
      "    LPF package: horizontal hydraulic conductivity values below checker threshold of 1e-11\n",
      "    LPF package: horizontal hydraulic conductivity values above checker threshold of 100000.0\n",
      "    GHB package: BC indices valid\n",
      "    GHB package: not a number (Nan) entries\n",
      "    GHB package: BC in inactive cells\n",
      "    GHB package: BC elevation below cell bottom\n",
      "\n",
      "DETAILED SUMMARY:\n",
      "type\tpackage\tk\ti\tj\tvalue\tdesc\n",
      "Warning\tOC \t0\t0\t0\t0.00e+00\tOC package: action(s) defined in OC stress_period_data ignored as they are not part the stress periods defined by DIS\n",
      "Warning\tRCH \t0\t0\t0\t1.18e-09\tRCH package: Mean R/T ratio < checker warning threshold of 2e-08 for 1 stress periods\n",
      "Warning\tRCH \t0\t0\t0\t1.00e+00\tRCH package: Variable NRCHOP set to value other than 3\n"
     ]
    },
    {
     "data": {
      "text/plain": [
       "<flopy.utils.check.check at 0x11ef20d68>"
      ]
     },
     "execution_count": 7,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "m.check(level=2)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### example of package level check and summary file"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "\n",
      "RCH PACKAGE DATA VALIDATION:\n",
      "  2 Warnings:\n",
      "    1 instance of \r",
      "    Mean R/T ratio < checker warning threshold of 2e-08 for 1 stress periods\n",
      "    1 instance of \r",
      "    Variable NRCHOP set to value other than 3\n",
      "\n"
     ]
    },
    {
     "data": {
      "text/plain": [
       "<flopy.utils.check.check at 0x11ef20b38>"
      ]
     },
     "execution_count": 8,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "m.rch.check()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### example of summary output file"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "\n",
      "test1ss MODEL DATA VALIDATION SUMMARY:\n",
      "  3 Warnings:\n",
      "    1 instance of \r",
      "    OC package: action(s) defined in OC stress_period_data ignored as they are not part the stress periods defined by DIS\n",
      "    1 instance of \r",
      "    RCH package: Mean R/T ratio < checker warning threshold of 2e-08 for 1 stress periods\n",
      "    1 instance of \r",
      "    RCH package: Variable NRCHOP set to value other than 3\n",
      "  see data/checksummary.csv for details.\n",
      "\n",
      "  Checks that passed:\n",
      "    Compatible solver package\n",
      "    Unit number conflicts\n",
      "    DIS package: zero or negative thickness\n",
      "    DIS package: thin cells (less than checker threshold of 1.0)\n",
      "    DIS package: nan values in top array\n",
      "    DIS package: nan values in bottom array\n",
      "    BAS6 package: isolated cells in ibound array\n",
      "    BAS6 package: Not a number\n",
      "    LPF package: zero or negative horizontal hydraulic conductivity values\n",
      "    LPF package: zero or negative vertical hydraulic conductivity values\n",
      "    LPF package: negative horizontal anisotropy values\n",
      "    LPF package: vertical hydraulic conductivity values below checker threshold of 1e-11\n",
      "    LPF package: vertical hydraulic conductivity values above checker threshold of 100000.0\n",
      "    LPF package: horizontal hydraulic conductivity values below checker threshold of 1e-11\n",
      "    LPF package: horizontal hydraulic conductivity values above checker threshold of 100000.0\n",
      "    GHB package: BC indices valid\n",
      "    GHB package: not a number (Nan) entries\n",
      "    GHB package: BC in inactive cells\n",
      "    GHB package: BC elevation below cell bottom\n",
      "\n"
     ]
    },
    {
     "data": {
      "text/plain": [
       "<flopy.utils.check.check at 0x121348c88>"
      ]
     },
     "execution_count": 9,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "m.check(f='checksummary.csv')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>type</th>\n",
       "      <th>package</th>\n",
       "      <th>k</th>\n",
       "      <th>i</th>\n",
       "      <th>j</th>\n",
       "      <th>value</th>\n",
       "      <th>desc</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>0</th>\n",
       "      <td>Warning</td>\n",
       "      <td>OC</td>\n",
       "      <td>0</td>\n",
       "      <td>0</td>\n",
       "      <td>0</td>\n",
       "      <td>0.0</td>\n",
       "      <td>action(s) defined in OC stress_period_data ign...</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1</th>\n",
       "      <td>Warning</td>\n",
       "      <td>RCH</td>\n",
       "      <td>0</td>\n",
       "      <td>0</td>\n",
       "      <td>0</td>\n",
       "      <td>0.0</td>\n",
       "      <td>Mean R/T ratio &lt; checker warning threshold of ...</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2</th>\n",
       "      <td>Warning</td>\n",
       "      <td>RCH</td>\n",
       "      <td>0</td>\n",
       "      <td>0</td>\n",
       "      <td>0</td>\n",
       "      <td>1.0</td>\n",
       "      <td>Variable NRCHOP set to value other than 3</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "      type package  k  i  j  value  \\\n",
       "0  Warning      OC  0  0  0    0.0   \n",
       "1  Warning     RCH  0  0  0    0.0   \n",
       "2  Warning     RCH  0  0  0    1.0   \n",
       "\n",
       "                                                desc  \n",
       "0  action(s) defined in OC stress_period_data ign...  \n",
       "1  Mean R/T ratio < checker warning threshold of ...  \n",
       "2          Variable NRCHOP set to value other than 3  "
      ]
     },
     "execution_count": 10,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "try:\n",
    "    import pandas as pd\n",
    "    df = pd.read_csv('data/checksummary.csv')\n",
    "except:\n",
    "    df = open('data/checksummary.csv').readlines()\n",
    "df"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### checking on `write_input()`\n",
    "checking is also performed by default when `write_input()` is called at the package or model level. Checking on write is performed with the same `verbose` setting as specified for the model. However, if errors or warnings are encountered and `level=1` (default) or higher, a screen message notifies the user of the errors.\n",
    "\n",
    "By default, the checks performed on `load()` and `write_input()` save results to a summary file, which is named after the packge or the model."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {},
   "outputs": [],
   "source": [
    "m.write_input()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "anaconda-cloud": {},
  "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.7.3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 1
}