Skip to content

Latest commit

 

History

History
191 lines (139 loc) · 6.16 KB

README.md

File metadata and controls

191 lines (139 loc) · 6.16 KB
Raw

LibSLSM

Copyright © 2015-2017 Lester Hedges

Build Status

About

LibSLSM is a small C++ library that forms an accompaniment to the paper Stochastic level-set method for shape optimisation. The library provides a simple set of building blocks for implementing the method. Various example codes illustrate how to make make use of the library and reproduce the data in the paper.

Unlike traditional level-set optimisation methods, which use a steepest descent approach, SLSM updates the level set using a stochastic differential equation. The addition of thermal noise enables the exploration of design space during the optimisation process. In situations where the objective function is non-convex, this allows for the possibility of escaping local minima and converging to the true global optimum. See the paper for further details.

Using the Code

LibSLSM is intended to be used on a Unix-like operating system and has been extensively tested on macOS (formerly OS X) and Linux. Windows users are advised to use the Ubuntu Bash shell on WIndows 10, or MinGW to build LibSLSM. For modern, 64-bit Windows systems, we recommend using MYSYS2. This has been used to successfully build LibSLSM on Windows 7 and 10. After installing MYSYS2 (following the instructions on the website) you will need to install several additional packages:

pacman -S cmake gcc git make python3
  • Clone the LibSLSM source via:

Downloading

git clone --recursive https://github.com/lohedges/slsm.git

(Alternatively, a zip file can be downloaded from here. Note, however, that you'll need to download the submodules separately.)

Compiling and Installing

  • Change to the newly created slsm directory:
cd slsm
  • Create a fresh build directory:
mkdir build
cd build

(This is recommended, although in source builds are allowed.)

  • Configure, build, and install:
cmake .. && make -j4 install

(Here we use four cores for the build. If you have a lot of cores, try make -j${nproc}.)

On macOS you may wish to use LLVM's libc++ rather than libstdc++. If so, build as follows (this assumes a fresh build, or a clear cache):

CXXFLAGS=-stdlib=libc++ cmake .. && make -j4 install

By default, the library installs to /usr/local. Therefore, you may need admin privileges for the final make install step above. An alternative is to change the install location:

cmake -DCMAKE_INSTALL_PREFIX:PATH=MY_INSTALL_DIR .. && make -j4 install

(Note that there is no need to install the library in order to use it. You can always build locally and link against the library using whatever path is appropriate.)

Linking with C/C++

To use LibSLSM with a C/C++ code first include the library header file in the code:

//example.cpp
#include <slsm/slsm.h>

Then to compile, we can use something like the following:

g++ -std=c++11 example.cpp -lslsm -lnlopt

This assumes that we have used the default install location /usr/local/. If we specify an install location, we would use a command more like the following:

g++ -std=c++11 example.cpp -I/my/path/include -L/my/path/lib -lslsm -lnlopt

Note that the -std=c++11 compiler flag is needed for std::function and std::random.

External Dependencies

To aid portability, dependencies are handled via git submodlules. If you are using LibSLSM for the first time, and didn't clone using the --recursive flag, then you'll need to initialise the submodules:

git submodule update --init --recursive

Existing submodules can be updated using:

git submodule update --recursive

Brief details of the submodules are given below:

  • The Optimise class makes use of NLopt.

  • Python bindings are generated using pybind11. See here for details about using the Python module, pyslsm.

Documentation

Source code

Comprehensive documentation is provided via Doxygen. Make sure you also have working Graphviz (for DOT) and Tex Live (for LaTeX) installations. To generate the documentation, run:

make doc

Following this, point your web browser to doc/html/index.html.

Class Structure

For an overview of the class structure and details on how to instantiate and use objects, see:

Tests

To learn how to compile and run unit tests, see:

Examples

To get a feel for the how to write code using the library, see the demonstration programs:

A set of utility scripts are provided for processing the output data:

Python

Full Python bindings are generated using pybind11. For more details, and to learn more about the Python extension module pyslsm, see:

Acknowledgements

  • Parts of this library were based on code written by Peter Dunning.

  • The Fast Marching Method implementation was adapted from Scikit-FMM.

Disclaimer

Please be aware that this a working repository so the code should be used at your own risk.

It would be great to hear from you if this code was of use in your research. Email bugs, comments, and suggestions to [email protected].