PY: Added NeighborList python bindings (#1314)

* Added NeighborList python bindings
* Added example test script
* Added loop example
* Added dtype property to NeighborList bindings
* Added NeighborList python documentation

Signed-off-by: Jared Duffey <[email protected]>

---------

Signed-off-by: Jared Duffey <[email protected]>

Author: JDuffeyBQ

src/Plugins/SimplnxCore/wrapping/python/simplnxpy.cpp

@@ -25,6 +25,7 @@
 #include <simplnx/DataStructure/Geometry/TetrahedralGeom.hpp>
 #include <simplnx/DataStructure/Geometry/TriangleGeom.hpp>
 #include <simplnx/DataStructure/Geometry/VertexGeom.hpp>
+#include <simplnx/DataStructure/NeighborList.hpp>
 #include <simplnx/DataStructure/StringArray.hpp>
 #include <simplnx/Filter/Actions/CopyArrayInstanceAction.hpp>
 #include <simplnx/Filter/Actions/CopyDataObjectAction.hpp>
@@ -209,6 +210,35 @@ auto BindDataArray(py::handle scope, const char* name)
 #define SIMPLNX_PY_BIND_DATA_STORE(scope, className) BindDataStore<className::value_type>(scope, #className)
 #define SIMPLNX_PY_BIND_ABSTRACT_DATA_STORE(scope, className) SIMPLNX_PY_BIND_CLASS_VARIADIC(scope, className, IDataStore, std::shared_ptr<className>)
 
+template <class T>
+auto BindNeighborList(py::handle scope, const char* name)
+{
+  using NeighborListType = NeighborList<T>;
+
+  auto neighborList = py::class_<NeighborListType, INeighborList, std::shared_ptr<NeighborListType>>(scope, name);
+  neighborList.def_property_readonly_static("dtype", []([[maybe_unused]] py::object self) { return py::dtype::of<T>(); });
+  neighborList.def("get_list", &NeighborListType::getList, "grain_id"_a);
+  neighborList.def("set_list", py::overload_cast<int32, const typename NeighborListType::VectorType&>(&NeighborListType::setList), "grain_id"_a, "neighbor_list"_a);
+  neighborList.def(
+      "get_value",
+      [](const NeighborListType& self, int32 grainId, int32 index) {
+        bool ok = false;
+        int32 value = self.getValue(grainId, index, ok);
+        if(!ok)
+        {
+          throw std::out_of_range(fmt::format("NeighborList.get_value called with grain_id = {} and index = {} which was out of range", grainId, index));
+        }
+        return value;
+      },
+      "grain_id"_a, "index"_a);
+  neighborList.def("add_entry", &NeighborListType::addEntry, "grain_id"_a, "value"_a);
+  neighborList.def("get_list_size", &NeighborListType::getListSize, "grain_id"_a);
+  neighborList.def("get_number_of_lists", &NeighborListType::getNumberOfLists);
+  return neighborList;
+}
+
+#define SIMPLNX_PY_BIND_NEIGHBOR_LIST(scope, className) BindNeighborList<className::value_type>(scope, #className)
+
 template <class GeomT>
 auto BindCreateGeometry2DAction(py::handle scope, const char* name)
 {
@@ -1026,6 +1056,19 @@ PYBIND11_MODULE(simplnx, mod)
   stringArray.def_property_readonly("values", &StringArray::values);
   stringArray.def("resize_tuples", &StringArray::resizeTuples, "Resize the tuples with the given shape");
 
+  auto iNeighborList = py::class_<INeighborList, IArray, std::shared_ptr<INeighborList>>(mod, "INeighborList");
+
+  auto neighborListInt8 = SIMPLNX_PY_BIND_NEIGHBOR_LIST(mod, Int8NeighborList);
+  auto neighborListUInt8 = SIMPLNX_PY_BIND_NEIGHBOR_LIST(mod, UInt8NeighborList);
+  auto neighborListInt16 = SIMPLNX_PY_BIND_NEIGHBOR_LIST(mod, Int16NeighborList);
+  auto neighborListUInt16 = SIMPLNX_PY_BIND_NEIGHBOR_LIST(mod, UInt16NeighborList);
+  auto neighborListInt32 = SIMPLNX_PY_BIND_NEIGHBOR_LIST(mod, Int32NeighborList);
+  auto neighborListUInt32 = SIMPLNX_PY_BIND_NEIGHBOR_LIST(mod, UInt32NeighborList);
+  auto neighborListInt64 = SIMPLNX_PY_BIND_NEIGHBOR_LIST(mod, Int64NeighborList);
+  auto neighborListUInt64 = SIMPLNX_PY_BIND_NEIGHBOR_LIST(mod, UInt64NeighborList);
+  auto neighborListFloat32 = SIMPLNX_PY_BIND_NEIGHBOR_LIST(mod, Float32NeighborList);
+  auto neighborListFloat64 = SIMPLNX_PY_BIND_NEIGHBOR_LIST(mod, Float64NeighborList);
+
   auto dataArrayInt8 = SIMPLNX_PY_BIND_DATA_ARRAY(mod, Int8Array);
   auto dataArrayUInt8 = SIMPLNX_PY_BIND_DATA_ARRAY(mod, UInt8Array);
   auto dataArrayInt16 = SIMPLNX_PY_BIND_DATA_ARRAY(mod, Int16Array);

wrapping/python/docs/source/DataObjects.rst

@@ -366,6 +366,75 @@ DataStore Example Usage
    # The developer can also just inline the above lines into a single line
    npdata = data_structure[output_array_path].store.npview
 
+
+.. _NeighborList:
+
+NeighborList
+-----------
+
+.. py:class:: NeighborList[T]
+
+   .. py:property:: tuple_shape
+      :type: list[int]
+
+      The dimensions of the NeighborList from slowest to fastest (C Ordering)
+
+   .. py:property:: component_shape
+      :type: list[int]
+
+      The dimensions of the components of the NeighborList from slowest to fastest (C Ordering)
+
+   .. py:property:: dtype
+      :type: numpy.dtype
+
+      The type of the NeighborList elements
+
+   .. py:method:: get_list(grain_id: int) -> list[T]
+
+      Returns the target neighbor list.
+
+      :param int grain_id: The grain id of the target list
+      :return: The target list
+      :rtype: list[T]
+
+   .. py:method:: set_list(grain_id: int, neighbor_list: list[T])
+
+      Set the target neighbor list to the given list.
+
+      :param int grain_id: The grain id of the target list
+      :param list[T] neighbor_list: The replacement list
+
+   .. py:method:: get_value(grain_id: int, index: int) -> T
+
+      Returns the value at the given index in the target neighbor list.
+
+      :param int grain_id: The grain id of the target list
+      :param int index: The index into the target list
+      :return: The target value
+      :rtype: T
+
+   .. py:method:: add_entry(grain_id: int, value: T)
+
+      Appends the given value to the target neighbor list.
+
+      :param int grain_id: The grain id of the target list
+      :param T value: The value to append
+
+   .. py:method:: get_list_size(grain_id: int) -> int
+
+      Returns the size of the target neighbor list.
+
+      :param int grain_id: The grain id of the target list
+      :return: The target list size
+      :rtype: int
+
+   .. py:method:: get_number_of_lists() -> int
+
+      Returns the total number of lists.
+
+      :return: The total number of lists
+      :rtype: int
+
 .. _AttributeMatrix:
 
 AttributeMatrix

wrapping/python/examples/scripts/SourceList.cmake

@@ -14,6 +14,7 @@ set(SIMPLNX_PYTHON_TESTS
   "output_file" 
   "pipeline" 
   "read_csv_file"
+  "neighbor_list"
 #  "read_esprit_data"
 )
 

wrapping/python/examples/scripts/neighbor_list.py

@@ -0,0 +1,34 @@
+import simplnx as nx
+
+ds = nx.DataStructure()
+
+SIZE = 42
+PATH = nx.DataPath(['foo'])
+
+action = nx.CreateNeighborListAction(nx.DataType.int32, SIZE, PATH)
+
+assert action.apply(ds, nx.IDataAction.Mode.Execute)
+
+nl: nx.Int32NeighborList = ds[PATH]
+assert nl.get_number_of_lists() == SIZE
+
+INDEX = 2
+
+# get_list returns a copy
+assert nl.get_list(INDEX) == []
+assert nl.get_list_size(INDEX) == 0
+
+VALUE = 4
+
+nl.add_entry(INDEX, VALUE)
+
+assert nl.get_list(INDEX) == [VALUE]
+assert nl.get_list_size(INDEX) == 1
+
+for i in range(3):
+  nl.add_entry(1, i)
+
+for grain_id in range(nl.get_number_of_lists()):
+  print(f'grain_id={grain_id}')
+  for value in nl.get_list(grain_id):
+    print(value)