Merge branch 'master' of https://git.lemmasoftware.org/FEM4EllipticPDE

dox/book.tex

@@ -0,0 +1,85 @@
+%\documentclass[11pt]{article}
+%\documentclass[a4paper,11pt]{report}
+%\documentclass[11pt]{report}
+%\documentclass[a4paper,11pt]{scrartcl}
+\documentclass[a4paper,11pt]{scrreprt} %book}
+%\usepackage{times}
+\usepackage{fullpage,amsmath,placeins,graphicx,color,amssymb,setspace,listings,tikz,amsthm,yfonts,subfigure}
+\usepackage{natbib}
+
+\usepackage[linkbordercolor=white,citecolor={1 1 1}]{hyperref}
+
+\usepackage{amsthm} % theorem
+	
+\newcounter{proof}
+\stepcounter{proof}	
+\newtheorem{corollary}{Corollary}[proof]
+
+\definecolor{dkgreen}{rgb}{0,0.6,0}
+\definecolor{gray}{rgb}{0.5,0.5,0.5}
+
+%\lstset{language=c++,numbers=left,numberstyle=\tiny,showstringspaces=false,color=true}
+\lstset{language=c++,
+   keywords={real, VectorXd, SparseMatrix, string, this, default, exit, float, double,int, break, case,
+             catch,continue,else,elseif,end,for,function,Real,Complex,
+             global,if,otherwise,persistent,return,switch,try,while,long, unsigned, vector},
+   basicstyle=\ttfamily,
+   keywordstyle=\color{blue},
+   commentstyle=\color{red},
+   stringstyle=\color{dkgreen},
+   numbers=left,
+   numberstyle=\tiny\color{gray},
+   stepnumber=1,
+   numbersep=10pt,
+   backgroundcolor=\color{white},
+   tabsize=4,
+   showspaces=false,
+   showstringspaces=false}
+
+
+\def\LAPL#1{\nabla^2 {#1}}
+\def\VEC#1{\mathbf{#1}}
+\def\LBM{ \mathcal{L} ( \mathbb{R}^n ) }
+\def\LBO{ \mathcal{L} ( \mathbb{R}^1 ) }
+\def\LBT{ \mathcal{L} ( \mathbb{R}^2 ) }
+\def\REB{ \mathbb{R} }
+\def\REBN{ \mathbb{R}^n }
+\def\CENSECA{\alpha(U_{n+1}^m-2U_n^m+U_{n-1}^m)}
+%\def\DD#1{\frac{\partial}{\partial #1}}
+\def\DD#1{\frac{d}{d #1}}
+
+\author{Trevor Irons \\  
+        XRI Geophysics, LLC \\ 
+        Trevor.Irons@xrigeo.com   }
+
+\title{FEM4EllipticPDE}
+\subtitle{Lemma module v1.0}
+
+\begin{document}
+
+\maketitle
+
+\tableofcontents
+
+\renewcommand{\labelenumi}{(\Roman{enumi})}
+\renewcommand{\labelenumii}{(\arabic{enumii})}
+\renewcommand{\labelenumiii}{(\roman{enumiii})}
+
+\abstract
+	This Lemma module provides a Galerkin-style finite element solution to general elliptic problems. 
+	Lemma is an open source geophysical programming API that supports modular plug-ins, such as this one. 
+	Lemma may be freely downloaded from \href{http://lemmasoftware.org}{http://lemmasoftware.org}.
+	This module is currently closed source. Development of FEM4EllipticPDE started at the 
+	Center for Gravity Electrical and Magnetic Studies (CGEM) at the Colorado School of Mines. The modules  
+	was completed by XRI Geophysics, LLC. 
+
+\input{chapters/derivation}
+\input{chapters/usage}
+
+\input{chapters/magnetics}
+\input{chapters/examples}
+
+\bibliographystyle{seg}
+\bibliography{nmr}
+
+\end{document}

dox/chapters/derivation.tex

@@ -0,0 +1,269 @@
+\chapter{Derivation}
+
+\section{Problem Statement}
+FEM4EllipticPDE is a Lemma module implementing a Galerkin finite element solution to a family of commonly encountered 
+elliptic  problems taking the form
+%Considering the uniformly elliptic Dirichlet BVP: 
+\begin{eqnarray}
+	\label{eq:scheme}
+	-\nabla \cdot \left( \sigma(\mathbf{r}) \nabla u(\mathbf{r}) \right) = g(\mathbf{r}) & \mathop{\forall}_{u \in \Omega} \\
+	u = 0                                            & \mathop{\forall}_{u \in \partial \Omega} 
+\end{eqnarray}
+
+Where $0 < \sigma_{min} \leq \sigma(\mathbf{r}) \leq \sigma_{max} \ll \infty $  and $\Omega \in \mathbb{R}^3$. When $\sigma \equiv 1$, this 
+reduces to Poisson's equation $\left( \nabla^2 u  = g \right)$. These types of problem arises in several areas of geophysics: gravitational or magnetic potentials 
+obey Poisson's equation, while the more general form can be used to solve electrostatic (DC and SP) problems. 
+
+\begin{enumerate}
+	\item The Galerkin finite element method is defined by reposing the global problem in terms of numerous local ones through the use of 
+	appropriate test functions. 
+	\begin{itemize}
+
+		\item Test functions $v$ must be from a suitable subspace. 
+		In this case, due to the Dirichlet boundary conditions,
+		\[
+			v  \in H^a_b(\Omega)
+		\]
+		meet our requirements. $H^a_b$ represents the subspace of weakly differentiable functions that are zero valued at $a$, and $b$
+		and $\textgoth{V}$ represents the actual functions. % Hilbert space.
+
+		The 3D variational problem may be written
+
+%		\[
+%				-\nabla \cdot \left( \sigma(\mathbf{r}) \nabla u(\mathbf{r}) \right) = g(\mathbf{r}) & \mathop{\forall}_{u \in \Omega} \\
+%	u = 0                                            & \mathop{\forall}_{u \in \partial \Omega} 
+%
+		%\] 
+		\[
+		  \int	-v \nabla \cdot \sigma  \nabla u = v g.
+		\]
+		This can be simplified 
+		\[
+			\int_a^b \sigma \frac{du}{dx} \frac{dv}{dx} dx = v g
+		\]
+		The proof of which follows below. 
+		%\item The variational form may be found by multiplying the elliptic PDE by any arbitrary
+		%\[ 
+		%	v \in H_a^b(\Omega) 
+		%\]
+		
+		%In 1D ($\Omega \in \mathbb{R}^1$) \autoref{eq:scheme} reduces to:
+		%\begin{equation} \label{eq:oned}
+		%	- \DD{x} \sigma \DD{x} u = g
+		%\end{equation}
+		%Using the variational (weak) formulation for any arbitrary $v \in \textgoth{V} 
+	
+		\item In any arbitrary dimension $x$, if the boundaries in that dimension of $\partial \Omega = [a,b]$ the variational problem using 
+		test functions can be constructed 
+		\begin{equation} \label{eq:oned}
+			-\int_a^b v(x) \DD{x} \sigma(x) \DD{x} u(x)  dx = \int_a^b v(x) g(x) dx ,  
+		\end{equation}
+
+				
+		The variation problem can be reduced to a simplified version, if appropriate test functions we may instead write the 
+		variational problem as 
+		\[
+			\int_a^b  \sigma \frac{du}{dx} \frac{dv}{dx} dx = \int_a^b v(x) g(x) dx
+		\]
+		
+
+		In one dimension this resolves to
+		\[
+			%	-\int_a^b v \frac{d}{dx} \left[ \sigma \frac{du}{dx} \right] dx = 
+			\int_a^b  \sigma \frac{du}{dx} \frac{dv}{dx} dx = \int_a^b v(x) g(x) dx
+		\]
+
+		
+				
+
+		\begin{corollary}
+		\[
+		\frac{d}{dx} \left[ v \sigma \frac{du}{dx}  \right] = v \frac{d}{dx} \left[ \sigma \frac{du}{dx} \right] +
+		 \sigma \frac{du}{dx} \frac{dv}{dx}  
+		\]	
+		\end{corollary}
+
+		
+
+		\begin{proof}
+		and the integration by parts on the left hand side yields
+		\begin{eqnarray*}
+		\int_a^b v \frac{d}{dx} \left[ v \sigma \frac{du}{dx} \right] dx &=&  \int_a^b v \frac{d}{dx} 
+		\left[ \sigma \frac{du}{dx} \right] dx + 
+		\int_a^b \sigma \frac{du}{dx} \frac{dv}{dx} dx  \\
+		\Rightarrow & & \\
+		\left[ v \sigma \frac{du}{dx} \right]_a^b &=& \int_a^b v \frac{d}{dx} \left[ 
+		\sigma \frac{du}{dx} \right]  + \int_a^b \sigma \frac{dv}{dx}\frac{du}{dx} dx \\
+		\Rightarrow & & \\\
+			-\int_a^b v \frac{d}{dx} \left[ \sigma \frac{du}{dx} \right] dx &=& \left[ v \sigma 
+			\frac{du}{dx} \right]_a^b + \int_a^b \sigma \frac{du}{dx} \frac{dv}{dx} dx
+		\end{eqnarray*}
+		\[
+				-\int_a^b v \frac{d}{dx} \left[ \sigma \frac{du}{dx} \right] dx = \int_a^b 
+		\sigma \frac{du}{dx} \frac{dv}{dx} dx
+		\]
+		\end{proof}
+
+		Because $v\in H^1_0$ the solution vanishes at the boundaries $\left[ v \sigma \frac{du}{dx} \right]_a^b =0 $.
+		Therefore the scheme reduces to:
+
+% 		Which can be rewritten as
+% 		\[
+% 			a(u,v) = <g,v>
+% 		\] 
+		
+		The Galerkin FEM method uses triangle (hat) functions for $v$, which are renamed $\phi$ as 
+		they are specific. I will occasionally use these interchangeably.  
+
+		Through induction it can be shown then that the 3D problem can similarity be posed 
+		So that Equation \ref{eq:scheme} may be rewritten
+		\[
+			-v \nabla \cdot \sigma  \nabla u = g v.
+		\]
+
+		\FloatBarrier
+	
+		\item \FloatBarrier Define mesh. Since $\Omega = (0,\pi)$ is an uncountable subset of $\mathbb{R}^1$ a 
+		countable subset of $\Omega$ must be defined. A mesh is defined over the interval $(0,\pi)$.
+		This mesh is defined and shown in Figure \ref{fig:mesh}.	
+
+		\begin{figure}[ht]
+		\begin{center}
+		\input{chapters/mesh}
+		\caption{A 1D FEM mesh is defined. $N$ nodes ($n$) are defined over the interval. Between the 
+		nodes an element is defined. The mesh is general and the spacing between nodes is defined by 
+		$N-1$ discritisation parameters $h$.}
+		\label{fig:mesh}
+		\end{center}
+		\end{figure}
+
+		\item Define a finite dimensional subspace based on the mesh and a particular test function.  
+		A subspace  $\textgoth{V}_h \subset \textgoth{V}$ is sought such that $ \textgoth{V}_h$ is finite 
+		dimensional. 
+		Particular linearity independent test functions $\phi$ are defined on $\textgoth{V}_h$ such that 
+		$\textgoth{V}_h = \mathrm{span}(\phi_i)$. The test functions form a basis of this space. 
+		If the weak formulation of the derivative is used these
+		test functions may be constructed such as they are only piecewise differentiable. We may define test 
+		functions as Kronecker delta $\delta$ functions taking values of unity at a particular node of the mesh. 		
+		The linear spline Galerkin method of FEM interpolates these $\delta$ functions. They are zero valued at the 
+		neighbouring nodes. In 1D this interpolation yields hat functions.
+		Therefore the test functions  $\phi_i$  are defined as:
+
+		\begin{equation}
+		\phi_i(x) = \left\{ \begin{array}{ccl} 
+		0 & \textrm{if}  & x\in[\alpha, x_{i-1}]  \\
+		\frac{x - x_{i-1}}{h_i} & \textrm{if}  & x\in[x_{i-1}, x_i]  \\
+		\frac{x_{i+1}-x}{h_{i+1}} & \textrm{if}  & x\in[x_i, x_{i+1}]  \\
+		0 & \textrm{if}  & x\in[x_{i+1}, \beta ]  \\
+		\end{array} \right.
+		\end{equation} 
+
+		Define the variational form of the solution solution 
+
+		\begin{equation} \label{eq:sol1}
+		a(u, v) = <g,v> 
+		\end{equation}
+
+		A is a symmetric bilinear form such that $a(u,v) = a(v,u)   \forall v \in \textgoth{V}_h$.
+		
+	\end{itemize}
+
+	In 3D things are a little different. For a given element (tetrahedra) comprised of 4 points we construct the 
+	location matrix
+	\[ \mathbf{C}  = 
+		\left[ \begin{matrix}
+			1 & x_1 & y_1 & z_1  \\
+			1 & x_2 & y_2 & z_2  \\
+			1 & x_3 & y_3 & z_3  \\
+			1 & x_4 & y_4 & z_4
+		       \end{matrix} \right]
+	\]
+
+	We can then fill the stiffness matrix
+	\[
+		K_{ij} = \sum_{i=0}^{N} \int_{Tet_k} = c \nabla \phi_i \cdot \phi_j
+	\]
+
+	\item The solution may be written in matrix(stiffness matrix) vector (load vector) notation. 
+
+	We approximate the solution (Equation \ref{eq:sol1}) using the trial and test functions $\phi$ discussed 
+	previously. Let 
+	\begin{eqnarray*}
+		\sigma(x) &=& x + 1 \\
+		u(x) &=& \sin(x) 
+	\end{eqnarray*}
+
+	At each node $u_h \in \textgoth{V}_h : a(u_h, v) = <g,v>$ the stiffness matrix $A$
+	\begin{eqnarray*}
+		A_{ij} &=& a(\phi_i, \phi_j) = \int_0^\pi \sigma(x) \phi'_i \phi'_j \\
+		       &=&  \int_0^\pi (x+1) \phi'_i \phi'_j 
+	\end{eqnarray*}
+	
+	%//Since $\phi$ is a triangle, $\phi'$ becomes a step function.
+
+	We have for $i= 1,\cdots , n$
+	\[
+		\phi'(x) = \left\{ \begin{array}{ccl}
+			0 & \textrm{if}  & x\in[\alpha, x_{i-1}]  \\
+			\frac{1}{h_i} & \textrm{if}  & x\in[x_{i-1}, x_i]  \\
+			-\frac{1}{h_{i+1}} & \textrm{if}  & x\in[x_i, x_{i+1}]  \\
+			0 & \textrm{if}  & x\in[x_{i+1}, \beta ]  \\
+		\end{array} \right.
+	\]
+
+	The product $\phi_i'(x) \phi_j(x)$ vanishes when $|i - j| > 1$. So that in a 1D case, A becomes tri-diagonal. 
+	Following the general equation:
+	\begin{eqnarray*}
+		A_{ij} &=&  \int_{i-1}^{i+1} (x+1) \phi'_i(x) \phi'_j(x) \\ 
+	\end{eqnarray*}
+
+	The load vector $g$ is given:
+	\[
+		[g]_i = <g, \phi_i> = \int_0^\pi g \phi_i
+	\]
+
+	Using $ g = [g]$, the linear system becomes:
+	\[
+		Au = g
+	\]
+
+	\item For this case the entries of the stiffness matrix  and load vector are
+	
+	For the three non-zero cases of $A$:
+	\begin{eqnarray*}
+		A_{ii} &=&  \int_{i-1}^{i+1} (x+1) \phi'_i(x) \phi'_i(x) \\ 
+		A_{ii} &=& \int_{{i-1}}^{i} (x+1) \phi_i'^2 dx + \int_{i}^{x_{i+1}} (x+1)\phi_i'^2 \\ 
+		A_{ii} &=& \frac{1}{h_i^2}\int_{{i-1}}^{i} (x+1)  dx + \frac{1}{h_{i+1}^2} \int_{i}^{{i+1}} (x+1) dx 
+	\end{eqnarray*}
+
+	\begin{eqnarray*}
+		A_{i,i+1} &=& \int_{i}^{i+1} (x+1) \phi'_i(x) \phi'_{i+1}(x) \\ 
+		A_{i,i+1} &=& \int_{i}^{i+1} (x+1) \phi_i' \phi_{i+1}' dx \\ %+ \int_{i}^{x_{i+1}} (x+1)\phi_i' \phi_{i+1}'  \\ 
+		A_{i,i+1} &=& \frac{1}{h_i + h_{i+1}}\int_{i}^{i+1} (x+1)  dx %+ \frac{1}{h_{i+1}^2} \int_{i}^{{i+1}} (x+1) dx 
+	\end{eqnarray*}
+
+	\begin{eqnarray*}
+		A_{i,i-1} &=&  \int_{i-1}^{i} (x+1) \phi'_i(x) \phi'_{i-1}(x) \\ 
+		A_{i,i-1} &=&  \int_{i-1}^{i} (x+1) \phi_i' \phi_{i-1}' dx \\%+ \int_{i}^{x_{i+1}} (x+1)\phi_i' \phi_{i-1}' \\ 
+		A_{i,i-1} &=& \frac{1}{h_i + h_{i-1}}\int_{{i-1}}^{i} (x+1) dx % dx + \frac{1}{h_{i+1}^2} \int_{i}^{{i+1}} (x+1) dx 
+	\end{eqnarray*}
+	
+	These integrals are evaluated numerically in my program \textit{gfemddn} using Simpson's Rule.
+
+	Solving for the forcing function $g$ in  \autoref{eq:scheme}
+	\begin{eqnarray*}
+		-\nabla \cdot \sigma(x) \nabla u(x) &=& g(x) \\
+		-\frac{\partial}{\partial x} \cdot (x+1) \frac{\partial }{\partial x} \sin(x) &=& g(x) \\
+		-\frac{\partial}{\partial x} \cdot (x+1) \cos(x) &=& g(x) \\
+		 \sin(x) + x\sin(x) - \cos(x) &=& g(x) \\
+		 \sin(x) (x+1) - \cos(x) &=& g(x) \\
+	\end{eqnarray*}	 
+
+	The load vector $g$ is then:
+	\[
+		g_i = <g, \phi_i> = \int_0^\pi \left(  \sin(x) (x+1) - \cos(x) \right) \phi_i
+	\]
+	In \textit{gfemddn} this integral is again evaluated using Simpson's Rule.
+
+	\end{enumerate}
+

dox/chapters/examples.tex

@@ -0,0 +1,58 @@
+\chapter{Examples and Verification}
+
+\section{Coulombic Magnetic Potential}
+		In the absence of external current densities, we may write $\nabla \times \mathbf{H} = 0$.
+		This allows the $H$ field to be represented using a scalar potential term  
+		\begin{align} 
+			\mathbf{H} = \nabla \phi_M.
+		\end{align}
+		Static magnetics problems (in linear media) can be solved using a scalar potential term obeying the 
+		following relationship \cite[e.g.,][]{Jackson1998}
+		\begin{align} \label{eq:permMagnet}
+			%-\nabla \cdot \mu(\mathbf{r}) \nabla \phi_M(\mathbf{r}) = \mu(\mathbf{r}) M_0(\mathbf{r}).
+			-\LAPL{\phi_M} = \rho_M(\mathbf{r}).
+		\end{align}
+		Where $\phi_M$ represents the Coulomb magnetic potential (appropriate for static magnetics problems) 
+		and $\rho_M$ is the effective magnetic charge density (=$\nabla \cdot \mathbf{M}$).
+		This formulation is particularity useful in calculating the fields of permanent magnets, where the 
+		magnetisation of the magnet is given by $\mathbf{M}(\mathbf{r})$.
+		The left hand side of (\ref{eq:permMagnet}) can easily be solved using {\bf{FEM4EllipticPDE}}, however 
+		the right hand side requires some special care. 
+
+	\subsection{Calculation of Charge Density}
+		For uniformly magnetised media $\rho_M$ vanishes everywhere except at the boundaries of the magnet.  
+		In truth, $\mathbf{M}$ is well behaved and there are no truly uniformly magnetized magnets, but the 
+		true nature of $\mathbf{M}$ is rarely known, and the assumption of uniform magnetisation becomes necessary. 
+		Practical permanent magnets are \emph{effectively} uniformly magnetised, and this assumption is completely 
+		reasonable, and even necessary. 
+
+		We can therefore apply the divergence theorem to to the boundaries to calculate the surface charge density
+		$\sigma_M = \hat{\mathbf{n}} \cdot \mathbf{M}$ which exists on the 2D surface of the media and has zero 
+		Riemann measure, formally necessitating a Lebesgue integral. 
+		We may then let $\rho_M \rightarrow \sigma_M$ in 
+		(\ref{eq:permMagnet}). 
+		The FEM variational formulation for an particular element in the load vector $g$ that spans 
+		the boundary of the media at point $\mathbf{r}_0$  can be written
+		\begin{align}
+			[g]_i & = \left< \rho_M, \phi_i \right> = \int \rho_M \phi_i \\
+			      %//& = \int_L \delta\{\hat{\mathbf{r}_0}\} \sigma_M \phi_i \\ 
+			      & = \int_L \sigma_M \phi_i \\ 
+			      & = \sigma_M \phi_i(\mathbf{r}_0). 
+		\end{align}
+
+	\subsection{Uniformly Charged Sphere}
+	The scalar potential of a uniformly charged sphere is given \cite[p. 198, ][]{Jackson1998} 
+	\begin{align}
+		\phi_M(\rho, \theta) = \frac{1}{3} M_0 a^2 \frac{r_<}{r_>^2} \cos(\theta).
+	\end{align}
+	Where the notation $r_<, r_>$ represents the smaller or larger of the distance $\rho$ and sphere radius $a$.
+
+	Inside the sphere
+	\begin{align}
+		%\phi_M &= \frac{1}{3} M_0 \rho \cos \theta  & \text{inside the sphere} \\
+		\phi_M &= \frac{1}{3} M_0 z  & \text{inside the sphere} \\
+		\phi_M &= \frac{1}{3} M_0 a^3 \frac{\cos \theta}{\rho^2}  & \text{outside the sphere} 
+	\end{align}
+	
+
+ 

dox/chapters/magnetics.tex

@@ -0,0 +1,9 @@
+\chapter{Magnetics}
+
+\section{Linear approximation}
+
+Linear induced magnetism. For low values of $\kappa$, the induced field can be approximated. For higher suceptibilities for for 
+remanance furthur corrections are needed, see section \
+\[
+	\nabla^2 u = \nabla \cdot \kappa \mathbf{H}
+\]

dox/chapters/mesh.tex

@@ -0,0 +1,189 @@
+% Graphic for TeX using PGF
+% Title: /home/tirons/CGEM/tirons/Class/npde/ass2/report/mesh.dia
+% Creator: Dia v0.96.1
+% CreationDate: Sun Mar 29 11:45:22 2009
+% For: tirons
+% \usepackage{tikz}
+% The following commands are not supported in PSTricks at present
+% We define them conditionally, so when they are implemented,
+% this pgf file will use them.
+\ifx\du\undefined
+  \newlength{\du}
+\fi
+\setlength{\du}{15\unitlength}
+\begin{tikzpicture}
+\pgftransformxscale{1.000000}
+\pgftransformyscale{-1.000000}
+\definecolor{dialinecolor}{rgb}{0.000000, 0.000000, 0.000000}
+\pgfsetstrokecolor{dialinecolor}
+\definecolor{dialinecolor}{rgb}{1.000000, 1.000000, 1.000000}
+\pgfsetfillcolor{dialinecolor}
+\pgfsetlinewidth{0.100000\du}
+\pgfsetdash{}{0pt}
+\pgfsetdash{}{0pt}
+\pgfsetbuttcap
+{
+\definecolor{dialinecolor}{rgb}{0.000000, 0.000000, 0.000000}
+\pgfsetfillcolor{dialinecolor}
+% was here!!!
+\definecolor{dialinecolor}{rgb}{0.000000, 0.000000, 0.000000}
+\pgfsetstrokecolor{dialinecolor}
+\draw (12.012500\du,10.037500\du)--(27.337500\du,10.062500\du);
+}
+% setfont left to latex
+\definecolor{dialinecolor}{rgb}{0.000000, 0.000000, 0.000000}
+\pgfsetstrokecolor{dialinecolor}
+\node[anchor=west] at (11.712500\du,12.537500\du){0};
+% setfont left to latex
+\definecolor{dialinecolor}{rgb}{0.000000, 0.000000, 0.000000}
+\pgfsetstrokecolor{dialinecolor}
+\node[anchor=west] at (26.820000\du,12.410000\du){$\pi$};
+\pgfsetlinewidth{0.100000\du}
+\pgfsetdash{}{0pt}
+\pgfsetdash{}{0pt}
+\pgfsetbuttcap
+{
+\definecolor{dialinecolor}{rgb}{0.000000, 0.000000, 0.000000}
+\pgfsetfillcolor{dialinecolor}
+% was here!!!
+\definecolor{dialinecolor}{rgb}{0.000000, 0.000000, 0.000000}
+\pgfsetstrokecolor{dialinecolor}
+\draw (13.270437\du,9.662500\du)--(13.295437\du,10.474332\du);
+}
+\pgfsetlinewidth{0.100000\du}
+\pgfsetdash{}{0pt}
+\pgfsetdash{}{0pt}
+\pgfsetbuttcap
+{
+\definecolor{dialinecolor}{rgb}{0.000000, 0.000000, 0.000000}
+\pgfsetfillcolor{dialinecolor}
+% was here!!!
+\definecolor{dialinecolor}{rgb}{0.000000, 0.000000, 0.000000}
+\pgfsetstrokecolor{dialinecolor}
+\draw (12.056953\du,9.640847\du)--(12.032938\du,11.749332\du);
+}
+\pgfsetlinewidth{0.100000\du}
+\pgfsetdash{}{0pt}
+\pgfsetdash{}{0pt}
+\pgfsetbuttcap
+{
+\definecolor{dialinecolor}{rgb}{0.000000, 0.000000, 0.000000}
+\pgfsetfillcolor{dialinecolor}
+% was here!!!
+\definecolor{dialinecolor}{rgb}{0.000000, 0.000000, 0.000000}
+\pgfsetstrokecolor{dialinecolor}
+\draw (14.981953\du,9.665847\du)--(15.006953\du,10.477678\du);
+}
+\pgfsetlinewidth{0.100000\du}
+\pgfsetdash{}{0pt}
+\pgfsetdash{}{0pt}
+\pgfsetbuttcap
+{
+\definecolor{dialinecolor}{rgb}{0.000000, 0.000000, 0.000000}
+\pgfsetfillcolor{dialinecolor}
+% was here!!!
+\definecolor{dialinecolor}{rgb}{0.000000, 0.000000, 0.000000}
+\pgfsetstrokecolor{dialinecolor}
+\draw (17.016953\du,9.680847\du)--(17.041953\du,10.492678\du);
+}
+\pgfsetlinewidth{0.100000\du}
+\pgfsetdash{}{0pt}
+\pgfsetdash{}{0pt}
+\pgfsetbuttcap
+{
+\definecolor{dialinecolor}{rgb}{0.000000, 0.000000, 0.000000}
+\pgfsetfillcolor{dialinecolor}
+% was here!!!
+\definecolor{dialinecolor}{rgb}{0.000000, 0.000000, 0.000000}
+\pgfsetstrokecolor{dialinecolor}
+\draw (18.026953\du,9.670847\du)--(18.051953\du,10.482678\du);
+}
+\pgfsetlinewidth{0.100000\du}
+\pgfsetdash{}{0pt}
+\pgfsetdash{}{0pt}
+\pgfsetbuttcap
+{
+\definecolor{dialinecolor}{rgb}{0.000000, 0.000000, 0.000000}
+\pgfsetfillcolor{dialinecolor}
+% was here!!!
+\definecolor{dialinecolor}{rgb}{0.000000, 0.000000, 0.000000}
+\pgfsetstrokecolor{dialinecolor}
+\draw (18.986953\du,9.660847\du)--(19.011953\du,10.472678\du);
+}
+\pgfsetlinewidth{0.100000\du}
+\pgfsetdash{}{0pt}
+\pgfsetdash{}{0pt}
+\pgfsetbuttcap
+{
+\definecolor{dialinecolor}{rgb}{0.000000, 0.000000, 0.000000}
+\pgfsetfillcolor{dialinecolor}
+% was here!!!
+\definecolor{dialinecolor}{rgb}{0.000000, 0.000000, 0.000000}
+\pgfsetstrokecolor{dialinecolor}
+\draw (20.971953\du,9.700847\du)--(20.996953\du,10.512678\du);
+}
+\pgfsetlinewidth{0.100000\du}
+\pgfsetdash{}{0pt}
+\pgfsetdash{}{0pt}
+\pgfsetbuttcap
+{
+\definecolor{dialinecolor}{rgb}{0.000000, 0.000000, 0.000000}
+\pgfsetfillcolor{dialinecolor}
+% was here!!!
+\definecolor{dialinecolor}{rgb}{0.000000, 0.000000, 0.000000}
+\pgfsetstrokecolor{dialinecolor}
+\draw (27.356953\du,9.665847\du)--(27.357938\du,11.724332\du);
+}
+\pgfsetlinewidth{0.100000\du}
+\pgfsetdash{}{0pt}
+\pgfsetdash{}{0pt}
+\pgfsetbuttcap
+{
+\definecolor{dialinecolor}{rgb}{0.000000, 0.000000, 0.000000}
+\pgfsetfillcolor{dialinecolor}
+% was here!!!
+\definecolor{dialinecolor}{rgb}{0.000000, 0.000000, 0.000000}
+\pgfsetstrokecolor{dialinecolor}
+\draw (24.216953\du,9.680847\du)--(24.241953\du,10.492678\du);
+}
+% setfont left to latex
+\definecolor{dialinecolor}{rgb}{0.000000, 0.000000, 0.000000}
+\pgfsetstrokecolor{dialinecolor}
+\node[anchor=west] at (11.445438\du,9.274332\du){$n_0$};
+% setfont left to latex
+\definecolor{dialinecolor}{rgb}{0.000000, 0.000000, 0.000000}
+\pgfsetstrokecolor{dialinecolor}
+\node[anchor=west] at (12.817938\du,9.306832\du){$n_1$};
+% setfont left to latex
+\definecolor{dialinecolor}{rgb}{0.000000, 0.000000, 0.000000}
+\pgfsetstrokecolor{dialinecolor}
+\node[anchor=west] at (14.602938\du,9.346832\du){$n_2$};
+% setfont left to latex
+\definecolor{dialinecolor}{rgb}{0.000000, 0.000000, 0.000000}
+\pgfsetstrokecolor{dialinecolor}
+\node[anchor=west] at (16.567938\du,9.306832\du){$n_3$};
+% setfont left to latex
+\definecolor{dialinecolor}{rgb}{0.000000, 0.000000, 0.000000}
+\pgfsetstrokecolor{dialinecolor}
+\node[anchor=west] at (26.967938\du,9.231832\du){$n_N$};
+% setfont left to latex
+\definecolor{dialinecolor}{rgb}{0.000000, 0.000000, 0.000000}
+\pgfsetstrokecolor{dialinecolor}
+\node[anchor=west] at (12.282938\du,10.974332\du){$h_0$};
+% setfont left to latex
+\definecolor{dialinecolor}{rgb}{0.000000, 0.000000, 0.000000}
+\pgfsetstrokecolor{dialinecolor}
+\node[anchor=west] at (13.542938\du,11.006832\du){$h_1$};
+% setfont left to latex
+\definecolor{dialinecolor}{rgb}{0.000000, 0.000000, 0.000000}
+\pgfsetstrokecolor{dialinecolor}
+\node[anchor=west] at (15.377938\du,10.971832\du){$h_2$};
+% setfont left to latex
+\definecolor{dialinecolor}{rgb}{0.000000, 0.000000, 0.000000}
+\pgfsetstrokecolor{dialinecolor}
+\node[anchor=west] at (17.017938\du,10.981832\du){$h_3$};
+% setfont left to latex
+\definecolor{dialinecolor}{rgb}{0.000000, 0.000000, 0.000000}
+\pgfsetstrokecolor{dialinecolor}
+\node[anchor=west] at (25.202938\du,11.121832\du){$h_{N-1}$};
+\end{tikzpicture}

dox/chapters/usage.tex

@@ -0,0 +1,5 @@
+\chapter{Usage}
+
+The main resource for using FEM4EllipticPDE is the Doxygen generated man pages. However, in this document 
+a more high level, simplified and incomplete, but also practical description of the API is presented for 
+those just wanting to use, and not extend the module. 

examples/magnet/toroid.geo

@@ -1,106 +0,0 @@
-/* This file is part of Lemma, a geophysical modelling and inversion API.
- * More information is available at http://lemmasoftware.org
- */
-
-/* This Source Code Form is subject to the terms of the Mozilla Public
- * License, v. 2.0. If a copy of the MPL was not distributed with this
- * file, You can obtain one at http://mozilla.org/MPL/2.0/.
- */
-
-/**
- * @file
- * @date      02/04/2016 02:58:54 PM
- * @version   $Id$
- * @author    Trevor Irons (ti)
- * @email     tirons@egi.utah.edu
- * @copyright Copyright (c) 2016, University of Utah
- * @copyright Copyright (c) 2016, Lemma Software, LLC
- */
-
-radius = 3.25;   // Radius of the damn thing
-blc = radius/2;  //  0.25;   // Target element size
-Box = 3*radius;  // The down side of potential
-lc = radius/2;        // toroid characteristic length
-
-
-tpp = newp;
-ts = 1;         // height of toroid
-tx = radius;  // radial width of toroid, measured in centre of ring
-tl = 0;         // centre of rotation
-
-Point(tpp  ) = {    tx,    0, 0,  lc};
-Point(tpp+1) = { ts+tx,    0, 0,  lc};
-Point(tpp+2) = {    tx,   ts, 0,  lc};
-Point(tpp+3) = {    tx,  -ts, 0,  lc};
-Point(tpp+4) = {-ts+tx,    0, 0,  lc};
-
-cc = newc;
-Circle(cc  ) = {tpp+1, tpp, tpp+2};
-Circle(cc+1) = {tpp+2, tpp, tpp+4};
-Circle(cc+2) = {tpp+4, tpp, tpp+3};
-Circle(cc+3) = {tpp+3, tpp, tpp+1};
-
-ll = newll;
-Line Loop(ll) = {cc, cc+1, cc+2, cc+3};
-
-ps = news;
-pio2=Pi/2;
-Plane Surface(ps) = {ll};
-tv1[] = Extrude {{0, 1, 0},{-tl,0,0}, 2*Pi/3} { Surface{ps}; };
-tv2[] = Extrude {{0, 1, 0},{-tl,0,0}, 2*Pi/3} { Surface{28}; };
-tv3[] = Extrude {{0, 1, 0},{-tl,0,0}, 2*Pi/3} { Surface{50}; };
-//t1[] = Rotate {{0,0,1},{0,0,0},pio2  } {Duplicata{Surface{ps};}};
-//Extrude Surface {ps, {0,1,0}, {-tl,0,0}, 2*Pi/3} { Recombine ;};
-//Extrude Surface {28, {0,1,0}, {-tl,0,0}, 2*Pi/3}; //{Layers{10,73,1};};
-//Extrude Surface {50, {0,1,0}, {-tl,0,0}, 2*Pi/3}; //{Layers{10,73,1};};
-
-/* Make a list of a ring (annulus) of surfaces around the hole */
-//allParts[] = {tv1[1], tv2[1], tv3[1]};
-
-/* Make surfaces to be meshed by transfinite algorithm */
-//Transfinite Surface {allParts[]};
-
-/* The "Recombine Surface" command is issued in order to
- * crate quadrilateral elements.
- */
-//Recombine Surface {allParts[]};
-
-// Extrude Surface {12, {0,0,1}, {0,0,0}, 2*Pi/3} {
-//   Recombine ; Layers { 6, 54, 1 } ;
-// } ;
-
-// Total Solution Space
-X0 = -Box;
-X1 =  Box;
-Y0 = -Box;
-Y1 =  Box;
-Z0 = -Box;
-Z1 =  Box;
-/////////////////////////////////////
-// Large Bounding box
-pp = newp;
-Point(pp)    = {X0, Y0, Z0, blc};
-Point(pp+1)  = {X1, Y0, Z0, blc};
-Point(pp+2)  = {X1, Y1, Z0, blc};
-Point(pp+3)  = {X0, Y1, Z0, blc};
-//
-lv = newl;
-Line(lv) = {pp,pp+1};
-Line(lv+1) = {pp+1,pp+2};
-Line(lv+2) = {pp+2,pp+3};
-Line(lv+3) = {pp+3,pp};
-Line Loop(lv+4) = {lv, lv+1, lv+2, lv+3};
-//
-// Hard coded doom
-bs = news;
-Plane Surface(bs) = {lv+4};
-//
-//v = newv;
-v[] = Extrude {0, 0, Z1-Z0} { Surface{bs}; };
-
-/* This is GOOD */
-//Surface{ allParts[1] } In Volume{v[1]};
-Surface{ ps } In Volume{v[1]};
-//Surface{t1[0]} In Volume{v[1]};
-//Surface{t2[0]} In Volume{v[1]};
-//Surface{t3[0]} In Volume{v[1]};