Skip to content

Latest commit

 

History

History
389 lines (239 loc) · 12 KB

tdycore_qa_setup.rst

File metadata and controls

389 lines (239 loc) · 12 KB
Raw

QA Repository Setup

Each test for the qa-toolbox consists of input decks for simulators, a configuration file, and an options file.

Tests can be run to produce a time slice (all locations at one time) and/or an observation point (one location at all times).

Install Software

The following software needs to be installed in order to run tdycore-qa:

  • PETSc
  • PFLOTRAN
  • TDycore
  • Sphinx

  1. Install PETSc

    1. Clone PETSc and check out supoorted version

      $ git clone https://gitlab.com/petsc/petsc petsc
$ cd petsc
$ git checkout v3.11.3

    2. Configure PETSc

      $ ./configure --CFLAGS='-O3' --CXXFLAGS='-O3' --FFLAGS='-O3' --with-debugging=no --download-mpich=yes --download-hdf5=yes --download-fblaslapack=yes --download-metis=yes --download-parmetis=yes

    3. Set PETSC_DIR and PETSC_ARCH enviornment variables in ~/.bashrc file.

      $ export PETSC_DIR=/home/username/path_to_top_level_petsc
$ export PETSC_ARCH=gnu-c-debug

    4. Compile PETSc

      $ cd $PETSC_DIR
$ make all

  2. Install PFLOTRAN

    1. Clone PFLOTRAN

      $ git clone https://bitbucket.org/pflotran/pflotran

    2. Compile PFLOTRAN

      $ cd pflotran/src/pflotran
$ make pflotran

  3. Install TDycore

    1. Clone TDycore

      $ git clone https://github.com/TDycores-Project/TDycore.git

    2. Checkout appropriate branch and make TDycore

      $ cd TDycore
$ git checkout rosie/test-prefix-error
$ make

    3. Cd into appropriate folder and make TDycore

      $ cd demo/steadyblock
$ make

  4. Clone qa-toolbox

    $ git clone  https://github.com/TDycores-Project/qa-toolbox.git

Adding Tests to Suite

  1. To create a new test, create a new folder and cd into the folder. All tests placed in the same folder will be grouped together in the documentation. The default title of the group will be the folder name. This can be overwritten in the configuration file (see Step 4 below). If underscores are used in the folder name they will be replaced with spaces in the title for the documentation.

    $ mkdir my_test
$ cd my_test

  2. Create two or more input files for the desired simulators you wish to test. The input file has a file extension based on the simulator you wish to run, such as filename.pflotran, filename.tdycore. The filename will be specified in the configuration file and must be the same for all simulators. For example, you can browse the input decks within the qa-toolbox tests. Note: If working in 2D, 3D, or calculating error only two simulators may be run at a time.

  3. The QA toolbox reads in an options file specified by the user in a standard .opt extension. The options file consists of a series of sections with key-value pairs.

    [section-name]
key = value

    Section names are all lower case with an underscore between words. Required section names are:

    • ouput_options

    Optional section names include:

    • swap_options
    • mapping_options
    • solution_convergence

    An example output_options section is as follows:

    [output_options]
times = 10.0 y, 50.0 y, 100.0 y
locations = 1.0 1.0 1.0, 5.0 1.0 1.0
plot_time_units = years
plot_dimension = 1D
plot_x_label = Time [yr], Distance X [m]
plot_y_label = Liquid Pressure, Liquid Pressure
plot_title = Pflotran Test
variables = liquid_pressure
plot_type = observation, time slice
plot_to_screen = True
plot_error = True
print_error = True
    • times: (Required for time slice) List of times to plot and compare solutions at. Must match the times of outputs created by simulators. Must specify units on last time or all times listed. If running a steady state problem use time: '-999' (No unit required for steady state).
    • locations: (Required for observation point) List of locations (x y z) where specified observation point(s) is indicated in simulator file. Units in [m].
    • plot_time_units: (Required) Units of time to be displayed on plot. (If steady state this variable will be ignored).
    • plot_dimension: (Required) Dimension of simulation. Options include: 1D, 2D, 3D. If plotting in 2D or 3D only two simulators may be tested at a time.
    • plot_x_label: (Required) Label to be put on x axis of plot. If plotting both a time slice and an observation file, two values must be specified here separted by a comma and order must match order of plot_type.
    • plot_y_label: (Required) Label to be put on y axis of plot. If plotting both a time slice and an observation file, two values must be specified here separted by a comma and order must match order of plot_type.
    • plot_title: (Required) Title to be displayed on plot.
    • variables: (Required) Variable to be plotted from the output files. Must match the simulator output format. Custom mapping of variables can be specified in optional section mapping_options.
    • plot_type: (Optional, default: time slice) Observation if plotting observation point, time slice if plotting time slice. If plotting both order must match plot_x_label and plot_y_label.
    • plot_error: (Optional, default: False) True if plotting relative and absolute error, False if not. If True only two simulatos may be run at a time.
    • print_error: (Optional, default: False) When set to True a .stat file will be created with list of error metrics.
    • plot_to_screen: (Optional, default: False) When set to True images will pop up as python script is being run.

    Optional section swap_options defines values of variables in input decks to be tested. Each value will correspond to a different run number when outputting figures.

    [swap_options]
method = list
nx = 20, 40
ny = 30, 50
    • method: (default: list) Options: list, iterative.
      • List: Specifies list of values for different variables. All variables must have the same number of values. The length for each variable should be equal.
      • Iterative: Variables will be increased incrementally for an amount specified by max_attempts. A starting value and an increment should be specified sepearted by a comma. (For example: nx = 12,2 will start nx with a value of 12 and will multiple the value by 2 until max_attempts is reached.)
    • max_attemps: (Required if iterative) Maximum number of iterations to take with iterative method.

    Variables names are listed based on what is defined in the input decks. When defining the variable within the input deck the following format must be used swap{nx,10}.

    An example is shown in pflotran:

    GRID
  TYPE structured
  NXYZ swap{nx,10} 1 1
  BOUNDS
    0.d0 0.d0 0.d0
    100.d0 1.d0 1.d0
  END
END

    The optional section mapping_options can be used when trying to plot unconvential variables and when simulator output names do not match.

    [mapping_options]
Free X1 [M] = X1
Free_X1 [M] = X1

    where Free X1 [M] is the variable name outputted by the simulator and X1 is the variable listed under the variables key in output_options. As many key and value pairs can be listed as needed.

  4. Create the configuration file as a standard .cfg and specify the option file, input deck filenames, and simulators. The title variable is optional and will be displayed as the title for the test in the documentaiton. If no title is specified the title will be the input field for template.

    [OPTIONSFILENAME]
title = Test
template = filename
simulators = pflotran, tdycore

    For example:

    [tpf_vs_pft]
title = Tdycore Two-Point Flux Test
template = tpf_vs_pft
simulators = tdycore, pflotran

    Where tpf_vs_pft.opt is the options file and input decks are named tpf_vs_pft.pflotran and tpf_vs_pft.tdycore.

    Available simulators the toolbox can run include:

    • pflotran
    • tdycore
    • python
    • crunchflow
    • tough3

    If running multiple tests in the same folder, the title for the collection of tests can be set (default is name of folder tests are located in) with an optional info section in the configuration file:

    [info]
title = Tdycore Tests

Setup Qa-Toolbox

  1. Cd in qa-toolbox and set up simulators.sim and config_files.txt.
    1. Create a file called simulators.sim and set local paths to executables of the simulators. See default_simulators.sim as an example.
    2. Create a file called config_files.txt and set the local path to the configuration file for the desired tests. See config_files.txt as an example.

Setup Directory

  1. Make a new folder for the QA repository

    $ mkdir tdycore-qa

  2. Cd into the qa repository and create a documentation directory

    $ cd tdycore-qa
$ mkdir docs

  3. Setup sphinx in documentation directory and follow setup instructions.

    $ sphinx-quickstart

  4. Setup makefile

    1. Cd out of documentation folder and open up new makefile in main directory

      $ cd ..
$ emacs makefile

    2. In makefile set python, and directory to qa_toolbox path.

      PYTHON = python3
QA_TOOLBOX_DIR = ../qa-toolbox

    3. Run the qa_tests in the makefile by setting the directory and documentation directory.

      $(MAKE) --directory=$(QA_TOOLBOX_DIR) DOC_DIR=${PWD}

Running tdycore-qa in Cloud

To run tdycore_qa in the cloud set up travis-ci with the repository and create a.travis.yml file and .sh file in .travis to install petsc, pflotran, and tdycore and run the qa-toolbox.

  1. Write .sh script for travis to run

    1. Clone qa-toolbox

    2. Install PETSc and export PETSc variables

      git clone https://gitlab.com/petsc/petsc petsc
PETSC_GIT_HASH=v3.11.3
DEBUG=1
cd petsc
git checkout ${PETSC_GIT_HASH}
export PETSC_DIR=$PWD
expot PETSC_ARCH=petsc-arch


./configure PETSC_ARCH=petsc-arch \
--with-cc=gcc \
--with-cxx=g++ \
--with-fc=gfortran \
--CFLAGS='-g -O0' --CXXFLAGS='-g -O0' --FFLAGS='-g -O0 -Wno-unused-function' \
--with-clanguage=c \
--with-debug=$DEBUG  \
--with-shared-libraries=0 \
--download-hdf5 \
--download-metis \
--download-parmetis \
--download-fblaslapack \
--download-mpich=http://www.mpich.org/static/downloads/3.2/mpich-3.2.tar.gz


make all

    3. Install Tdycore

    4. Install PFLOTRAN

    5. Clone Tdycore test directory you created previously with the configuration file, options file, and input decks

    6. Move back to the home directory and purge python2.7 and install python3

      cd ../../..
sudo apt-get update
sudo apt purge python2.7-minimal
sudo apt-get -y install python3 python3-h5py python3-matplotlib
sudo apt-get -y install python3-tk python3-scipy

    7. Create file called simulators.sim within qa-toolbox that sets paths to simulator executables

      echo '[simulators]
tdycore =' $pwd'/TDycore/demo/steadyblock/steadyblock
pflotran =' $pwd'/pflotran/src/pflotran/pflotran' >$PWD/qa-toolbox/simulators.sim

    8. Create file called config_files.txt within qa-toolbox that sets paths to the configuration file you wish to run

      echo '../TDycore-test/2d_block/2d_block.cfg'>$PWD/qa-toolbox/config_files.txt

    9. Run the makefile created earlier in tdycore-qa

      make all

  2. Create a .travis.yml document

    1. Set ubuntu version to Bionic

      dist: Bionic

    2. Set compiler to gcc

      compiler:
  - gcc

    3. Addon package cmake

      addons:
  apt:
    packages:
      - cmake

    4. Set script to run .sh file in /.travis