Merge topic '113-ArrayHandleDiscard'

17b2dd66 Add ArrayHandleDiscard for unused outputs.

Acked-by: Kitware Robot <kwrobot@kitware.com>
Acked-by: Kenneth Moreland <kmorel@sandia.gov>
Merge-request: !682

vtkm/cont/ArrayHandleDiscard.h

@@ -0,0 +1,246 @@
+//============================================================================
+//  Copyright (c) Kitware, Inc.
+//  All rights reserved.
+//  See LICENSE.txt for details.
+//  This software is distributed WITHOUT ANY WARRANTY; without even
+//  the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
+//  PURPOSE.  See the above copyright notice for more information.
+//
+//  Copyright 2017 Sandia Corporation.
+//  Copyright 2017 UT-Battelle, LLC.
+//  Copyright 2017 Los Alamos National Security.
+//
+//  Under the terms of Contract DE-AC04-94AL85000 with Sandia Corporation,
+//  the U.S. Government retains certain rights in this software.
+//
+//  Under the terms of Contract DE-AC52-06NA25396 with Los Alamos National
+//  Laboratory (LANL), the U.S. Government retains certain rights in
+//  this software.
+//============================================================================
+#ifndef vtk_m_cont_ArrayHandleDiscard_h
+#define vtk_m_cont_ArrayHandleDiscard_h
+
+#include <vtkm/cont/ArrayHandle.h>
+#include <vtkm/TypeTraits.h>
+
+namespace vtkm {
+namespace exec {
+namespace internal {
+
+/// \brief An output-only array portal with no storage. All written values are
+/// discarded.
+template <typename ValueType_>
+class ArrayPortalDiscard
+{
+public:
+  using ValueType = ValueType_;
+
+  VTKM_SUPPRESS_EXEC_WARNINGS
+  VTKM_EXEC_CONT
+  ArrayPortalDiscard()
+    : NumberOfValues(0)
+  {  } // needs to be host and device so that cuda can create lvalue of these
+
+  VTKM_CONT
+  explicit ArrayPortalDiscard(vtkm::Id numValues)
+    : NumberOfValues(numValues)
+  {  }
+
+  /// Copy constructor for any other ArrayPortalDiscard with an iterator
+  /// type that can be copied to this iterator type. This allows us to do any
+  /// type casting that the iterators do (like the non-const to const cast).
+  ///
+  template<class OtherV>
+  VTKM_CONT
+  ArrayPortalDiscard(const ArrayPortalDiscard<OtherV> &src)
+    : NumberOfValues(src.NumberOfValues)
+  {  }
+
+  VTKM_EXEC_CONT
+  vtkm::Id GetNumberOfValues() const
+  {
+    return this->NumberOfValues;
+  }
+
+  ValueType Get(vtkm::Id index) const {
+    VTKM_ASSERT(index < this->GetNumberOfValues());
+    VTKM_ASSERT("Method not supported for ArrayPortalDiscard." && false);
+    (void)index;
+    return vtkm::TypeTraits<ValueType>::ZeroInitialization();
+  }
+
+  VTKM_EXEC
+  void Set(vtkm::Id index, const ValueType &) const
+  {
+    VTKM_ASSERT(index < this->GetNumberOfValues());
+    (void)index;
+    // no-op
+  }
+
+private:
+  vtkm::Id NumberOfValues;
+};
+
+} // end namespace internal
+} // end namespace exec
+
+namespace cont {
+
+namespace internal {
+
+struct VTKM_ALWAYS_EXPORT StorageTagDiscard { };
+
+template <typename ValueType_>
+class Storage<ValueType_, StorageTagDiscard>
+{
+public:
+  using ValueType = ValueType_;
+  using PortalType = vtkm::exec::internal::ArrayPortalDiscard<ValueType>;
+  using PortalConstType = vtkm::exec::internal::ArrayPortalDiscard<ValueType>;
+
+  VTKM_CONT
+  Storage() { }
+
+  VTKM_CONT
+  PortalType GetPortal()
+  {
+    return PortalType(this->NumberOfValues);
+  }
+
+  VTKM_CONT
+  PortalConstType GetPortalConst()
+  {
+    return PortalConstType(this->NumberOfValues);
+  }
+
+  VTKM_CONT
+  vtkm::Id GetNumberOfValues() const
+  {
+    return this->NumberOfValues;
+  }
+
+  VTKM_CONT
+  void Allocate(vtkm::Id numValues)
+  {
+    this->NumberOfValues = numValues;
+  }
+
+  VTKM_CONT
+  void Shrink(vtkm::Id numValues)
+  {
+    this->NumberOfValues = numValues;
+  }
+
+  VTKM_CONT
+  void ReleaseResources()
+  {
+    this->NumberOfValues = 0;
+  }
+
+private:
+  vtkm::Id NumberOfValues;
+};
+
+template <typename ValueType_, typename DeviceAdapter_>
+class ArrayTransfer<ValueType_, StorageTagDiscard, DeviceAdapter_>
+{
+  using StorageTag = StorageTagDiscard;
+  using StorageType = Storage<ValueType_, StorageTag>;
+
+public:
+  using ValueType = ValueType_;
+  using PortalControl = typename StorageType::PortalType;
+  using PortalConstControl = typename StorageType::PortalConstType;
+  using PortalExecution = vtkm::exec::internal::ArrayPortalDiscard<ValueType>;
+  using PortalConstExecution = vtkm::exec::internal::ArrayPortalDiscard<ValueType>;
+
+  VTKM_CONT
+  ArrayTransfer(StorageType *storage)
+    : Internal(storage)
+  {  }
+
+  VTKM_CONT
+  vtkm::Id GetNumberOfValues() const
+  {
+    VTKM_ASSERT(this->Internal != nullptr);
+    return this->Internal->GetNumberOfValues();
+  }
+
+  VTKM_CONT
+  PortalConstExecution PrepareForInput(bool vtkmNotUsed(updateData))
+  {
+    throw vtkm::cont::ErrorControlBadValue(
+          "Input access not supported: "
+          "Cannot read from an ArrayHandleDiscard.");
+  }
+
+  VTKM_CONT
+  PortalExecution PrepareForInPlace(bool vtkmNotUsed(updateData))
+  {
+    throw vtkm::cont::ErrorControlBadValue(
+          "InPlace access not supported: "
+          "Cannot read from an ArrayHandleDiscard.");
+  }
+
+  VTKM_CONT
+  PortalExecution PrepareForOutput(vtkm::Id numValues)
+  {
+    VTKM_ASSERT(this->Internal != nullptr);
+    this->Internal->Allocate(numValues);
+    return PortalConstExecution(this->Internal->GetNumberOfValues());
+  }
+
+  VTKM_CONT
+  void RetrieveOutputData(StorageType *storage) const
+  {
+    VTKM_ASSERT(storage == this->Internal);
+    (void)storage;
+    // no-op
+  }
+
+  VTKM_CONT
+  void Shrink(vtkm::Id numValues)
+  {
+    VTKM_ASSERT(this->Internal != nullptr);
+    this->Internal->Shrink(numValues);
+  }
+
+  VTKM_CONT
+  void ReleaseResources()
+  {
+    VTKM_ASSERT(this->Internal != nullptr);
+    this->Internal->ReleaseResources();
+  }
+
+private:
+  StorageType *Internal;
+};
+
+template <typename ValueType_>
+struct ArrayHandleDiscardTraits
+{
+  using ValueType = ValueType_;
+  using StorageTag = StorageTagDiscard;
+  using Superclass = vtkm::cont::ArrayHandle<ValueType, StorageTag>;
+};
+
+} // end namespace internal
+
+/// ArrayHandleDiscard is a write-only array that discards all data written to
+/// it. This can be used to save memory when a filter provides optional outputs
+/// that are not needed.
+template <typename ValueType_>
+class ArrayHandleDiscard
+    : public internal::ArrayHandleDiscardTraits<ValueType_>::Superclass
+{
+public:
+  VTKM_ARRAY_HANDLE_SUBCLASS(
+      ArrayHandleDiscard,
+      (ArrayHandleDiscard<ValueType_>),
+      (typename internal::ArrayHandleDiscardTraits<ValueType_>::Superclass));
+};
+
+} // end namespace cont
+} // end namespace vtkm
+
+#endif // vtk_m_cont_ArrayHandleDiscard_h

vtkm/cont/CMakeLists.txt

@@ -25,6 +25,7 @@ set(headers
   ArrayHandleCompositeVector.h
   ArrayHandleConstant.h
   ArrayHandleCounting.h
+  ArrayHandleDiscard.h
   ArrayHandleGroupVec.h
   ArrayHandleGroupVecVariable.h
   ArrayHandleImplicit.h

vtkm/cont/testing/CMakeLists.txt

@@ -36,6 +36,7 @@ set(unit_tests
   UnitTestArrayHandleCartesianProduct.cxx
   UnitTestArrayHandleCompositeVector.cxx
   UnitTestArrayHandleCounting.cxx
+  UnitTestArrayHandleDiscard.cxx
   UnitTestArrayHandleImplicit.cxx
   UnitTestArrayHandleIndex.cxx
   UnitTestArrayHandlePermutation.cxx

vtkm/cont/testing/TestingFancyArrayHandles.h

@@ -28,6 +28,7 @@
 #include <vtkm/cont/ArrayHandleConcatenate.h>
 #include <vtkm/cont/ArrayHandleConstant.h>
 #include <vtkm/cont/ArrayHandleCounting.h>
+#include <vtkm/cont/ArrayHandleDiscard.h>
 #include <vtkm/cont/ArrayHandleGroupVec.h>
 #include <vtkm/cont/ArrayHandleGroupVecVariable.h>
 #include <vtkm/cont/ArrayHandleImplicit.h>
@@ -796,6 +797,37 @@ private:
     }
   };
 
+  struct TestDiscardAsOutput
+  {
+    template< typename ValueType>
+    VTKM_CONT void operator()(const ValueType vtkmNotUsed(v)) const
+    {
+      using DiscardHandleType = vtkm::cont::ArrayHandleDiscard<ValueType>;
+      using ComponentType = typename vtkm::VecTraits<ValueType>::ComponentType;
+
+      typedef typename vtkm::cont::ArrayHandle<ValueType>::PortalControl Portal;
+
+      const vtkm::Id length = ARRAY_SIZE;
+
+      vtkm::cont::ArrayHandle<ValueType> input;
+      input.Allocate(length);
+      Portal inputPortal = input.GetPortalControl();
+      for(vtkm::Id i=0; i < length; ++i)
+        {
+        inputPortal.Set(i,ValueType(ComponentType(i)));
+        }
+
+      DiscardHandleType discard;
+      discard.Allocate(length);
+
+      vtkm::worklet::DispatcherMapField< PassThrough, DeviceAdapterTag > dispatcher;
+      dispatcher.Invoke(input, discard);
+
+      // No output to verify since none is stored in memory. Just checking that
+      // this compiles/runs without errors.
+    }
+  };
+
   struct TestPermutationAsOutput
   {
     template< typename ValueType>
@@ -1036,6 +1068,12 @@ private:
                               TestingFancyArrayHandles<DeviceAdapterTag>::TestPermutationAsOutput(),
                               HandleTypesToTest());
 
+      std::cout << "-------------------------------------------" << std::endl;
+      std::cout << "Testing ArrayHandleDiscard as Output" << std::endl;
+      vtkm::testing::Testing::TryTypes(
+            TestingFancyArrayHandles<DeviceAdapterTag>::TestDiscardAsOutput(),
+            HandleTypesToTest());
+
       std::cout << "-------------------------------------------" << std::endl;
       std::cout << "Testing ArrayHandleZip as Output" << std::endl;
       vtkm::testing::Testing::TryTypes(

vtkm/cont/testing/UnitTestArrayHandleDiscard.cxx

@@ -0,0 +1,143 @@
+//============================================================================
+//  Copyright (c) Kitware, Inc.
+//  All rights reserved.
+//  See LICENSE.txt for details.
+//  This software is distributed WITHOUT ANY WARRANTY; without even
+//  the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
+//  PURPOSE.  See the above copyright notice for more information.
+//
+//  Copyright 2017 Sandia Corporation.
+//  Copyright 2017 UT-Battelle, LLC.
+//  Copyright 2017 Los Alamos National Security.
+//
+//  Under the terms of Contract DE-AC04-94AL85000 with Sandia Corporation,
+//  the U.S. Government retains certain rights in this software.
+//
+//  Under the terms of Contract DE-AC52-06NA25396 with Los Alamos National
+//  Laboratory (LANL), the U.S. Government retains certain rights in
+//  this software.
+//============================================================================
+
+#include <vtkm/cont/ArrayHandle.h>
+#include <vtkm/cont/ArrayHandleDiscard.h>
+#include <vtkm/cont/DeviceAdapterAlgorithm.h>
+
+#include <vtkm/cont/serial/internal/ArrayManagerExecutionSerial.h>
+#include <vtkm/cont/serial/internal/DeviceAdapterAlgorithmSerial.h>
+#include <vtkm/cont/serial/internal/DeviceAdapterTagSerial.h>
+
+#include <vtkm/cont/testing/Testing.h>
+
+#include <vtkm/BinaryOperators.h>
+
+#include <algorithm>
+
+namespace UnitTestArrayHandleDiscardDetail
+{
+
+template <typename ValueType>
+struct Test
+{
+  static const vtkm::Id ARRAY_SIZE = 100;
+  static const vtkm::Id NUM_KEYS = 3;
+
+  using DeviceTag = vtkm::cont::DeviceAdapterTagSerial;
+  using Algorithm = vtkm::cont::DeviceAdapterAlgorithm<DeviceTag>;
+  using Handle = vtkm::cont::ArrayHandle<ValueType>;
+  using DiscardHandle = vtkm::cont::ArrayHandleDiscard<ValueType>;
+  using OutputPortal = typename Handle::PortalControl;
+  using ReduceOp = vtkm::Add;
+
+  // Test discard arrays by using the ReduceByKey algorithm. Two regular arrays
+  // handles are provided as inputs, but the keys_output array is a discard
+  // array handle. The values_output array should still be populated correctly.
+  void TestReduceByKey()
+  {
+    // The reduction operator:
+    ReduceOp op;
+
+    // Prepare inputs / reference data:
+    ValueType keyData[ARRAY_SIZE];
+    ValueType valueData[ARRAY_SIZE];
+    ValueType refData[NUM_KEYS];
+    std::fill(refData, refData + NUM_KEYS, ValueType(0));
+    for (vtkm::Id i = 0; i < ARRAY_SIZE; ++i)
+    {
+      const vtkm::Id key = i % NUM_KEYS;
+      keyData[i] = static_cast<ValueType>(key);
+      valueData[i] = static_cast<ValueType>(i * 2);
+      refData[key] = op(refData[key], valueData[i]);
+    }
+
+    // Prepare array handles:
+    Handle keys = vtkm::cont::make_ArrayHandle(keyData, ARRAY_SIZE);
+    Handle values = vtkm::cont::make_ArrayHandle(valueData, ARRAY_SIZE);
+    DiscardHandle output_keys;
+    Handle output_values;
+
+    Algorithm::SortByKey(keys, values);
+    Algorithm::ReduceByKey(keys, values, output_keys, output_values, op);
+
+    OutputPortal outputs = output_values.GetPortalControl();
+
+    VTKM_TEST_ASSERT(outputs.GetNumberOfValues() == NUM_KEYS,
+                     "Unexpected number of output values from ReduceByKey.");
+
+    for (vtkm::Id i = 0; i < NUM_KEYS; ++i)
+    {
+      VTKM_TEST_ASSERT(outputs.Get(i) == refData[i],
+                       "Unexpected output value after ReduceByKey.");
+    }
+  }
+
+  void TestPrepareExceptions()
+  {
+    DiscardHandle handle;
+    handle.Allocate(50);
+
+    try
+    {
+      handle.PrepareForInput(DeviceTag());
+    }
+    catch (vtkm::cont::ErrorControlBadValue exp)
+    {
+      // Expected failure.
+    }
+
+    try
+    {
+      handle.PrepareForInPlace(DeviceTag());
+    }
+    catch (vtkm::cont::ErrorControlBadValue exp)
+    {
+      // Expected failure.
+    }
+
+    // Shouldn't fail:
+    handle.PrepareForOutput(ARRAY_SIZE, DeviceTag());
+  }
+
+  void operator()()
+  {
+    TestReduceByKey();
+    TestPrepareExceptions();
+  }
+};
+
+void TestArrayHandleDiscard()
+{
+  Test<vtkm::UInt8>()();
+  Test<vtkm::Int16>()();
+  Test<vtkm::Int32>()();
+  Test<vtkm::Int64>()();
+  Test<vtkm::Float32>()();
+  Test<vtkm::Float64>()();
+}
+
+} // end namespace UnitTestArrayHandleDiscardDetail
+
+int UnitTestArrayHandleDiscard(int, char *[])
+{
+  using namespace UnitTestArrayHandleDiscardDetail;
+  return vtkm::cont::testing::Testing::Run(TestArrayHandleDiscard);
+}