{"id":26005406,"url":"https://github.com/precice/matlab-bindings","last_synced_at":"2026-03-16T02:35:39.793Z","repository":{"id":38678931,"uuid":"224451046","full_name":"precice/matlab-bindings","owner":"precice","description":"MATLAB language bindings for preCICE","archived":false,"fork":false,"pushed_at":"2025-01-22T13:14:59.000Z","size":479,"stargazers_count":5,"open_issues_count":15,"forks_count":2,"subscribers_count":5,"default_branch":"develop","last_synced_at":"2025-01-22T13:46:55.565Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://www.precice.org","language":"MATLAB","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"lgpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/precice.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"custom":"https://precice.org/community-support-precice"}},"created_at":"2019-11-27T14:38:17.000Z","updated_at":"2025-01-22T12:55:14.000Z","dependencies_parsed_at":"2024-01-25T22:24:13.693Z","dependency_job_id":"80f978d5-ee1a-414f-b8a1-2aba024232fc","html_url":"https://github.com/precice/matlab-bindings","commit_stats":null,"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/precice%2Fmatlab-bindings","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/precice%2Fmatlab-bindings/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/precice%2Fmatlab-bindings/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/precice%2Fmatlab-bindings/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/precice","download_url":"https://codeload.github.com/precice/matlab-bindings/tar.gz/refs/heads/develop","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":242103943,"owners_count":20072368,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-03-05T20:53:53.208Z","updated_at":"2026-03-16T02:35:39.788Z","avatar_url":"https://github.com/precice.png","language":"MATLAB","funding_links":["https://precice.org/community-support-precice"],"categories":[],"sub_categories":[],"readme":"# MATLAB bindings\n\nThese bindings allow to use preCICE with MATLAB based on the C++ MEX and C data API. They are still in an experimental state, so please utilize them with care. Any feedback is welcome.\n\nNote that the first two digits of the version number of the bindings indicate the major and minor version of the preCICE version that the bindings support. The last digit represents the version of the bindings. Example: `v3.1.0` and `v3.1.1` of the bindings represent versions `0` and `1` of the bindings that are compatible with preCICE `v3.1.x`. Note that this versioning scheme was introduced from bindings `v3.1.0`, which is different than the [old versioning scheme](#old-versioning-scheme).\n\n## Requirements\n\nMATLAB R2018a or later is required. The bindings are actively tested on versions R2024a and R2023b.\n\n⚠️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)⚠️\n\n## Restrictions\n\n- 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.\n- 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).\n- 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.\n\n## Compilation\n\nThe MATLAB script `compile_matlab_bindings_for_precice.m` located in this folder compiles the bindings. Simply running it from MATLAB should do.\n\nIn some cases, MATLAB's own `libstdc++` library may be an old version, which leads an error while compiling the bindings, of the kind \"version 'CXXABI_1.3.11' not found\". In this case, one can set MATLAB to use another version of `libstdc++` with the `LD_PRELOAD` variable (see [here](https://alexxunxu.wordpress.com/2018/01/15/version-cxxabi_1-3-8-not-found/) for further reference). For example, for using the system's default `libstdc++`, one can open MATLAB with the following command:\n\n```bash\nLD_PRELOAD=/usr/lib/x86_64-linux-gnu/libstdc++.so.6 matlab\n```\n\nThe script uses `pkg-config` to determine the necessary flags. If `pkg-config` is unable to find the flags, the script will throw an error. Please refer to the [Linking to preCICE](https://precice.org/installation-linking.html) page in the preCICE wiki for details regarding `pkg-config`.\n\nIf using the script fails for some reason, please let us know.\n\n## Add to path\n\nTo use the bindings, you have to add this folder (e.g. `/home/user/matlab-bindings`) to your MATLAB path using [`addpath`](https://de.mathworks.com/help/matlab/ref/addpath.html?searchHighlight=addpath\u0026s_tid=doc_srchtitle). Adding this folder alone is sufficient (you don't have to use `genpath`). You can let MATLAB do this at startup by adding the respective line to your `startup.m`, see [here](https://de.mathworks.com/help/matlab/matlab_env/add-folders-to-matlab-search-path-at-startup.html).\n\n## Usage\n\nThe 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.\n\nThe function syntax is mostly identical to the syntax of the C++ API. The following things should be noted:\n\n- C++ `int`s correspond to MATLAB `int32`s.\n- Wherever the C++ API expects pointers, the MATLAB API expects a matrix/vector instead. If the user wants to pass vector data (e.g. vertex coordinates) for multiple vertices, the shape of the corresponding matrix must be `[dim numVertices]`, where `dim` is the problem dimension. Thus, each **column** must correspond to a vertex, and each line must correspond to a coordinate - **not** vice versa. Users should try to respect this in their MATLAB code from the start, because transposing can be costly for huge matrices.\n- There are two changes in the input arguments for the MATLAB API with respect to the C++ API: \n    - Output arguments which are pointers passed as input arguments to the C++ preCICE API are replaced by output matrices.\n    - As the MATLAB API receives matrices/vectors instead of pointers, the size (e.g. number of vertices) of the arrays is not an input argument, but instead it is inferred from the array.\n\nAs an example, the C++ API function\n\n```bash\nvoid readData(\n    ::precice::string_view          meshName, \n    ::precice::string_view          dataName, \n    ::precice::span\u003cconst VertexID\u003e ids,\n    double                          relativeReadTime, \n    ::precice::span\u003cdouble\u003e         values) const\n```\n\nis found in the MATLAB bindings as\n\n```bash\nvalues = readData(meshName, dataName, ids, relativeReadTime)\n```\n\n## Out of process variant\n\nThe 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.\nThis has the following advantages:\n\n- Multiple instances of `ParticipantOOP` can exist at the same time.\n- If the gateway function crashes, then MATLAB will not crash. Only the mexHost object will crash.\nHowever, using the OOP variant is **significantly** slower than the normal in process\n\n## Troubleshooting\n\n## `libprecice.so` cannot be found\n\n```bash\nInvalid MEX-file 'SOMEPATH/matlab-bindings/+precice/@Participant/private/preciceGateway.mexa64':\nlibprecice.so.3: cannot open shared object file: No such file or directory \n```\n\nTells 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).\n\nYou can also run `pkg-config --cflags --libs libprecice` to see whether the paths provided by `pkg-config` point to the correct place. Example output, if everything is correct and you installed preCICE via `sudo make install`:\n\n```bash\n$ pkg-config --cflags --libs libprecice\n-I/usr/local/include -L/usr/local/lib -lprecice\n```\n\nIf 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).\n\n## version `GLIBCXX_X.X.XX` not found\n\n```bash\nInvalid MEX-file 'SOMEPATH/matlab-bindings/+precice/@Participant/private/preciceGateway.mexa64':\n/usr/local/MATLAB/R2021a/bin/glnxa64/../../sys/os/glnxa64/libstdc++.so.6:\nversion `GLIBCXX_3.4.26' not found (required by /lib/x86_64-linux-gnu/libprecice.so.2)\n```\n\nMATLAB ships with a version of `libstdc++.so.6` that may be too old. This version does not find the preCICE C++ library. \n\nSo 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.\n\nThere are two possible solutions:\n\n### (recommended) Update your MATLAB installation\n\nThis problem does not appear, for example, for MATLAB R2023b (Update 7). For information on how to update MATLAB, please refer to the MATLAB documentation.\n\n### Set `LD_PRELOAD` to use the system-provided `libstdc++.so.6`\n\nPlease start MATLAB with the following command:\n\n```shell\nLD_PRELOAD=/usr/lib/x86_64-linux-gnu/libstdc++.so.6 matlab\n```\n\n## Old versioning scheme\n\nBindings versions up to `v3.0.0.0` have four digits, where the first three digits are the supported preCICE version, and the fourth digit is the bindings version. Example: `v2.0.0.1` and `v2.0.0.2` of the bindings represent versions `1` and `2` of the bindings that are compatible with preCICE `v2.0.0`. We dropped the third digit of the preCICE version as bugfix releases are always compatible and do not impact the bindings. The new three digit format is now consistent with other preCICE bindings.\n\n## Contributors\n\n- [Dominik Volland](https://github.com/Dominanz) contributed first working prototype in [PR #494 on `precice/precice`](https://github.com/precice/precice/pull/494)\n- [Gilberto Lem](https://github.com/gilbertolem) integrated bindings into existing infrastructure of preCICE in [PR #580 on `precice/precice`](https://github.com/precice/precice/pull/580)\n- [Benjamin Rodenberg](https://github.com/BenjaminRodenberg)\n- [Frédéric Simonis](https://github.com/fsimonis)\n- [Erik Scheurer](https://github.com/erikscheurer) contributed automated CI tests.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprecice%2Fmatlab-bindings","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fprecice%2Fmatlab-bindings","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprecice%2Fmatlab-bindings/lists"}