#+OPTIONS: toc:2   
* About =ngsxfem= 
=ngsxfem= is an Add-on library to Netgen/NGSolve which enables the use of unfitted finite element technologies known as XFEM, CutFEM, TraceFEM, Finite Cell, ... .
=ngsxfem= is an academic software. Its primary intention is to facilitate the development and validation of new numerical methods.

** The main features
*** Numerical integration on implicitly described (via a level set function) geometries which are not fitted to the mesh
Given a level set function \phi which describes the geometry (e.g. \Omega = { \phi < 0 }) a piecewise linear approximation is made. On simplices (triangles and tetrahedra) this gives a planar intersection on every element which allows for an explicit decomposition into simple geometries.
On these simple (uncut) geometries standard quadrature rules of arbitrary order can be applied which results in quadrature rules for the (approximated) subdomains where the level set is positive/negative/zero.
#+html: <p align="center"><img src="doc/graphics/cuttet.jpg" height="175"/><img src="doc/graphics/intpoints.jpg" height="175"/></p>

*** Tools to work on an "active mesh" only
In unfitted finite element methods some functions and integrals are only defined on a subset of the mesh. Accordingly finite element spaces and integrals have to be defined only on this active mesh. 
=ngsxfem= offers the tools to mark the corresponding elements and facets and use the marking during assembly and definition of finite element spaces. On cut elements one often also uses locally modified finite elements, e.g. by restriction of finite elements on the background mesh.
#+html: <p align="center"><img src="doc/graphics/unfittedmesh.jpg" height="175"/> <img src="doc/graphics/xfem.jpg" height="175"/></p> 

*** Higher order representation of implicit level-set geometries 
To obtain higher order accuracy, we offer a mesh transformation technique in the spirit of isoparametric finite element methods. Thereby the piecewise linear approximation (which is only of second order) is mapped onto a higher order accurate approximation of the true geometry.
#+attr_html: :width 175px
#+html: <p align="center"><img src="doc/graphics/lsetcurv.jpg" height="175"/></p>

*** Space-Time Finite Elements for the treatment of moving domain problems
To obtain robust method for PDEs on unfitted moving domain we can formulate space-time discretization. =ngsxfem= provides necessary tools (so far only in two space dimensions) to define space-time finite element spaces and to integrate on space-time domains. Further, it extends the tools for higher order accurate geometry handling to the space-time setting.
#+html: <p align="center"><img src="doc/graphics/spacetime1.png" height="175"/><img src="doc/graphics/spacetime2.png" height="175"/></p> 

** Applications
This section is to be added soon ...

* Installation
** Linux Build Steps
You require Netgen/NGSolve to run and build the xfem module (=ngsxfem=). 
You can either install it before hand (default option) 
or let Netgen/NGSolve be installed as an external dependency. 
#+BEGIN_SRC shell
git clone https://github.com/ngsxfem/ngsxfem.git
cd ngsxfem
mkdir build
cd build
#+END_SRC

*** Building xfem with pre-installed NGSolve 
You have Netgen/NGSolve installed? Perfect. Then let INSTLOCATION be the location 
Netgen/NGSolve is already installed to. To install xfem make sure that you have 
write access to that same directory. Then build =ngsxfem= with 
#+BEGIN_SRC shell
cmake ../ -DCMAKE_INSTALL_PREFIX=INSTLOCATION -DBUILD_NGSOLVE=OFF
make
make install
#+END_SRC

**** Prerequisites on Ubuntu
On Ubuntu you require =python3-dev= to build =ngsxfem= (and similar dependencies as NGSolve has, cf. [[www.ngsolve.org]])

**** Fix of potential issues
If you have compiling problems or at run time some NGSolve symbols are not found, it may be (happened in some configurations) that the NGSolve compiler and linker wrapper =ngscxx= and =ngsld= were not used. In this case you may add
#+BEGIN_SRC shell
cmake ... -DCMAKE_CXX_COMPILER=ngscxx -DCMAKE_LINKER=ngsld
#+END_SRC
to the cmake configuration.

**** =ngsxfem= on MacOSX
On MacOSX, you need to add the location of the NGSolve cmake configuration files, i.e.:
#+BEGIN_SRC shell
cmake \
-DCMAKE_INSTALL_PREFIX=NGSOLVE_INSTALLATION_LOCATION \
-DNGSolve_DIR=NGSOLVE_INSTALLATION_LOCATION/Contents/Resources/CMake \
-DBUILD_NGSOLVE=OFF \
..
#+END_SRC
If NGSolve is installed from the dmg-file =NGSOLVE_INSTALLATION_LOCATION= is =/Applications/Netgen.app=.
*** Building the NGS-Suite and =ngsxfem= together 
If you do not have Netgen/NGSolve installed, you may first call
#+BEGIN_SRC shell
git submodule update --init
#+END_SRC
which pulls Netgen/NGSolve as external dependencies. Then, just call
#+BEGIN_SRC shell
cmake ../ -DCMAKE_INSTALL_PREFIX=INSTLOCATION -DBUILD_NGSOLVE=ON
make
make install
#+END_SRC
For INSTLOCATION you choose a nice installation location.
Afterwards make sure that the installed NGS/xfem-libraries and executable will be found 
by PATH and python.

** Updating =ngsxfem=
To update =ngsxfem=, update the sources
#+BEGIN_SRC shell
git pull origin master
#+END_SRC
As the ngsolve-version that the updated xfem-version depends on can be updated in the mean time, 
make sure to update NGSolve. 
If you build NGSolve as an external dependency update the submodule NGSolve:
#+BEGIN_SRC shell
git submodule update --init --recursive
#+END_SRC
Otherwise update your NGSolve version manually. 
As a rule we try to be compatible to the latest release of NGSolve. 
To be sure check the version in external_dependencies/ngsolve


** Examples
To run the python examples be sure to follow the build steps above.
Then navigate into the =py_tutorials= and run
#+BEGIN_SRC shell
netgen example.py
#+END_SRC
where =example.py= stands for any of the available python files.

** Testing
Tests are enabled by default.
To run the test navigate to the build directory and run =make test=
or =ctest=.
If you need to see specific tests failing use =ctest -V=.
To run individual tests use =ctest -R <regex>=. E.g. =ctest -R cutint= to only run cut integration tests.
Note that we use pytest (with python version > 3). 

** pde vs. py files
From version 1.0.0 on there are no pde-files used in this project anymore. 
Only python-files are used.

* Examples 
At [[https://github.com/ngsxfem/ngsxfem-jupyter]] you can find tutorial-style jupyter notebooks for ngsxfem.
Further, in =py_tutorials/= there are some simple examples for some known unfitted discretizations:
 * =py_tutorials/cutfem.py= : stationary interface problem with a (P1) CutFEM method with Nitsche
 * =py_tutorials/nxfem.py= : stationary interface problem with a (P1) XFEM method with Nitsche (similar to =cutfem.py=)
 * =py_tutorials/nxfem_higher_order.py= : stationary interface problem with a higher order isoparametric unfitted FEM with Nitsche (similar to =nxfem.py=)
 * =py_tutorials/fictdom_ghostpen.py= : stationary fictitious domain problem with isoparametric CutFEM, Nitsche and ghost penalty stabilization
 * =py_tutorials/fictdom_dg_ghostpen.py= : stationary fictitious domain problem with isoparametric Cut-DG-FEM, Nitsche and ghost penalty stabilization
 * =py_tutorials/stokesxfem.py= : stationary Stokes interface problem with an isoparametric (P2X/P1X) Taylor-Hood-Nitsche-XFEM discretization
 * =py_tutorials/tracefem.py= : stationary 2D surface PDE problem with a TraceFEM discretization (low order)
 * =py_tutorials/tracefem3d.py= : stationary 3D surface PDE problem with a TraceFEM discretization (higher order)
 * =spacetime/py_tutorials/spacetimeP1P1.py= : moving fictitous domain problem using a space time unfitted FEM


* Literature
=ngsxfem= has been used in the following scientific articles (that we are aware of):
 * T. Jankuhn, A. Reusken. Higher order Trace Finite Element Methods for the Surface Stokes Equation [[https://arxiv.org/pdf/1909.08327][pdf]] 
 * T. Jankuhn, A. Reusken. Trace Finite Element Methods for Surface Vector-Laplace Equations [[https://arxiv.org/pdf/1904.12494][pdf]] 
 * E. N. Karatzas, F. Ballarin, G. Rozza. Projection-based reduced order models for a cut finite element method in parametrized domains [[https://arxiv.org/pdf/1901.03846][pdf]] 
 * C. Lehrenfeld, M. A. Olshanskii. An Eulerian finite element method for PDEs in time-dependent domains [[https://arxiv.org/pdf/1803.01779.pdf][pdf]]
 * F. Heimann, C. Lehrenfeld. Numerical integration on hyperrectangles in isoparametric unfitted finite elements. [[https://link.springer.com/chapter/10.1007/978-3-319-96415-7_16][link]]
 * C. Lehrenfeld, A. Reusken. L2-estimates for a high order unfitted finite element method for elliptic interface problems. [[https://www.degruyter.com/view/j/jnma.just-accepted/jnma-2017-0109/jnma-2017-0109.xml?format=INT][http]]
 * J. Grande, C. Lehrenfeld, A. Reusken. Analysis of a high-order trace finite element method for PDEs on level set surfaces [[http://epubs.siam.org/doi/abs/10.1137/16M1102203][http]]
 * C. Lehrenfeld, A. Reusken. Analysis of a high order unfitted finite element method for an elliptic interface problem. [[https://academic.oup.com/imajna/article-abstract/doi/10.1093/imanum/drx041/4084723/Analysis-of-a-highorder-unfitted-finite-element][http]]
 * C. Lehrenfeld, A. Reusken. Optimal preconditioners for Nitsche-XFEM discretizations of interface problems. [[https://link.springer.com/article/10.1007/s00211-016-0801-6][http]]
 * C. Lehrenfeld. High order unfitted finite element methods on level set domains using isoparametric mappings. [[http://www.sciencedirect.com/science/article/pii/S0045782515004004][http]]
 * C. Lehrenfeld. A higher order isoparametric fictitious domain method for level set domains. [[https://link.springer.com/chapter/10.1007/978-3-319-71431-8_3][http]]
 * P. Lederer, C.-M. Pfeiler, C. Wintersteiger, C. Lehrenfeld. Higher order unfitted FEM for Stokes interface problems. [[https://onlinelibrary.wiley.com/doi/abs/10.1002/pamm.201610003][http]]
 * C. Lehrenfeld. Removing the stabilization parameter in fitted and unfitted symmetric Nitsche formulations. [[https://www.eccomas2016.org/proceedings/pdf/4573.pdf][http]]