4.18. Configuration

Todo

Configuration handles ingestion of human-readable text to produce an initialized framework program.

  • Includes validation of the configuration

  • Includes command-line interface

  • Develop configuration schema for program resources

The application of a specific configuration to a particular invocation of Phlex may be factorized into:

  1. The mechanics of how the configuration is specified and evaluated

  2. The way the configuration is accessed programmatically by both framework and user code

  3. The semantic structure of the configuration as it relates to the structure and operation of the application

4.18.1. Mechanics of Configuration Specification

A Phlex program is configured by:

  1. ingesting a configuration document in a specific language, and then

  2. adjusting the configuration according to any command-line options specified when invoking the Phlex executable [DUNE 125]

Generally speaking, command-line options take precedence over any corresponding configuration specified in the configuration document itself.

A Phlex program is configured by only one configuration document [DUNE 69], although that document may be compiled from more than one source (such as included files). Phlex intends to support configuration documents written in the following languages: Jsonnet, YAML, JSON (as a strict subset of Jsonnet), or FHiCL [DUNE 72]. A given configuration can be written in any of these languages, but no configuration document may be written in more than one language.

Phlex shall evaluate the entire configuration at program initialization time [DUNE 70], and configuration values shall be converted into a canonical form to facilitate meaningful comparison between two different evaluated configurations [DUNE 98].

Where supported by the input language and requested by the user, Phlex will provide tracing, and other diagnostic information about the evaluation of the configuration [DUNE 127].

Phlex shall provide the option to persist its configuration to the execution’s configured output data destination [DUNE 27].

For each supported configuration input language, Phlex shall support facilities enabling a single point of maintenance for configuration documents [DUNE 128], including (but not limited to):

  • Specifically overriding configuration items specified earlier in the configuration document [DUNE 126], and

  • The ability to compose a single configuration document from multiple distinct sources [DUNE 133].

4.18.2. Programmatic Access to the Configuration

In order to preserve the framework-independent nature of user algorithms, the appropriate section of configuration will be made available to the appropriate algorithm’s registration code in the form of a hierarchical configuration object in the appropriate programming language (C++ or Python). The author of that registration code is then responsible for ensuring that relevant configuration information is passed to the user algorithm itself.

Customizable facilities will exist to enable the presentation of configuration items not only as simple types, but as complex strucutres in the appropriate programming language.

Users will not be able generally to access live configuration outside the scope of their own algorithm, although “framework-level” configuration will be viewable from registration code, as will configuration metadata attached to any input data registered for the algorithm.

4.18.3. Semantic Structure of the Configuration

The semantic structure of the configuration is constrained by (a) the common features of the permitted document languages, and (b) the C++ and Python representations of the configuration. At the top level, the configuration document will be organized as a single associative array of key-value pairs, with the key being a string identifier, and the value being either a scalar, a sequence of values, or a nested associative array. The configuration for user algorithms will be represented by an associative arrays.

Sequences are allowed to contain heterogeneous values, but limitations imposed by the corresponding C++ and Python representations may diminish the usefulness of such sequences.

Facilities will exist to constrain and validate configurations for user algorithms particular framework feature categories or user code by specifying a schema [DUNE 64]; when used, any issues with the validity of user-provided configuration will be flagged at the time of evaluation of the configuration [DUNE 70], rather than being left to the author of the registration code and/or algorithm. A human-readable representation of a specific validation schema will be provided by the framework upon request [DUNE 67].

4.18.4. Program Resource Specification

The configuration supports a block of parameters that specify the hardware resources required by the program [DUNE 47].