From 2a29831f405e2352cbc496348700de0f42060e84 Mon Sep 17 00:00:00 2001
From: Sebastian Havens <sebastian.havens@outlook.com>
Date: Thu, 15 Aug 2024 23:05:43 +0100
Subject: [PATCH] Addition of singularity build file and documentation to run
calculations using the container.
---
calphy.def | 71 +++++++++++++++++++++++++++++++++++
docs/source/gettingstarted.md | 21 +++++++++++
2 files changed, 92 insertions(+)
create mode 100644 calphy.def
diff --git a/calphy.def b/calphy.def
new file mode 100644
index 0000000..090aca7
--- /dev/null
+++ b/calphy.def
@@ -0,0 +1,71 @@
+BootStrap: library
+From: ubuntu:22.04
+
+%labels
+ Author: Sebastian Havens
+ Image for a calphy container
+%environment
+ export PATH=/scripts:$PATH
+ export OMP_NUM_THREADS=1
+ . /singularity-venv/bin/activate
+ source /singularity-venv/bin/activate
+
+%post
+ # Update package lists and install necessary packages
+ export DEBIAN_FRONTEND=noninteractive
+ echo . /singularity-venv/bin/activate
+
+ apt-get update -y
+ apt-get install -y build-essential libopenmpi-dev libmpich-dev vim emacs htop \
+ mpi-default-bin mpi-default-dev mpich libjpeg-dev libpng-dev git \
+ fftw3 fftw3-dev software-properties-common
+
+ # Add repository and install Python 3.8
+ add-apt-repository ppa:deadsnakes/ppa
+ apt-get update -y
+ apt-get install -y python3.8-dev python3.8-venv
+
+ # Setup Python virtual environment
+ python3.8 -m venv /singularity-venv
+ . /singularity-venv/bin/activate
+
+ # Install packages
+ pip install numpy==1.24.4 ase==3.23.0 mpi4py==3.1.5
+ pip install mendeleev==0.17.0 pylammpsmpi==0.2.16 pyscal==0.12 pyyaml==6.0.2 scipy==1.10.1 tqdm==4.66.2
+ pip install calphy
+
+ # Clone lammps source and make
+ git clone https://github.com/lammps/lammps.git --branch patch_2Aug2023_update3
+ cd /lammps/src/
+ sed -i '35s/.*/LMP_INC = -DLAMMPS_GZIP -DLAMMPS_JPEG -DLAMMPS_PNG -DLAMMPS_FFMPEG -DLAMMPS_EXCEPTIONS/' MAKE/MACHINES/Makefile.ubuntu
+ make yes-manybody
+ make yes-meam
+ make yes-EXTRA-FIX
+ make yes-EXTRA-PAIR
+ make -j 8 ubuntu mode=shlib
+ make install-python
+ cp liblammps_ubuntu.so /singularity-venv/lib/python3.8/site-packages/lammps
+ cd ../../
+%runscript
+
+ echo "Input file: $1"
+ echo "Calculation starting"
+ calphy_kernel -i $1 -k 0
+ exec echo "Calculation finished"
+
+
+
+%help
+ This is a container for carrying out calphy calculations which perform free energy calculations.
+ The container is designed to run locally or on HPC machines.
+
+ The calphy calcualtion can be initiated via the container with the following command:
+ singularity exec --bind $PWD --pwd $PWD {location_of_.sif_image} calphy_kernel -i {input_file} -k 0
+ This line can be contained within a slurm script
+
+ The scheduler used in the calphy input file should be 'local'.
+ On HPC machines the singularity executable can usually be loaded via 'module load singularity' or it will already be within your
+ path.
+
+ In the calphy input file, the scheduler should be set to local.
+ The OpenMPI version on the host system must be at least 4.1.2, which will need to be loaded if you are using a HPC machine.
diff --git a/docs/source/gettingstarted.md b/docs/source/gettingstarted.md
index f4390ce..ccdfc07 100644
--- a/docs/source/gettingstarted.md
+++ b/docs/source/gettingstarted.md
@@ -21,6 +21,27 @@
`python setup.py install`
```
+```{tab} Singularity
+A singularity containter can also be used for running calphy locally or on HPC machines.
+The containerised environment contains all of the packages required to run calphy.
+
+The containerised environemnt can be pulled from the repository with:
+'singularity pull --arch amd64 library://sebastianhavens/calphy/calphy:latest'
+(https://cloud.sylabs.io/library/sebastianhavens/calphy/calphy)
+
+On HPC machines you can usually load the singularity module with:
+'module load singularity' if it is not already available.
+
+You can initiate calculations using this container with the following line:
+'singularity exec --bind $PWD --pwd $PWD {location_of_.sif_image} calphy_kernel -i {input_file} -k 0'
+where {location_of_.sif_image} is the file location of the containerlised environment you just pulled and {input_file} is the name of your input file.
+This line can be placed within a slurm script.
+
+In the calphy input file, the scheduler should be set to local.
+For parallel calculations to run effectively, the OpenMPI module on the host system must be at least 4.1.2.
+```
+
+
### Using a conda environment
It is **strongly** recommended to install and use `calphy` within a conda environment. To see how you can install conda see [here](https://docs.conda.io/projects/conda/en/latest/user-guide/install/).