# $Id: README.conf 5330 2011-04-19 10:50:18Z leydold $
#############################################################################
#
# Config file for test routines
#
# This file contains section with subsections.
# Sections are indicated by [<sect>], subsections by [<sect> - <subsect>:]
# (the brackets '[]', the dash '-' and the colon ':' are required).
# There must be a line break after the closing bracket ']'.
#
# The names of the other sections can be arbitrary. However there are some
# restrictions:
#
#   (*) There alway must be a section [main].
#
#   (*) There must no be section [start] nor a subjection [<sect> - start:].
#
#   (*) The sections [main], [verbatim], [validate], and [special]
#       are reserved and have a special meaning.
#
# Lines starting with '#' are ignored (comments). Similarly any text from
# '#' til the end of a line is deleted.
# `#' can be inserted by using `\#'.
#
#############################################################################
#
# [main]
#
# Section [main] contains global data and there must be two subsections:
# [main - data:] and [main - header:]
#
# Subsection [main - data:] must contain the following keywords:
#
#   (*) method: <name of method>
#       e.g.
#       method: AROU
#
# Everything in the subsection [main - header:] is copied verbatim
# into the C file header.
# eg. for prototypes for functions defined in section [verbatim].
#
# Important: C header files can be included here. However, the path
# must be relative to the 'top_srcdir' directory.
#
# Moreover this subsection must contain the following to definitions:
#    static int COMPARE_SAMPLE_SIZE = 500;
#    static int VIOLATE_SAMPLE_SIZE = 20;   /* or any appropriate samples size */
#
# Optionally the following macros can be defined:
# (defaults given in brackets)
#
#    CHI2_FAILURES_TOLERATED  (2):
#       number of failures in section [validate - test chi2:], see below
#
#    SEED:
#       if defined it is used to set the seed of the random number generator
#
#	Notice: One also can set a global seed by setting the environment
#       variable 'SEED'. This is used in every generated C test file instead
#       of a randomly chosen one. However, it is overridden by the macro
#       'SEED' #defined in the conf file.
#
#       Both settings, however, are overwritten at runtime when the
#       environmental variable 'SEED' is defined.
#
#############################################################################
#
# [verbatim]
#
# Everthing in section [verbatim] is copies AS IS into the C file immediately
# after the C file header.
#
#
#############################################################################
#
# [special]
#
# There any tests can be added. There must be two subsections:
#
# [special - decl:]
#    Contains all declarations.
#
# [special - start:]
#    Contains the actual code
#    The variable FAILED should be set to a nonzero interger if one (or more)
#    tests have failed.
#
#############################################################################
#
# [validate]
#
# Section [validate] describes tests for the implemented generators.
#
# It contains the following subsections:
#
# [validate - generators:]
#    List of generator types. Each type has to be declared by the
#    corresponding UNU.RAN calls to build a parameter object.
#    Different types are separated by empty lines.
#    The parameter object must be called `par[x]', where `x'
#    is an integer. It can be used for numbering the objects. However
#    this is just for convinience since it is ignored when scanning
#    the file. internally the first parameter object that appear in
#    the file is labeled with `0' the second with `1', and so on.
#
#    IMPORTANT: the distribution object in the unur_..._new() call
#    has to be encoded by `@distr@'.
#    Example: to get a parameter object for method TDR and change
#    the parameter c you have to write:
#	par[0] = unur_tdr_new(@distr@);
#	unur_tdr_set_c(par[0],0.);
#
#    It is also possible to change an existing generator object.
#    The generator object must be called `gen'.
#    It is not necessary (and even verboten) to call unur_init().
#    Example: To get a generator for method SROU, change the domain
#    of the distribution, and reinitialize the generator
#    you have to write:
#       par[1] = unur_srou_new(@distr@);
#       unur_srou_chg_domain(gen,0.9,0.91);
#       unur_srou_upd_pdfarea(gen);
#       unur_srou_upd_mode(gen);
#       unur_srou_reinit(gen);
#
#
# [validate - distributions:]
#    List of distributions. Each distribution object has to be
#    declared by the corresponding UNU.RAN calls.
#    Different distibutions are separated by empty lines.
#    If a pointer to a double array is required use `darray'.
#    If an array for parameters of the PDF is required use `fpm'.
#    The distribution object must be called `distr[x]', where
#    `x' is an integer. `x' is used to refer to this distribution
#    object.
#
#    IMPORTANT: when there n distributions, all the `x' must be
#    different and run through 1,...,n. There is no checking! (However
#    the C compiler might complain.)
#
#
# [validate - test chi2:]
#    Run chi-square goodness-of-fit tests.
#    The threshold p-value for a failure is set by the constant
#    PVAL_LIMIT in file 'testunuran.h' (currently 1.e-3).
#    A failed test is repeated once.
#    The entire test is failed if
#     - a particular test fails twice
#     - more than 'CHI2_FAILURES_TOLERATED' particular tests fail
#       at least once
#       The default for CHI2_FAILURES_TOLERATED is 2 and can be changed
#       In section [main] in the '*.conf' file (see above).
#       Notice: "Real" failures count for 1000 "soft" failures.
#
#    The section contains a table which test has to be performed.
#    Each line starts with `<dd>' where `dd' indicates the number of the
#    distributions as declared in section [validate - distributions:].
#    One lines contains the tests that should be performed by with
#    a particular distribution.
#    Each line consists of the `<dd>' marker followed by a list of
#    one character symbols. All entries are separated by white space
#    characters. There must be one symbol for each of the generator
#    types declared in subsection [validate - generators:] that
#    describes the expected result of the test when performed with the
#    choosen generator and the choosen distribution.
#    The following symbols can be used:
#	+    should pass test
#	0    should fail to initialize generator
#	-    should fail to iniialize or fail the test (not implemented yet)
#	/    either init fails or test successful (necessary for special generators)
#	.    do not run the test
#
#    Each line can be preceded by the letters 'x' or 'X' to exclude the
#    corresponding tests from 'make check' runs.
#    These optional tests are then only run when the environment variable
#    'UNURANFULLCHECK' is defined (regardless of the actual value of the
#    variable). Likewise it is possible to mark particular tests for a
#    distribution by prefixing the corresponding symbol ('+', '0', '-',
#    '/', or '.') by a single 'x' or 'X'; no blanks are allowed between
#    'x' and the symbol.
#
#    Example:
#
#	#par	[0]	[1]	[2]
#	#---------------------------
#	 <0>	 +	 +       .
#	 <1>	 -	 +       0
#	 <2>	 -	 +	 0
#	 <3>	 +	 +	 -
#	 <4>	 +	 -	 .
#	x<5>	 +	 .	 -
#	 <6>	x+	 +	x+
#
#    That is:
#	run test and expect that the test is passed for
#		distribution 0 with generator 0 and 1
#		distribution 1 with generator 1
#		distribution 2 with generator 1
#		distribution 3 with generator 0 and 1
#		distribution 4 with generator 0
#	expect that initialization of the generator fails
#		distribution 1 with generator 2
#		distribution 2 with generator 2
#	expect that initialization of the generator fails or
#	that the test is expected to fail for
#		distribution 1 with generator 0
#		distribution 2 with generator 0
#		distribution 3 with generator 2
#		distribution 4 with generator 1
#       do not run the test for
#		distribution 0 with generator 2
#		distribution 4 with generator 2
#
#	run the tests only in fullcheck mode for
#		distribution 5
#		distribution 6 with generators 0 and 2
#
#   Notice that the line
#	#par	[0]	[1]	[2]
#   is just a comment line for convinience. Moreover the numbering
#   [0], [1], and [2] coincides with the order of definition in the
#   subsection [validate - generators:].
#
# [validate - verify hat:]
#    Tests if condition of method is satisfied. It counts the number
#    occurences when unur_errno is equal to UNUR_ERR_GEN_CONDITION,
#    i.e. when when one of the following conditions is violated
#    	squeeze <= PDF <= hat
#    or a violation is detected during an adaptive step.
#
#    Contains a table which test has to be performed.
#    Each line starts with `<dd>' where `dd' indicates the number of the
#    distributions as declared in section [validate - distributions:].
#    One lines contains the tests that should be performed by with
#    a particular distribution.
#    Each line consists of the `<dd>' marker followed by a list of
#    one character symbols. All entries are separated by white space
#    characters. There must be one symbol for each of the generator
#    types declared in subsection [validate - generators:] that
#    describes the expected result of the test when performed with the
#    choosen generator and the choosen distribution.
#    The following symbols can be used:
#	+    should pass test
#       ~    condition might fail in at most 1% of all samples
#	0    should fail to initialize generator
#	-    should fail to iniialize or fail the test (not implemented yet)
#	/    either init fails or test successful (necessary for special generators)
#	.    do not run the test
#
#    Each line can be preceded by the letters 'x' or 'X' to exclude the
#    corresponding tests from 'make check' runs.
#    These optional tests are then only run when the environment variable
#    'UNURANFULLCHECK' is defined (regardless of the actual value of the
#    variable). Likewise it is possible to mark particular tests for a
#    distribution by prefixing the corresponding symbol ('+', '~', '0', '-',
#    '/', or '.') by a single 'x' or 'X'; no blanks are allowed between
#    'x' and the symbol.
#
#    Example:
#
#	#par	[0]	[1]	[2]
#	#---------------------------
#	 <0>	 +	 ~       .
#	 <1>	 -	 +       0
#	 <2>	 -	 +	 0
#	 <3>	 +	 +	 -
#	 <4>	 +	 -	 .
#	x<5>	 +	 .	 -
#	 <6>	x+	 +	x+
#
#    That is:
#	run test and expect that the test is passed for
#		distribution 0 with generator 0
#		distribution 1 with generator 1
#		distribution 2 with generator 1
#		distribution 3 with generator 0 and 1
#		distribution 4 with generator 0
#       run test and expect that in at most of 1% the test fails for
#		distribution 0 with generator 1
#	expect that initialization of the generator fails
#		distribution 1 with generator 2
#		distribution 2 with generator 2
#	expect that initialization of the generator fails or
#	that the test is expected to fail for
#		distribution 1 with generator 0
#		distribution 2 with generator 0
#		distribution 3 with generator 2
#		distribution 4 with generator 1
#       do not run the test for
#		distribution 0 with generator 2
#		distribution 4 with generator 2
#
#	run the tests only in fullcheck mode for
#		distribution 5
#		distribution 6 with generators 0 and 2
#
#   Notice that the line
#	#par	[0]	[1]	[2]
#   is just a comment line for convinience. Moreover the numbering
#   [0], [1], and [2] coincides with the order of definition in the
#   subsection [validate - generators:].
#
#
#############################################################################
#
# All other sections
#
# Each of these sections decribe tests.
# For each subsection definitions can be but into the subsection label,
# eg.: [reinit - exist:
#        double fpar[2] = {0.,1.};
#        distr = unur_distr_normal(fpar,2);
#        par = unur_srou_new(distr);
#        gen = unur_init( par ); <-- ! NULL ]
# (the "<-- ! NULL" (in the same line) indicates, that the result should
# be checked for an invalid NULL pointer.)
#
# The following names _must_ be used through out.
#   distr ... for distribution objects.
#   par   ... for parameter objects.
#   gen   ... for generator objects.
# These there variables are declared automatically whenever they occur.
#
# Tests are separated by empty lines. Each test has the form
# [ <set of C calls> ] --> <name of test> [ --> <expected error code> ]
# (the first and the third part are optional).
#
# eg.:
#   unur_srou_new( distr );
#	--> expected_NULL --> UNUR_ERR_NULL
#
# It is also possible to insert C code without a test, e.g. for
# freeing some memory.
#
# A ~ (tilde) at the beginning of a line is expanded to
# unur_<method>_<sect>.
# e.g. in file srou.c, section [set]
#   ~_cdfatmode(par,0.); is equivalent to unur_srou_set_cdfatmode(par,0.);
#
#
# List of tests:
#
# --> none
#       do not check return value (useful if only error code in unur_errno
#       should be tested).
#
# --> expected_NULL
#       check if the last C call returns a NULL pointer.
#
# --> expected_zero
#       check if the last C call return zero (int 0).
#
# --> expected_INFINITY
# --> expected_negINFINITY
#        check if last C call returns INFINITY or -INFINITY, resp.
#
# --> expected_INTMAX
#       check if the last C call return INTMAX (of type int).
#
# --> expected_setfailed
#       check if the last set of chg call has failed.
#
# --> expected_reinit
#       check if unur_reinit works.
#
# --> run_verify_generator
#       run a generator in the verifying mode.
#
# --> compare_sequence_par_start
# --> compare_sequence_par
#       compare random string generated by generator created by last
#       parameter object with the random string generated by generator
#       object from the last compare_double_sequence_par_start test.
#
# --> compare_sequence_gen
# --> compare_sequence_gen_start
#       Analogously except that a generator object is used.
#
# -->compare_double_sequence_urng_start
#       Analogously but for the output of uniform random number generators.
#
#############################################################################