Merge pull request #59 from precice/matlab-bindings-v3.2.0

Release v3.2.0

Author: IshaanDesai

+precice/@Participant/Participant.m

@@ -247,7 +247,6 @@ function writeData(obj,meshName,dataName,valueIndices,values)
             end
             inSize = length(valueIndices);
             values = preciceGateway(uint8(61),meshName,dataName,int32(inSize),valueIndices,relativeReadTime);
-            values = reshape(values,obj.getDataDimensions(meshName,dataName),[]);
         end
 
         % requiresGradientDataFor

+precice/@Participant/private/preciceGateway.cpp

@@ -304,7 +304,8 @@ class MexFunction: public matlab::mex::Function {
                 const TypedArray<double> relativeReadTime = inputs[5];
                 std::vector<double> values(size[0]*dim);
                 interface->readData(meshName,dataName,vertexIDs,relativeReadTime[0],values);
-                outputs[0] = factory.createArray<double>({1, size[0]*dim}, values.data(), values.data()+values.size());
+                assert(values.size() == dim*vertexIDs.size());
+                outputs[0] = factory.createArray<double>({dim, vertexIDs.size()}, values.data(), values.data()+values.size());
                 break;
             }
             case FunctionID::requiresGradientDataFor:
@@ -339,8 +340,8 @@ class MexFunction: public matlab::mex::Function {
                 size_t dim = interface->getMeshDimensions(meshName);
                 std::vector <double> positions(size[0]*dim);
                 interface->getMeshVertexIDsAndCoordinates(meshName,ids,positions);
-                outputs[0] = factory.createArray<int32_t>({size[0]}, ids.data(), ids.data()+ids.size());
-                outputs[1] = factory.createArray<double>({size[0], dim}, positions.data(), positions.data()+positions.size());
+                outputs[0] = factory.createArray<int32_t>({1, ids.size()}, ids.data(), ids.data()+ids.size());
+                outputs[1] = factory.createArray<double>({dim, ids.size()}, positions.data(), positions.data()+positions.size());
                 break;
             } 
 

.github/workflows/test.yml

@@ -13,81 +13,54 @@ jobs:
   test-solverdummies:
     name: Test MATLAB solverdummmies
     runs-on: ubuntu-latest
-    # container: precice/precice:develop # does not work somehow because of sudo
-    # see e.g. https://github.com/precice/matlab-bindings/actions/runs/4366307887/jobs/7636136347
+    container:
+      image: precice/precice:nightly
     strategy:
       fail-fast: true
       matrix:
         include:
-        - release: latest
+        # - release: latest  #   R2024b segfaults; 24.2.0.2863752 (R2024b) Update 5
+        - release: R2024a
         - release: R2023b
-        - release: R2023a
-        - release: R2022b
-        - release: R2022a
-        - release: R2021b
+        # - release: R2023a # throws an error: symbol lookup error: /usr/lib/x86_64-linux-gnu/libpython3.12.so: undefined symbol: XML_SetReparseDeferralEnabled
+        # - release: R2022b
+        # - release: R2022a
+        # - release: R2021b
         # - release: R2021a # throws an error: https://github.com/precice/matlab-bindings/pull/42
     steps:
-
-      - name: install precice
-        uses: precice/setup-precice-action@main
-        with:
-          precice-version: 'v3.1.0'
-
-      - name: Set up MATLAB
-        uses: matlab-actions/setup-matlab@v1
-        with: 
-          release: ${{ matrix.release }}
-
-      - name: Check out repository
-        uses: actions/checkout@v3
-
-      - name: Run compilation script
-        uses: matlab-actions/run-command@v1
-        with:
-          command: compile_matlab_bindings_for_precice
-
-      - name: Run Solverdummies
-        shell: bash
+      - name: Install Dependencies
         run: |
-          export LD_PRELOAD="/usr/lib/x86_64-linux-gnu/libstdc++.so.6:/usr/lib/x86_64-linux-gnu/libgfortran.so.5"
-          matlab -sd "./solverdummy" -batch "addpath('../'); solverdummy precice-config.xml SolverOne;" & matlab -sd "./solverdummy" -batch "addpath('../'); solverdummy precice-config.xml SolverTwo;"
-  
-  test-tutorial:
-    name: Test MATLAB Tutorials
-    runs-on: ubuntu-latest
-    strategy:
-      fail-fast: true
-      matrix:
-        include:
-        - release: latest
-        - release: R2023b
-        - release: R2023a
-        - release: R2022b
-        - release: R2022a
-        - release: R2021b
-        # - release: R2021a
-    steps:
-
-      - name: install precice
-        uses: precice/setup-precice-action@main
-        with:
-          precice-version: 'develop'
-
+          apt-get -qq update
+          apt-get -qq install wget
+          rm -rf /var/lib/apt/lists/*
       - name: Set up MATLAB
-        uses: matlab-actions/setup-matlab@v1
+        uses: matlab-actions/setup-matlab@v2
         with: 
           release: ${{ matrix.release }}
-
       - name: Check out repository
         uses: actions/checkout@v3
-
       - name: Run compilation script
-        uses: matlab-actions/run-command@v1
+        uses: matlab-actions/run-command@v2
         with:
           command: compile_matlab_bindings_for_precice
-
-      - name: Run Tutorials
+      #- name: Run Solverdummies
+      #  uses: matlab-actions/run-command@v2
+      #  env:
+      #    LD_PRELOAD: /usr/lib/x86_64-linux-gnu/libstdc++.so.6:/usr/lib/x86_64-linux-gnu/libgfortran.so.5
+      #  with:
+      #    startup-options: -sd examples/solverdummy
+      #    command: addpath('../..'), 
+      #    # not possible to run following two commands in parallel
+      #    solverdummy precice-config.xml SolverOne
+      #    solverdummy precice-config.xml SolverTwo
+      # workaround from https://github.com/matlab-actions/run-command/issues/53
+      - name: Get run-matlab-command
         run: |
-          export LD_PRELOAD="/usr/lib/x86_64-linux-gnu/libstdc++.so.6:/usr/lib/x86_64-linux-gnu/libgfortran.so.5"
-          matlab -sd "./tutorial/implicit" -batch "addpath('../../'); Solver_I;" & matlab -sd "./tutorial/implicit" -batch "addpath('../../'); Solver_U;"
-
+          wget -O /usr/local/bin/run-matlab-command https://ssd.mathworks.com/supportfiles/ci/run-matlab-command/v2/glnxa64/run-matlab-command
+          chmod +x /usr/local/bin/run-matlab-command
+      - name: Run Solverdummies
+        working-directory: examples/solverdummy
+        env:
+          LD_PRELOAD: /usr/lib/x86_64-linux-gnu/libstdc++.so.6:/usr/lib/x86_64-linux-gnu/libgfortran.so.5
+        run: | 
+          run-matlab-command "addpath('../..'), solverdummy precice-config.xml SolverOne" & run-matlab-command "addpath('../..'), solverdummy precice-config.xml SolverTwo"

Contents.m

@@ -1,5 +1,5 @@
 % MATLAB-bindings for coupling library preCICE
-% Version 3.1.0 (R2023b, R2023a, R2022b, R2022a, R2021b) 12-Apr-2024
+% Version 3.2.0 (R2024a, R2023b) 03-Apr-2025
 %
 % Files
 %   getVersionInformation - 

README.md

@@ -6,13 +6,15 @@ Note that the first two digits of the version number of the bindings indicate th
 
 ## Requirements
 
-MATLAB R2018a or later is required. The bindings are actively tested on versions R2023b, R2023a, R2022b, R2022a, and R2021b.
+MATLAB R2018a or later is required. The bindings are actively tested on versions R2024a and R2023b.
+
+⚠️Note that we currently observe problems in our CI pipeline for MATLAB R2024b and R2022b and older. If you are any active user of any of these versions, we would appreciate your feedback under [this issue](https://github.com/precice/matlab-bindings/issues/58)⚠️
 
 ## Restrictions
 
-- An issue causes MATLAB to crash upon SolverInterface initialization if precice was compiled with openmpi. This issue can be resolved by installing openmpi from source using the option `-disable-dlopen`. For reference, see e.g. [here](https://stackoverflow.com/questions/26901663/error-when-running-openmpi-based-library). Alternatively, the user can switch to a different MPI implementation, e.g. MPICH (other implementations were not tested). Note that for [using a different MPI implementation](https://precice.org/installation-source-advanced.html#mpi---build-precice-using-non-default-mpi-implementation) one has to specify the alternative implementation while building preCICE. For more information on this issue, please refer to https://github.com/precice/matlab-bindings/issues/19.
-- Currently, only one instance of the `SolverInterface` class can exist at the same time in a single MATLAB instance. If the user wishes to couple multiple participants based on MATLAB, he is supposed to start them in different MATLAB instances. If, for some reason, the user needs multiple instances of `SolverInterface`, he should use the OOP variant (Multiple instances of `SolverInterfaceOOP` can exist at the same time).
-- There is a known bug, if the `SolverInterface` destructor is called. For a possible workaround refer to https://github.com/precice/precice/issues/378. This issue is tracked in https://github.com/precice/matlab-bindings/issues/28.
+- An issue causes MATLAB to crash upon Participant initialization if preCICE was compiled with OpenMPI. This issue can be resolved by installing OpenMPI from source using the option `-disable-dlopen`. For reference, see e.g. [here](https://stackoverflow.com/questions/26901663/error-when-running-openmpi-based-library). Alternatively, the user can switch to a different MPI implementation, e.g. MPICH (other implementations were not tested). Note that for [using a different MPI implementation](https://precice.org/installation-source-advanced.html#mpi---build-precice-using-non-default-mpi-implementation) one has to specify the alternative implementation while building preCICE. For more information on this issue, please refer to https://github.com/precice/matlab-bindings/issues/19.
+- Currently, only one instance of the `Participant` class can exist at the same time in a single MATLAB instance. If the user wishes to couple multiple participants based on MATLAB, he is supposed to start them in different MATLAB instances. If, for some reason, the user needs multiple instances of `Participant`, he should use the OOP variant (Multiple instances of `ParticipantOOP` can exist at the same time).
+- There is a known bug, if the `Participant` destructor is called. For a possible workaround refer to https://github.com/precice/precice/issues/378. This issue is tracked in https://github.com/precice/matlab-bindings/issues/28.
 
 ## Compilation
 
@@ -34,7 +36,7 @@ To use the bindings, you have to add this folder (e.g. `/home/user/matlab-bindin
 
 ## Usage
 
-The API introduces a MATLAB wrapper class for the `SolverInterface` class and a namespace for the preCICE constants. They are accessible in MATLAB as `precice.SolverInterface` and `precice.constants` respectively.
+The API introduces a MATLAB wrapper class for the `Participant` class and a namespace for the preCICE constants. They are accessible in MATLAB as `precice.Participant` and `precice.constants` respectively.
 
 The function syntax is mostly identical to the syntax of the C++ API. The following things should be noted:
 
@@ -47,21 +49,26 @@ The function syntax is mostly identical to the syntax of the C++ API. The follow
 As an example, the C++ API function
 
 ```bash
-readBlockScalarData(int dataID, int size, const int *valueIndices, double *values)
+void readData(
+    ::precice::string_view          meshName, 
+    ::precice::string_view          dataName, 
+    ::precice::span<const VertexID> ids,
+    double                          relativeReadTime, 
+    ::precice::span<double>         values) const
 ```
 
 is found in the MATLAB bindings as
 
 ```bash
-values = readBlockScalarData(dataID, valueIndices)
+values = readData(meshName, dataName, ids, relativeReadTime)
 ```
 
 ## Out of process variant
 
-The C++ MEX API supports [out of process execution](https://de.mathworks.com/help/matlab/matlab_external/out-of-process-execution-of-c-mex-functions.html) of MEX functions. This feature is implemented in the class `precice.SolverInterfaceOOP`. This class works exactly like `precice.SolverInterface`. Internally, however, the gateway function that calls the preCICE routines is run on a `mexHost` object.
+The C++ MEX API supports [out of process execution](https://de.mathworks.com/help/matlab/matlab_external/out-of-process-execution-of-c-mex-functions.html) of MEX functions. This feature is implemented in the class `precice.ParticipantOOP`. This class works exactly like `precice.Participant`. Internally, however, the gateway function that calls the preCICE routines is run on a `mexHost` object.
 This has the following advantages:
 
-- Multiple instances of `SolverInterfaceOOP` can exist at the same time.
+- Multiple instances of `ParticipantOOP` can exist at the same time.
 - If the gateway function crashes, then MATLAB will not crash. Only the mexHost object will crash.
 However, using the OOP variant is **significantly** slower than the normal in process
 
@@ -70,8 +77,8 @@ However, using the OOP variant is **significantly** slower than the normal in pr
 ## `libprecice.so` cannot be found
 
 ```bash
-Invalid MEX-file 'SOMEPATH/matlab-bindings/+precice/@SolverInterface/private/preciceGateway.mexa64':
-libprecice.so.2: cannot open shared object file: No such file or directory.
+Invalid MEX-file 'SOMEPATH/matlab-bindings/+precice/@Participant/private/preciceGateway.mexa64':
+libprecice.so.3: cannot open shared object file: No such file or directory 
 ```
 
 Tells you that the MATLAB bindings cannot find the C++ library preCICE. Make sure that you [installed preCICE correctly](https://precice.org/installation-source-installation.html#testing-your-installation).
@@ -85,19 +92,27 @@ $ pkg-config --cflags --libs libprecice
 
 If everything until this point looks good and you are still facing problems and you installed preCICE to a custom location using `CMAKE_INSTALL_PREFIX`, MATLAB might not be able to find `libprecice.so`, since it is not discoverable. Please add the location of `libprecice.so` (see `pkg-config --libs-only-L libprecice`, without the `-L`) to your `LD_LIBRARY_PATH`. For further instructions refer to the [MATLAB documentation](https://de.mathworks.com/help/matlab/matlab_external/set-run-time-library-path-on-linux-systems.html).
 
-## version \`GLIBCXX_3.4.26' not found
+## version `GLIBCXX_X.X.XX` not found
 
 ```bash
-Invalid MEX-file 'SOMEPATH/matlab-bindings/+precice/@SolverInterface/private/preciceGateway.mexa64':
+Invalid MEX-file 'SOMEPATH/matlab-bindings/+precice/@Participant/private/preciceGateway.mexa64':
 /usr/local/MATLAB/R2021a/bin/glnxa64/../../sys/os/glnxa64/libstdc++.so.6:
 version `GLIBCXX_3.4.26' not found (required by /lib/x86_64-linux-gnu/libprecice.so.2)
 ```
 
-Matlab ships with a version of `libstdc++.so.6` that may be too old. This version does not find the preCICE C++ library. By using the system-provided version of `libstdc++.so.6`, you can fix the error.
+MATLAB ships with a version of `libstdc++.so.6` that may be too old. This version does not find the preCICE C++ library. 
+
+So far, this problem was encountered with Ubuntu Version `20.04.04 LTS`, GNU C++ `10.5.0`, on MATLAB versions `R2020b (Update 8)`, `R2021a`, `R2021b (Update 7)`. See https://github.com/precice/matlab-bindings/issues/53 for more details.
+
+There are two possible solutions:
+
+### (recommended) Update your MATLAB installation
+
+This problem does not appear, for example, for MATLAB R2023b (Update 7). For information on how to update MATLAB, please refer to the MATLAB documentation.
 
-So far, this problem was encountered with Ubuntu Version `20.04.04 LTS`, GNU C++ `9.4.0`, on matlab versions `R2020b`, `R2021a`, `R2021b`.
+### Set `LD_PRELOAD` to use the system-provided `libstdc++.so.6`
 
-To solve this error start matlab with the following command:
+Please start MATLAB with the following command:
 
 ```shell
 LD_PRELOAD=/usr/lib/x86_64-linux-gnu/libstdc++.so.6 matlab