create_testΒΆ

create_test is a script in CIMEROOT/scripts.

$ ./create_test --help
usage: create_test [-h] [-d] [-v] [-s] [--no-run] [--no-build] [--no-setup]
                   [-u] [--save-timing] [--no-batch] [--single-exe]
                   [--single-submit] [-r TEST_ROOT]
                   [--output-root OUTPUT_ROOT] [--baseline-root BASELINE_ROOT]
                   [--clean] [-m MACHINE] [--mpilib MPILIB] [-b BASELINE_NAME]
                   [-c] [-g] [--compiler COMPILER] [-n] [-p PROJECT]
                   [-t TEST_ID] [-j PARALLEL_JOBS] [--proc-pool PROC_POOL]
                   [--walltime WALLTIME] [-q QUEUE] [-f TESTFILE] [-o]
                   [--wait] [--allow-pnl] [--check-throughput]
                   [--check-memory] [--ignore-namelists] [--ignore-memleak]
                   [--force-procs FORCE_PROCS] [--force-threads FORCE_THREADS]
                   [-i INPUT_DIR] [--pesfile PESFILE] [--retry RETRY] [-N]
                   [--workflow WORKFLOW] [--chksum] [--mail-user MAIL_USER]
                   [-M MAIL_TYPE]
                   testargs [testargs ...]

Script to create, build and run CIME tests. This script can:

1) Run a single test, or more than one test
   ./create_test TESTNAME
   ./create_test TESTNAME1 TESTNAME2 ...
2) Run a test suite from a text file with one test per line
   ./create_test -f TESTFILE
3) Run an E3SM test suite:
  Below, a suite name, SUITE, is defined in $CIMEROOT/scripts/lib/get_tests.py
  - Run a single suite
   ./create_test SUITE
  - Run two suites
   ./create_test SUITE1 SUITE2
  - Run all tests in a suite except for one
   ./create_test SUITE ^TESTNAME
  - Run all tests in a suite except for tests that are in another suite
   ./create_test SUITE1 ^SUITE2
  - Run all tests in a suite with baseline comparisons against master baselines
   ./create_test SUITE1 -c -b master
4) Run a CESM test suite(s):
   ./create_test --xml-category XML_CATEGORY [--xml-machine XML_MACHINE] [--xml-compiler XML_COMPILER] [ --xml-testlist XML_TESTLIST]

If this tool is missing any feature that you need, please add an issue on
https://github.com/ESMCI/cime

positional arguments:
  testargs              Tests or test suites to run. Testname form is TEST.GRID.COMPSET[.MACHINE_COMPILER]

options:
  -h, --help            show this help message and exit
  -d, --debug           Print debug information (very verbose) to file /home/titters/devel/E3SM/cime/master/scripts/create_test.log
  -v, --verbose         Add additional context (time and file) to log messages
  -s, --silent          Print only warnings and error messages
  --no-run              Do not run generated tests
  --no-build            Do not build generated tests, implies --no-run
  --no-setup            Do not setup generated tests, implies --no-build and --no-run
  -u, --use-existing    Use pre-existing case directories they will pick up at the 
                        latest PEND state or re-run the first failed state. Requires test-id
  --save-timing         Enable archiving of performance data.
  --no-batch            Do not submit jobs to batch system, run locally.
                        If false, this will default to machine setting.
  --single-exe          Use a single build for all cases. This can 
                        drastically improve test throughput but is currently use-at-your-own risk.
                        It's up to the user to ensure that all cases are build-compatible.
                        E3SM tests belonging to a suite with share enabled will always share exes.
  --single-submit       Use a single interactive allocation to run all the tests. This can 
                        drastically reduce queue waiting but only makes sense on batch machines.
  -r TEST_ROOT, --test-root TEST_ROOT
                        Where test cases will be created. The default is output root
                        as defined in the config_machines file
  --output-root OUTPUT_ROOT
                        Where the case output is written.
  --baseline-root BASELINE_ROOT
                        Specifies a root directory for baseline datasets that will 
                        be used for Bit-for-bit generate and/or compare testing.
  --clean               Specifies if tests should be cleaned after run. If set, all object
                        executables and data files will be removed after the tests are run.
  -m MACHINE, --machine MACHINE
                        The machine for creating and building tests. This machine must be defined
                        in the config_machines.xml file for the given model. The default is to 
                        to match the name of the machine in the test name or the name of the 
                        machine this script is run on to the NODENAME_REGEX field in 
                        config_machines.xml. WARNING: This option is highly unsafe and should 
                        only be used if you are an expert.
  --mpilib MPILIB       Specify the mpilib. To see list of supported MPI libraries for each machine, 
                        invoke ./query_config. The default is the first listing .
  -b BASELINE_NAME, --baseline-name BASELINE_NAME
                        If comparing or generating baselines, use this directory under baseline root. 
                        Default will be current branch name.
  -c, --compare         While testing, compare baselines
  -g, --generate        While testing, generate baselines. 
                        NOTE: this can also be done after the fact with bless_test_results
  --compiler COMPILER   Compiler for building cime. Default will be the name in the 
                        Testname or the default defined for the machine.
  -n, --namelists-only  Only perform namelist actions for tests
  -p PROJECT, --project PROJECT
                        Specify a project id for the case (optional).
                        Used for accounting and directory permissions when on a batch system.
                        The default is user or machine specified by PROJECT.
                        Accounting (only) may be overridden by user or machine specified CHARGE_ACCOUNT.
  -t TEST_ID, --test-id TEST_ID
                        Specify an 'id' for the test. This is simply a string that is appended 
                        to the end of a test name. If no test-id is specified, a time stamp plus a 
                        random string will be used (ensuring a high probability of uniqueness). 
                        If a test-id is specified, it is the user's responsibility to ensure that 
                        each run of create_test uses a unique test-id. WARNING: problems will occur 
                        if you use the same test-id twice on the same file system, even if the test 
                        lists are completely different.
  -j PARALLEL_JOBS, --parallel-jobs PARALLEL_JOBS
                        Number of tasks create_test should perform simultaneously. The default 
                         is min(num_cores, num_tests).
  --proc-pool PROC_POOL
                        The size of the processor pool that create_test can use. The default is 
                        MAX_MPITASKS_PER_NODE + 25 percent.
  --walltime WALLTIME   Set the wallclock limit for all tests in the suite. 
                        Use the variable CIME_GLOBAL_WALLTIME to set this for all tests.
  -q QUEUE, --queue QUEUE
                        Force batch system to use a certain queue
  -f TESTFILE, --testfile TESTFILE
                        A file containing an ascii list of tests to run
  -o, --allow-baseline-overwrite
                        If the --generate option is given, then an attempt to overwrite 
                        an existing baseline directory will raise an error. WARNING: Specifying this 
                        option will allow existing baseline directories to be silently overwritten.
  --wait                On batch systems, wait for submitted jobs to complete
  --allow-pnl           Do not pass skip-pnl to case.submit
  --check-throughput    Fail if throughput check fails. Requires --wait on batch systems
  --check-memory        Fail if memory check fails. Requires --wait on batch systems
  --ignore-namelists    Do not fail if there namelist diffs
  --ignore-memleak      Do not fail if there's a memleak
  --force-procs FORCE_PROCS
                        For all tests to run with this number of processors
  --force-threads FORCE_THREADS
                        For all tests to run with this number of threads
  -i INPUT_DIR, --input-dir INPUT_DIR
                        Use a non-default location for input files
  --pesfile PESFILE     Full pathname of an optional pes specification file. The file
                        can follow either the config_pes.xml or the env_mach_pes.xml format.
  --retry RETRY         Automatically retry failed tests. >0 implies --wait
  -N, --non-local       Use when you've requested a machine that you aren't on. Will reduce errors for missing directories etc.
  --workflow WORKFLOW   A workflow from config_workflow.xml to apply to this case. 
  --chksum              Verifies input data checksums.
  --mail-user MAIL_USER
                        Email to be used for batch notification.
  -M MAIL_TYPE, --mail-type MAIL_TYPE
                        When to send user email. Options are: never, all, begin, end, fail.
                        You can specify multiple types with either comma-separated args or multiple -M flags.