Author(s)

• find_program: Tom Terwilliger

Purpose

The routine find_program will show all the programs that match supplied text (either in program name or in program descriptions). The locations of the programs (which tab in the GUI or command-line name) are shown.

Alternatively, find_program can search for a regression test based on words in the name of the test or based on the name of a module that is tested by that regression test.

Lastly, find_program can find all the Python programs that have changed since last checking in programs to github and list all the regression tests that test those programs.

Usage

How find_program works:

Searches for programs:

Find_program uses the list of programs and short descriptions in the file $PHENIX/modules/phenix/phenix/utilities/phenix_list_help.py as a list of program names. Additionally it compiles program names and descriptions from $PHENIX/modules/phenix/wxGUI2/Programs/__init__.params and $PHENIX/modules/phenix/wxGUI2/Home/Tools.py.

Find_program then makes a list of all programs, descriptions, and locations.

This list is then searched with the search_text values provided.

Searches for regression tests:

Find_program can also look for and display regression tests. A database (test_and_module_info.pkl) of regression tests and all the modules called by each test is created using the tool phenix_regression.get_test_and_module_info. This database is read by find_program and can be searched either by words from the name of a regression test (providing the full path of the regression test), or by words from the name of a module (providing the full path of regression tests that use that module).

The search for regression tests by module is a way to find a test that will run a module that you are interested in.

Search for regression tests affecting all changed programs:

Find_program can find all the Python programs that have changed since the last check-in to github (it uses git to do this). Then for each of these programs, it finds all the regression tests that are affected. Then it lists all the regression tests it finds.

This search is a way to find all the tests that could possibly fail due to any changed Python module. Note that this search will not find C++ code that is affected. It will also not find code that is accessed in tests using the easy_run command which uses a system call that does not pass back traceback information.

Running regression tests

The standard framework for running regression tests is described in Running Phenix regression tests . This approach uses find_program if you use the git or sort options.

Standard run of find_program:

You can use find_program to find a program like this:

phenix.find_program search_text=autosol

You can also use it to try and find a regression test that exercises a routine with the word anomalous in it (anywhere) and also the word signal (anywhere):

phenix.find_program search_type=tests search_tests_by=function_called search_text=anomalous search_text=signal

Setting up the database for find_program:

You can update the database for find_program by running the tool

phenix_regression.get_test_and_module_info nproc=64

in an empty directory. This will take a while (perhaps an hour or so with nproc=64) and produce a file called:

test_and_module_info.pkl

You can copy this file to its official location at:

$PHENIX/modules/phenix_regression/misc/test_and_module_info.pkl

and then find_program will use this new version. You can also specify where this .pkl file is located with the keyword:

phenix_test_database_file=xxx.pkl

Possible Problems

Specific limitations and problems:

The search_tests and git_affected_tests features of find_program do not find C++ code that is affected by a test (only Python code).

Literature

Additional information

List of all available keywords

• all_tests = False Find all regression tests
• git_affected_tests = False Find regression tests to cover all changed Python files in github
• directories_to_search = phenix cctbx_project solve_resolve Directories to search to find changed files
• search_type = *programs tests You can search for programs (real_space_refine) or tests (tst_ncs.py). For programs, your search text must match part of the program name or its description. For tests you can search based on the name of the test or based on the name of any function that is accessed by the test.
• search_text = None Text to search for. If multiple, any match is displayed. If search_text=ANY (must be capitalized) or None (empty) then searches will match any text. Each entry of search_text counts as one search term. So if there are two entries of search text like < density modification > and <autosol> , then if all_search_terms_required=True, the phrase < density modification > and the word < autosol > must both appear somewhere in the name or description to be selected.
• case_sensitive_search = False Normally searches are case-insensitive. You can force a case-sensitive search with this keyword.
• all_search_terms_required = True All search terms required (a AND b AND c). Alternative is to match any search terms (a OR b OR c). Each entry of search_text counts as one search term. So if there are two entries of search text like < density modification > and <autosol> , then if all_search_terms_required=True, the phrase < density modification > and the word < autosol > must both appear somewhere in the name or description to be selected.
• try_splitting_text = True If no programs are found, try splitting search text entries into individual words and search for all the words in any order.
• ignore_hyphens = True Ignore hyphens in searches
• number_to_display = 20 Number of programs or tests to display. Up to this number of entries will be shown.
• show_tests_by_module = True Show tests by module
• find_programs_without_tests = None Find programs without tests
• job_title = None Job title in PHENIX GUI, not used on command line
• input_files
  • program_data_file_name = None Input data file name with program information
  • read_program_data_if_available = True Read program data
  • phenix_test_database_file = None Input database file (.pkl) with information about all Phenix tests and modules that are called by those tests. This is normally found automatically
• output_files
  • program_data_file_name = None Output data file name with program information
  • files_with_tests_file_name = files_with_tests.txt Output data file name with list of files with tests
  • files_with_no_tests_file_name = files_with_no_tests.txt Output data file name with list of files with no tests
  • modules_with_tests_file_name = modules_with_tests.txt Output data file name with list of modules with tests
  • modules_with_no_tests_file_name = modules_with_no_tests.txt Output data file name with list of modules with no tests
• programs
  • include_program_description = True Search in documentation string
• tests
  • search_tests_by = *test_name function_called For tests you can search based on the name of any function that is called by the test. This is a way to find a test that will run a function that you are interested in. The alternative is to search by the name of the test.
• guiGUI-specific parameter required for output directory
  • output_dir = None