[![GitHub Workflow Status](https://img.shields.io/github/workflow/status/ngsxfem/ngsxfem/Build,%20test%20(and%20publish%20release)%20of%20ngsxfem?label=build%20and%20test&logo=github)](https://github.com/ngsxfem/ngsxfem/actions/workflows/build-and-test-ngsxfem.yml) 
 [![GitHub release (latest by date)](https://img.shields.io/github/v/release/ngsxfem/ngsxfem?label=latest%20release&logo=github)](https://github.com/ngsxfem/ngsxfem) 
[![jossstatus](https://joss.theoj.org/papers/9fda1eadfc58af64b89dc7f27043f4cb/status.svg)](https://joss.theoj.org/papers/9fda1eadfc58af64b89dc7f27043f4cb)

 

[![PyPI](https://img.shields.io/pypi/v/xfem?color=blue&label=latest%20PyPI%20version&logo=pypi&logoColor=white)](https://pypi.org/project/xfem/)
[![PyPI - Implementation](https://img.shields.io/pypi/implementation/xfem?logo=pypi&logoColor=white)](https://pypi.org/project/xfem/)
[![PyPI - Downloads](https://img.shields.io/pypi/dm/xfem?color=green&label=PyPI%20downloads&logo=pypi&logoColor=white)](https://pypi.org/project/xfem/)

[![docker build](https://img.shields.io/docker/cloud/build/ngsxfem/ngsxfem?logo=docker&logoColor=white)](https://hub.docker.com/repository/docker/ngsxfem/ngsxfem) 
[![Docker Pulls](https://img.shields.io/docker/pulls/ngsxfem/ngsxfem?logo=docker&logoColor=white)](https://hub.docker.com/repository/docker/ngsxfem/ngsxfem) 
[![badge](https://img.shields.io/badge/launch-jupyter--tutorials-579ACA.svg?logo=data:image/png;base64, )](https://mybinder.org/v2/gh/ngsxfem/ngsxfem-jupyter/v2.0.2105?filepath=tutorials.ipynb)

# About `ngsxfem`

`ngsxfem` is an add-on library to the finite element package [`Netgen`/`NGSolve`](https://ngsolve.org) 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 for partial differential equations.

# The features of `ngsxfem`

The main features of `ngsxfem` are:

* Tools to work on an a subset of the triangulation, the \"active mesh\" only

* Numerical integration on geometries that are (implicitly) described through level set functions.

* Higher order representation of level set geometries

* Space-Time Finite Elements for the treatment of moving domain problems

* All these features combined with the usual flexibility and power of [NGSolve](https://ngsolve.org).

`ngsxfem` has been used in a variety of applications. In the document [doc/feature-details.md](doc/feature-details.md) (see also [`compiled pdf`](https://nightly.link/ngsxfem/ngsxfem/workflows/extras-workflow/master/doc-features.zip) ) more details on the features is given and in [doc/literature.md](doc/literature.md) (see also [`literature`](https://nightly.link/ngsxfem/ngsxfem/workflows/extras-workflow/master/doc-literature.zip) ) an overview of the scientific literature where `ngsxfem` is used is provided.

Not all features of `ngsxfem` and `NGSolve` can directly be combined. Here is an overview of `ngsxfem` and `NGSolve` features and if they can directly be combined:
| Features ⇲| `CFE` | `XFE` | `DGF` | `Iso` | `MLS` | `STF` | `GhP` | `Hex` | `Tet` | `MPI` |
|-|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|
| `CFE`: CutFEM form. | / | / | yes | yes | yes | yes | yes | yes | yes | yes |
| `XFE`: XFEM formulation | / | / | yes | yes | no | no | yes | yes | yes | yes |
| `DGF`: Discont. Galerkin  | yes | yes | / | yes | no | no | yes | no | yes | no |
| `Iso`: isoparametric map | yes | yes | yes | / | no | yes | yes | yes | yes | yes |
| `MLS`: multiple level set | yes | no | no | no | / | no | yes | no | yes | yes |
| `STF`: space-time FEM | yes | no | no | yes | no | / | yes | yes | yes | yes |
| `GhP`: Ghost penalty | yes | yes | yes | yes | yes | yes | / | yes | yes | no |
| `Hex`: quads / hexes | yes | yes | no | yes | no | yes | yes | / | / | yes |
| `Tet`: trigs./tets | yes | yes | yes | yes | yes | yes | yes | / | / | yes |
| `MPI`: MPI | yes | yes | no | yes | yes | yes | no | yes | yes | / |

Some of the *no*s are work in progress (e.g. `MLS`&`STF`) and some have not been considered so far (e.g. `DGF`&`STF`). If you need a certain combination to work, please contact us and we will see what we can do. 

# Examples and Documentation

We provide two main sources with which to learn how to use `ngsxfem`:
 * At <https://github.com/ngsxfem/ngsxfem-jupyter> you can find tutorial-style jupyter notebooks for `ngsxfem`. These explain the core functionalities and usage of the tools provided by `ngsxfem`. You can run those tutorials interactively (without the need of a local installation) through binder. 
 * in the [`demos`](./demos)-directory we provide several examples that demonstrate the usage of `ngsxfem` features. See [`demos/README.md`](demos/README.md) for details.

 # Installation
 We provide installation instructions for building/installing through `pip` and building/installing from sources in [`INSTALLATION.md`](INSTALLATION.md). Further, [a docker image](https://hub.docker.com/r/ngsxfem/ngsxfem) is available which can be used to run `ngsxfem` through docker.

# List of contributing authors (with major contributions)

-   Christoph Lehrenfeld (main author)
-   Fabian Heimann (cut integration, space-time)
-   Thomas Ludescher (multigrid)
-   Janosch Preuss (space-time)
-   Henry von Wahl (multiple levelsets)

# Community guidelines
If you observe any problems with the software / examples / documentation / installation or want to contribute, you can get in touch with us through either:
 * the [github issue tracker](https://github.com/ngsxfem/ngsxfem/issues) 
 * the [`NGSolve` user forum](https://ngsolve.org/forum/index).


# Citing

If you use `ngsxfem` for academic work, please consider citing our publication:

```
C. Lehrenfeld, F. Heimann, J. Preuß and H. von Wahl
ngsxfem: Add-on to NGSolve for geometrically unfitted finite element discretizations
Journal of Open Source Software, 6(64), 3237,
https://doi.org/10.21105/joss.03237
```

