Merge pull request #108 from mbakker7/dev

Release v6.4.0
mbakker7 · Feb 13, 2024 · bf13dca · bf13dca
2 parents d980d6a + 5d4d3c0
commit bf13dca
Show file tree

Hide file tree

Showing 63 changed files with 1,376 additions and 1,625 deletions.
diff --git a/.gitignore b/.gitignore
@@ -103,4 +103,4 @@ ENV/
 
 # docs
 _build/
-docs/04api/generated
+docs/05api/generated
diff --git a/.nojekyll b/.nojekyll
diff --git a/README.md b/README.md
@@ -18,11 +18,15 @@ TimML is coded in Python and uses numba to speed up evaluation of the bessel lin
 
 **Python versions:**
 
-TimML requires **Python** >= 3.7 and can be installed from PyPI.
+TimML requires Python >= 3.8 and can be installed from PyPI.
 
 **Dependencies:**
 
-TimML requires **numpy** >=1.17, **scipy** >=1.5 and **matplotlib** >=3.1, **numba>=0.5**.
+TimML requires:
+* numpy 
+* scipy
+* matplotlib
+* numba
 
 **Installation:**
 
@@ -44,16 +48,24 @@ To uninstall TimML type:
 * The documentation is hosted on [readthedocs](https://timml.readthedocs.io/).
 * Example Notebooks are available from the notebooks directory on github, of from [here](https://github.com/mbakker7/timml/tree/master/notebooks).
 
-## TimML Version 6
-
-TimML version 6 has the same functionality as version 5, but doesn't depend on a fortran extension anymore, so installation is easy on all platforms.
-TimML version 5 is a total rewrite and is not backwards compatible with previous TimML versions.
-TimML version 5 is intended to be compatible with TTim.
-TimML version 5 has many new features and elements, the code base is Python 3, and the object oriented design is much simpler.
-TimML version 4 remains available through the timml4 branch.
-
-## Release
-TimML 6.0. First release that depends on numba and doesn't depend on fortran extension anymore. Code is now pure python (with numba for speed).
+## Latest release
+TimML 0.6.5
+* Improved documentation: new look, better organization, tutorials, how-to guides etc. Check it out [here](https://timml.readthedocs.io/)!
+* New elements
+    * Building pit elements for 3D (multi-layer single aquifer) models.
+    * Large diamater wells (only for radial flow).
+* Enhancements
+    * Building pit leaky wall resistance can be set per layer and per side (for modeling leaks or gaps).
+    * Return integrated normal flux per layer and per line segment.
+
+## TimML Versions
+
+* TimML version 0.6 has the same functionality as version 5, but doesn't depend on a fortran extension anymore, so installation is easy on all platforms.
+* TimML version 0.5 
+    * is a total rewrite and is not backwards compatible with previous TimML versions.
+    * is intended to be compatible with TTim.
+    * has many new features and elements, the code base is Python 3, and the object oriented design is much simpler.
+* TimML version 0.4 remains available through the timml4 branch.
 
 ## Citation
 

diff --git a/docs/00tutorials/index.rst b/docs/00tutorials/index.rst
@@ -14,9 +14,7 @@ TimML tutorials.
 
 `Tutorial 0 - Well in a single aquifer`_
 
-.. _Tutorial 0 - Well in a single aquifer: tutorial0_well_single_layer_aquifer.html
-
-
 `Tutorial 1 - Well in a multi-aquifer system`_
 
-.. _Tutorial 1 - Well in a multi aquifer system: tutorial1_well_multi_layer_aquifer.html
+.. _Tutorial 0 - Well in a single aquifer: tutorial0_well_single_layer_aquifer.html
+.. _Tutorial 1 - Well in a multi-aquifer system: tutorial1_well_multi_layer_aquifer.html
diff --git a/docs/00tutorials/tutorial1_well_multi_layer_aquifer.ipynb b/docs/00tutorials/tutorial1_well_multi_layer_aquifer.ipynb
@@ -15,7 +15,7 @@
     "In this notebook, we will simulate steady flow to an extraction well in the middle aquifer of a three-aquifer system. \n",
     "Aquifer properties are given in the table shown below. The well is located at $(x,y)=(0,0)$, the discharge is $Q=10,000$ m$^3$/d and the radius is 0.2 m. There is a uniform flow from West to East with a gradient of 0.002. The head is fixed to 20 m at a distance of 10,000 m downstream of the well. \n",
     "\n",
-    "#### Aquifer properties\n",
+    "### Aquifer properties\n",
     "|Layer        |$k$ (m/d)|$z_b$ (m)|$z_t$|$c$ (days)|\n",
     "|-------------|--------:|--------:|----:|---------:|\n",
     "|Aquifer 0    |    10   |   -20   |  0  |    -     |\n",

diff --git a/notebooks/BuildingPit.ipynb → docs/03examples/BuildingPit.ipynb b/notebooks/BuildingPit.ipynb → docs/03examples/BuildingPit.ipynb
diff --git a/notebooks/circareasink_example.ipynb → docs/03examples/circareasink_example.ipynb b/notebooks/circareasink_example.ipynb → docs/03examples/circareasink_example.ipynb
diff --git a/notebooks/circular_buildingpit.ipynb → docs/03examples/circular_buildingpit.ipynb b/notebooks/circular_buildingpit.ipynb → docs/03examples/circular_buildingpit.ipynb
diff --git a/notebooks/figs/inhomogeneity_exercise3.png → ...examples/figs/inhomogeneity_exercise3.png b/notebooks/figs/inhomogeneity_exercise3.png → ...examples/figs/inhomogeneity_exercise3.png
diff --git a/notebooks/figs/layout_exercise2.PNG → docs/03examples/figs/layout_exercise2.PNG b/notebooks/figs/layout_exercise2.PNG → docs/03examples/figs/layout_exercise2.PNG
diff --git a/notebooks/figs/timml_notebook2_layout.png → ...3examples/figs/timml_notebook2_layout.png b/notebooks/figs/timml_notebook2_layout.png → ...3examples/figs/timml_notebook2_layout.png
diff --git a/...books/figs/timml_notebook2_layout_old.png → ...mples/figs/timml_notebook2_layout_old.png b/...books/figs/timml_notebook2_layout_old.png → ...mples/figs/timml_notebook2_layout_old.png
diff --git a/notebooks/figs/timml_notebook5_layout.png → ...3examples/figs/timml_notebook5_layout.png b/notebooks/figs/timml_notebook5_layout.png → ...3examples/figs/timml_notebook5_layout.png
diff --git a/docs/03examples/index.rst b/docs/03examples/index.rst
@@ -8,8 +8,59 @@ TimML example notebooks.
     :hidden:
 
     timml_notebook0_sol
+    timml_notebook1_sol
+    timml_notebook2_sol
+    timml_notebook3_3D_sol
+    timml_notebook3_sol
+    timml_notebook4_sol
+    timml_notebook5_sol
+    timml_notebook6_sol
+    timml_notebook7
+    BuildingPit
+    circareasink_example
+    circular_buildingpit
+    lake_horizontal_well
+    normal_flux
+    test_linesink_discharge
+    test_polygon_areasink
+    test_well_near_lake
+    timml_figures
 
 
-`TimML example notebook 0`_
+* `TimML example notebook 0`_
+* `timml_notebook1_sol`_
+* `timml_notebook2_sol`_
+* `timml_notebook3_3D_sol`_
+* `timml_notebook3_sol`_
+* `timml_notebook4_sol`_
+* `timml_notebook5_sol`_
+* `timml_notebook6_sol`_
+* `timml_notebook7`_
+* `BuildingPit`_
+* `circareasink_example`_
+* `circular_buildingpit`_
+* `lake_horizontal_well`_
+* `normal_flux`_
+* `test_linesink_discharge`_
+* `test_polygon_areasink`_
+* `test_well_near_lake`_
+* `timml_figures`_
 
 .. _TimML example notebook 0: timml_notebook0_sol.html
+.. _timml_notebook1_sol: timml_notebook1_sol.html
+.. _timml_notebook2_sol: timml_notebook2_sol.html
+.. _timml_notebook3_3D_sol: timml_notebook3_3D_sol.html
+.. _timml_notebook3_sol: timml_notebook3_sol.html
+.. _timml_notebook4_sol: timml_notebook4_sol.html
+.. _timml_notebook5_sol: timml_notebook5_sol.html
+.. _timml_notebook6_sol: timml_notebook6_sol.html
+.. _timml_notebook7: timml_notebook7.html
+.. _BuildingPit: BuildingPit.html
+.. _circareasink_example: circareasink_example.html
+.. _circular_buildingpit: circular_buildingpit.html
+.. _lake_horizontal_well: lake_horizontal_well.html
+.. _normal_flux: normal_flux.html
+.. _test_linesink_discharge: test_linesink_discharge.html
+.. _test_polygon_areasink: test_polygon_areasink.html
+.. _test_well_near_lake: test_well_near_lake.html
+.. _timml_figures: timml_figures.html
diff --git a/notebooks/lake_horizontal_well.ipynb → docs/03examples/lake_horizontal_well.ipynb b/notebooks/lake_horizontal_well.ipynb → docs/03examples/lake_horizontal_well.ipynb
diff --git a/notebooks/normal_flux.ipynb → docs/03examples/normal_flux.ipynb b/notebooks/normal_flux.ipynb → docs/03examples/normal_flux.ipynb
diff --git a/notebooks/test_linesink_discharge.ipynb → .../03examples/test_linesink_discharge.ipynb b/notebooks/test_linesink_discharge.ipynb → .../03examples/test_linesink_discharge.ipynb
@@ -4,7 +4,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "### TimML test line-sink discharge"
+    "# TimML test line-sink discharge"
    ]
   },
   {
@@ -239,7 +239,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "### Resistance line-sink"
+    "## Resistance line-sink"
    ]
   },
   {
@@ -384,7 +384,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "### Specifying heads along line-sinks"
+    "## Specifying heads along line-sinks"
    ]
   },
   {
@@ -480,7 +480,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "### LineSinkDitch"
+    "## LineSinkDitch"
    ]
   },
   {
@@ -541,7 +541,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "### Head line-sink string"
+    "## Head line-sink string"
    ]
   },
   {
@@ -841,7 +841,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "### Ditch string"
+    "## Ditch string"
    ]
   },
   {

diff --git a/notebooks/test_polygon_areasink.ipynb → docs/03examples/test_polygon_areasink.ipynb b/notebooks/test_polygon_areasink.ipynb → docs/03examples/test_polygon_areasink.ipynb
@@ -1,5 +1,12 @@
 {
  "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Test Polygon Area Sink"
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": 3,
@@ -102,7 +109,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "### Checks for numerical derivative"
+    "## Checks for numerical derivative"
    ]
   },
   {

diff --git a/notebooks/test_well_near_lake.ipynb → docs/03examples/test_well_near_lake.ipynb b/notebooks/test_well_near_lake.ipynb → docs/03examples/test_well_near_lake.ipynb
diff --git a/notebooks/timml_figures.ipynb → docs/03examples/timml_figures.ipynb b/notebooks/timml_figures.ipynb → docs/03examples/timml_figures.ipynb
@@ -1,5 +1,12 @@
 {
  "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# TimML aquifer figures"
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": 1,

diff --git a/notebooks/timml_notebook1_sol.ipynb → docs/03examples/timml_notebook1_sol.ipynb b/notebooks/timml_notebook1_sol.ipynb → docs/03examples/timml_notebook1_sol.ipynb
diff --git a/notebooks/timml_notebook2_sol.ipynb → docs/03examples/timml_notebook2_sol.ipynb b/notebooks/timml_notebook2_sol.ipynb → docs/03examples/timml_notebook2_sol.ipynb
@@ -16,7 +16,7 @@
     "\n",
     "Three wells are present. Well 1 is screened in aquifer 0 and has a discharge of 1000 m$^3$/d, well 2 is screened in aquifer 2 and has a discharge of 5000 m$^3$/d, and well 3 is screened in aquifers 1 and 2 and has a total discharge of 5000 m$^3$/d. A constant recharge through the upper boundary of aquifer 0 is simulated by one large circular infiltration area that covers the entire model area; the recharge rate is 0.2 mm/day. A head of 175 m is specified in layer 0 at the upper righthand corner of the model domain. A layout of all analytic elements, except the boundary of the infiltration area, is shown in Figure 1. \n",
     "\n",
-    "#### Table 1: Aquifer data for Exercise 2\n",
+    "### Table 1: Aquifer data for Exercise 2\n",
     "|Layer        | $k$ (m/d) | $z_b$ (m) | $z_t$ | $c$ (days) | $n$ (-) | $n_{ll}$ (-) |\n",
     "|------------:|----------:|----------:|------:|-----------:|--------:|----------:|\n",
     "|Aquifer 0    |   2       |   140     | 165   |      -     |  0.3    |    -      | \n",
@@ -27,7 +27,7 @@
     "\n",
     "<img src=\"figs/timml_notebook2_layout.png\"> </img>\n",
     "\n",
-    "#### Figure 1: Layout of elements for Exercise 2. Heads at centers of line-sinks are indicated. "
+    "### Figure 1: Layout of elements for Exercise 2. Heads at centers of line-sinks are indicated. "
    ]
   },
   {

diff --git a/notebooks/timml_notebook3_3D_sol.ipynb → docs/03examples/timml_notebook3_3D_sol.ipynb b/notebooks/timml_notebook3_3D_sol.ipynb → docs/03examples/timml_notebook3_3D_sol.ipynb
@@ -21,7 +21,7 @@
     "\n",
     "<img src=\"figs/inhomogeneity_exercise3.png\"> </img>\n",
     "\n",
-    "#### Figure 1: Layout of elements for exercise 3. A well is located inside inhomogeneity 1. Inhomogeneity 2 is added in the second part of the exercise."
+    "### Figure 1: Layout of elements for exercise 3. A well is located inside inhomogeneity 1. Inhomogeneity 2 is added in the second part of the exercise."
    ]
   },
   {

diff --git a/notebooks/timml_notebook3_sol.ipynb → docs/03examples/timml_notebook3_sol.ipynb b/notebooks/timml_notebook3_sol.ipynb → docs/03examples/timml_notebook3_sol.ipynb
diff --git a/notebooks/timml_notebook4_sol.ipynb → docs/03examples/timml_notebook4_sol.ipynb b/notebooks/timml_notebook4_sol.ipynb → docs/03examples/timml_notebook4_sol.ipynb
diff --git a/notebooks/timml_notebook5_sol.ipynb → docs/03examples/timml_notebook5_sol.ipynb b/notebooks/timml_notebook5_sol.ipynb → docs/03examples/timml_notebook5_sol.ipynb
diff --git a/notebooks/timml_notebook6_sol.ipynb → docs/03examples/timml_notebook6_sol.ipynb b/notebooks/timml_notebook6_sol.ipynb → docs/03examples/timml_notebook6_sol.ipynb
diff --git a/notebooks/timml_notebook7.ipynb → docs/03examples/timml_notebook7.ipynb b/notebooks/timml_notebook7.ipynb → docs/03examples/timml_notebook7.ipynb
diff --git a/docs/04xsections/index.rst b/docs/04xsections/index.rst
@@ -0,0 +1,15 @@
+Cross-sectional modeling
+========================
+
+This section describes how to build cross-sectional models in TimML.
+
+
+.. toctree::
+    :maxdepth: 4
+    :hidden:
+
+    timml_xsection
+
+* `timml_xsection`_
+
+.. _timml_xsection: timml_xsection.html
diff --git a/notebooks/timml_xsection.ipynb → docs/04xsections/timml_xsection.ipynb b/notebooks/timml_xsection.ipynb → docs/04xsections/timml_xsection.ipynb
diff --git a/docs/04api/index.rst → docs/05api/index.rst b/docs/04api/index.rst → docs/05api/index.rst
@@ -39,5 +39,5 @@ Python code.
 
 .. toctree::
     :hidden:
-    :maxdepth: 4
+    :maxdepth: 2
     :glob:
diff --git a/docs/06about/index.rst b/docs/06about/index.rst
@@ -0,0 +1,11 @@
+Cite
+====
+
+Publications
+------------
+
+.. bibliography:: publications.bib
+    :list: bullet
+
+    bakker2003
+    bakker_analytic_2006
diff --git a/docs/06about/publications.bib b/docs/06about/publications.bib
@@ -0,0 +1,28 @@
+
+@article{bakker2003,
+	title = {Analytic elements for multiaquifer flow},
+	volume = {271},
+	issn = {00221694},
+	url = {http://linkinghub.elsevier.com/retrieve/pii/S0022169402003190},
+	doi = {10.1016/S0022-1694(02)00319-0},
+	number = {1-4},
+	journal = {Journal of Hydrology},
+	author = {Bakker, Mark and Strack, Otto D. L.},
+	month = feb,
+	year = {2003},
+	keywords = {analytic element method, groundwater, leakage, multiaquifer flow},
+	pages = {119--129},
+	file = {Full Text:/home/david/Zotero/storage/8VHQ3TPN/Bakker and Strack - 2003 - Analytic elements for multiaquifer flow.pdf:application/pdf},
+}
+
+@article{bakker_analytic_2006,
+	title = {An analytic element approach for modeling polygonal inhomogeneities in multi-aquifer systems},
+	volume = {29},
+	doi = {10.1016/j.advwatres.2005.11.005},
+	abstract = {An analytic element approach is presented for the modeling of steady groundwater flow through multi-aquifer systems with piecewise constant aquifer and leaky layer properties. Different properties may be specified for domains bounded by closed polygons, referred to as polygonal inhomogeneities. The boundary of these inhomogeneities is modeled with two types of high-order line elements. First, a string of single-aquifer line-doublets is used; these elements cut through all aquifers and are valid both inside and outside the inhomogeneity. Second, two strings of multi-aquifer line-sinks are used, one string that is valid inside the inhomogeneity and one string that is valid outside; the comprehensive extraction of these line-sinks is zero at any point along the string. The proposed approach results in a comprehensive flow field of which the component normal to the boundary of the inhomogeneity is continuous across the boundary at any point. Within each individual aquifer, continuity of head and the component of flow normal to the boundary are met approximately across the boundary; the accuracy increases when the order of the line elements is increased and/or when shorter line elements are used. The proposed analytic element approach produces results that are virtually identical to the exact solution for a cylindrical inhomogeneity, and a high-resolution MODFLOW2000 model of two rectangular inhomogeneities with a shared boundary. The practical application of the approach is demonstrated through the solution of a problem with an irregularly shaped inhomogeneity with rivers crossing the inhomogeneity boundary.},
+	journal = {Advances in Water Resources - ADV WATER RESOUR},
+	author = {Bakker, Mark},
+	month = oct,
+	year = {2006},
+	pages = {1546--1555},
+}
diff --git a/docs/conf.py b/docs/conf.py
@@ -27,6 +27,7 @@
     "myst_nb",
     "sphinx_design",
     "sphinx.ext.autosectionlabel",
+    "sphinxcontrib.bibtex",
 ]
 
 templates_path = ["_templates"]
@@ -48,7 +49,7 @@
 html_theme_options = {
     "github_url": "https://github.com/mbakker7/timml",
     "use_edit_page_button": True,
-    "header_links_before_dropdown": 6,
+    "header_links_before_dropdown": 7,
     # "icon_links": [
     #     {
     #         "name": "GitHub",  # Label for this link
@@ -101,3 +102,9 @@
 nb_execution_allow_errors = True  # Allow errors in notebooks, to see the error online
 nb_execution_mode = "auto"
 nb_merge_streams = True
+
+# -- bibtex options ------------------------------------------------------------------
+
+# Add some settings for bibtex
+bibtex_bibfiles = ["06about/publications.bib"]
+bibtex_reference_style = "author_year"
diff --git a/docs/index.rst b/docs/index.rst
@@ -36,8 +36,14 @@ computed analytically at any point in the aquifer system. The Dupuit approximati
 
         TimML example notebooks.
 
+    .. grid-item-card:: Cross-sections
+        :link: 04xsections/index
+        :link-type: doc
+
+        Cross-sectional models explained.
+
     .. grid-item-card:: Code reference
-        :link: 04api/index
+        :link: 05api/index
         :link-type: doc
 
         TimML code reference.
@@ -78,6 +84,8 @@ Quick Example
 
     .. tab-item:: Result
 
+        In this example a well is modelled near a river in a single aquifer.
+
         .. figure:: _static/example_output.png
             :figwidth: 500px
 
@@ -90,4 +98,6 @@ Quick Example
     How-to guides <01howto/index>
     Concepts <02concepts/index>
     Examples <03examples/index>
-    Code reference <04api/index>
+    Cross-sections <04xsections/index>
+    Code reference <05api/index>
+    Cite <06about/index>