Skip to content

Commit

Permalink
Update README.md
Browse files Browse the repository at this point in the history
* Changed `SolverInterface` to `Participant`
* Updating some error messages pointing to version 2 to version 3
  • Loading branch information
BenjaminRodenberg authored Jan 22, 2025
1 parent 3ae2c78 commit 963e999
Showing 1 changed file with 12 additions and 12 deletions.
24 changes: 12 additions & 12 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,13 +6,13 @@ 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 R2024b, R2023b, R2023a, R2022b, R2022a, and R2021b.

## 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

Expand All @@ -34,7 +34,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 `SolverInterface` 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:

Expand All @@ -47,21 +47,21 @@ 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)
readData(int dataID, int size, const int *valueIndices, double *values)
```

is found in the MATLAB bindings as

```bash
values = readBlockScalarData(dataID, valueIndices)
values = readData(dataID, valueIndices)
```

## 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

Expand All @@ -70,8 +70,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).
Expand All @@ -88,7 +88,7 @@ If everything until this point looks good and you are still facing problems and
## 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)
```
Expand Down

0 comments on commit 963e999

Please sign in to comment.