start of vignette; some updates to examples & docs

.gitignore

@@ -4,3 +4,4 @@
 .httr-oauth
 .DS_Store
 docs
+inst/doc

DESCRIPTION

@@ -17,6 +17,8 @@ Imports:
     graphics,
     stats
 Suggests: 
+    knitr,
+    rmarkdown,
     testthat (>= 3.0.0)
 Config/testthat/edition: 3
 Encoding: UTF-8
@@ -34,3 +36,4 @@ Collate:
     'uniformflow.R'
     'utils.R'
     'well.R'
+VignetteBuilder: knitr

R/aem.R

@@ -79,7 +79,7 @@ aem <- function(k, top, base, n, ..., type = c('variable', 'confined'), verbose
 
 #' Solve an `aem` model
 #'
-#' [solve.aem()] solves system of equations as constructed by the supplied  elements in the `aem` model
+#' [solve.aem()] solves the system of equations as constructed by the elements in the `aem` model
 #'
 #' @param a `aem` object
 #' @param b ignored

R/flow-variables.R

@@ -96,8 +96,8 @@ domegainf <- function(...) UseMethod('domegainf')
 #'
 #' domega(ml, c(50, 0), c(25, -25))
 #'
-#' xg <- seq(-100, 100, length = 500)
-#' yg <- seq(-75, 75, length = 100)
+#' xg <- seq(-100, 100, length = 5)
+#' yg <- seq(-75, 75, length = 3)
 #' domega(ml, xg, yg, as.grid = TRUE)
 #'
 domega.aem <- function(aem, x, y, as.grid = FALSE, ...) {

R/state-variables.R

@@ -85,8 +85,8 @@ omegainf <- function(...) UseMethod('omegainf')
 #'
 #' omega(ml, c(50, 0), c(25, -25))
 #'
-#' xg <- seq(-100, 100, length = 500)
-#' yg <- seq(-75, 75, length = 100)
+#' xg <- seq(-100, 100, length = 5)
+#' yg <- seq(-75, 75, length = 3)
 #' omega(ml, xg, yg, as.grid = TRUE)
 #'
 omega.aem <- function(aem, x, y, as.grid = FALSE, ...) {

R/tracelines.R

@@ -137,15 +137,15 @@ outside_vertical <- function(aem, x, y, z, ...) {
 #' Compute tracelines of particles
 #'
 #' [tracelines()] tracks particle locations moving forward or backward with the advective groundwater flow
-#' by numerically integrating the velocity vector. The resulting set of connected coordinates produce the
+#' by numerically integrating the velocity vector. The resulting set of connected coordinates produces the
 #' tracelines.
 #'
 #' @param aem `aem` object
 #' @param x0 numeric vector, starting `x` locations of the particles
 #' @param y0 numeric vector, starting `y` locations of the particles
 #' @param z0 numeric vector, starting `z` locations of the particles
 #' @param times numeric vector with the times at which locations should be registered
-#' @param forward logical, should be forward (`TRUE`; default) or backward (`FALSE`) tracking be performed.
+#' @param forward logical, should forward (`TRUE`; default) or backward (`FALSE`) tracking be performed.
 #' @param R numeric, retardation coefficient passed to [velocity()]. Defaults to 1 (no retardation).
 #' @param tfunc function or list of functions with additional termination events for particles. See details. Defaults to `NULL`.
 #' @param tol numeric tolerance used to define when particles have crossed a line element. Defaults to 0.001 length units.

R/utils.R

@@ -71,7 +71,7 @@ satthick <- function(aem, x, y, as.grid = FALSE, ...) {
 #'
 #' @details The x and y components of `flow` are used to calculate the directed value using `angle`.
 #'    The `z` coordinate in [discharge()], [darcy()] or [velocity()] is set at the aquifer base. Under Dupuit-Forchheimer,
-#'    the x and y components of flow do not change along the vertical axis.
+#'    the x and y components of the flow vector do not change along the vertical axis.
 #'
 #' @return A vector of `length(x)` (equal to `length(y)`) with the flow values at `x` and `y` in the direction of `angle`.
 #'     If `as.grid = TRUE`, a matrix of dimensions `c(length(y), length(x))` described by
@@ -194,7 +194,7 @@ flow_through_line <- function(aem, x0, y0, x1, y1, flow = c('discharge', 'darcy'
 #' Get the discharge in or out of the aquifer from an element
 #'
 #' [element_discharge()] obtains the computed discharge into or out of the aquifer
-#'    for a individual analytic elements or all elements of a given type.
+#'    for a individual analytic element or all elements of a given type.
 #'
 #' @param aem `aem` object
 #' @param name character vector with the name of the element(s) as available in `aem$elements`.

_pkgdown.yml

@@ -1,4 +1,5 @@
 url: https://cneyens.github.io/raem/
 template:
   bootstrap: 5
+  bootswatch: lumen
 

vignettes/.gitignore

@@ -0,0 +1,2 @@
+*.html
+*.R

vignettes/overview.Rmd

@@ -0,0 +1,71 @@
+---
+title: "An overview"
+output: rmarkdown::html_vignette
+vignette: >
+  %\VignetteIndexEntry{An overview}
+  %\VignetteEngine{knitr::rmarkdown}
+  %\VignetteEncoding{UTF-8}
+---
+
+```{r, include = FALSE}
+knitr::opts_chunk$set(
+  collapse = TRUE,
+  comment = "#>"
+)
+```
+
+The `raem` package provides a set of R functions to create an analytic element model of steady-state, single layer groundwater flow under the Dupuit-Forchheimer assumption. This vignette gives a short overview of the theory and basics behind analytic element modeling and how the `raem` package implements this in R.
+
+# Introduction to analytic element modeling
+
+First developed by Otto Strack and Henk Haitjema in the late 1970's, the analytic element modeling (AEM) approach solves a groundwater flow problem by superimposing solutions for features such as wells, streams and recharge. Each feature is called *an element*.
+
+The governing equation is:
+
+The main assumption is based on the Dupuit-Forchheimer approximation, which states that
+
+This reduces the governing equation to:
+
+which described steady-state, single-layer two-dimensional flow in the $x-y$ plane.
+
+When the aquifer is phreatic, the saturated thickness is variable, which renders equation X non-linear when solving for $h$. Therefore, the discharge potential $\Phi$ is introduced:
+
+so that equation X becomes:
+
+This linear equation can be solved for $\Phi$. The resulting hydraulic heads can then be computed as:
+
+In addition to the discharge potential $\Phi$, there exists a streamfunction $\Psi$ which is defined as:
+
+$\Psi$ is only defined for the Laplace equation. When areal recharge is applied using area-sinks (see paragraph [Area-sink] below), the equation follows a Poisson equation and $\Psi$ is no longer meaningful.
+
+$\Phi$ and $\Psi$ fulfill the Cauchy-Riemann conditions, so they can be combined into a complex discharge potential $\Omega$:
+
+whose real and imaginary terms are $\Phi$ and $\Psi$, respectively. The flow problem is solved in terms of $\Omega$, which then yields $\Phi$ and eventually $h$.
+
+Each element gives a solution for the governing flow equation in terms of $\Omega$, which are superimposed in space. Since the solution for a given element depends on the results of all other elements, the complete system of equations needs to be solved simultaneously. This is done by setting up a matrix formulation of equation X in the form of $Ax=b$, which is then solved.
+
+For a more complete overview of analytic element modeling, the reader is referred to
+
+# Elements
+
+## Well
+
+```{r setup}
+library(raem)
+```
+
+## Line-sink
+
+## Area-sink
+
+## Reference point
+
+## Uniform flow
+
+# Setting up a model
+
+# Output
+
+# Particle traces
+
+# Additional functionality