-
Notifications
You must be signed in to change notification settings - Fork 35
DockerAndCI
Docker images are automatically created for each branch of both Amanzi and ATS, and stored at DockerHub under the group metsi.
To quickly test your local docker environment you can use
docker run -it --rm metsi/ats:ats-1.1-latest ats --version
and you should see output like,
ATS version 1.0.0_4dcfba79
Docker will download the image from dockerhub.com if you don't have it stored locally already.
To run the tests and demos with the Docker image, using the input files on your local system, and post process or plot with your own scripts, you don't need the ATS Source code.
To obtain the ATS demos we recommend using git,
cd <YOUR_PATH_TO_CODES>
git clone https://github.com/amanzi/ats-demos ats-demos-1.1
cd ats-demos-1.1
git checkout ats-demos-1.1
This will clone the ats-demos repository, and checkout the release branch (ats-1.1).
There is a script to help you run local files (https://github.com/amanzi/amanzi/Docker/run-ats-docker), and have the output written to a local directory. You can take this script and modify it to your needs, also we plan to improve the flexibility of the script over time.
Here we explain the options used in this script, and how this relates to the ATS image we created. Specifically, to run with a local input file and to have output written locally we have to share a directory from the host system (your computer) and the container system (the running Amanzi image). The options we use are:
-v mount_point_on_host:mount_point_on_container
-w sets current working directory on the container
--rm deletes the container on exit
If we define a few environment variables the use of these options in the docker run command should be fairly intuitive. Specifically, we define,
HOST_MNT=`pwd -P`
CONT_MNT=/home/amanzi_user/work
CONT_PWD=/home/amanzi_user/work
leads to a command like,
docker run --rm -v $HOST_MNT:$CONT_MNT:delegated -w $CONT_PWD metsi/ats:ats-1.1-latest ats --xml_file=<XML_INPUT_FILE>
To run in parallel with mpirun the command would be,
docker run --rm -v $HOST_MNT:$CONT_MNT:delegated -w $CONT_PWD metsi/ats:ats-1.1-latest mpirun -n 4 ats --xml_file=<XML_INPUT_FILE>
To use this approach to run a subsurface infiltration problem (a single column, with Richards model), you would take the following steps:
cd <path-to-ats-demos-repo>/02_richards
HOST_MNT=`pwd -P`
CONT_MNT=/home/amanzi_user/work
CONT_PWD=/home/amanzi_user/work
docker run --rm -v $HOST_MNT:$CONT_MNT:delegated -w $CONT_PWD metsi/ats:ats-1.1-latest ats --xml_file=infiltration.xml
Note:
- We use a serial run here because this is a single vertical column, so it can't be run in parallel with the default mesh partitioning.
- This assumes all data files are read from, and output files are written to, a directory level of the HOST_MNT or lower (in subdirectories), i.e., references like ../data/mymesh.exo are not allowed here (see next example for how to handle these cases).
Some of the demo problems use data files that are stored at a directory level above where the ATS simulation is run. For example, in the case of the integrated hydrology demos (04_integrated_hydrology), the directory/subdirectory structure is,
<path-to-ats-demos-repo>/04_integrated_hydrology
<path-to-ats-demos-repo>/04_integrated_hydrology/data
<path-to-ats-demos-repo>/04_integrated_hydrology/*.xml (input files)
However, the input files use meshes from the data directory and reference them as ../data/<mesh_file_name>. Thus, it's clear the simulation actually needs to be executed in a subdirectory, e.g., for the infiltration_limited1.xml simulation we would first create a subdirectory, and then run with a command that sets the HOST_MNT at the level of 04_integrated_hydrology.
cd <path-to-ats-demos-repo>/04_integrated_hydrology
HOST_MNT=`pwd -P`
CONT_MNT=/home/amanzi_user/work
CONT_PWD=/home/amanzi_user/work
mkdir infiltration_limited1
docker run --rm -v $HOST_MNT:$CONT_MNT:delegated -w $CONT_PWD metsi/ats:ats-1.1-latest /bin/bash -c "cd infiltration_limited1; mpirun -n 2 ats --xml_file=../infiltration_limited1.xml"
Note:
- We set the HOST_MNT at the highest level in the directory structure that the simulation needed access to (in this case /04_integrated_hydrology
- We executed ats inside a bash shell so we could change directories in the docker image, thereby ensuring references like ../data/<mesh_file_name>, which are in the input file, are correct and can be accessed in the simulation.
To use the python scripts included with the tests and demos you need the ATS source code. There are a number of ways to get the source code (probably need a page on the options or is it in the user guide).
To obtain the ATS 1.1 release source using git,
cd <YOUR_PATH_TO_CODES>
git clone https://github.com/amanzi/amanzi amanzi-1.1
cd amanzi-1.1
git checkout amanzi-1.1
git submodule update --init --recursive
cd src/physics/ats
git checkout ats-1.1
This will clone the amanzi repository, checkout the release branch (amanzi-1.1), then from there update the submodule for ATS (also putting you on the ats-1.1 branch).
Now that you have the source, you need to set the ATS_SRC_DIR so the python scripts can find a few custom modules. For bash you would enter
export ATS_SRC_DIR=<YOUR_PATH_TO_CODES>/amanzi-1.1/src/physics/ats
They can be run as an ATS executable (without building Amanzi or TPLs). UPDATE THESE INSTRUCTIONS -- Can we run this executable with an xml in the host machine's drive?
docker run --rm meets/ats:<BRANCH>-<SHORTHASH> ats --version
Or the docker container's executable can be run in the container itself:
docker run -it --rm metsi/ats:master-latest /bin/bash
$> ats path_to.xml
Or the docker executable can be used directly in demos and regression tests:
python regression_tests.py my_config.cfg -e metsi/ats/latest -t my_test