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.

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.

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:

Literature

Additional information

List of all available keywords

• 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.
• 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
• 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