A fast, simple, and extensible Python library for transforming Finite Element simulations into MR Images

---

FEelMRI is an open-source, cross-platform library designed to generate synthetic magnetic resonance (MR) images from finite element (FE) simulations. It can handle complex physical phenomena governed by partial differential equations (PDEs) and supports arbitrary cell geometries and discrete function spaces.

---

Orthogonal-CSPAMM	4D Flow
Abdominal FFE	Free Running

---

📚 Table of Contents

• Installation
• Quick Start Example
• First Run
• Docker Setup (Cross-Platform)
• How to Contribute
• Citation
• License

---

🚀 Installation

These steps were tested primarily on Linux systems. For Windows and macOS, please refer to Docker Setup.

1️⃣ System Dependencies

You’ll need some basic system libraries and build tools. On Ubuntu/Debian:

apt-get update && apt-get install -y --no-install-recommends \
    build-essential \
    python3 \
    python3-dev \
    python3-pip \
    python3-tk \
    cmake \
    ninja-build \
    git \
    libopenmpi-dev \
    screen \
    nano \
    libblas-dev \
    liblapack-dev \
    ccache

These dependencies can also be installed via pip`` by setting up the variable INSTALL_SYSTEM_DEPS``` as described below.

2️⃣ Clone the Repository

git clone https://github.com/hernanmella/feelmri.git
cd feelmri

3️⃣ Install FEelMRI

pip install .

System dependencies can also be installed by setting the cmake argument INSTALL_SYSTEM_DEPS as:

CMAKE_ARGS="-DINSTALL_SYSTEM_DEPS=ON" pip install .

Verify installation ✅:

python3 -c "import feelmri; print(feelmri.__version__)"

4️⃣ (Optional) Unzip Example Phantoms

7z x examples/phantoms/phantoms_compressed.zip -oexamples/phantoms/

---

🐍 First Run

Example scripts are provided in the examples/ directory. To run an example using multiple cores:

cd examples/
mpirun -n <nb_cores> python3 <example_script>.py

Replace <nb_cores> with the number of CPU cores to use.

MRI planning with ParaView

To plan and position the FOV position and orientation, you are referred to examples/planning/ directory.

---

🐳 Docker Setup (Cross-Platform)

If you prefer an isolated or multi-platform setup, you can use Docker.

Build the Docker Image

docker build \
  --build-arg UID=$(id -u) \
  --build-arg GID=$(id -g) \
  -f docker/Dockerfile \
  -t feelmri:latest .

Run the Container

docker run --name feelmri_container \
  --shm-size 256m -ti \
  -v $(pwd):/home/feelmri/ \
  feelmri:latest

Enable GUI/Plots in Docker

If you want to visualize plots (e.g., matplotlib):

xhost +local:root
docker run -it \
  --env="DISPLAY" \
  --volume="/tmp/.X11-unix:/tmp/.X11-unix:rw" \
  -v $(pwd):/home/feelmri/ \
  feelmri:latest

---

🤝 How to Contribute

We welcome community contributions! To get started:

1. Fork the repository
2. Create a new branch (git checkout -b feature-name)
3. Make your changes
4. Submit a pull request 🎉

More details are in CONTRIBUTING.md.

---

📖 Citation

The related research article is currently under review. Citation details will be added soon.

---

📜 License

This project is distributed under the MIT License. See the LICENSE file for details.

© 2025 Hernán Mella — FEelMRI Project