Portage is a framework for building a highly customized, hybrid parallel (MPI+X) remapping library for the transfer of field data between meshes or particle swarms in computational physics applications.
Application developers can:
- use one of the included drivers with a mix of available and custom components to readily deploy a powerful remapping capability into their application, or
- write a custom remapping driver and use it with a mix of available and custom components to create a remapping capability uniquely tailored to their application needs.
The drivers furnished with Portage provide:
- conservative remapping of multi-material fields between general polygonal/polyhedral meshes.
- higher-order, non-conservative interpolation between particle swarms as well as between meshes and particle swarms.
- a modern design templated on the major components - mix and match from the furnished suite or use a custom component.
- direct (no-copy) use of client application's native mesh/particle and field data structures whenever possible (see distributed remap).
- built-in distributed and on-node parallelism even with custom components (see scaling results).
They also have the following known limitations:
- Only remapping of scalar fields is supported; vectors and tensors must be remapped component by component.
- Multi-material remap is not yet supported for distributed meshes.
- Conservative remapping of compound quantities such as momentum is not supported when they are not the primary fields.
- Field fixup in the presence of mismatched mesh boundaries is not implemented for multi-material fields.
- Remapping involving particles is currently non-conservative.
See the Concepts page for a high-level discussion of the methods used within Portage.
See the Example Use page for a simple example of hooking Portage up to a mesh and state manager.
Requirements
At a minimum, Portage requires:
- A C++-11 compatible compiler; regular testing is performed with GCC 6.3+ and Intel 17+.
- CMake 3.8+
- LAPACKE 3.8.0+
- Boost 1.68.0+ or Thrust 1.8.1+
Portage depends on the Wonton library to provide mesh/state wrapper interfaces and some common defintions and functionality. Portage is known to work with Wonton mesh/state wrappers for version 1.0.0 of the Jali and #e78c594 of flecsi-sp (along with #374b56b of FleCSI).
The supplied mesh-mesh remap driver of Portage also requires the use of the R3D library for intersection of polyhedra.
Distributed parallelism of Portage is currently supported through MPI; regular testing is performed with OpenMPI 1.10.3+ . Most application tests and all of the units tests are currently only built if MPI is used. MPI is enabled in Portage by setting the CMake variable ENABLE_MPI=True.
On-node parallelism is enabled through the Thrust library. The default on-node parallelism mechanism is OpenMP (YMMV for TBB, no support yet for CUDA). Regular testing happens with Thrust 1.8. If you turn on Thrust for multi-threading-enabled executables, the team strongly recommends linking to the TCMalloc library available in Google Performance Tools to see the expected scaling.
Multi-material remapping requires use of the Tangram library for interface reconstruction and optionally, the XMOF2D library. Portage has been tested with version 0.9.1 of both Tangram and the X-MOF library.
Downloading
The latest release of Portage lives on GitHub. Portage makes use of git submodules, so it must be cloned recursively:
Building
Portage uses the CMake build system. In the simplest case where you want to build a serial version of the code, and CMake knows where to find your Boost and LAPACKE installations, one can do
This will build a serial version of the code into a library (without any tests). A more complete build with MPI, Thrust/OpenMP, unit and application test support, documentation support, and support for both Jali and the Burton specialization of the FleCSI library would look like:
Useful CMake Flags
Below is a non-exhaustive list of useful CMake flags for building Portage.
| CMake flag:type | Description | Default |
|---|---|---|
CMAKE_BUILD_TYPE:STRING | Debug or optimized Release build | Debug |
CMAKE_INSTALL_PREFIX:PATH | Location for the Portage library and headers to be installed | /usr/local |
CMAKE_PREFIX_PATH:PATH | Locations where CMake can look for packages; needs to be set to the FleCSI and FleCSI-SP locations if using FleCSI | NO_DEFAULT |
ENABLE_APP_TESTS:BOOL | Turn on compilation and test harness of application tests | False |
ENABLE_DOXYGEN:BOOL | Create a target to build this documentation | False |
ENABLE_FleCSI:BOOL | Turn on support for the FleCSI Burton specialization; must set CMAKE_PREFIX_PATH to a location where both FleCSI and FleCSI-SP can be found. Both FleCSI packages are under constant development. | False |
ENABLE_MPI:BOOL | Build with support for MPI | False |
ENABLE_TCMALLOC:BOOL | Build with support for TCMalloc | False |
ENABLE_THRUST:BOOL | Turn on Thrust support for on-node parallelism | False |
ENABLE_UNIT_TESTS:BOOL | Turn on compilation and test harness of unit tests | False |
ENABLE_FleCSI:BOOL | Turn on support for FleCSI; requires C++14-compatible compiler | False |
Jali_DIR:PATH | Hint location for CMake to find Jali | NO_DEFAULT |
LAPACKE_DIR:PATH | Hint location for CMake to find LAPACKE include and library files | NO_DEFAULT |
TCMALLOC_LIB:PATH | The TCMalloc library to use (recommended if enabling Thrust) | NO_DEFAULT |
THRUST_DIR:PATH | Directory of the Thrust install | NO_DEFAULT |
THRUST_BACKEND:STRING | Backend to use for Thrust | "THRUST_DEVICE_SYSTEM_OMP" |