aliraeini/porescale repository overview

⁠pore scale modelling and image analysis

Docker image to facilitate running opensource apps for modelling flow through porous media by Imperial College Pore-scale Consortium on pore-scale imaging and modelling, and several other third party packages. This include most public Github repositories currently maintained by Ali Q Raeini, including pnextract⁠ and pnflow⁠ network exaction and flow modelling codes, porefoam⁠ direct single- and two-phase flow simulators, ContactAngle⁠ and other utilities for basic image processing, mesh generation and post-processing of two-phase flow through confined media.

⁠Pull docker image

First, of course, you need to have docker installed in your system.

In Mac/Windows, you can pull latest docker image by running the command:

docker pull aliraeini/porescale

docker tag aliraeini/porescale porescale

The latter command is just to rename the image to be compatible with the instructions given below.

In Linux, the above commands will work too but to avoid file permission problems when sharing files between docker and host computer, you should rebuild the docker image with your host user ID. This can be done by running the following (multiline) commands:

echo  '
FROM  aliraeini/porescale:latest
ARG UNAME=psim
ARG UID=1000
ARG GID=1000
RUN userdel     psim | echo ignore
RUN groupdel  psim | echo ignore
RUN groupadd  -g $GID psim
RUN useradd -m -u $UID -g $GID -o -s /bin/bash $UNAME
USER $UNAME
WORKDIR /home/$UNAME
CMD /bin/bash
'                  > Dockerfile_psim

docker build --build-arg UID=$(id -u) --build-arg GID=$(id -g)  -f Dockerfile_psim   -t porescale   . 

You can delete the generated Dockerfile_psim file afterwards.

⁠Usage

To start the docker container, open the folder in which you want to run the apps in a terminal or cmd/PowerShell in Windows and run the following commands:

In Windows, assuming you want to run the apps in a directory namedD:\data, run in a Cmd/PowerShell/... terminal:

docker run -v D:\data:/data -w /data -it porescale:latest

In Linux, run:

docker run -v$PWD:$PWD -w $PWD -it porescale:latest

Where $PWD expands to the current working directory of the terminal. The flag -v mounts volumes into docker directories and the -w flag sets the docker terminals working directory.

The flag -it is for opening an interactive terminal. You can remove this flag if you want the docker run your commands non-interactively, e.g (in Windows replace '$PWD' with folder name where the .mhd images are saved):

# Print direct single-phase flow simulation help message:
docker run -v $PWD:/data -w /data  porescale:latest  /opt/src/porefoam1f/script/AllRunImagePar -h

# Copy AllRunImageTwoPhaseCFMesh to local folder  for editing and then running two-phase flow simulations :
docker run -v $PWD:/data -w /data  porescale:latest  /opt/src/porefoam1f/script/AllRunImageTwoPhaseCFMesh 
# Warning: running two-phase flow simulation is experimental and more involved so you should use the interactive mode above instead.


# Run curvature and contact angle analysis code (Warning experimental, and no help message yet):
docker run -v $PWD:/data -w /data  porescale:latest  /opt/src/ContAngle/AllRunContAngle  Image.mhd
# Warning: for now Image.mhd has no effect and the AllRunContAngle will run on all .mhd files in the /data folder.

# Run network extraction code:
docker run -v $PWD:/data -w /data  porescale:latest   /opt/bin/pnextract  Image.mhd

# Run network flow simulation:
docker run -v $PWD:/data -w /data  porescale:latest   /opt/bin/pnflow  input_pnflow.dat

⁠References and further instructions

The porefoam⁠, porefoam-singlePhase⁠, pnextract⁠, pnflow⁠ and ContactAngle⁠ codes are pre-compiled and installed on this docker image in the /opt/ directory. The instructions for using them are provided in the /opt/doc directory, which can also be accessed from the codes' Github repositories. For downloading the source codes and for contacts and references please refer to the above Github pages.

⁠Useful docker commands

# List  tags and ids of docker image available locally on your system:
docker image ls 

# Force remove docker image using image tag or id:
docker rmi -f  image-tag_or_id  

# To attach and run on a docker container (?):
docker exec -it porescale  /bin/bash  

# To use a diifferent entry point than what suggested by the image:
docker run -it --entrypoint /bin/bash image-tag_or_id 

# get root access to the docker container:
docker run -v${PWD}:/home/psim  -it --user root  porescale:latest