driver_script

A driver_script file is used to generate a driver script that can be used to automate several steps, including running multiple cases, and comparing output. This file contains information describing how to create a script that can be used to perform multiple steps in the process of running a test. This includes running multiple run scripts within case directories, or performing standard actions, such as comparing multiple output files.

Below, you will see text describing the various XML tags available in a driver_script file. Each will describe the tag itself, any attributes the tag can have, and what children can be placed below the tag.

<driver_script> - This tag defines a driver script for a set of case directories.

  • Attributes:

    • name: The name of the driver script that will be generated

  • Children:

    • <case>

    • <step>

    • <define_env_var>

    • <validation>

<case> - This tag defines the case that will be used for part of a driver script. It implies the driver script should cd into the case directory before executing the steps and arguments defined within.

  • Attributes:

    • name: The name of the case directory that will be used for this portion of the driver script.

  • Children:

    • <step>

    • <define_env_var>

<step> - This tag defines a step in a driver script

  • Attributes:

    • executable: The base executable for this step of the script. e.g. test_model

    • executable_name: The name of the executable that has been defined in the configuration file to be used for this step of the script.

  • Children:

    • <argument>

<argument> - This tag defines arguments for the executable in a specific step of a script.

  • Attributes:

    • flag: A flag that will come before the argument. e.g. -n

  • Text:

    • The text between the <argument> and </argument> tags will be used as the argument after the flag. In the example mpirun -np 4 the flag would be -np, and the text would be 4.

<define_env_var> - This tag is used to define an environment variable which might be needed when running the model. For example, setting the value of OMP_NUM_THREADS to ensure OpenMP threading is used.

  • Attributes:

    • name: The name of the variable that will be set

    • value: The value that will be given to the variable

<validation> - This tag is used to define a block of validations that should happen within the driver script. These validations are standard operations that multiple driver scripts can use easily, such as comparing fields in multiple files or against baselines. Test case specific validations might happen in separate steps.

  • Children:

    • <compare_fields>

    • <compare_timers>

<compare_fields> - This tag is used to define a comparison of specified fields in two NetCDF files.

  • Attributes:

    • file1: This defines the first file in the comparison. Relative to the <core>/<configuration>/<resolution> directory. Will also cause file1 to be compared against file1 in the baseline directory.

    • file2: This defines the second file in the comparison. Relative to the <core>/<configuration>/<resolution> directory. Will also cause file2 to be compared against file2 in the baseline directory.

    • NOTE: If only one of file1 or file2 is specified, the testcase will only compare against baselines.

  • Children:

    • <field>

    • <template>

<field> - This tag is used to define a field that will be compared within a <compare_fields> tag. Any norm thresholds that are specified all must pass to have the comparison pass.

  • Attributes:

    • name: This attribute defines the name of the field that will be compared

    • l1_norm: This attribute defines the threshold for an L1 norm, to define a pass. If not specified, the L1 norm will not be used in determining if the comparison passes or fails.

    • l2_norm: This attribute defines the threshold for an L2 norm, to define a pass. If not specified, the L2 norm will not be used in determining if the comparison passes or fails.

    • linf_norm: This attribute defines the threshold for an L-Infinity norm, to define a pass. If not specified, the L-Infinity norm will not be used in determining if the comparison passes or fails.

<template> - This tag defines a template that should be applied to define a list of field comparisions.

  • Attributes:

    • file: The file that contains the template that should be expanded here.

    • path_base: The base that the path attribute should be used relative to. Can be a pre-defined paths (see config)

    • path: The path that the file lives in, relative to path_base.

<compare_timers> - This tag is used to define a comparison of timers in two run directories. The comparison will work with native or gptl timers automatically.

  • Attributes:

    • rundir1: This is the first run directory to compare. If it is the only one specified timers in it will be compared only against it’s baseline.

    • rundir2: This is the second run directory to compare. If it is the only one specified timers in it will be compared only against it’s baseline.

  • Children:

    • <timer>

    • <template>

<timer> - This tag is used to define a timer that should be compared between two run directories.

  • Attributes:

    • name: This is the name of the timer to compare. It should be the full expected name of the timer, not the printed name from the timer library.