Untitled Document

Back to the Start

A Related Page

On This Page

A Heading Down Below

Notes from Joanne:

(See: MOOT Working Documents.)

(Also see: Status Fields in MOOT.)

Status-like database fields for objects in MOOT

This document is intended to address JIRA LCT-4

Object type	Field name	Allowed values	Notes
Config	status	STARTED ABORT CREATED INVALID	Since creating a Config is a lengthy procedure with many possible failures, the db entry is first created with status = STARTED. Only if the procedure completes successfully is it changed to CREATED. After creation, clients may mark a Config INVALID. No client-callable MOOT functions are provided to change status to CREATED from any of the other values.
Config	active_state	ACTIVE INACTIVE MULTI	A successfully-created Config starts out ACTIVE. Applications may change it at will between states ACTIVE and INACTIVE. State MULTI is currently unused.
Parameter file	status	STARTED ABORT CREATED INVALID	Similar to Config, the db entry is first created with status = STARTED. Only if the procedure completes successfully is it changed to CREATED.
Ancillary file	status	STARTED ABORT CREATED INVALID	Similar to Config, the db entry is first created with status = STARTED. Only if the procedure completes successfully is it changed to CREATED.
Ancillary file	quality	PROD DEV TEST SUPSED INVALID	Use of this field is deprecated in favor of ancillary aliases
Vote file	status	STARTED ABORT CREATED INVALID	Similar to Config, the db entry is first created with status = STARTED. Only if the procedure completes successfully is it changed to CREATED.
FSW input	status	new added invalid (or any other string up to 32 characters)	Refers to a binary file suitable for registration with fmx. new is the status assigned when the row is first created. added means the corresponding binary file has been successfully registered with fmx.

Note: currently the status and active_state fields of Config are the only status-like fields which may be modified directly by client code. However Vote files and Ancillary files may in effect be activated or de-activated by assigning or deassigning aliases to them.

Status-like database fields for classes of objects in MOOT

Class type	Field name	Allowed values	Notes
Parameter class	active_state	ACTIVE INACTIVE	Allows for evolution of collection of supported Parameter classes
Precincts	status	OK (or any other string up to 32 characters in length)	Precincts may be thought of as vote classes. If status is set to some value other than OK precinct cannot be referred to by new entries in other tables.

There are more tables with status-like fields but, even more than the class tables referred to above, they are internal constructs not of much interest to clients.

Created: 03-Dec-2007
Last revised: Monday, 03-Dec-2007 16:22:08 PST

(Also see http://www.slac.stanford.edu/exp/glast/ground/notes/moot/intent.shtml, which is a subset of above working documents)

Relation tables

Parameters_to_Ancillary: Keeps track of ancillary files used in generation of a particular parameter file. This table already exists in MOOD but is unused.
Precincts_to_AClass: One or more kinds of ancillary file may be associated with a precinct [probably MOOT doesn't need to keep track of this]

Several other relation tables will be added for various purposes: Vote_PClass_AClass, Container_Precinct, LATC_Backup.

Other relations

Some relationships are more conveniently expressed with additional foreign keys.

Add vote_fk, a foreign key referencing Votes, to Parameters
Add precinct_fk, a foreign key referencing Precincts, to Parameter_class

Use Cases:

Registering ancillary files

A typical ancillary file (e.g., ACD pedestal calibration; calorimeter calibration table) is created by the subsystem (or other delegate, but non-subsystem delegates tend to be simpler and might not need ancillary files at all), probably as a result of analyzing charge injection data or physics data or both. Ancillary files are at the beginning of the processing chain required to make a new Config. Most likely all that's needed here is a simple function taking as arguments the file path, the ancillary class it belongs to, and other mundane items. The function will copy the file to the MOOT archive in SLAC afs space.

Managing precincts and votes

The set of precincts is expected to be relatively static. They will be defined by subsystem or other experts once and for all (or nearly) and corresponding rows will be added to Precincts by the MOOT maintainer.

The collection of votes is likely to continue to increase, albeit slowly. A MOOT function will be provided so that experts can register them on their own. If all subsystems use Eric's scheme (and they will since Eric has done the work of defining precincts for them), a vote corresponds to an XML element, including its attributes and child elements, as serialized in a file. This file will be archived (that is, copied to MOOT's archive in SLAC afs space) upon registration just as parameter and ancillary files are archived.

Creating and registering parameter files

Parameter files may be derived from any number (including zero) of ancillary files. In the new scheme of things, they will always be related to a vote. Someone (subsystem expert to begin with; ultimately perhaps an operator) will determine which vote should be used to generate a parameter file or files. The vote should, directly or indirectly, specify the procedure to be run and the inputs: ancillary files and/or constants. At the close of the procedure whoever (or whatever) invoked it should have all information necessary to register the new parameter file(s) and indicate which ancillary files they depend upon. MOOT functions will be available to

Register a parameter file
Make new entries in Parameters_to_Ancillary. (Will provide a single function to do both if the call interface is not too horrendous.)
Determine whether it is necessary to rebuild using the specified vote file. In particular, have any of the referents of aliases it uses changed since the last rebuild (if any) using it? In order to determine this, MOOT will have to be able to parse the vote file at least to the extent of finding ancillary file aliases and determining which ancillary class they are referring to.

Building a config

There is already a routine to build a new config which takes a list of keys from Parameters as input. We need to add facilities which will aid an operator in choosing the right collection of keys, based on some idea of intent. Intent in this scheme is represented as a collection of votes, one for each precinct, so one step in this process will be something which, given a particular vote and perhaps other constraints (e.g., on status, on creation time,..) will return a collection of parameter files. Then the operator's job becomes one of selecting votes rather than parameter files. To simplify the operator's life further, Vote_aliases can be used to keep track of a standard collection or collections of votes for each delegate. Then, for example, to configure for a CAL charge-injection run, the operator would specify a special set of votes for the precincts belonging to the CAL delegate, but might just ask for a standard set-up for some or all of the other delegates.

Note that the complete process, all the way from generating ancillary files to coming out with a new config, takes place in a sequence of steps which can be spaced out in time. Steps or parts of steps which are done via MOOT services are indicated like this.

(Optional) Create entry or entries in Votes defining intent. This step is optional because most of the time the operator will want to apply an old definition of intent to new data.
(Optional) Create new ancillary files from charge injection or other data. Register the ancillary files. This step normally will occur, but it could conceivably be omitted if the same data are to be used with a new vote (intent). Even when this step does occur, it need not be executed for all delegates or all precincts controlled by a delegate.
Run (delegate-owned) procedures to create new parameter files based on intent. This usually involves invoking a MOOT function to resolve ancillary file aliases. Register the new parameter files and relations between them and ancillary files. This step need not occur for all delegates, nor for all precincts belonging to a delegate.
By specifying a collection of votes and perhaps other criteria, select parameters for a new config and build it. This may involve creating new FSW binaries.

Recovering intent

For a given config, it is already possible to

get a list of parameter files supplied as input when the config was built
get a list of the parameter files actually used to generate the binaries constituting the config

The essential content (e.g., register settings) of the two sets of files will be identical, but other features, such as the votes associated with the parameter files when they were registered, may differ.

A new MOOT query will be added to return the key of the vote associated with a parameter file, making it possible to recover the complete set of votes (= intent) associated with a config.

Glossary and examples

Delegates, precincts and votes

A Delegate is a sphere of influence or control within the universe of configurable quantities. The most typical example is a subsystem, such as the ACD. Delegates don't show up much in the implementation of MOOT because the concept is too coarse.

A precinct is defined by the quantities it determines, and by the kinds of inputs (e.g., data like ACD pedestal calibrations or settings like "number of counts above pedestal") used to determine them. Register values or other quantities controlled by a precinct would normally be established all at the same time by means of a single procedure.

A vote describes the particular inputs and (perhaps) procedure to be used (e.g., "run program X, using the most recent good pedestal calibration, establishing thresholds 17 counts above pedestal"). A vote file corresponds to the intent for the items (e.g. registers; flight software parameters) it controls. Roughly speaking, precinct/vote have a class/instance relationship. A global intent file is another xml file whose only content is a list of references to vote aliases. At any given time these may be resolved using MOOT's vote_alias table.

Ancillary file, ancillary class

Ancillary files are typically generated as a result of analysis of one or more data sets from physics running or special charge-injection runs. They are in turn input to procedures producing configuration source files (aka parameter files, q.v.), such as those for LATC, and offline calibrations (e.g., ACD pedestals). Each ancillary file belongs to a particular ancillary class. Examples of ancillary classes are ACD_BiasDacCalibration, CAL_trg_alignment, TKR_Mask.

FSW input file, class

A FSW input file is a binary which, if all goes well, will be registered with fmx and ultimately uploaded to the instrument. Each file belongs to one of the known FSW input classes. Examples of such classes are latc_SPT, lci_ACD.

Parameter file, class

A parameter file is source used to produce an FSW (binary) input, typically by running a flight software program like LATC_parser. Several parameter files may be used to produce a single FSW input (but not the other way around; that is, the association of {parameter files} to {FSW inputs} may be many-to-one, but never one-to-many). Like ancillary files or FSW inputs, parameter files always belong to one of the known set of types, called parameter classes (e.g., latc_CFE_CAL_FLE, latc_DFT_GNL_Timing, lci_TKR).