To create a new test case, first make a folder in psi4/tests. The directory name may not contain an underscore; to indicate spaces, use a hyphen instead. This directory will need two files. The first is CMakeLists.txt, which is necessary to add the test case to the suite. This file should have the following lines:

 1 2 3 include(TestingMacros) add_regression_test(directory_name "psi;semicolon_separated-list-of-applicable-test-labels") 

The labels specify which groups of tests include the test case. The psi label should always be added, but the other labels are test-specific. The method tested should always be included, and this is often sufficient. If adding a test for an already existing module, the labels for other tests of the module will suggest other labels to add.

A test requiring over 15 minutes should be labeled longtests. A short test used for general bug checking should be labeled quicktests. A test that confirms PSI4 is operational should be labeled smoketests.

The other necessary file is the input file itself, input.dat. The input file should be just a simple input file to run the test, with small modifications.

  1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 #! RI-SCF cc-pVTZ energy of water, with Z-matrix input and cc-pVTZ-RI auxilliary basis. #! Also a bit more to force a second line. nucenergy = 8.801466202085710 #TEST refenergy = -76.05098402733282 #TEST molecule h2o { symmetry c1 O H 1 1.0 H 1 1.0 2 104.5 } set { basis cc-pVTZ scf_type df df_basis_scf cc-pVTZ-RI e_convergence 10 } thisenergy = energy('rhf') compare_values(nucenergy, h2o.nuclear_repulsion_energy(), 9, "Nuclear repulsion energy") #TEST compare_values(refenergy, thisenergy, 9, "Reference energy") #TEST compare_values(refenergy, get_variable('scf total energy'), 9, "Reference energy") #TEST 

Of those small modifications, first, note the special comment at the top (starting with the #! comment marker). This should be very descriptive since it is inlined into the manual (unless !nosample is present in this comment) as a sample input.

The reference values are assigned to variables for later use. The compare_values function (along with several relatives in psi4/psi4/driver/p4util/util.py for comparing strings, matrices, etc.) checks that the computed values match these reference values to suitable precision. This function prints an error message and signals that the test failed to the make system, if the values don’t match. Any lines of the input associated with the validation process should be flagged with #TEST at the end of each line, so that they can be removed when copying from the tests to the samples directory.

Finally, add the directory name to the list of tests in psi4/tests/CMakeLists.txt.

In preparing the test case, turn energy, density, amplitude, and geometry convergence criteria to very tight levels, and use these results for reference energies, reference geometries, reference cube files, etc.. Then, either remove or relax the convergence settings, if these are not a vital part of the test. In choosing the number of digits for compare_values and other compare_* functions, select a number looser than the convergence set in the test or the default convergence for the calculation type (energy, gradient, etc.).