From d507f0ef68931579f1cc1f2db6bd067286d7f0a1 Mon Sep 17 00:00:00 2001 From: Ishaan Desai Date: Sun, 15 Jun 2025 14:40:24 +0200 Subject: [PATCH 1/3] Modify docstrings to clearly state the flexibility of the API in accepting multidimensional data structures --- cyprecice/cyprecice.pyx | 36 ++++++++++++++++++++++++++++-------- 1 file changed, 28 insertions(+), 8 deletions(-) diff --git a/cyprecice/cyprecice.pyx b/cyprecice/cyprecice.pyx index 29120a2c..3fe54831 100644 --- a/cyprecice/cyprecice.pyx +++ b/cyprecice/cyprecice.pyx @@ -401,6 +401,7 @@ cdef class Participant: positions : array_like The coordinates of the vertices in a numpy array [N x D] where N = number of vertices and D = dimensions of geometry. + A list of the same shape is also accepted. Returns ------- @@ -496,6 +497,7 @@ cdef class Participant: vertices : array_like The IDs of the vertices in a numpy array [N x 2] where N = number of edges and D = dimensions of geometry. + A list of the same shape is also accepted. Examples -------- @@ -557,6 +559,7 @@ cdef class Participant: vertices : array_like The IDs of the vertices in a numpy array [N x 3] where N = number of triangles and D = dimensions of geometry. + A list of the same shape is also accepted. Examples -------- @@ -621,6 +624,7 @@ cdef class Participant: vertices : array_like The IDs of the vertices in a numpy array [N x 4] where N = number of quads and D = dimensions of geometry. + A list of the same shape is also accepted. Examples -------- @@ -685,6 +689,7 @@ cdef class Participant: vertices : array_like The IDs of the vertices in a numpy array [N x 4] where N = number of quads and D = dimensions of geometry. + A list of the same shape is also accepted. Examples -------- @@ -794,6 +799,13 @@ cdef class Participant: >>> vertex_ids = [1, 2, 3, 4, 5] >>> values = np.array([[v1_x, v1_y, v1_z], [v2_x, v2_y, v2_z], [v3_x, v3_y, v3_z], [v4_x, v4_y, v4_z], [v5_x, v5_y, v5_z]]) >>> participant.write_data(mesh_name, data_name, vertex_ids, values) + + Write vector data for a 3D (D=3) problem with 5 (N=5) vertices, where the values are provided as a list of tuples: + >>> mesh_name = "MeshOne" + >>> data_name = "DataOne" + >>> vertex_ids = [1, 2, 3, 4, 5] + >>> values = [(v1_x, v1_y, v1_z), (v2_x, v2_y, v2_z), (v3_x, v3_y, v3_z), (v4_x, v4_y, v4_z), (v5_x, v5_y, v5_z)] + >>> participant.write_data(mesh_name, data_name, vertex_ids, values) """ check_array_like(vertex_ids, "vertex_ids", "write_data") check_array_like(values, "values", "write_data") @@ -934,8 +946,14 @@ cdef class Participant: >>> coordinates = np.array([[c1_x, c1_y], [c2_x, c2_y], [c3_x, c3_y], [c4_x, c4_y], [c5_x, c5_y]]) >>> values = np.array([v1, v2, v3, v4, v5]) >>> participant.write_and_map_data(mesh_name, data_name, coordinates, values) - """ + Write scalar data for a 2D problem with 5 vertices, where the coordinates are provided as a list of tuples, and the values are provided as a list of scalars: + >>> mesh_name = "MeshOne" + >>> data_name = "DataOne" + >>> coordinates = [(c1_x, c1_y), (c2_x, c2_y), (c3_x, c3_y), (c4_x, c4_y), (c5_x, c5_y)] + >>> values = [v1, v2, v3, v4, v5] + >>> participant.write_and_map_data(mesh_name, data_name, coordinates, values) + """ check_array_like(coordinates, "coordinates", "write_and_map_data") check_array_like(values, "values", "write_and_map_data") @@ -988,7 +1006,6 @@ cdef class Participant: >>> values.shape >>> (2, ) """ - check_array_like(coordinates, "coordinates", "map_and_read_data") if not isinstance(coordinates, np.ndarray): @@ -1045,6 +1062,13 @@ cdef class Participant: >>> gradients = np.array([[v1x_dx, v1y_dx, v1x_dy, v1y_dy], [v2x_dx, v2y_dx, v2x_dy, v2y_dy]]) >>> participant.write_gradient_data(mesh_name, data_name, vertex_ids, gradients) + Write gradient vector data for a 2D problem with 2 vertices, where the gradients are provided as a list of tuples: + >>> mesh_name = "MeshOne" + >>> data_name = "DataOne" + >>> vertex_ids = [1, 2] + >>> gradients = [(v1x_dx, v1y_dx, v1x_dy, v1y_dy), (v2x_dx, v2y_dx, v2x_dy, v2y_dy)] + >>> participant.write_gradient_data(mesh_name, data_name, vertex_ids, gradients) + Write vector data for a 3D problem with 2 vertices: >>> mesh_name = "MeshOne" >>> data_name = "DataOne" @@ -1072,7 +1096,6 @@ cdef class Participant: self.thisptr.writeGradientData (convert(mesh_name), convert(data_name), cpp_vertex_ids, cpp_gradients) - def requires_gradient_data_for(self, mesh_name, data_name): """ Checks if the given data set requires gradient data. We check if the data object has been intialized with the gradient flag. @@ -1096,11 +1119,9 @@ cdef class Participant: >>> data_name = "DataOne" >>> participant.is_gradient_data_required(mesh_name, data_name) """ - return self.thisptr.requiresGradientDataFor(convert(mesh_name), convert(data_name)) - - def set_mesh_access_region (self, mesh_name, bounding_box): + def set_mesh_access_region(self, mesh_name, bounding_box): """ This function is required if you don't want to use the mapping schemes in preCICE, but rather want to use your own solver for data mapping. As opposed to the usual preCICE mapping, only a @@ -1156,8 +1177,7 @@ cdef class Participant: self.thisptr.setMeshAccessRegion(convert(mesh_name), cpp_bounding_box) - - def get_mesh_vertex_ids_and_coordinates (self, mesh_name): + def get_mesh_vertex_ids_and_coordinates(self, mesh_name): """ Iterating over the region of interest defined by bounding boxes and reading the corresponding coordinates omitting the mapping. This function is still experimental. From 73260a937c9bda0e85d28df25df6dc683b86487f Mon Sep 17 00:00:00 2001 From: Ishaan Desai Date: Sun, 15 Jun 2025 15:07:27 +0200 Subject: [PATCH 2/3] Modify set_mesh_vertices docstring and add changelog entry --- CHANGELOG.md | 1 + cyprecice/cyprecice.pyx | 10 ++++++++++ 2 files changed, 11 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 171668ad..76c96395 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,7 @@ All notable changes to this project will be documented in this file. ## latest +* Modify docstrings to higlight flexbility of the API in terms of its ability to handle multidimensional input data structures https://github.com/precice/python-bindings/pull/239 * Fix bug in `map_and_read_data` https://github.com/precice/python-bindings/pull/237 ## 3.2.0 diff --git a/cyprecice/cyprecice.pyx b/cyprecice/cyprecice.pyx index 3fe54831..e81794c2 100644 --- a/cyprecice/cyprecice.pyx +++ b/cyprecice/cyprecice.pyx @@ -436,6 +436,16 @@ cdef class Participant: >>> vertex_ids = participant.set_mesh_vertices(mesh_name, positions) >>> vertex_ids.shape (5,) + + Set mesh vertices for a 3D problem with 5 mesh vertices, where the positions are a list of tuples. + + >>> positions = [(1, 1, 1), (2, 2, 2), (3, 3, 3), (4, 4, 4), (5, 5, 5)] + >>> positions.shape + (5, 3) + >>> mesh_name = "MeshOne" + >>> vertex_ids = participant.set_mesh_vertices(mesh_name, positions) + >>> vertex_ids.shape + (5,) """ check_array_like(positions, "positions", "set_mesh_vertices") From 56c964756cdc1b5285454c6959fff9d13779db8a Mon Sep 17 00:00:00 2001 From: Ishaan Desai Date: Mon, 16 Jun 2025 12:27:06 +0200 Subject: [PATCH 3/3] Add list of tuples input example to read_and_map_data --- cyprecice/cyprecice.pyx | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/cyprecice/cyprecice.pyx b/cyprecice/cyprecice.pyx index e81794c2..06095e46 100644 --- a/cyprecice/cyprecice.pyx +++ b/cyprecice/cyprecice.pyx @@ -1010,6 +1010,15 @@ cdef class Participant: Read scalar data for a 2D problem with 2 vertices: >>> mesh_name = "MeshOne" >>> data_name = "DataOne" + >>> coordinates = np.array([[1.0, 1.0], [2.0, 2.0]]) + >>> dt = 1.0 + >>> values = map_and_read_data(mesh_name, data_name, coordinates, dt) + >>> values.shape + >>> (2, ) + + Read scalar data for a 2D problem with 2 vertices, where the coordinates are provided as a list of tuples: + >>> mesh_name = "MeshOne" + >>> data_name = "DataOne" >>> coordinates = [(1.0, 1.0), (2.0, 2.0)] >>> dt = 1.0 >>> values = map_and_read_data(mesh_name, data_name, coordinates, dt)