Merge pull request #266 from SouthernMethodistUniversity/update_gaussian_example

Update gaussian example

Author: jrlagrone

docs/examples/chemistry.md

@@ -10,4 +10,5 @@ please [contact us.](about:contact).
 You can also submit issues and/or pull requests for updates or additions at
 [our github page](https://github.com/SouthernMethodistUniversity/hpc_docs)
 
-- [Amber](amber/index.md)
+- [Amber](amber/index.md)
+- [Gaussian](gaussian/index.md)

docs/examples/gaussian/gaussian_cpu_example.sbatch

@@ -0,0 +1,70 @@
+#!/bin/bash
+#SBATCH -J gaussian            # job name shown in queue
+#SBATCH -o gaussian_%j.out     # output file, %j is the job id number
+#SBATCH -p dev                 # request the dev queue
+#SBATCH -c 16                  # request 16 CPU cores
+#SBATCH --mem=1G               # Request 1GB of memory
+#SBATCH -t 00:01:00            # request 1 minute
+#SBATCH -A peruna_project_0001 # example account
+
+# specify the input file
+input_file=gaussian_example.cpu
+
+# module purge clears any existing modules so only the modules
+# requested will be loaded. This improves reproducibility
+module purge
+
+# load gaussian. It is a good practice to include the version
+# the default modules without a version may change when software
+# is updated
+module load gaussian/g16c/zen3
+
+# create a temporary job directory in scratch
+# copy the input file and cd into it
+# Note: scratch is intended for temporary job storage
+# you should move any files you need to keep when the job
+# completes and delete unneeded files. Files in $SCRATCH
+# are subject to automatic deletion after 60 days.
+job_dir=${SCRATCH}/${SLURM_JOB_ID}
+mkdir -p ${job_dir}
+cp ${input_file} ${job_dir}
+cd ${job_dir}
+GAUSS_SCRDIR=${job_dir}
+
+# gets requested mem in GB
+sleep 5 # to make sure the job info is available
+mem=$(sacct -o "ReqMem" --units=G -j ${SLURM_JOB_ID} -n | xargs)
+
+# get the cores assigned to the job
+# This is M3 specific, though something similar will work on many systems
+cpus=$(cat /sys/fs/cgroup/system.slice/slurmstepd.scope/job_${SLURM_JOB_ID}/cpuset.cpus)
+
+# make sure mem is an int with correct units
+mem=${mem%.*}
+mem=${mem//[!0-9]/}
+mem="${mem}GB"
+
+# this function fills in the cpu and memory information into the
+# input file
+cpu_mem() {
+  sed -i -e "/^%CPU/c\%CPU=${1}" ${input_file}
+  sed -i -e "/^%Mem/c\%Mem=${2}" ${input_file}
+}
+
+cpu_mem ${cpus} ${mem}
+
+# run gaussian
+g16 < ${input_file}
+
+# clean up temp $SCRATCH directory
+# this moves the rwf file from Gaussian to the
+# directory you submitted the job from. 
+# Note, if the job runs out of time, memory, or
+# fails in some other way, these commands may not be reached.
+
+# You should make sure you are keeping the files you need
+# this is just an example of a plausible workflow.
+# For instance, you may want to keep the checkpoint files
+mv *.rwf ${SLURM_SUBMIT_DIR}/
+cd ${SLURM_SUBMIT_DIR}
+rm -rf ${job_dir}

docs/examples/gaussian/gaussian_example.cpu

@@ -0,0 +1,17 @@
+%CPU=
+%Mem=
+%Chk=gaussian_example_cpu.chk
+%rwf=water.rwf
+#opt HF/3-21g
+
+! this is a comment, and it is ignored by Gaussian
+water molecule energy and geometry optimization
+
+0 1
+O 0.000000 0.000000 0.062600
+H -0.792701 0.000000 -0.497300
+H 0.792701 0.000000 -0.497300
+
+1 2 3
+2 1
+3 1

docs/examples/gaussian/index.md

@@ -0,0 +1,84 @@
+# Gaussian
+
+:::{important}
+Access to Gaussian requires permission. Please open a help ticket by emailing
+[help@smu.edu with
+"[HPC]"](mailto:help@smu.edu?subject=[HPC]%20Gaussian%20Access%20Request)
+in the subject line.
+:::
+
+**Gaussian** Gaussian series of electronic structure programs, used by chemists, chemical engineers, biochemists, physicists and other scientists worldwide.
+
+**Gaussian homepage**: [gaussian.com/](https://gaussian.com/)
+
+**Official Gaussian Manual**: [gaussian.com/man/](https://gaussian.com/man/)
+
+:::{seealso}
+For examples and tips on submitting jobs, see [our SLURM documentation](tutorials:slurm) and [Best Practices for Jobs](tutorials:slurm:best_practices)
+
+For compute resources, see [HPC Queues](about:queues)
+:::
+
+<!-- ## Using Gaussian on the SuperPod
+
+Files used in the example are available:
+
+  - [on github](https://github.com/SouthernMethodistUniversity/hpc_docs/tree/main/docs/examples/gaussian)
+  - on the SuperPod at `/hpc/mp/examples/gaussian/`
+
+### Example submission script
+
+The following job script can be submitted using `sbatch gaussian_gpu_example.sbatch`.
+
+```{literalinclude} gaussian_gpu_example.sbatch
+---
+language: bash
+linenos: true
+---
+``` -->
+
+## Using Gaussian on M3
+
+Files used in the example are available:
+
+  - [on github](https://github.com/SouthernMethodistUniversity/hpc_docs/tree/main/docs/examples/gaussian)
+  - on M3 at `/hpc/m3/examples/gaussian/` 
+
+### Example submission script
+
+The following job script can be submitted using `sbatch guassian_cpu_example.sbatch`.
+
+This example will run in about 10 seconds and use less that `1GB` of memory.
+In general, more complicated simulations will take much longer and should typically
+use more cores and memory. Note, we know this from running the job.
+It is always a good idea to review the resources your jobs use
+and adjust future jobs to more accurately request resources.
+
+This uses the `dev`
+queue which has a 2 hour time limit.
+In general, the `dev` queue should only be used for testing code and running interactive
+sessions.
+Most normal jobs should be submitted to the standard queues such as `standard-s` where
+longer runtimes are allowed.
+
+This example also writes output to `$SCRATCH`. 
+`$SCRATCH` is a high performance file system designed to be used for temporary
+job files and data.
+After a job has finished running, any data you need to keep should be moved to
+a project directory or your $HOME directory.
+**Files in `SCRATCH` are subject to a 60 day purge policy where files older than 60 days
+may be automatically deleted without warning.**
+
+:::{note}
+This job script will not run without modification. In particular, you must change
+the account from `peruna_project_0001` to the account name for an allocation you
+have access to.
+:::
+
+```{literalinclude} gaussian_cpu_example.sbatch                 
+---
+language: bash
+linenos: true
+---
+```
+