pbtoast / polytope

A library for generating Voronoi and Voronoi-like tessellations for computational domains with nontrivial boundaries.

Polytope

Copyright (c) 2013, Lawrence Livermore National Security, LLC. Produced at the Lawrence Livermore National Laboratory Written by Mike Owen, David Starinshak, and Jeffrey Johnson. LLNL-CODE-647432 All rights reserved.

Polytope is a C++ library for generating polygonal and polyhedral meshes. It makes use of various 2D and 3D tessellation techniques, but provides a single representation for these tessellations, and a simple interface for generating them.

Polytope has a simple C interface for use with other languages. It also includes bindings for Python. These bindings allow you to easily incorporate Polytope into your own mesh generation tools.

Installation

Polytope works on most Linux and Mac systems.

Software Requirements

• A C++11 compiler (and a C compiler if you want the C interface).
• MPI for parallelism
• The Bourne Again SHell (bash), for bootstrapping
• CMake 3.1+, for configuring and generating build files
• GNU Make or Ninja, for performing the actual build

If you want to build Python bindings, you also need the following:

• A Python 2 interpreter
• pybind11, a Python/C++11 interoperability layer
• PYB11Generator, a code generator that processes binding definitions in Python. PYB11Generator produces C++ code that uses pybind11 to expose your C++ classes as Python classes.

Building

To build polytope on a UNIX-like system, change to your polytope source directory and type the following:

./bootstrap build_dir

where build_dir is the directory in which you want to build.

Then just follow the onscreen directions: you change to that build directory, edit config.sh to define your build, run it with sh config.sh, and start the build using your generator's build process. For the default generator (UNIX makefiles), this is just make. For Ninja (recommended if you have it), it's ninja.

Installing

To install polytope, use the install command for the generator you've selected. For example, if you're using a generator that writes UNIX makefiles, run

make install [-j #threads]

from your build directory.

Other Targets

These targets all work with Make and Ninja.

• test - Runs all unit tests for the library. Use ctest -j #threads instead, though, to run the tests in parallel.
• clean - Removes all build assets but retains configuration options.
• distclean - Performs clean and completely removes the build directory.

Other Considerations

Polytope provides interfaces for a number of geometry-related tools:

• Voro++ by Chris Rycroft (now at Harvard)
• Triangle by Jonathan Shewchuk at Berkeley
• Tetgen by Hang Si at Weierstrass Institute for Applied Analysis and Stochastics
• Boost.Polygon.Voronoi, part of the Boost C++ Library

Using Triangle and Tetgen

It's easy to use Triangle and Tetgen to generate tessellations. There's only one complication: you must comply with the licenses for these tools. Briefly, this means that if you want to use Triangle or Tetgen in a commercial application, you must contact the author for permission.

To keep things simple, we don't distribute the source for either of these tools. Once you've made arrangements to comply with the license(s), you can copy the source for the tool(s) into place:

• For Triangle, copy triangle.h and triangle.c to the src directory.
• For Tetgen, copy tetgen.h and tetgen.cxx to the src directory.

Then (re)configure and build.

polytope's Issues

A continuous integration (CI) system would be nice.

We could use Travis CI (https://travis-ci.org) to set up automated builds/tests when we submit pull requests. This would give us a lot more confidence that things are working.

Configuration to not build tests broken?

Setting "TESTING=OFF" in the generated "build.sh" does not seem to prevent polytope from building the tests anyway. Am I misunderstanding how to use this, or is this a bug?

cmake looks for non-existent files triangle.h, triangle.c, tetgen.h, tetgen.cxx in its source directory

here and here

Since these files are not there - HAVE_TRIANGLE and HAVE_TETGEN are always OFF.

Too many C++ warnings

I'm seeing tons of warnings in various source files during the build. It would be nice to get rid of these.

Python bindings need finishing.

Looks like there's still some work remaining in updating the Python bindings for polytope. The changes in #2 add support for discovering the binding definitions and generating the target source file dependencies, but there's probably a bit of additional work.

Support C++17

C++17 removes std::bind2nd from the std library. It's easy to replace the two instances of it in src/MeshEditor.cc.

Original code:
replace_if(mNodeMask.begin(), mNodeMask.end(), bind2nd(equal_to<unsigned>(), 2), 1);

New code:
replace_if(mNodeMask.begin(), mNodeMask.end(), [] (unsigned val) { return val == 2; }, 1);

Versions of Boost > 1.55 cause failures in tessellation(?)

Reading the INSTALL, I found a note about how newer versions of Boost "cause polytope to fail". Is this still an issue?

Unit tests aren't all passing.

We have some work in flight, and are still reviving polytope, so this is understandable. But when we start using Travis CI to vet pull requests, we need all of our tests to pass. This issue represents that goal.

CMake config/build system needs some love

It's been a while since we put together polytope's build and configuration system, and the rules have changed a bit since.

• A lot of the CMakeLists.txt files need small improvements and cleanup.
• I'd like to move to a new model that uses a bootstrap script to let you pick a build tree explicitly, and then go there to invoke your builds.

Polytope needs to migrate from Python 2 to Python 3

Python 3 has been around long enough, and now does everything Python 2 does, and more. With support for Python 2 ending in the near future, we should move to Python 3.

Unit tests take a little too long.

Right now some of the tests take upwards of 10 minutes on the hardware we're using. It would be good to get that time down to below a minute if at all possible.

In particular:

• test_UnitSquare takes over 5 minutes on our CI hardware.
• test_RandomPoints takes almost 13 minutes(!)

Test test_hash fails: Unhash position too far : 15.2568

 8/28 Test  #8: test_hash ........................***Failed  Required regular expression not found. Regex=[PASS
]  0.01 sec
2D random hash test, doubles, fine tolerance.
FAIL: (geometry::distance<Dimension, RealType>(&coords[Dimension*i], pos) <= tol)
Unhash position too far : 15.2568

clang-14
FreeBSD 13.1