Level Set Method Library (LSMLIB)

Announcement

(May 2022) LSMLIB v2.0.x is intended to be a stable version of LSMLIB that can serve as a foundation for specialized applications and packages. The library has been refactored and only includes support for serial computations implemented in C/C++ (the parallel LSMLIB and Python interfaces have been moved to their own separate codebases and repositories). There are currently no plans to further develop LSMLIB parallel LSMLIB or the Python interface.

Overview

1.1. Package Contents

1.2. Software Dependencies

1.3. License
Installation

2.1. Building the Package

2.2. Running Tests

2.3. Installing the Package

2.4. Uninstalling the Package
Known Issues
Acknowledgments

1. Overview

The Level Set Method Library (LSMLIB) provides support for simulation of implicit surface and curve dynamics in two- and three-dimensions. It contains an implementation of the basic level set method algorithms and numerical kernels described in "Level Set Methods and Dynamics Implicit Surfaces" by S. Osher and R. Fedkiw and "Level Set Methods and Fast Marching Methods" by J.A. Sethian. It also contains implementations of several advanced level set method techniques available in the literature.

The library consists of a collection of Fortran subroutines and C/C++ functions. The main features of the library include:

high-computational and high-programmer performance through the use of mixed-language programming (e.g. C++/Fortran77, C/Fortran77);
support for narrow-band/localized computation.

1.1. Package Contents

LSMLIB contains a collection of numerical kernels that are commonly used in level set method calculations. It currently provides numerical kernels for the following:

computation of spatial derivatives using high-order ENO/WENO schemes
TVD Runge-Kutta time integration schemes
imposing boundary conditions
computation of a variety of geometric quantities (e.g. normal, area/volume, curvature, etc.)
integration over regions defined by implicit functions
computing the right-hand side of specific level set method partial differential equations;
localization/narrow-band calculations
fast marching method calculations (e.g. signed distance function, solution to Eikonal equation); and
mathematical functions (e.g. delta functions, norms, etc.).

In addition, LSMLIB provides several utility functions for

managing of computational grids and data,
initializing level set functions for simple geometries,
imposing boundary conditions,
computing signed distance functions and extension fields via the fast marching method,
carrying out common data manipulations (e.g. copying data, computing the norm of a grid function).

1.2. Software Dependencies

Compilers: C, C++, Fortran

1.3. License

See the LICENSE file for copyright and license information.

2. Installation

2.1. Building the Package

Create a build directory, and change into it.
```
$ mkdir build
$ cd build
```
Generate the build files.
```
$ cmake ..
```
Build the package.
```
$ make
```

2.2. Running Tests

From the build directory, use make tests to build the unit tests.
```
$ make tests
```
From the build directory, use ctest or make test to run the unit tests.
```
$ ctest
```
For a more detailed test report, use ctest --verbose.
```
$ ctest --verbose
```

2.3. Installing the Package

Set the installation location for the package.
```
$ cd build
$ cmake -DCMAKE_INSTALL_PREFIX=/PATH/TO/INSTALL/LOCATION ..
```
Note: the -DCMAKE_INSTALL_PREFIX option could have been included in the command used when generating the build files.
Use make install to install the package.
```
$ make install
```
(OPTIONAL) Remove the build directory.

2.4. Uninstalling the Package

To uninstall the package, use make uninstall from within the build directory.
```
$ cd build
$ make uninstall
```

3. Known Issues

Several of the numerical kernels lack unit tests.
The package only supports one-, two-, and three-dimensional calculations.
Adapative mesh refinement is not yet available.
Computation of the maximum stable time step is incorrect for problems involving both advection and motion in the normal direction.
There are a few warnings that show up when using strict compilers (e.g. Intel Compilers). These are primarily a result of not explicitly dealing with return values from standard C library functions and do not lead to any numerical inaccuracies.
We do not officially support Windows at this time.

4. Acknowledgments

The LSMLIB developers gratefully acknowledge support from the following funding agencies:

Department of Energy under contract numbers DE-FG02-97ER25308 (Computational Science Graduate Fellowship) and DE-FC26-06NT43067
Department of Agriculture under grant #2007-35102-18162
National Science Foundation
Air Force Office of Scientific Research

We would also like to thank the following individuals:

Professor David J. Srolovitz (Yeshiva University) and Professor Steven L. Bryant (University of Texas at Austin) - support and encouragement in developing LSMLIB
Zhaoxuan Wu - original autoconf system for building LSMLIB
Xiaohai Wan, Thomas Pintelon, and Ning Zhang - documentation for building LSMLIB on Windows
Contributing Users/Bug Reporters: Daniel Thorpe, Markus Gross, Anatoliy Kats, Yi Li, Guillaume Walck and his students, Burak Ozkalayci, Zhang Ning, Stefan Sokoll, Moslem Kazemi, Danping Zou, Marc Day, and Ruhollah Tavakoli.
Our humblest apologies if we have accidentally left anybody off of this list. Please let us know and we will remedy the situation immediately.

Second order issue with `KNOWN` and `TRIAL` values

This seems to be an issue with both LSMLIB and Scikit-fmm. The following test fails with LSMLIB, but passes (by luck) in Scikit-fmm.

>>> from skfmm import distance
>>> phi = distance([[-1, -1, -1, -1],
                 [ 1,  1, -1, -1],
                 [ 1,  1, -1, -1],
                 [ 1,  1, -1, -1]], order=2)
>>> print distance(phi, order=2)
[[-0.5        -0.58578644 -1.08578644 -1.85136395]
 [ 0.5         0.29289322 -0.58578644 -1.54389939]
 [ 1.30473785  0.5        -0.5        -1.5       ]
 [ 1.49547948  0.5        -0.5        -1.5       ]]

One gets a different answer with LSMLIB

 >>> from pylsmlib import distance
 >>> phi = distance([[-1, -1, -1, -1],
 ...           [ 1,  1, -1, -1],
 ...           [ 1,  1, -1, -1],
 ...           [ 1,  1, -1, -1]], order=2)
 >>> print distance(phi, order=2)
[[-0.5        -0.58578644 -1.08578644 -1.85170563]
 [ 0.5         0.29289322 -0.58578644 -1.54468054]
 [ 1.30473785  0.5        -0.5        -1.5       ]
 [ 1.49547948  0.5        -0.5        -1.5       ]]

The issue is that newly created KNOWN values only update their closest neighbour's values. For second order schemes newly created KNOWN values need to update all values in the stencil. That is cells that are two steps away with a KNOWN value between.

Toy Problem

Take three cells lieing in a larger 2D array of cells. Say that 0.5 is the smallest value in the TRIAL cells

| TRIAL 0.5 | TRIAL 0.5 | TRIAL 0.51 |

One of the two values becomes updated to KNOWN, but that now information happens to lower the value of the left side cell.

| TRIAL 0.405 | KNOWN 0.5 | TRIAL 0.505 |

The left cell then becomes KNOWN

| KNOWN 0.405 | KNOWN 0.5 | TRIAL 0.505 |

TRIAL 0.51 is not reupdated when the left cell becomes KNOWN although the value is required for second order accuracy.

| KNOWN 0.405 | KNOWN 0.5 | KNOWN 0.505|

velexi-research / lsmlib Goto Github PK

lsmlib's Introduction

Level Set Method Library (LSMLIB)

Announcement

Table of Contents

1. Overview

1.1. Package Contents

1.2. Software Dependencies

1.3. License

2. Installation

2.1. Building the Package

2.2. Running Tests

2.3. Installing the Package

2.4. Uninstalling the Package

3. Known Issues

4. Acknowledgments

lsmlib's People

Contributors

Stargazers

Watchers

Forkers

lsmlib's Issues

Toy Problem

Recommend Projects

Recommend Topics

Recommend Org