Tutorial improvements (#162)

* explaining Python version check

* commenting future Tutorials

* commenting missing

* adding Changelog

* more tests

* improve ModelPart C tutorial

* minor

* adding ModelPart tutorial for C++

* adding python ModelPart tutorial

* switch order

* proper fix

* Update test_model_part.c

Author: philbucher

CHANGELOG.md

@@ -0,0 +1,29 @@
+# Changelog
+
+All important and notable changes in the _CoSimIO_ will be documented in this file.
+
+## 2.0.0
+- Changes in Connecting:
+    - Now instead of specifying `connection_name` directly, `my_name` and `connect_to` are used for the call to `Connect`.
+    - The `CoSimIO::Info` that is returned from `Connect` now contains the `connection_name` that needs to be used in subsequent calls to _CoSimIO_.
+    - This change was done to make the connection more robust and to make the selection of primary/secondary partner clear. This is only used internally e.g. for who opens a port and who connects to it.
+- Introduced `CoSimIO::ModelPart` for exchanging of meshes
+    - Simplified version of [`Kratos::ModelPart`](https://github.com/KratosMultiphysics/Kratos/blob/master/kratos/includes/model_part.h)
+    - Simplifies and unifies the usage of `Import-/ExportMesh`
+    - See the tutorials on how to use it:
+        - [C++](tutorial/cpp/model_part.md)
+        - [C](tutorial/c/model_part.md)
+        - [Python](tutorial/python/model_part.md)
+- FileCommunication:
+    - By default now done in folder. This way leftovers from previous simulations can be easily deleted (done automatically).
+    - working directory can be specified
+    - stability of initial connection was significantly improved.
+- Python interface: Data is no longer copied when going from Python to C++ and vice versa.
+    - `Import-/ExportData` now uses `CoSimIO::DoubleVector` (small wrapper around `std::wrapper`)
+    - `Import-/ExportMesh` now uses `CoSimIO::ModelPart`
+- Continuous Integration:
+    - Adding Python 3.9 (now has Python v3.5 - v3.9)
+    - Adding CentOS 7 build with GCC 4.8.5
+    - Enforcing C89 standard
+
+- Many improvements and cleanups under the hood

co_sim_io/c/co_sim_io_c.cpp

@@ -290,7 +290,7 @@ double CoSimIO_Node_Z(CoSimIO_Node I_Node)
 
 double CoSimIO_Node_Coordinate(CoSimIO_Node I_Node, const int I_Index)
 {
-    // add debug error if I_Index is out of bound (admissible values: 0,1,2)
+    // TODO add debug error if I_Index is out of bound (admissible values: 0,1,2)
     return static_cast<CoSimIO::Node*>(I_Node.PtrCppNode)->Coordinates()[I_Index];
 }
 

tests/co_sim_io/c/model_part/test_model_part.c

@@ -20,6 +20,8 @@ int main()
     /* declaring variables */
     int i;
     int connectivity[2];
+    CoSimIO_Node node;
+    CoSimIO_Element elem;
     CoSimIO_ModelPart model_part;
 
     model_part = CoSimIO_CreateModelPart("my_model_part");
@@ -37,6 +39,16 @@ int main()
             -i);
     }
 
+    /* iterate the nodes */
+    for (i=0; i<CoSimIO_ModelPart_NumberOfNodes(model_part); ++i) {
+        node = CoSimIO_ModelPart_GetNodeByIndex(model_part, i);
+        COSIMIO_CHECK_INT_EQUAL(CoSimIO_Node_Id(node), i+1);
+    }
+
+    /* get a specific node by Id */
+    node = CoSimIO_ModelPart_GetNodeById(model_part, 3);
+    COSIMIO_CHECK_INT_EQUAL(CoSimIO_Node_Id(node), 3);
+
     COSIMIO_CHECK_INT_EQUAL(CoSimIO_ModelPart_NumberOfNodes(model_part), 4);
     COSIMIO_CHECK_INT_EQUAL(CoSimIO_ModelPart_NumberOfElements(model_part), 0);
 
@@ -50,6 +62,16 @@ int main()
             connectivity);
     }
 
+    /* iterate the elements */
+    for (i=0; i<CoSimIO_ModelPart_NumberOfElements(model_part); ++i) {
+        elem = CoSimIO_ModelPart_GetElementByIndex(model_part, i);
+        COSIMIO_CHECK_INT_EQUAL(CoSimIO_Element_Id(elem), i+1)
+    }
+
+    /* get a specific element by Id */
+    elem = CoSimIO_ModelPart_GetElementById(model_part, 1);
+    COSIMIO_CHECK_INT_EQUAL(CoSimIO_Element_Id(elem), 1);
+
     COSIMIO_CHECK_INT_EQUAL(CoSimIO_ModelPart_NumberOfNodes(model_part), 4);
     COSIMIO_CHECK_INT_EQUAL(CoSimIO_ModelPart_NumberOfElements(model_part), 2);
 

tests/co_sim_io/impl/test_model_part.cpp

@@ -413,7 +413,7 @@ TEST_CASE("model_part_ostream")
 
     SUBCASE("with_entities")
     {
-        const int node_ids[] = {2, 159, 61};
+        const std::vector<IdType> node_ids {2, 159, 61};
         const std::array<double, 3> node_coords = {1.0, -2.7, 9.44};
         model_part.CreateNewNode(node_ids[0], node_coords[0], node_coords[1], node_coords[2]);
         model_part.CreateNewNode(node_ids[1], node_coords[1], node_coords[2], node_coords[0]);

tutorial/c/README.md

@@ -14,10 +14,10 @@ This tutorial helps you to integrate the _CoSimIO_ into a solver/software-tool u
   - [Tutorial 5: Mesh Exchange](#tutorial-5-mesh-exchange)
   - [Tutorial 6: Kratos CoSimulation Library Overview](#tutorial-6-kratos-cosimulation-library-overview)
   - [Tutorial 7: Building Kratos with CoSimulation](#tutorial-7-building-kratos-with-cosimulation)
-  - [Tutorial 8: Connecting/Disconnecting to/from Kratos](#tutorial-8-connectingdisconnecting-tofrom-kratos)
+  <!-- - [Tutorial 8: Connecting/Disconnecting to/from Kratos](#tutorial-8-connectingdisconnecting-tofrom-kratos)
   - [Tutorial 9: Data Exchange with Kratos](#tutorial-9-data-exchange-with-kratos)
   - [Tutorial 10: Mesh Exchange with Kratos](#tutorial-10-mesh-exchange-with-kratos)
-  - [Tutorial 11: Mapping with Kratos](#tutorial-11-mapping-with-kratos)
+  - [Tutorial 11: Mapping with Kratos](#tutorial-11-mapping-with-kratos) -->
 
 ## What you need
 - Downloading the _CosimIO_ from the repository:
@@ -215,40 +215,13 @@ After seeing how we transfer raw data between solvers/software-tools, it is time
 CoSimIO_Info export_settings = CoSimIO_CreateInfo();
 CoSimIO_Info_SetString(export_settings, "identifier", "fluid_mesh");
 CoSimIO_Info_SetString(export_settings, "connection_name", connection_name); // connection_name is obtained from calling "Connect"
-CoSimIO_Info export_info = CoSimIO_ExportMesh(export_settings, model_part);
-```
-
-The argument `model_part` is a container for mesh, it contains nodes and elements. Check the [implementation](../../co_sim_io/c/co_sim_io_c_model_part.h) and the [tests](../../tests/co_sim_io/c/model_part/test_model_part.c) for details of `CoSimIO::ModelPart`.
-
-Nodes can be created like this:
-```c
-CoSimIO_ModelPart model_part = CoSimIO_CreateModelPart("my_model_part");
-
-CoSimIO_ModelPart_CreateNewNode(
-    model_part,
-    1,    // Id
-    0.0,  // X-Coordinate
-    1.5,  // Y-Coordinate
-    -4.22 // Z-Coordinate
-);
-```
 
-Elements can be created after nodes were created:
-```c
-int connectivity[2] = {1,2};
+CoSimIO_ModelPart model_part = CoSimIO_CreateModelPart("name_of_model_part_to_export");
 
-CoSimIO_ModelPart_CreateNewElement(
-    model_part,
-    2, // Id
-    CoSimIO_Line2D2, // Type of element, see "co_sim_io/c/co_sim_io_c_model_part.h"
-    connectivity // Connectivity information, i.e. Ids of nodes that the element has
-);
+CoSimIO_Info export_info = CoSimIO_ExportMesh(export_settings, model_part);
 ```
 
-Don't forget to free the `CoSimIO_ModelPart` after using it with
-```c
-CoSimIO_FreeModelPart(model_part);
-```
+The argument `model_part` is of type `CoSimIO_ModelPart`. Its usage is explained [here](model_part.md).
 
 On the other side one can use the `ImportMesh()` method to get the mesh sent by the export:
 
@@ -257,6 +230,8 @@ CoSimIO_Info import_settings=CoSimIO_CreateInfo();
 CoSimIO_Info_SetString(import_settings, "identifier", "fluid_mesh");
 CoSimIO_Info_SetString(import_settings, "connection_name", connection_name); // connection_name is obtained from calling "Connect"
 
+CoSimIO_ModelPart model_part = CoSimIO_CreateModelPart("name_of_imported_model_part");
+
 CoSimIO_Info import_info = CoSimIO_ImportMesh(import_settings, model_part);
 ```
 
@@ -268,10 +243,10 @@ The overview of the Kratos CoSimulation Library can be found [here](../README.md
 
 ## Tutorial 7: Building Kratos with CoSimulation
 The building instructions for the Kratos CoSimulation Library can be found [here](../README.md#building-kratos-with-cosimulation).
-
+<!--
 ## Tutorial 8: Connecting/Disconnecting to/from Kratos
 coming soon!
-<!-- For connecting to Kratos it is very important to have in mind that Kratos also uses *CoSimIO* for interprocess communication so its python interface reflects the CoSimIO. So we may create a python script for connecting and disconnecting in the same way described in the [python tutorial](https://github.com/KratosMultiphysics/CoSimIO/blob/master/tutorial/python/README.md):
+For connecting to Kratos it is very important to have in mind that Kratos also uses *CoSimIO* for interprocess communication so its python interface reflects the CoSimIO. So we may create a python script for connecting and disconnecting in the same way described in the [python tutorial](https://github.com/KratosMultiphysics/CoSimIO/blob/master/tutorial/python/README.md):
 
 ```Python
 from KratosMultiphysics.CoSimulationApplication import CoSimIO
@@ -297,11 +272,11 @@ Then you may run your executable with python script of Kratos from your working
 
 ```shell
 path/to/bin/tests_c/connect_disconnect_c_test & python3 path/to/connect_disconnect.py
-``` -->
+```
 
 ## Tutorial 9: Data Exchange with Kratos
 coming soon!
-<!-- Here we try to send some data to Kratos and get it back from it. Then we can check if both data are the same. Again the python file for Kratos side is very similar to the one descirbed in the [python tutorial](https://github.com/KratosMultiphysics/CoSimIO/blob/master/tutorial/python/README.md):
+Here we try to send some data to Kratos and get it back from it. Then we can check if both data are the same. Again the python file for Kratos side is very similar to the one descirbed in the [python tutorial](https://github.com/KratosMultiphysics/CoSimIO/blob/master/tutorial/python/README.md):
 
 
 ```python
@@ -375,11 +350,11 @@ Now for running the test:
 
 ```shell
 path/to/bin/tests_c/export_import_data_c_test & python3 path/to/import_export_data.py
-``` -->
+```
 
 ## Tutorial 10: Mesh Exchange with Kratos
 coming soon!
-<!-- In this step we send a mesh to Kratos and receive it back and we will check if they are the same. (like previous tutorial with data).
+In this step we send a mesh to Kratos and receive it back and we will check if they are the same. (like previous tutorial with data).
 
 Recalling from what we had in tutorial 5 we just merge the export mesh and import mesh codes into one as we did for data exchage in previous tutorial:
 
@@ -505,11 +480,11 @@ Now for running the test:
 
 ```shell
 path/to/bin/tests_c/export_import_mesh_c_test & python3 path/to/import_export_mesh.py
-``` -->
+```
 
 ## Tutorial 11: Mapping with Kratos
 coming soon!
-<!-- This tutorial shows how to map data between (non matching) meshes with Kratos. It is based on tutorials 9 & 10.
+This tutorial shows how to map data between (non matching) meshes with Kratos. It is based on tutorials 9 & 10.
 
 In this tutorial we first send two meshes based on the same geometry but with different discretizations to Kratos. Those meshes are used as basis for the mapping. In Kratos teminology those are the origin and the destination.
 

tutorial/c/model_part.md

@@ -0,0 +1,121 @@
+# ModelPart
+
+The `ModelPart` is a container for mesh, it contains nodes and elements.
+It is a simplified version of [`Kratos::ModelPart`](https://github.com/KratosMultiphysics/Kratos/blob/master/kratos/includes/model_part.h).
+
+### Interface of _CoSimIO_ModelPart_
+Create and free a `ModelPart` like this:
+```c
+// create CoSimIO_ModelPart
+CoSimIO_ModelPart model_part = CoSimIO_CreateModelPart("my_model_part");
+
+// use model_part
+// ...
+
+// access the name of the ModelPart:
+const char* name = CoSimIO_ModelPart_Name(model_part);
+
+// don't forget to free it after using it
+CoSimIO_FreeModelPart(model_part);
+```
+
+Nodes can be created like this:
+```c
+// memory of node is managed by model_part!
+CoSimIO_Node node = CoSimIO_ModelPart_CreateNewNode(
+    model_part,
+    1,    // Id
+    0.0,  // X-Coordinate
+    1.5,  // Y-Coordinate
+    -4.22 // Z-Coordinate
+);
+```
+
+Elements can be created after nodes were created:
+```c
+int connectivity[2] = {1,2}; // Ids of the Nodes
+
+// memory of element is managed by model_part!
+CoSimIO_Element element = CoSimIO_ModelPart_CreateNewElement(
+    model_part,
+    2, // Id
+    CoSimIO_Line2D2, // Type of element, see "co_sim_io/c/co_sim_io_c_model_part.h"
+    connectivity // Connectivity information, i.e. Ids of nodes that the element has
+);
+```
+
+Use the following functions to get the number of nodes and elements:
+```c
+int number_of_nodes = CoSimIO_ModelPart_NumberOfNodes(model_part);
+
+int number_of_elements = CoSimIO_ModelPart_NumberOfElements(model_part);
+```
+
+The nodes and elements can be iterated with:
+```c
+// iterate nodes
+for (int i=0; i<CoSimIO_ModelPart_NumberOfNodes(model_part); ++i) {
+    CoSimIO_Node node = CoSimIO_ModelPart_GetNodeByIndex(model_part, i);
+    // do sth with node
+}
+
+// iterate elements
+for (int i=0; i<CoSimIO_ModelPart_NumberOfElements(model_part); ++i) {
+    CoSimIO_Element element = CoSimIO_ModelPart_GetElementByIndex(model_part, i);
+    // do sth with element
+}
+```
+
+Nodes and elements can also be accessed by Id:
+```c
+// get the node with Id 3
+CoSimIO_Node node = CoSimIO_ModelPart_GetNodeById(model_part, 3);
+
+// get the element with Id 12
+CoSimIO_Element element = CoSimIO_ModelPart_GetElementById(model_part, 12);
+```
+
+Removing all nodes and elements can be done with the following:
+```c
+// removing all nodes and elements
+CoSimIO_ModelPart_Clear(model_part);
+```
+
+### Interface of _CoSimIO_Node_
+The _CoSimIO_Node_ an be used in the following way:
+```c
+// access Id of node:
+int node_id = CoSimIO_Node_Id(node);
+
+// access the coordinates:
+double node_x = CoSimIO_Node_X(node);
+double node_y = CoSimIO_Node_Y(node);
+double node_z = CoSimIO_Node_Z(node);
+
+// or with index:
+double node_x_idx = CoSimIO_Node_Coordinate(node, 0);
+double node_y_idx = CoSimIO_Node_Coordinate(node, 1);
+double node_z_idx = CoSimIO_Node_Coordinate(node, 2);
+```
+
+### Interface of _CoSimIO_Element_
+The _CoSimIO_Element_ provides the following interface:
+```c
+// access Id of element:
+int element_id = CoSimIO_Element_Id(element);
+
+// the type can be accessed:
+CoSimIO_ElementType element_type = CoSimIO_Element_Type(element); // e.g. CoSimIO_Point3D or CoSimIO_Tetrahedra3D4
+
+// number of nodes of the element:
+int num_nodes_element = CoSimIO_Element_NumberOfNodes(element);
+
+// iterate the nodes of the element:
+for (int i=0; i<CoSimIO_Element_NumberOfNodes(element); ++i) {
+    CoSimIO_Node node = CoSimIO_Element_GetNodeByIndex(element, i);
+    // do sth with node
+}
+```
+
+### Further information
+For more information check the [implementation](../../co_sim_io/c/co_sim_io_c_model_part.h) and the [tests](../../tests/co_sim_io/c/model_part/test_model_part.c).