From 3bc8822cb5284024ca32efc61779617aaddc9048 Mon Sep 17 00:00:00 2001 From: Jason Fleming Date: Mon, 24 May 2021 11:00:07 -0400 Subject: [PATCH 1/9] Added usage notes to the container readme --- .gitignore | 2 +- CONTAINER-README.md | 31 ++++++++++++++++++------------- 2 files changed, 19 insertions(+), 14 deletions(-) diff --git a/.gitignore b/.gitignore index 16181d2..ff1e0e4 100644 --- a/.gitignore +++ b/.gitignore @@ -6,7 +6,7 @@ cmake-build-debug example *.png *.jpg - +.vscode */Temp .gmtdefaults* \ No newline at end of file diff --git a/CONTAINER-README.md b/CONTAINER-README.md index e986a61..6f33cc8 100644 --- a/CONTAINER-README.md +++ b/CONTAINER-README.md @@ -1,11 +1,11 @@ # Using the FigureGen Containers -Contact: Georgia Stuart, georgia.stuart@austin.utexas.edu +Contact: Georgia Stuart, georgia.stuart@austin.utexas.edu 7 February 2021 ## Input File Setup -For both Singularity and Docker container use, the path option for `ghostscript` and `gmt` +For both Singularity and Docker container use, the path option for `ghostscript` and `gmt` **must be left blank**. See `autotest/docker-test/BathyFilledCPT.inp` for example. ## Singularity Containers @@ -20,19 +20,19 @@ In addition, we maintain a [FigureGen folder](https://cloud.sylabs.io/library/_c ### Using pre-built Singularity containers from the library -Running singularity containers assumes **your current working directory is where your ADCIRC datafiles are**. +Running singularity containers assumes **your current working directory is where your ADCIRC datafiles are**. By default, singularity mounts your current working directory and `$HOME` so we have direct file access. -To download the image from the cloud library (e.g., to the root `FigureGen` folder of this repository, or to some other +To download the image from the cloud library (e.g., to the root `FigureGen` folder of this repository, or to some other convenient location for singularity images), run the command: ```bash singularity pull figuregen.sif library://georgiastuart/figuregen/figuregen ``` -This command will pull down the latest `figuregen` image located at the cloud library and save it locally +This command will pull down the latest `figuregen` image located at the cloud library and save it locally to `figuregen.sif`. Similarly, replace `figuregen` with `figuregen-serial` or `figuregen-tacc` to run the -serial or TACC versions of `figuregen`, respectively. +serial or TACC versions of `figuregen`, respectively. ------------------------- **NOTE** @@ -61,7 +61,7 @@ singularity pull figuregen-serial.sif library://georgiastuart/figuregen/figurege singularity pull figuregen-tacc.sif library://georgiastuart/figuregen/figuregen-tacc ``` -To run the tests in this repository, `cd` to `autotest/TestFiles` and run the following +To run the tests in this repository, `cd` to `autotest/TestFiles` and run the following command (for example): ##### MPI Example @@ -97,7 +97,7 @@ Replace `figuregen.def` with `figuregen-serial.def` or `figuregen-tacc.def` as a ## Docker Containers For use on MacOS and Windows, we also provide Docker containers. **All docker container instructions -rely on your data files and input files being in the same directory** (e.g., the `autotest/docker-test` directory in this +rely on your data files and input files being in the same directory** (e.g., the `autotest/docker-test` directory in this repository). We maintain two Docker images for use on local machines (not HPC clusters. Use Singularity for HPC). @@ -109,7 +109,7 @@ georgiastuart/figuregen-serial ### Install Docker -Mac instructions: https://docs.docker.com/docker-for-mac/install/ +Mac instructions: https://docs.docker.com/docker-for-mac/install/ Windows instructions: https://docs.docker.com/docker-for-windows/install/ ### Run FigureGen Containers @@ -122,7 +122,7 @@ Running `FigureGen` in a Docker container requires four steps: #### Pull the Docker Image -First, pull the Docker image with the following command: +First, pull the Docker image with the following command: ``` docker pull georgiastuart/figuregen @@ -132,8 +132,8 @@ Similarly, `georgiastuart/figuregen-serial`. #### Launch the Docker Container -We need to launch the docker container while binding your desired data directory to `/data` -in the container. Use the following command (**assuming your current working directory is +We need to launch the docker container while binding your desired data directory to `/data` +in the container. Use the following command (**assuming your current working directory is where your data and input files are**): ##### Mac/Linux @@ -163,14 +163,19 @@ Next, we will run the `FigureGen` program and set the working directory to `/dat ``` docker exec -it -w /data figuregen mpirun -np figuregen -I ``` +To run FigureGen in serial, the executable is named `figuregen` although the container is named `figuregen-serial`: +``` +docker exec -it -w /data figuregen-serial figuregen -I +``` #### Shut Down the Container -Finally, after your plots are satisfactory, we shut down the Docker container. **A new container must +Finally, after your plots are satisfactory, we shut down and remove the Docker container. **A new container must be launched each time you want to plot in a new directory**. ``` docker stop figuregen +docker container rm figuregen ``` ## Tests Completed: From ca29f41783ca80d3c5f9bfe1ec1b0aafa58f58ac Mon Sep 17 00:00:00 2001 From: Jason Fleming Date: Mon, 24 May 2021 11:03:17 -0400 Subject: [PATCH 2/9] clarified meaning of launch --- CONTAINER-README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTAINER-README.md b/CONTAINER-README.md index 6f33cc8..ac5c26e 100644 --- a/CONTAINER-README.md +++ b/CONTAINER-README.md @@ -171,7 +171,7 @@ docker exec -it -w /data figuregen-serial figuregen -I #### Shut Down the Container Finally, after your plots are satisfactory, we shut down and remove the Docker container. **A new container must -be launched each time you want to plot in a new directory**. +be launched with 'docker run' each time you want to plot in a new directory**. ``` docker stop figuregen From 36ee2ef56e2efd04fef0e427be4350a2b38c068c Mon Sep 17 00:00:00 2001 From: Jason Fleming Date: Mon, 24 May 2021 11:31:12 -0400 Subject: [PATCH 3/9] clarify inp files --- CONTAINER-README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/CONTAINER-README.md b/CONTAINER-README.md index ac5c26e..5a233a0 100644 --- a/CONTAINER-README.md +++ b/CONTAINER-README.md @@ -5,8 +5,8 @@ Contact: Georgia Stuart, georgia.stuart@austin.utexas.edu ## Input File Setup -For both Singularity and Docker container use, the path option for `ghostscript` and `gmt` -**must be left blank**. See `autotest/docker-test/BathyFilledCPT.inp` for example. +For both Singularity and Docker container use, the path option for `ghostscript` and `gmt` in the FigureGen input +parameters file (ending in `.inp`) **must be left blank**. See `autotest/docker-test/BathyFilledCPT.inp` for example. ## Singularity Containers From 086adfaf2050164b62c87494e72dd6119beb8d10 Mon Sep 17 00:00:00 2001 From: Jason Fleming Date: Thu, 27 May 2021 12:39:32 -0400 Subject: [PATCH 4/9] Added documentation of multiple execution --- CONTAINER-README.md | 67 +++++++++++++++++++++++++++++++++++++-------- 1 file changed, 55 insertions(+), 12 deletions(-) diff --git a/CONTAINER-README.md b/CONTAINER-README.md index 5a233a0..af76c47 100644 --- a/CONTAINER-README.md +++ b/CONTAINER-README.md @@ -130,25 +130,25 @@ docker pull georgiastuart/figuregen Similarly, `georgiastuart/figuregen-serial`. -#### Launch the Docker Container +#### Launch, Execute, Stop, Remove -We need to launch the docker container while binding your desired data directory to `/data` -in the container. Use the following command (**assuming your current working directory is -where your data and input files are**): +There are two ways to use the FigureGen container. The first way, described in this section, is to launch the docker container in the same directory that holds the FigureGen controls parameter file (`*.inp`) and all the ADCIRC data files that it will need. In this case, you will be binding your desired data directory to `/data` in the container. Once execution is complete in this scenario, you will need to stop and remove the container before repeating this sequence in a different directory. -##### Mac/Linux +To start, use the following command (**assuming your current working directory is where your data and input files are**): + +##### Mac/Linux Launch ``` docker run -d -it --name figuregen --mount type=bind,source="$(pwd)",target=/data georgiastuart/figuregen ``` -##### Windows (Command Prompt) +##### Windows Launch (Command Prompt) ``` docker run -d -it --name figuregen --mount type=bind,source="%cd%",target=/data georgiastuart/figuregen ``` -##### Windows (Power Shell) +##### Windows Launch (Power Shell) ``` docker run -d -it --name figuregen --mount type=bind,source="${PWD}",target=/data georgiastuart/figuregen @@ -156,9 +156,9 @@ docker run -d -it --name figuregen --mount type=bind,source="${PWD}",target=/dat Similarly for `georgiastuart/figuregen-serial`. -#### Run the FigureGen Program +##### Execute FigureGen -Next, we will run the `FigureGen` program and set the working directory to `/data`: +Next, we will execute the `FigureGen` program and set the working directory to `/data`: ``` docker exec -it -w /data figuregen mpirun -np figuregen -I @@ -168,10 +168,53 @@ To run FigureGen in serial, the executable is named `figuregen` although the con docker exec -it -w /data figuregen-serial figuregen -I ``` -#### Shut Down the Container +##### Stop and Remove the Container + +Finally, after your plots are satisfactory, we shut down and remove the Docker container. **A new container must be launched with 'docker run' each time you want to plot in a new directory**. + +``` +docker stop figuregen +docker container rm figuregen +``` +#### Launch, Multiple Executions + +A second way to use the FigureGen container is to specify a "data root" directory when launching it (e.g., `/home/myname/alldata`). The idea is that this directory contains multiple subdirectories with ADCIRC data and associated FigureGen control parameter files (`*.inp`). Then FigureGen can be executed more than once, with data in different subdirectories, without shutting down, removing, and relaunching the container in betweeen executions. This second method is described in this section. + +To start, use the following command (**assuming the /home/myname/alldata (or c:\myname\alldata) directory contains subdirectories where your data and input files are**): + +##### Mac/Linux Launch + +``` +docker run -d -it --name figuregen --mount type=bind,source="/home/myname/alldata",target=/data georgiastuart/figuregen +``` + +##### Windows Launch + +``` +docker run -d -it --name figuregen --mount type=bind,source="c:\myname\alldata",target=/data georgiastuart/figuregen +``` + +Similarly for `georgiastuart/figuregen-serial`. + +##### Execute FigureGen + +Next, we will execute the `FigureGen` program multiple times and specify the subdirectory containing the data each time. If we assume that there are three and that they are named according to the pattern `run[n]`, for example `/home/myname/alldata/run1` (or `c:\myname\alldata\run1`): + +``` +docker exec -it --workdir=/data/run1 figuregen mpirun -np figuregen -I +docker exec -it --workdir=/data/run2 figuregen mpirun -np figuregen -I +docker exec -it --workdir=/data/run3 figuregen mpirun -np figuregen -I +``` +To run FigureGen in serial, the executable is named `figuregen` although the container is named `figuregen-serial`: +``` +docker exec -it --workdir=/data/run1 figuregen-serial figuregen -I +docker exec -it --workdir=/data/run2 figuregen-serial figuregen -I +docker exec -it --workdir=/data/run3 figuregen-serial figuregen -I +``` + +##### Stop and Remove the Container -Finally, after your plots are satisfactory, we shut down and remove the Docker container. **A new container must -be launched with 'docker run' each time you want to plot in a new directory**. +Finally, after your plots are satisfactory, and you don't have any more plots to make, you can shut down and remove the Docker container. **A new container must be launched with 'docker run' each time you want to plot in a new "data root" directory**. ``` docker stop figuregen From 025dbdc521798e8bc2f34c9cd208e2e6c27b4ba6 Mon Sep 17 00:00:00 2001 From: Jason Fleming Date: Thu, 27 May 2021 13:00:50 -0400 Subject: [PATCH 5/9] Updated image and container usage --- CONTAINER-README.md | 34 ++++++++++++++++------------------ 1 file changed, 16 insertions(+), 18 deletions(-) diff --git a/CONTAINER-README.md b/CONTAINER-README.md index af76c47..f94d4b1 100644 --- a/CONTAINER-README.md +++ b/CONTAINER-README.md @@ -83,10 +83,9 @@ ibrun singularity exec figuregen -I ../Tests/BathyF **Note:** The TACC container gives some harmless errors that can be safely ignored. -### Building Singularity Containers +### Building Singularity Images -To build a Singularity container yourself, from the root `FigureGen` directory of this repository, -use this command *on a machine where you have sudo privileges*: +To build a Singularity image yourself, from the root `FigureGen` directory of this repository, use this command *on a machine where you have sudo privileges*: ``` sudo singularity build figuregen.sif container-files/singularity-def-files/figuregen.def @@ -96,11 +95,7 @@ Replace `figuregen.def` with `figuregen-serial.def` or `figuregen-tacc.def` as a ## Docker Containers -For use on MacOS and Windows, we also provide Docker containers. **All docker container instructions -rely on your data files and input files being in the same directory** (e.g., the `autotest/docker-test` directory in this -repository). - -We maintain two Docker images for use on local machines (not HPC clusters. Use Singularity for HPC). +For use on MacOS and Windows, we also provide Docker images. We maintain two Docker images for use on local machines (not HPC clusters. Use Singularity for HPC). ``` georgiastuart/figuregen @@ -110,29 +105,32 @@ georgiastuart/figuregen-serial ### Install Docker Mac instructions: https://docs.docker.com/docker-for-mac/install/ + Windows instructions: https://docs.docker.com/docker-for-windows/install/ ### Run FigureGen Containers Running `FigureGen` in a Docker container requires four steps: -1. Pull the desired Docker container (listed above) -1. Launch the container and bind the directory with your data and input files to `/data` -2. Execute the `figuregen` executable and set working directory to `/data` -4. Shut the docker container down +1. Pull the desired Docker image (listed above) +2. Launch the container and bind the host directory of interest to the `/data` directory in the container +3. Execute `figuregen`, setting the working directory inside the container on the command line +4. Stop the docker container and remove it + +Steps 2 and 3 can be set two different ways depending on whether FigureGen will be executed multiple times (more details in the description below). Steps 1 and 4 are the same for any launch and execution scenario. #### Pull the Docker Image First, pull the Docker image with the following command: - ``` docker pull georgiastuart/figuregen ``` - Similarly, `georgiastuart/figuregen-serial`. +This step normally only needs to be done once, the first time FigureGen is used on that platform. It would also have to be repeated if the image is updated on DockerHub. + #### Launch, Execute, Stop, Remove -There are two ways to use the FigureGen container. The first way, described in this section, is to launch the docker container in the same directory that holds the FigureGen controls parameter file (`*.inp`) and all the ADCIRC data files that it will need. In this case, you will be binding your desired data directory to `/data` in the container. Once execution is complete in this scenario, you will need to stop and remove the container before repeating this sequence in a different directory. +There are two ways to use the FigureGen container. The first way, described in this section, is to launch the docker container in the same directory that holds the FigureGen controls parameter file (`*.inp`) and all the ADCIRC data files that it will need. In this case, you will be binding your desired data directory on the host machine to the `/data` directory in the container. Once execution is complete in this scenario, you will need to stop and remove the container before repeating this sequence in a different directory. To start, use the following command (**assuming your current working directory is where your data and input files are**): @@ -178,7 +176,7 @@ docker container rm figuregen ``` #### Launch, Multiple Executions -A second way to use the FigureGen container is to specify a "data root" directory when launching it (e.g., `/home/myname/alldata`). The idea is that this directory contains multiple subdirectories with ADCIRC data and associated FigureGen control parameter files (`*.inp`). Then FigureGen can be executed more than once, with data in different subdirectories, without shutting down, removing, and relaunching the container in betweeen executions. This second method is described in this section. +A second way to use the FigureGen container is to specify a "data root" directory on the host machine when running it (e.g., `/home/myname/alldata`). The idea is that this directory contains multiple subdirectories with ADCIRC data and associated FigureGen control parameter files (`*.inp`). Then FigureGen can be executed more than once, with data in different subdirectories, without shutting down, removing, and relaunching the container in betweeen executions in different directories. This second method is described in this section. To start, use the following command (**assuming the /home/myname/alldata (or c:\myname\alldata) directory contains subdirectories where your data and input files are**): @@ -198,7 +196,7 @@ Similarly for `georgiastuart/figuregen-serial`. ##### Execute FigureGen -Next, we will execute the `FigureGen` program multiple times and specify the subdirectory containing the data each time. If we assume that there are three and that they are named according to the pattern `run[n]`, for example `/home/myname/alldata/run1` (or `c:\myname\alldata\run1`): +Next, we will execute the `FigureGen` program multiple times and specify the subdirectory containing the data each time. If we assume that there are three subdirectories and that they are named according to the pattern `run[n]`, for example `/home/myname/alldata/run1` (or `c:\myname\alldata\run1`): ``` docker exec -it --workdir=/data/run1 figuregen mpirun -np figuregen -I @@ -214,7 +212,7 @@ docker exec -it --workdir=/data/run3 figuregen-serial figuregen -I Date: Thu, 27 May 2021 13:03:22 -0400 Subject: [PATCH 6/9] Another update container vs image usage --- CONTAINER-README.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/CONTAINER-README.md b/CONTAINER-README.md index f94d4b1..1377006 100644 --- a/CONTAINER-README.md +++ b/CONTAINER-README.md @@ -18,7 +18,7 @@ We provide three Singularity definition files: In addition, we maintain a [FigureGen folder](https://cloud.sylabs.io/library/_collection/602041171e573cd09be5c019) at the [Singularity Container Library](https://cloud.sylabs.io/library). -### Using pre-built Singularity containers from the library +### Pre-Built Singularity Images Running singularity containers assumes **your current working directory is where your ADCIRC datafiles are**. By default, singularity mounts your current working directory and `$HOME` so we have direct file access. @@ -30,9 +30,7 @@ convenient location for singularity images), run the command: singularity pull figuregen.sif library://georgiastuart/figuregen/figuregen ``` -This command will pull down the latest `figuregen` image located at the cloud library and save it locally -to `figuregen.sif`. Similarly, replace `figuregen` with `figuregen-serial` or `figuregen-tacc` to run the -serial or TACC versions of `figuregen`, respectively. +This command will pull down the latest `figuregen` image located at the cloud library and save it locally to `figuregen.sif`. Similarly, replace `figuregen` with `figuregen-serial` or `figuregen-tacc` to run the serial or TACC versions of `figuregen`, respectively. ------------------------- **NOTE** From 87ad98c4497c888246f5fd829bb83c2925dd8b7e Mon Sep 17 00:00:00 2001 From: Jason Fleming Date: Thu, 27 May 2021 13:09:53 -0400 Subject: [PATCH 7/9] Rearranged the singularity section: build and exec --- CONTAINER-README.md | 42 +++++++++++++++++++++++------------------- 1 file changed, 23 insertions(+), 19 deletions(-) diff --git a/CONTAINER-README.md b/CONTAINER-README.md index 1377006..9e28898 100644 --- a/CONTAINER-README.md +++ b/CONTAINER-README.md @@ -32,6 +32,23 @@ singularity pull figuregen.sif library://georgiastuart/figuregen/figuregen This command will pull down the latest `figuregen` image located at the cloud library and save it locally to `figuregen.sif`. Similarly, replace `figuregen` with `figuregen-serial` or `figuregen-tacc` to run the serial or TACC versions of `figuregen`, respectively. +```bash +singularity pull figuregen-serial.sif library://georgiastuart/figuregen/figuregen-serial +singularity pull figuregen-tacc.sif library://georgiastuart/figuregen/figuregen-tacc +``` + +### Building Singularity Images + +To build a Singularity image yourself, from the root `FigureGen` directory of this repository, use this command *on a machine where you have sudo privileges*: + +``` +sudo singularity build figuregen.sif container-files/singularity-def-files/figuregen.def +``` + +Replace `figuregen.def` with `figuregen-serial.def` or `figuregen-tacc.def` as appropriate. + +### Running Singularity Containers + ------------------------- **NOTE** @@ -49,31 +66,27 @@ To use an `idev` node on `Stampede2`, run idev -A -N 1 -n ``` -**At least two processes must be specified to run the TACC-compatible singularity container.** It *cannot* -run serially. +**At least two processes must be specified to run the TACC-compatible singularity container.** It *cannot* run serially. ------------------------ -```bash -singularity pull figuregen-serial.sif library://georgiastuart/figuregen/figuregen-serial -singularity pull figuregen-tacc.sif library://georgiastuart/figuregen/figuregen-tacc -``` - To run the tests in this repository, `cd` to `autotest/TestFiles` and run the following command (for example): -##### MPI Example +#### MPI Example ```bash singularity exec mpirun -np figuregen -I ../Tests/BathyFilledCPT.inp ``` -##### Serial Example +#### Serial Example ```bash singularity exec figuregen -I ../Tests/BathyFilledCPT.inp ``` -##### TACC/HPC Example (e.g. on Stampede2. DO NOT RUN ON LOGIN NODE.) +##### TACC/HPC Example + +For example, on Stampede2. **DO NOT RUN ON LOGIN NODE.** ```bash ibrun singularity exec figuregen -I ../Tests/BathyFilledCPT.inp @@ -81,15 +94,6 @@ ibrun singularity exec figuregen -I ../Tests/BathyF **Note:** The TACC container gives some harmless errors that can be safely ignored. -### Building Singularity Images - -To build a Singularity image yourself, from the root `FigureGen` directory of this repository, use this command *on a machine where you have sudo privileges*: - -``` -sudo singularity build figuregen.sif container-files/singularity-def-files/figuregen.def -``` - -Replace `figuregen.def` with `figuregen-serial.def` or `figuregen-tacc.def` as appropriate. ## Docker Containers From 684eab8eb624b74a287ed822a28522f6cdd9d001 Mon Sep 17 00:00:00 2001 From: Jason Fleming Date: Thu, 27 May 2021 13:11:55 -0400 Subject: [PATCH 8/9] Corrected header level --- CONTAINER-README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTAINER-README.md b/CONTAINER-README.md index 9e28898..a2ec975 100644 --- a/CONTAINER-README.md +++ b/CONTAINER-README.md @@ -84,7 +84,7 @@ singularity exec mpirun -np figuregen -I singularity exec figuregen -I ../Tests/BathyFilledCPT.inp ``` -##### TACC/HPC Example +#### TACC/HPC Example For example, on Stampede2. **DO NOT RUN ON LOGIN NODE.** From 522ab3b3b4ea21dcf55c172d10eeb6c5d894b836 Mon Sep 17 00:00:00 2001 From: Jason Fleming Date: Thu, 27 May 2021 13:15:44 -0400 Subject: [PATCH 9/9] Updated to clarify subdirectory --- CONTAINER-README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTAINER-README.md b/CONTAINER-README.md index a2ec975..3d45028 100644 --- a/CONTAINER-README.md +++ b/CONTAINER-README.md @@ -178,7 +178,7 @@ docker container rm figuregen ``` #### Launch, Multiple Executions -A second way to use the FigureGen container is to specify a "data root" directory on the host machine when running it (e.g., `/home/myname/alldata`). The idea is that this directory contains multiple subdirectories with ADCIRC data and associated FigureGen control parameter files (`*.inp`). Then FigureGen can be executed more than once, with data in different subdirectories, without shutting down, removing, and relaunching the container in betweeen executions in different directories. This second method is described in this section. +A second way to use the FigureGen container is to specify a "data root" directory on the host machine when running it (e.g., `/home/myname/alldata`). The idea is that this directory contains multiple subdirectories with ADCIRC data and associated FigureGen control parameter files (`*.inp`). Then FigureGen can be executed more than once, with data in different subdirectories, without shutting down, removing, and relaunching the container in betweeen executions in different subdirectories. This second method is described in this section. To start, use the following command (**assuming the /home/myname/alldata (or c:\myname\alldata) directory contains subdirectories where your data and input files are**):