This package provides Julia language bindings for the C++ library preCICE. It is a Julia package that wraps the API of preCICE.

Note that the first two digits of the version number of the bindings indicate the preCICE major and minor version that the bindings support. The last digit represents the version of the bindings. Example: v2.5.1 and v2.5.2 of the bindings represent versions 1 and 2 of the bindings that are compatible with preCICE v2.5.0.

Technical information about the initial design of these bindings can be found in the Bachelor thesis of Pavel Kharitenko.

The Julia bindings for preCICE can be used by either by adding them as a package in a Julia environment or also directly including the package in a Julia script. For both type of usages preCICE needs to be installed on the system. For preCICE installation, have a look at the installation documentation.

Add the Julia bindings to the Julia environment in the following way:

julia> ]
pkg> add PreCICE 
Then exit the package mode with 🔙 or Ctrl + c
julia> using PreCICE

Alternatively you can also include the package in a Julia script in the following way:

import Pkg; Pkg.add("PreCICE")
using PreCICE

If you have cloned or downloaded the Julia bindings on your local machine, add the Julia bindings to your Julia environment in the following way:

julia> ]
pkg> add <path-to-repository>
Then exit the package mode with 🔙 or Ctrl + c
julia> using PreCICE

Alternatively, you can install a specific branch of this repository with the following command:

pkg> add https://github.com/precice/PreCICE.jl#<branch-name>

If preCICE is installed at a custom path, errors of the form ERROR: could not load library "/..." can occur after adding the Julia bindings package. Make sure the preCICE library is in the system library path through echo $LD_LIBRARY_PATH and otherwise update the variable with the correct path.

~$ export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:<path-to-precice.so>

A different way to fix this error is to set the custom path of the preCICE installation through the environment variable PRECICE_JL_BINARY. Afterwards you need to rebuild this package:

~$ export PRECICE_JL_BINARY=/usr/lib/x86_64-linux-gnu/
~$ julia (--project)
julia> ]
pkg> build PreCICE
julia> using PreCICE
...

If you get an error message like:

ERROR: LoadError: could not load library "libprecice"
/usr/bin/../lib/libstdc++.so.6: version `GLIBCXX_3.4.30' not found (required by /usr/local/lib/libprecice.so)

It is caused by an incompatible version of libstdc++ as described in the issue. Julia ships its own libraries, which are older than the ones shipped by the system or the ones used to compile preCICE.

As a first solution, consider updating your julia version. The versions used in Julia are fairly up to date and should work with older systems. The problem is also known to the developers of Julia and they are working on a solution. From Julia v1.8.3 on, the problem should be fixed.

If you cannot update your julia version, or the problem persists, you can try preloading the system libstdc++:

LD_PRELOAD=/usr/lib/x86_64-linux-gnu/libstdc++.so.6 julia

ERROR: ERROR: LoadError: LoadError: could not load library "libprecice"
/path/to/julia-1.8.1/bin/../lib/julia/libcurl.so: version `CURL_OPENSSL_4' not found (required by /lib/x86_64-linux-gnu/libhdf5_openmpi.so.103)could not load library "libprecice"
/path/to/julia-1.8.1/bin/../lib/julia/libcurl.so: version `CURL_OPENSSL_4' not found (required by /lib/x86_64-linux-gnu/libhdf5_openmpi.so.103)

LD_PRELOAD="/usr/lib/x86_64-linux-gnu/libstdc++.so.6:/usr/lib/x86_64-linux-gnu/libcurl.so.4" julia

alias julia='LD_PRELOAD="/usr/lib/x86_64-linux-gnu/libstdc++.so.6:/usr/lib/x86_64-linux-gnu/libcurl.so.4" julia'

mv /path/to/julia/lib/julia/libstdc++.so.6 /path/to/julia/lib/julia/libstdc++.so.6.bak
ln -s /usr/lib/x86_64-linux-gnu/libstdc++.so.6 /path/to/julia/lib/julia/libstdc++.so.6

The solverdummy shows an example of how to use the Julia bindings for preCICE.

To test the bindings, run:

julia> ]
pkg> test PreCICE

This checks if the preCICE bindings can be found and accessed correctly. You can also test the full functionality of PreCICE.jl. If not set up, the output of the previous test shows an info on what command you need to execute. It will be along the lines of:

cd /home/<user>/.julia/packages/PreCICE/<code>/test && make

After this, you can run the tests again, resulting individual 22 tests being executed.

This package works with official Julia binaries listed below. See the Platform Specific Instructions for official Binaries or Julia's documentation if you are not sure how to download them.

The package is actively tested for Julia versions 1.8.0, 1.9.0, and 1.10.0. Julia versions prior to 1.6.0 are not supported.

Unofficial Julia binaries may not be compatible.