----------------------------------------

This directory contains the Xyce regression test scripts.

----------------------------------------

run_xyce_regression
  This is the shell script to start a run of the regression suite.

  It takes several optional arguments, the most important one is the absolute
  path to the Xyce binary you want to test.  If you do not specify any
  arguments, then it will use the first Xyce binary on your path.

    There are several optional environment variables that can be specified.
    The first is "XYCE_TEST_HOME".  This environment variable should point to
    which Xyce_Regression you want to run the regression suite on.  If you run this
    script from Xyce_Regression/TestScripts, then the script will assume you want to
    run the regression suite on the Xyce_Regression tree you are currently in.

    The second environment variable is "XYCE_VERIFY".  This environment
    variable should point to which xyce_verify.pl you want to use for comparing
    Xyce runs.  If you don't specify this environment variable, then the script
    will assume you want to use the default:
    $XYCE_TEST_HOME/TestScripts/xyce_verify.pl.

    The third environment variable is "XYCE_COMPARE".  This environment
    variable should point to which compare you want to use for comparing Xyce
    runs.  If you don't specify this environment variable, then the script will
    assume you want to use the default:  $XYCE_TEST_HOME/TestScripts/compare.

    All three of these can be over-ridden with command-line options.

  There are also several command-line options for run_xyce_regression
  that can be examined with the option --help.
  
    The option --testlist=filename, allows you to specify a file containing a
    list of tests to run.  In this case, only those tests will be run.  The
    format for this file is one test per line, the first word on the line is
    the subdirectory of Netlists which contains the test, and the second word
    on the line is the name of the cir file for the test.  For example:

    # Test list title
    # Author / Date
    # Xyce options this set is intended for: ...
    VEXP vexp.cir
    VPULSE vpulse.cir
    VPWL vpwl.cir # This test is just to check pwl waveforms
    VPWL vpwl_filebased.cir
    VSFFM vsffm.cir
    VSIN vsin.cir # And this test is for sine waves
    VSWITCH Vswitch_A1.cir
    Certification_Tests/BUG_408 test.cir
    SandiaTests/FOO foo.cir
    SandiaTests/Certification_Tests/BAR bar.cir

    !NOTE!:  07/30/07 tscoffe:  The correct way to access tests in a checkout
    of Xyce_SandiaRegression is through the symlinks that are generated after
    run_xyce_regression is run.  The "SandiaTests" tests listed above
    demonstrate correct inclusion of these tests.

    One way to generate a list of all the tests currently in Xyce_Regression is as
    follows:
    > cd .../Xyce_Regression/Netlists
    > find ./* -name '*.cir' > test_list_all
    Note that the format returned by find will be parsed correctly by
    run_xyce_regression also.

    If you wish to exclude a set of tests from the default search for tests,
    put a file named "exclude" in the subdirectory where the test resides and
    list the .cir file on a line by itself inside "exclude".  For example:
    > cd .../Xyce_Regression/Netlists/1N759_-55/
    > echo "1N759_-55.cir # Removed for testing" >> exclude

    Another way to exclude tests is through the use of a global exclude file.
    The format is exactly the same as for the testlist file and it is passed to
    run_xyce_regression with the argument --excludelist=filename.  The tests
    listed in the global exclude file will be removed both from searched-for
    tests and from tests listed in a testlist file.

    The Xyce output and test output from the regression tests can be
    re-directed to a different directory by use of the --output=directory
    argument.  

    Here are several example run_xyce_regression commands:

    cd Xyce_Test/TestScripts

    # Find Xyce on path and search for tests in current Xyce_Test tree:
    ./run_xyce_regression 

    # Specify a Xyce binary and a list of tests:
    ./run_xyce_regression /home/user/Xyce/BUILD/src/Xyce --testlist=TestLists/short_list_serial 

    # Specify a Xyce binary and a list of tests and an exclude list and turn on verbose mode:
    ./run_xyce_regression /home/user/Xyce/BUILD/src/Xyce --testlist=TestLists/short_list_serial --excludelist=TestLists/rad_tests --verbose 

    # Specify a Xyce binary, a list of tests, and an output directory:
    ./run_xyce_regression /home/user/Xyce/BUILD/src/Xyce --testlist=TestLists/short_list_serial --output=/tmp/Intel_Linux_SERIAL_regression

    # Specify a Xyce binary and search for tests with a global exclude file and write the resulting list to a file:
    ./run_xyce_regression /home/user/Xyce/BUILD/src/Xyce --excludelist=TestLists/rad_tests --writelist=TestLists/test_for_today 

    # Use run_xyce_regression from a different directory and specify with Xyce_Test to use:
    cd /home/user
    /home/user/Xyce_Test/TestScripts/run_xyce_regression --xyce_test=/home/user/Xyce_Test 


xyce_verify.pl
  This is the comparison program for examining Xyce output and verifying that
  it is correct and matches the gold standard output.  There is a manual page
  for this script in this directory.  To read it use one of the following
  methods.
  > less xyce_verify.pl.man
  > man ./xyce_verify.pl.1

  This script can be run manually on a test, E.g.:
  > cd Xyce_Test/Netlists/MCNC_BJT_LATCH/
  > ../../TestScripts/xyce_verify.pl latch.cir ../../OutputData/MCNC_BJT_LATCH/latch.cir.prn latch.cir.prn
  You can also get xyce_verify.pl to produce an output file for plotting the
  difference between solutions and the calculated relative errors.
  > ../../TestScripts/xyce_verify.pl latch.cir ../../OutputData/MCNC_BJT_LATCH/latch.cir.prn latch.cir.prn plotfile
  You can use your normal plotting routines on this file, except that it does
  not have an "Index" column.

XyceVerify/
  This is where perl modules are stored for use by xyce_verify.pl.

compare.c
  This is the original compare program used for the regression testing.  Not
  all of the tests currently pass the new compare program, xyce_verify.pl, so
  this compare program is used to check these tests.  You will need to compile
  this program before you can use these regression scripts.  See Make_util
  below.

Make_util
  This is the makefile for compare.  You can run it using:
  make -f Make_util

shell_script.cir.sh
  This is an example shell script that will use compare instead of xyce_verify.
  This script can be copied into any [test] directory and renamed [test].cir.sh
  and it will use compare on that test instead of xyce_verify. 

README
  This file.

nightly_build_scripts/
  This is a directory containing old nightly build scripts for Xyce.  
  
