From 31288c7c4b24a0d7318ca58dc8f9833fc88e5945 Mon Sep 17 00:00:00 2001
From: dcluo <dc.luo@outlook.com>
Date: Sun, 26 May 2024 14:07:02 -0500
Subject: [PATCH] updated installation instructions for arm macos and docker

---
 INSTALL.md | 41 ++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 40 insertions(+), 1 deletion(-)

diff --git a/INSTALL.md b/INSTALL.md
index ba6fcaf..5bcec75 100644
--- a/INSTALL.md
+++ b/INSTALL.md
@@ -18,6 +18,11 @@
 conda create -n soupy -c conda-forge python=3.11 fenics==2019.1.0 petsc4py==3.19 matplotlib scipy jupyter
 conda activate soupy
 ```
+**Note**: `FEniCS` is only available on x86 systems. When running on an ARM based mac with the ARM version of conda installed, add the flag `--platform osx-64`, i.e. 
+```
+conda create -n soupy --platform osx64 -c conda-forge python=3.11 fenics==2019.1.0 petsc4py==3.19 matplotlib scipy jupyter
+conda activate soupy
+```
 
 2. Install `hIPPYlib` via pip
 ```
@@ -37,7 +42,7 @@ git clone https://github.com/hippylib/soupy.git
 Examples in the `applications` directory can now be run. We refer to the full `FEniCS` [installation instructions](https://hippylib.readthedocs.io/en/3.0.0/installation.html) from `hIPPYlib` for more detail. 
 
 ### Installation for developers 
-1. Create an environment with `FEniCS` with appropriate dependencies
+1. Create an environment with `FEniCS` with appropriate dependencies (add `--platform osx64` if using ARM conda, see above)
 ```
 conda create -n soupy -c conda-forge python=3.11 fenics==2019.1.0 petsc4py==3.19 matplotlib scipy jupyter
 ```
@@ -67,3 +72,37 @@ Documentation for `SOUPy` can be built using `sphinx`, along with extensions
 `myst_nb` and `sphinx_rtd_theme`. These can be installed via `pip`.
 
 To build simply run `make html` from `doc` folder.
+
+## Installation with Docker
+
+SOUPy (and hIPPYlib) can be used with a Docker image built with FEniCS/dolfin. 
+The [FEniCS documentation](https://fenics.readthedocs.io/projects/containers/en/latest/) provides installation instructions for FEniCS's official images (note these are built on older versions of python). Alternatively, a customized docker image built off the FEniCS 2019.1.0 image with hIPPYlib pre-installed is available [here](https://hub.docker.com/r/hippylib/fenics)
+
+More recent builds of the docker images with FEniCS that are compatible with the [Frontera(https://frontera-portal.tacc.utexas.edu/) HPC system] at the Texas Advanced Computing Center can be found under the `hippylib/tacc-containers` [repository](https://github.com/hippylib/tacc-containers). The repository also provides instructions for usage on Frontera using Apptainer. Here, we will summarize the procedure for using the image on local machines with Docker.
+
+1. Pull one the docker images 
+``` 
+docker pull uvilla/fenics-2019.1-tacc-mvapich2.3-ib:latest 
+```
+
+2. Under the desired working directory, clone hIPPYlib and SOUPy
+```
+git clone https://github.com/hippylib/hippylib.git
+git clone https://github.com/hippylib/soupy.git
+```
+
+3. The images are built for the MPI implementations on TACC systems. When running locally, the environment variables `MV2_SMP_USE_CMA=0` and `MV2_ENABLE_AFFINITY=0` need to be set.
+```
+docker run -e MV2_SMP_USE_CMA=0 -e MV2_ENABLE_AFFINITY=0 -ti -v $(pwd):/home1/ uvilla/fenics-2019.1-tacc-mvapich2.3-ib:latest /bin/bash 
+```
+This will run the container and bind the current working directory to `/home1`.
+The executed container should now have `/home1/hippylib` and `/home1/soupy`. 
+
+4. With the container running, first set the path to hippylib `export HIPPYLIB_PATH=/home1/hippylib`. The examples in the SOUPy repository can then be executed as 
+```
+cd /home1/soupy/examples/poisson
+python3 driver_poisson_mean.py
+```
+Compilation can take a while when executing for the first time. 
+
+**Note**: benign MPI warning messages may show up when running on ARM machines.