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:

sudo apt-get update && sudo apt-get install -y --no-install-recommends \
    build-essential \
    python3 python3-dev python3-pip python3-tk \
    cmake ninja-build git libopenmpi-dev

2️⃣ Clone the Repository

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

3️⃣ Install FEelMRI

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