User Interface

For programs that use the "official" application interface (e.g. via the Katydid application) a user sets options in a program using either a configuration file, or command-line options. Both of these mechanisms allow the user to change the parameters of a program without recompiling any code.

Before getting to the configuration files or command-line options, there are three important built-in command line options that all users should be aware of:

• -h [--help] -- Print the help message for the executable and exit.
• -v [--version] -- Print the version information for the executable and exit.
• -c [--config] /path/to/config/file.json -- Specifies the path to the configuration file that should be used.

Configuration Files

Configuration files in Katydid are formatted using JSON. All standard JSON notation is supported. The parameters in a configuration file are organized into blocks with curly brackets. Parameters appear as comma-separated name-value pairs, where the name is a string in quotes, and the value can be a quoted string, an integer or floating-point number (floating-point numbers should NOT end in a decimal), a boolean ("true" or "false" without quotes), an array of parameters, or a nested block of parameters.

Configuration files are broken up into two main sections:

• Configuring the processor toolbox, including defining which processors will be used, how they are connected, and which processor(s) is in charge of the run,
• Configuring each individual processor.

Here is an example of an annotated JSON-formatted configuration file:

{
    "processor-toolbox":
    {
        "comment": "declare which processors will be used, and how they will be referenced in this file",
        "processors":
        [
	        { "type": "egg-processor",       "name": "egg" },
	        { "type": "simple-fft",          "name": "fft" },
	        { "type": "basic-root-writer",   "name": "writer" },
	        { "type": "throughput-profiler", "name": "profiler" }
        ],
        
        "comment": "set the connections between the processors",
        "connections":
        [
	        {
	            "signal": "egg:header",
	            "slot": "fft:header",
	            "order": 0
	        },
	        {
	            "signal": "egg:header",
	            "slot": "profiler:start",
	            "order": 1
	        },
	        
	        {
	            "signal": "egg:ts",
	            "slot": "profiler:data",
	            "order": 0
	        },
	        {
	            "signal": "egg:ts",
	            "slot": "fft:ts",
	            "order": 1
	        },
	        {
	            "signal": "fft:fft-forward",
	            "slot": "writer:fs-polar"
	        },
	        
	        {
	            "signal": "egg:egg-done",
	            "slot": "profiler:stop"
	        }
        ],
        
        "comment": "which processor is in charge",
        "run-queue":
        [
            "egg"
        ]
    },
    
    "comment": "configure each processor",

    "egg":
    {
        "filename": "/path/to/file.egg",
        "slice-size": 16384,
        "number-of-slices": 1
    },
    
    "fft":
    {
        "transform-flag": "ESTIMATE"
    },
    
    "writer":
    {
        "output-file": "/path/to/file.root",
        "file-flag": "recreate"
    }
}

Command-Line Options

The built-in options are discussed above. Those are available for any program using Katydid's application interface.

Other command-line options can be added by various parts of the code to provide short-cuts for setting certain parameters. Generally there are also configuration-file options available that can set the same parameters; Command-line options always take precedence over settings from a configuration file. The command-line options available for an application can be found using the -h (--help) command-line option.

Modifying Configuration-File Parameters from the Command Line

Even if an application or a class does not specify a command-line option for modifying a certain parameter, it is still possible to set that parameter from the command line, or add parameters to the configuration. The entire nested address of the parameter is used as the command-line-option name. For example, to change the FFTW transform flag in the above configuration file, one would use --fft.transform-flag="PATIENT".