Merge branch 'master' of https://gitlab.kitware.com/vtk/vtk-m into spatialsearch

CMake/VTKmCPUVectorization.cmake

@@ -68,7 +68,7 @@
 #
 #
 
-# guard agaisnt building vectorization_flags more than once
+# guard against building vectorization_flags more than once
 if(TARGET vtkm_vectorization_flags)
   return()
 endif()

CMake/VTKmConfig.cmake.in

@@ -27,6 +27,9 @@
 #   vtkm::tbb       Target that contains tbb related link information
 #                   implicitly linked to by `vtkm_cont` if tbb is enabled
 #
+#   vtkm::openmp    Target that contains openmp related link information
+#                   implicitly linked to by `vtkm_cont` if openmp is enabled
+#
 #   vtkm::cuda      Target that contains cuda related link information
 #                   implicitly linked to by `vtkm_cont` if cuda is enabled
 #
@@ -41,6 +44,7 @@
 #  VTKm_BUILD_SHARED_LIBS     Will be enabled if VTK-m was built shared/dynamic
 #  VTKm_ENABLE_CUDA           Will be enabled if VTK-m was built with CUDA support
 #  VTKm_ENABLE_TBB            Will be enabled if VTK-m was built with TBB support
+#  VTKm_ENABLE_OPENMP         Will be enabled if VTK-m was built with OpenMP support
 #  VTKm_ENABLE_MPI            Will be enabled if VTK-m was built with MPI support
 #  VTKm_ENABLE_RENDERING      Will be enabled if VTK-m was built with rendering support
 #  VTKm_ENABLE_GL_CONTEXT     Will be enabled if VTK-m rendering was built with a GL context
@@ -49,7 +53,13 @@
 #
 #
 
-cmake_minimum_required(VERSION 3.3 FATAL_ERROR)
+if (CMAKE_VERSION VERSION_LESS "3.3")
+  message(FATAL_ERROR "VTK-m requires CMake 3.3+")
+endif()
+if("${CMAKE_GENERATOR}" MATCHES "Visual Studio" AND
+   CMAKE_VERSION VERSION_LESS "3.11")
+  message(FATAL_ERROR "VTK-m requires CMake 3.11+ when using the Visual Studio Generators")
+endif()
 
 @PACKAGE_INIT@
 
@@ -63,6 +73,7 @@ set(VTKm_VERSION "@VTKm_VERSION@")
 set(VTKm_BUILD_SHARED_LIBS "@VTKm_BUILD_SHARED_LIBS@")
 set(VTKm_ENABLE_CUDA "@VTKm_ENABLE_CUDA@")
 set(VTKm_ENABLE_TBB "@VTKm_ENABLE_TBB@")
+set(VTKm_ENABLE_OPENMP "@VTKm_ENABLE_OPENMP@")
 set(VTKm_ENABLE_RENDERING "@VTKm_ENABLE_RENDERING@")
 set(VTKm_ENABLE_GL_CONTEXT "@VTKm_ENABLE_GL_CONTEXT@")
 set(VTKm_ENABLE_OSMESA_CONTEXT "@VTKm_ENABLE_OSMESA_CONTEXT@")

CMake/VTKmDeviceAdapters.cmake

@@ -18,10 +18,43 @@
 ##  this software.
 ##============================================================================
 
+#
+function(vtkm_extract_real_library library real_library)
+  if(NOT UNIX)
+    set(${real_library} "${library}" PARENT_SCOPE)
+    return()
+  endif()
+
+  #Read in the first 4 bytes and see if they are the ELF magic number
+  set(_elf_magic "7f454c46")
+  file(READ ${library} _hex_data OFFSET 0 LIMIT 4 HEX)
+  if(_hex_data STREQUAL _elf_magic)
+    #we have opened a elf binary so this is what
+    #we should link too
+    set(${real_library} "${library}" PARENT_SCOPE)
+    return()
+  endif()
+
+  file(READ ${library} _data OFFSET 0 LIMIT 1024)
+  if("${_data}" MATCHES "INPUT \\(([^(]+)\\)")
+    #extract out the so name from REGEX MATCh command
+    set(_proper_so_name "${CMAKE_MATCH_1}")
+
+    #construct path to the real .so which is presumed to be in the same directory
+    #as the input file
+    get_filename_component(_so_dir "${library}" DIRECTORY)
+    set(${real_library} "${_so_dir}/${_proper_so_name}" PARENT_SCOPE)
+  else()
+    #unable to determine what this library is so just hope everything works
+    #add pass it unmodified.
+    set(${real_library} "${library}" PARENT_SCOPE)
+  endif()
+endfunction()
+
 if(VTKm_ENABLE_TBB AND NOT TARGET vtkm::tbb)
   find_package(TBB REQUIRED)
 
-  # Workaround a bug in older versions of cmake prevents linking with UNKOWN IMPORTED libraries
+  # Workaround a bug in older versions of cmake prevents linking with UNKNOWN IMPORTED libraries
   # refer to CMake issue #17245
   if (CMAKE_VERSION VERSION_LESS 3.10)
     add_library(vtkm::tbb SHARED IMPORTED GLOBAL)
@@ -32,24 +65,49 @@ if(VTKm_ENABLE_TBB AND NOT TARGET vtkm::tbb)
   set_target_properties(vtkm::tbb PROPERTIES
       INTERFACE_INCLUDE_DIRECTORIES "${TBB_INCLUDE_DIRS}")
 
-    if(TBB_LIBRARY_RELEASE)
-      set_property(TARGET vtkm::tbb APPEND PROPERTY IMPORTED_CONFIGURATIONS RELEASE)
-      set_target_properties(vtkm::tbb PROPERTIES IMPORTED_LOCATION_RELEASE "${TBB_LIBRARY_RELEASE}")
-    endif()
+  if(EXISTS "${TBB_LIBRARY_RELEASE}")
+    vtkm_extract_real_library("${TBB_LIBRARY_RELEASE}" real_path)
+    set_property(TARGET vtkm::tbb APPEND PROPERTY IMPORTED_CONFIGURATIONS RELEASE)
+    set_target_properties(vtkm::tbb PROPERTIES
+      IMPORTED_LINK_INTERFACE_LANGUAGES "CXX"
+      IMPORTED_LOCATION_RELEASE "${real_path}"
+      )
+  endif()
 
-    if(TBB_LIBRARY_DEBUG)
-      set_property(TARGET vtkm::tbb APPEND PROPERTY IMPORTED_CONFIGURATIONS DEBUG)
-      set_target_properties(vtkm::tbb PROPERTIES IMPORTED_LOCATION_DEBUG "${TBB_LIBRARY_DEBUG}")
-    endif()
+  if(EXISTS "${TBB_LIBRARY_DEBUG}")
+    vtkm_extract_real_library("${TBB_LIBRARY_DEBUG}" real_path)
+    set_property(TARGET vtkm::tbb APPEND PROPERTY IMPORTED_CONFIGURATIONS DEBUG)
+    set_target_properties(vtkm::tbb PROPERTIES
+      IMPORTED_LINK_INTERFACE_LANGUAGES "CXX"
+      IMPORTED_LOCATION_DEBUG "${real_path}"
+      )
+  endif()
+endif()
+
+
+if(VTKm_ENABLE_OPENMP AND NOT TARGET vtkm::openmp)
+  cmake_minimum_required(VERSION 3.9...3.12 FATAL_ERROR)
+  find_package(OpenMP 4.0 REQUIRED COMPONENTS CXX QUIET)
+
+  add_library(vtkm::openmp INTERFACE IMPORTED GLOBAL)
+  if(OpenMP_CXX_FLAGS)
+    set_property(TARGET vtkm::openmp
+      APPEND PROPERTY INTERFACE_COMPILE_OPTIONS $<$<COMPILE_LANGUAGE:CXX>:${OpenMP_CXX_FLAGS}>)
 
-    if(NOT TBB_LIBRARY_RELEASE AND NOT TBB_LIBRARY_DEBUG)
-      set_property(TARGET vtkm::tbb APPEND PROPERTY IMPORTED_LOCATION "${TBB_LIBRARY}")
+    if(VTKm_ENABLE_CUDA)
+      string(REPLACE ";" "," openmp_cuda_flags "-Xcompiler=${OpenMP_CXX_FLAGS}")
+      set_property(TARGET vtkm::openmp
+        APPEND PROPERTY INTERFACE_COMPILE_OPTIONS $<$<COMPILE_LANGUAGE:CUDA>:${openmp_cuda_flags}>)
     endif()
+  endif()
+  if(OpenMP_CXX_LIBRARIES)
+    set_target_properties(vtkm::openmp PROPERTIES
+      INTERFACE_LINK_LIBRARIES "${OpenMP_CXX_LIBRARIES}")
+  endif()
 endif()
 
-
 if(VTKm_ENABLE_CUDA AND NOT TARGET vtkm::cuda)
-  cmake_minimum_required(VERSION 3.9 FATAL_ERROR)
+  cmake_minimum_required(VERSION 3.9...3.12 FATAL_ERROR)
   enable_language(CUDA)
 
   #To work around https://gitlab.kitware.com/cmake/cmake/issues/17512
@@ -58,7 +116,7 @@ if(VTKm_ENABLE_CUDA AND NOT TARGET vtkm::cuda)
     list(APPEND CMAKE_CUDA_IMPLICIT_INCLUDE_DIRECTORIES "${CMAKE_CXX_IMPLICIT_INCLUDE_DIRECTORIES}")
   endif()
 
-  # Workaround a bug in older versions of cmake prevents linking with UNKOWN IMPORTED libraries
+  # Workaround a bug in older versions of cmake prevents linking with UNKNOWN IMPORTED libraries
   # refer to CMake issue #17245
   if (CMAKE_VERSION VERSION_LESS 3.10)
     add_library(vtkm::cuda STATIC IMPORTED GLOBAL)
@@ -75,24 +133,27 @@ if(VTKm_ENABLE_CUDA AND NOT TARGET vtkm::cuda)
   if("x${CMAKE_CUDA_SIMULATE_ID}" STREQUAL "xMSVC")
     get_filename_component(VTKM_CUDA_BIN_DIR "${CMAKE_CUDA_COMPILER}" DIRECTORY)
 
-    set_property(TARGET vtkm::cuda APPEND PROPERTY IMPORTED_LOCATION "${VTKM_CUDA_BIN_DIR}/../lib/x64/cudadevrt.lib")
-
-    set_target_properties(vtkm::cuda PROPERTIES INTERFACE_INCLUDE_DIRECTORIES "${VTKM_CUDA_BIN_DIR}/../include/")
+    set_target_properties(vtkm::cuda PROPERTIES
+        IMPORTED_LINK_INTERFACE_LANGUAGES "CXX"
+        IMPORTED_LOCATION "${VTKM_CUDA_BIN_DIR}/../lib/x64/cudadevrt.lib"
+        INTERFACE_INCLUDE_DIRECTORIES "${VTKM_CUDA_BIN_DIR}/../include/"
+        )
 
   else()
     list(GET CMAKE_CUDA_IMPLICIT_LINK_LIBRARIES 0 VTKM_CUDA_LIBRARY)
     if(IS_ABSOLUTE "${VTKM_CUDA_LIBRARY}")
-      set_property(TARGET vtkm::cuda APPEND PROPERTY IMPORTED_LOCATION "${VTKM_CUDA_LIBRARY}")
+      set_target_properties(vtkm::cuda PROPERTIES IMPORTED_LOCATION "${VTKM_CUDA_LIBRARY}")
     else()
       find_library(cuda_lib
               NAME ${VTKM_CUDA_LIBRARY}
               PATHS ${CMAKE_CUDA_IMPLICIT_LINK_DIRECTORIES}
               )
       set(VTKM_CUDA_LIBRARY ${cuda_lib})
-      set_property(TARGET vtkm::cuda APPEND PROPERTY IMPORTED_LOCATION "${VTKM_CUDA_LIBRARY}")
+      set_target_properties(vtkm::cuda PROPERTIES IMPORTED_LOCATION "${VTKM_CUDA_LIBRARY}")
       unset(cuda_lib CACHE)
     endif()
     set_target_properties(vtkm::cuda PROPERTIES
+            IMPORTED_LINK_INTERFACE_LANGUAGES "CXX"
             INTERFACE_INCLUDE_DIRECTORIES "${CMAKE_CUDA_TOOLKIT_INCLUDE_DIRECTORIES}")
   endif()
 
@@ -140,7 +201,7 @@ if(VTKm_ENABLE_CUDA AND NOT TARGET vtkm::cuda)
   set(VTKm_CUDA_Architecture "native" CACHE STRING "Which GPU Architecture(s) to compile for")
   set_property(CACHE VTKm_CUDA_Architecture PROPERTY STRINGS native fermi kepler maxwell pascal volta all none)
 
-  #detect what the propery is set too
+  #detect what the property is set too
   if(VTKm_CUDA_Architecture STREQUAL "native")
 
     if(VTKM_CUDA_NATIVE_EXE_PROCESS_RAN_OUTPUT)

CMake/VTKmWrappers.cmake

@@ -61,7 +61,7 @@ endfunction(vtkm_pyexpander_generated_file)
 
 #-----------------------------------------------------------------------------
 function(vtkm_compile_as_cuda output)
-  # We cant use set_source_files_properties(<> PROPERTIES LANGUAGE "CUDA")
+  # We can't use set_source_files_properties(<> PROPERTIES LANGUAGE "CUDA")
   # for the following reasons:
   #
   # 1. As of CMake 3.10 MSBuild cuda language support has a bug where files

CMakeLists.txt

@@ -25,11 +25,11 @@
 # If you want CUDA support, you will need to have CMake 3.9 on Linux/OSX.
 # We require CMake 3.11 with the MSVC generator as the $<COMPILE_LANGUAGE:>
 # generator expression is not supported on older versions.
-cmake_minimum_required(VERSION 3.3)
+cmake_minimum_required(VERSION 3.3...3.12)
 project (VTKm)
 
 if(${CMAKE_GENERATOR} MATCHES "Visual Studio")
-  cmake_minimum_required(VERSION 3.11 FATAL_ERROR)
+  cmake_minimum_required(VERSION 3.11...3.12 FATAL_ERROR)
 endif()
 
 # Update module path
@@ -86,6 +86,7 @@ endmacro ()
 # Configurable Options
 vtkm_option(VTKm_ENABLE_CUDA "Enable Cuda support" OFF)
 vtkm_option(VTKm_ENABLE_TBB "Enable TBB support" OFF)
+vtkm_option(VTKm_ENABLE_OPENMP "Enable OpenMP support" OFF)
 vtkm_option(VTKm_ENABLE_RENDERING "Enable rendering library" ON)
 vtkm_option(VTKm_ENABLE_TESTING "Enable VTKm Testing" ON)
 vtkm_option(VTKm_ENABLE_BENCHMARKS "Enable VTKm Benchmarking" OFF)
@@ -120,7 +121,7 @@ set(VTKm_BUILD_SHARED_LIBS ${BUILD_SHARED_LIBS})
 # This flag can be used to prevent VTK-m from exporting its warning flags in its
 # build interface. This is useful when building VTK-m as a thirdparty library
 # and the warnings are too strict for the parent project.
-vtkm_option(VTKm_ENABLE_DEVELOPER_FLAGS "Enable compiler flags that are usefull while developing VTK-m" ON)
+vtkm_option(VTKm_ENABLE_DEVELOPER_FLAGS "Enable compiler flags that are useful while developing VTK-m" ON)
 
 mark_as_advanced(
   VTKm_NO_ASSERT
@@ -165,7 +166,16 @@ endif()
 #-----------------------------------------------------------------------------
 if (VTKm_ENABLE_TESTING)
   enable_testing()
-  include(CTest)
+  # Only include CTest if it has not been included by a superproject. The
+  # variable DEFAULT_CTEST_CONFIGURATION_TYPE is a non-cached variable set by
+  # CTest.cmake, so we'll use that to determine if it's already included.
+  if(NOT DEFINED DEFAULT_CTEST_CONFIGURATION_TYPE)
+    include(CTest)
+    # Mark this as advanced to avoid confusion, since we actually rely on
+    # VTKm_ENABLE_TESTING.
+    mark_as_advanced(BUILD_TESTING)
+  endif()
+
   configure_file(${VTKm_SOURCE_DIR}/CTestCustom.cmake.in
     ${VTKm_BINARY_DIR}/CTestCustom.cmake @ONLY)
 
@@ -266,6 +276,7 @@ if(NOT VTKm_INSTALL_ONLY_LIBRARIES)
     FILES
       ${VTKm_SOURCE_DIR}/CMake/FindTBB.cmake
       ${VTKm_SOURCE_DIR}/CMake/FindOpenGL.cmake
+      ${VTKm_SOURCE_DIR}/CMake/FindOpenMP.cmake
     DESTINATION ${VTKm_INSTALL_CMAKE_MODULE_DIR}
     )
 

CTestCustom.cmake.in

@@ -28,6 +28,9 @@ list(APPEND CTEST_CUSTOM_WARNING_EXCEPTION
   # disable doxygen warning about not generating graph
   ".*warning: Included by graph for"
 
+  # Doxygen warns when creating output directory:
+  "Notice: Output directory.*does not exist. I have created it for you."
+
   # disable doxygen warnings from CONTRIBUTING.md, CodingConventions.md.
   # these files are really intended for Gitlab, hence we don't want to use
   # doxygen tags in them.

README.md

@@ -64,15 +64,17 @@ VTK-m Requires:
       + MSVC 2015+
   + [CMake](http://www.cmake.org/download/)
       + CMake 3.3+ (for any build)
-      + CMake 3.9+ (for CUDA build)
+      + CMake 3.9+ (for CUDA build or OpenMP build)
       + CMake 3.11+ (for Visual Studio generator)
 
 Optional dependencies are:
 
   + CUDA Device Adapter
-      + [Cuda Toolkit 7+](https://developer.nvidia.com/cuda-toolkit)
+      + [Cuda Toolkit 7.5+](https://developer.nvidia.com/cuda-toolkit)
   + TBB Device Adapter
       + [TBB](https://www.threadingbuildingblocks.org/)
+  + OpenMP Device Adapter
+      + Requires a compiler that supports OpenMP >= 4.0.
   + OpenGL Rendering
       + The rendering module contains multiple rendering implementations
         including standalone rendering code. The rendering module also

benchmarking/BenchmarkDeviceAdapter.cxx

@@ -46,7 +46,9 @@
 
 #if VTKM_DEVICE_ADAPTER == VTKM_DEVICE_ADAPTER_TBB
 #include <tbb/task_scheduler_init.h>
-#endif // TBB
+#elif VTKM_DEVICE_ADAPTER == VTKM_DEVICE_ADAPTER_OPENMP
+#include <omp.h>
+#endif
 
 // This benchmark has a number of commandline options to customize its behavior.
 // See The BenchDevAlgoConfig documentations for details.
@@ -748,6 +750,7 @@ private:
     const vtkm::Id N_VALID;
     const vtkm::Id PERCENT_VALID;
     ValueArrayHandle ValueHandle;
+    IndexArrayHandle IndexHandle;
 
     VTKM_CONT
     BenchStableSortIndicesUnique(vtkm::Id percent_valid)
@@ -759,12 +762,14 @@ private:
         FillModuloTestValueKernel<Value>(
           N_VALID, this->ValueHandle.PrepareForOutput(arraySize, DeviceAdapterTag())),
         arraySize);
+      this->IndexHandle = SSI::Sort(this->ValueHandle);
     }
 
     VTKM_CONT
     vtkm::Float64 operator()()
     {
-      IndexArrayHandle indices = SSI::Sort(this->ValueHandle);
+      IndexArrayHandle indices;
+      Algorithm::Copy(this->IndexHandle, indices);
       Timer timer;
       SSI::Unique(this->ValueHandle, indices);
       return timer.GetElapsedTime();
@@ -1190,6 +1195,8 @@ int main(int argc, char* argv[])
 {
 #if VTKM_DEVICE_ADAPTER == VTKM_DEVICE_ADAPTER_TBB
   int numThreads = tbb::task_scheduler_init::automatic;
+#elif VTKM_DEVICE_ADAPTER == VTKM_DEVICE_ADAPTER_OPENMP
+  int numThreads = omp_get_max_threads();
 #endif // TBB
 
   vtkm::benchmarking::BenchDevAlgoConfig& config = vtkm::benchmarking::Config;
@@ -1320,8 +1327,12 @@ int main(int argc, char* argv[])
       std::istringstream parse(argv[i]);
       parse >> numThreads;
       std::cout << "Selected " << numThreads << " TBB threads." << std::endl;
+#elif VTKM_DEVICE_ADAPTER == VTKM_DEVICE_ADAPTER_OPENMP
+      std::istringstream parse(argv[i]);
+      parse >> numThreads;
+      std::cout << "Selected " << numThreads << " OpenMP threads." << std::endl;
 #else
-      std::cerr << "NumThreads valid only on TBB. Ignoring." << std::endl;
+      std::cerr << "NumThreads not valid on this device. Ignoring." << std::endl;
 #endif // TBB
     }
     else
@@ -1334,6 +1345,8 @@ int main(int argc, char* argv[])
 #if VTKM_DEVICE_ADAPTER == VTKM_DEVICE_ADAPTER_TBB
   // Must not be destroyed as long as benchmarks are running:
   tbb::task_scheduler_init init(numThreads);
+#elif VTKM_DEVICE_ADAPTER == VTKM_DEVICE_ADAPTER_OPENMP
+  omp_set_num_threads(numThreads);
 #endif // TBB
 
   if (config.BenchmarkFlags == 0)

benchmarking/CMakeLists.txt

@@ -30,6 +30,12 @@ function(add_benchmark name files)
     target_compile_definitions(${name}_TBB PRIVATE "VTKM_DEVICE_ADAPTER=VTKM_DEVICE_ADAPTER_TBB")
   endif()
 
+  if (TARGET vtkm::openmp)
+    add_executable(${name}_OPENMP ${files})
+    list(APPEND benchmarks ${name}_OPENMP)
+    target_compile_definitions(${name}_OPENMP PRIVATE "VTKM_DEVICE_ADAPTER=VTKM_DEVICE_ADAPTER_OPENMP")
+  endif()
+
   if (TARGET vtkm::cuda)
     get_filename_component(fname "${name}" NAME_WE)
     get_filename_component(fullpath "${name}.cxx" ABSOLUTE)
@@ -70,6 +76,9 @@ if(TARGET vtkm_rendering)
   if(TARGET BenchmarkRayTracing_TBB)
     target_link_libraries(BenchmarkRayTracing_TBB PRIVATE vtkm_rendering)
   endif()
+  if(TARGET BenchmarkRayTracing_OPENMP)
+    target_link_libraries(BenchmarkRayTracing_OPENMP PRIVATE vtkm_rendering)
+  endif()
   if(TARGET BenchmarkRayTracing_CUDA)
     target_link_libraries(BenchmarkRayTracing_CUDA PRIVATE vtkm_rendering)
   endif()

docs/changelog/Allow-custom-range-in-histogram-filter.md

+#Allow histogram filter to take custom types
+
+By passing TypeList and StorageList type into FieldRangeGlobalCompute,
+upstream users(VTK) can pass custom types into the histogram filter.

docs/changelog/add-float-version-functions-pi.md

@@ -2,4 +2,4 @@
 
 Now PI related functions are evalulated at compile time as constexpr functions.
 It also removes the old static_cast<T>vtkm::Pi() usages with
-template ones and fix serveral conversion warnings.
+template ones and fix several conversion warnings.

docs/changelog/allow-CoordinateSystem-to-unload-execution-resources.md

+# Add a common API for CoordinateSystem to unload execution resources
+We now offer the ability to unload execution memory from ArrayHandleVirtualCoordinate
+and CoordinateSystem using the ReleaseResourcesExecution method.
+
+Field now has a ReleaseResourcesExecution.
+
+This commit also fixes a bug that ArrayTransfer of ArrayHandleVirtualCoordinate
+does not release execution resources properly.
+

docs/changelog/cell-measure.md

@@ -45,7 +45,7 @@ by definition and thus always return values above or equal to 0.0.
 Negative values indicate either the order in which vertices appear in its connectivity
 array is improper or the relative locations of the vertices in world coordinates
 result in a cell with a negative Jacobian somewhere in its interior.
-Finaly, note that cell measures may return invalid (NaN) or infinite (Inf, -Inf)
+Finally, note that cell measures may return invalid (NaN) or infinite (Inf, -Inf)
 values if the cell is poorly defined, e.g., has coincident vertices
 or a parametric dimension larger than the space spanned by its world-coordinate
 vertices.

docs/changelog/geometry.md

+# New geometry classes and header.
+
+There are now some additional structures available both
+the control and execution environments for representing
+geometric entities (mostly of dimensions 2 and 3).
+These new structures are now in `vtkm/Geometry.h` and
+demonstrated/tested in `vtkm/testing/TestingGeometry.h`:
+
++ `Ray<CoordType, Dimension, IsTwoSided>`.
+  Instances of this struct represent a semi-infinite line
+  segment in a 2-D plane or in a 3-D space, depending on the
+  integer dimension specified as a template parameter.
+  Its state is the point at the start of the ray (`Origin`)
+  plus the ray's `Direction`, a unit-length vector.
+  If the third template parameter (IsTwoSided) is true, then
+  the ray serves as an infinite line. Otherwise, the ray will
+  only report intersections in its positive halfspace.
++ `LineSegment<CoordType, Dimension>`.
+  Instances of this struct represent a finite line segment
+  in a 2-D plane or in a 3-D space, depending on the integer
+  dimension specified as a template parameter.
+  Its state is the coordinates of its `Endpoints`.
++ `Plane<CoordType>`.
+  Instances of this struct represent a plane in 3-D.
+  Its state is the coordinates of a base point (`Origin`) and
+  a unit-length normal vector (`Normal`).
++ `Sphere<CoordType, Dimension>`.
+  Instances of this struct represent a *d*-dimensional sphere.
+  Its state is the coordinates of its center plus a radius.
+  It is also aliased with a `using` statment to `Circle<CoordType>`
+  for the specific case of 2-D.
+
+These structures provide useful queries and generally
+interact with one another.
+For instance, it is possible to intersect lines and planes
+and compute distances.
+
+For ease of use, there are also several `using` statements
+that alias these geometric structures to names that specialize
+them for a particular dimension or other template parameter.
+As an example, `Ray<CoordType, Dimension, true>` is aliased
+to `Line<CoordType, Dimension>` and `Ray<CoordType, 3, true>`
+is aliased to `Line3<CoordType>` and `Ray<FloatDefault, 3, true>`
+is aliased to `Line3d`.
+
+## Design patterns
+
+If you plan to add a new geometric entity type,
+please adopt these conventions:
+
++ Each geometric entity may be default-constructed.
+  The default constructor will initialize the state to some
+  valid unit-length entity, usually with some part of
+  its state at the origin of the coordinate system.
++ Entities may always be constructed by passing in values
+  for their internal state.
+  Alternate construction methods are declared as free functions
+  such as `make_CircleFrom3Points()`
++ Use template metaprogramming to make methods available
+  only when the template dimension gives them semantic meaning.
+  For example, a 2-D line segment's perpendicular bisector
+  is another line segment, but a 3-D line segment's perpendicular
+  line segment is a plane.
+  Note how this is accomplished and apply this pattern to
+  new geometric entities or new methods on existing entities.
++ Some entities may have invalid state.
+  If this is possible, the entity will have an `IsValid()` method.
+  For example, a sphere may be invalid because the user or some
+  construction technique specified a zero or negative radius.
++ When signed distance is semantically meaningful, provide it
+  in favor of or in addition to unsigned distance.
++ Accept a tolerance parameter when appropriate,
+  but provide a sensible default value.
+  You may want to perform exact arithmetic versions of tests,
+  but please provide fast, tolerance-based versions as well.

docs/changelog/openmp-backend.md

+# OpenMP Device Adapter
+
+A device adapter that leverages OpenMP 4.0 for threading is now available. The
+new adapter is enabled using the CMake option `VTKm_ENABLE_OPENMP` and its
+performance is comparable to the TBB device adapter.

docs/changelog/swap.md

+# Add a CUDA-safe `vtkm::Swap` method.
+
+Added a swap implementation that is safe to call from all backends.
+
+It is not legal to call std functions from CUDA code, and the new
+`vtkm::Swap` implements a naive swap when compiled under NVCC while
+falling back to a std/ADL swap otherwise.

docs/changelog/vec-initializer-lists.md

+# Support initializer lists for Vec
+
+Add constructors to the `vtkm::Vec` classes that accept `std::initializer_list`. The
+main advantage of this addition is that it makes it much easier to initialize `Vec`s
+of arbitrary length.
+
+Although previously some `Vec` classes could be constructed with values listed in
+their parameters, that only worked for initializes up to size 4.
+
+``` cpp
+vtkm::Vec<vtkm::Float64, 3> vec1{1.1, 2.2, 3.3};  // New better initializer
+
+vtkm::Vec<vtkm::Float64, 3> vec2 = {1.1, 2.2, 3.3}; // Nice syntax also supported by
+                                                    // initializer lists.
+
+vtkm::Vec<vtkm::Float64, 3> vec3(1.1, 2.2, 3.3); // Old style that still works but
+                                                 // probably should be deprecated.
+```
+
+Nested initializer lists work to initialize `Vec`s of `Vec`s.
+
+``` cpp
+vtkm::Vec<vtkm::Vec<vtkm::Float64, 2>, 3> vec{ {1.1, 2.2}, {3.3, 4.4}, {5.5, 6.6} };
+```
+
+The nice thing about the `std::initializer_list` implementation is that it works for any
+size `Vec`. That keeps us from jumping through hoops for larger `Vec`s.
+
+``` cpp
+vtkm::Vec<vtkm::Float64, 5> vec1{1.1, 2.2, 3.3, 4.4, 5.5}; // Works fine.
+
+vtkm::Vec<vtkm::Float64, 5> vec2(1.1, 2.2, 3.3, 4.4, 5.5); // ERROR! This constructor
+                                                           // not implemented!
+```
+
+If a `vtkm::Vec` is initialized with a list of size one, then that one value is
+replicated for all components.
+
+``` cpp
+vtkm::Vec<vtkm::Float64, 3> vec{1.1};  // vec gets [ 1.1, 1.1, 1.1 ]
+```
+
+This "scalar" initialization also works for `Vec`s of `Vec`s.
+
+``` cpp
+vtkm::Vec<vtkm::Vec<vtkm::Float64, 2>, 3> vec1{ { 1.1, 2.2 } };
+// vec1 is [[1.1, 2.2], [1.1, 2.2], [1.1, 2.2]]
+
+vtkm::Vec<vtkm::Vec<vtkm::Float64, 2>, 3> vec2{ { 3.3}, { 4.4 }, { 5.5 } };
+// vec2 is [[3.3, 3.3], [4.4, 4.4], [5.5, 5.5]]
+```
+
+`vtkm::make_Vec` is also updated to support an arbitrary number initial values.
+
+``` cpp
+// Creates a vtkm::Vec<vtkm::Float64, 5>
+auto vec = vtkm::make_Vec(1.1, 2.2, 3.3, 4.4, 5.5);
+```
+
+This is super convenient when dealing with variadic function arguments.
+
+``` cpp
+template <typename... Ts>
+void ExampleVariadicFunction(const Ts&... params)
+{
+  auto vec = vtkm::make_Vec(params...);
+```
+
+Of course, this assumes that the type of all the parameters is the same. If not, you
+could run into compiler trouble.
+
+There is also a version of `vtkm::make_Vec` that accepts an `std::initializer_list`,
+but it is not very useful because you have to separately specify the length of the
+`Vec` (due to some limitations of `std::initializer_list` in C++11).
+
+``` cpp
+// Creates a vtkm::Vec<vtkm::Float64, 3>
+auto vec1 = vtkm::make_Vec<3>({1.1, 2.2, 3.3});
+
+// Creates exactly the same thing
+auto vec2 = vtkm::Vec<vtkm::Float64, 3>{1.1, 2.2, 3.3};
+```