SophT

Scalable One-stop Platform for Hydroelastic Things (SOPHT).

This repository corresponds to the development of flow-structure interaction simulator (2D and 3D) using immersed boundary method, while capturing Cosserat rod dynamics using pyelastica.

Installation

A Python version of at least 3.10 is required for installation.

sopht can be installed in one of two ways:

1. direct installation from GitHub, and
2. cloning the repository and building it manually.

1. Direct installation

The first approach is straightforward with pip:

pip install "git+https://github.com/SophT-Team/SophT.git"

or optionally with additional dependencies required by the examples:

pip install "sopht[examples]@git+https://github.com/SophT-Team/SophT.git"

2. Manual installation

To install sopht manually, first clone the repository

git clone https://github.com/SophT-Team/SophT.git

The user is free to choose any Python package manager or build-system for the following steps, although we recommand using UV as the package manager for which we have prepared a uv.lock file. We provide several dependency groups and optional dependencies for various development purposes:

# Dependency groups
# uv sync --group dev
# uv sync --group lint
# uv sync --group tests

# Optional dependencies
# uv sync --extra examples

# Install all groups
uv sync

3. (Optional) Install ffmpeg

sopht examples use ffmpeg for data animation. To install ffmpeg, please visit visit their website for instructions.

4. (MacOS only) pystencils adjustment

We use pystencils to perform just-in-time (JIT) of many computational routines for code acceleration. There is a long standing issue where MacOS's native compiler (AppleClang) does not support OpenMP directly, which is required by pystencils. Therefore, you may encounter linker errors during the JIT compilation. If you encounter this issue, follow these steps:

1. Install OpenMP through a third party (we will use brew as an example here)

brew install libomp
brew --prefix libomp # This is the install path for your libomp. It will be used later.

2. Find the pystencils configuration file. This file is automatically generated when the JIT compiler is run for the first time. It is typically located at ~/Library/Application\ Support/pystencils/config.json. Alternatively, you can edit your pystencils source code in cpujit.py to print out the configuration file path.
3. To tell the compiler where to find your openmp installation, add the following flags to the "compiler.flags" field. If your libomp install path is different, change accordingly.

{
  "compiler": {
    "os": "darwin",
    "command": "clang++",
    "flags": ["... -I/opt/homebrew/opt/libomp/include -L/opt/homebrew/opt/libomp/lib -lomp"],
    ...
  }
}

4. Rerun your code. Clear pystencils cache if necessary, which is typically located at ~/Library/Caches/pystencils/

Citation

We ask that any publications which use SophT cite as following:

@software{yashraj_bhosale_2023_7658908,
  author       = {Yashraj Bhosale and
                  Arman Tekinalp and
                  Songyuan Cui and
                  Fan Kiat Chan and
                  Mattia Gazzola},
  title        = {{Scalable One-stop Platform for Hydroelastic Things
                   (SOPHT)}},
  month        = feb,
  year         = 2023,
  publisher    = {Zenodo},
  version      = {v.0.0.1},
  doi          = {10.5281/zenodo.7658908},
  url          = {https://doi.org/10.5281/zenodo.7658908}
}