Front-End Configuration

Introduction

To each front-end controller the list of nomenclatures to be handled must be provided, combined with a description of the devices. This device configuration comprises, for each device:

• Nomenclature of the device
• HW address of the device, typically the address on the MIL-bus. For interfacing other than by MIL-bus a unique identification number must be provided.
• Type of front-end control software, the equipment model name
• Device specific constants

This device configuration is provided to the front-end controller as a file with the extension .dbs, named the same as the device manager (<device manager>.dbs, e.g. kg1cg01.dbs). This file is read by the device manager during startup.

To ease handling, the device configuration is provided in condensed form as database definition files with the extension .dbd (e.g. kg1cg01.dbd). The utility dbsgen converts the definition file to the source file which has to be provided for the device manager.

While most of the device data is hold in the database definition files, additional data describing the field of magnets is hold in a database and added automatically by the utility dbsgen.

The database definition files (.dbd-files) are tracked in the GIT source management system. Presently (October 2019) for each front-end node a seperate repository is used, named devacc/fec_<name of front-end>, that is devacc/fec_k1xcg01, devacc/fec_k1xcg02, devacc/fec_k2xcg01, etc.

Utility dbsgen

Purpose and Usage

Usage: dbsgen [options] <device manager>

Reads the database definition file <device manager>.dbd and outputs the configuration file <device manager>.dbs, which is interpreted by the device manager. Intentionally (but not tested in all cases) a directory path can be prefixed to the device managers's name.

If specified in the .dbd source file, device specific data from the front-end data base (accdbp) is added to the device's constant sets. This option is only used for magnets, to automatically add conversion polynom data (generarally called field polynoms).

For options see dbsgen -h .

Format of Input File

The utility dbsgen interprets input text files, the database definition files. The database definition files are structured by commands. Commands are indicated by a '/' (slash), followed by a command word.

Supported commands are

/device <nomenclature> [<device type>] <device address>

Defines a nomenclature. If the device type is set by the command '/type', the device type may be omitted. If a device type is specified, it overwrites a setting by '/type'. The sequence of <device type> and <device address> is arbitrary. When a <device address> is preceded by '0x', the address is interpreted as hexadexcimal number.

/type <equipment type>

Presets the equipment type for successive '/device' commands.

/structure <sequence of type identifiers>

Defines the counts and the types of device constants for the successive '/constant' commands. Valid type identifiers are

[n]i

integer constant (n times, if given)

[n]f, [n]r

float constant (n times, if given) f and r are equivalent (in Pascal the floats where called REAL)

c

character constant. A character constant is a string of up to 64 char without whitespace

*f or *r

float constants from device database: Insert device specific float constants from a database. This is presently only used to insert filed polynoms for magnets. $ n[:v]*f, n[:v]*r: similar as *f, but insert at least n constants (fill up the content in the database) with value v (default is 0).

/constant <list of constant values>

Defines the attached constants for all devices specified before. The constant values are assigned to all nomenclatures which are defined since the last '/constant' command before. Constant values are interpreted as defined in the last '/structure' command before.
Integer constants are interpreted as decimal values. When preceded by '0x', integer values are interpreted as hexadecimal data (0x47a11f).

! <text, to end of line>

Comment. All text from comment sign to end of line is ignored. The comment sign may be given somewhere in the line or at the start of a line. The exclamation mark for comments is a relict from OpenVMS where this was common for comments.

Commands (except comments) may extend over several lines.

Commands may be abbreviated up to the first significant character (indeed, only the first character is interpreted).

Input may be given as lower or as upper case characters. Text output into the .dbs database file will be converted to upper case characters (e.g. all nomenclatures will be converted to uppercase).

Example:

/type xxyy                         ! defines device type XXYY
/struct f 2f i *f                  ! defines constant structure of 3 floats, one int and the polynom set from the database
/device mydevice abc 4             ! defines nomenclature MYDEVICE which is of device type ABC with address 4
/device yourdevice 0x17             ! defines YOURDEVICE which is of device type XXYY with address 17hex (23 dec.)
/const   0.0   100.0   0.0 0x10c3  ! defines the constants for the nomenclatures MYDEVICE and YOURDEVICE

Conversion Field <-> Current: Field Polynom-Fits, Magnet Polarity

Background

The front-end control software for pulsed and for DC magnet power supplies provide conversion between current and magnetic field, and conversion of hall probe data if the magnet is equiped with a hall probe: Set and aquisition values can be handled equivalently as current and as field (and even in 'milli-volt', which is the percentage to full scale in the range 0 .. 10000). Conversion between field and current is non linear. For each magnet dedicated conversion data is required.

Conversion data between field and current is measured by the Normal Conducting Magnets and Alignment department (ENMA). The ENMA department provides conversion data as polynoms of third order which are fitted to the measured data. For each conversion three polynoms are provided, each valid for a different region. The polynom coefficients are provided by text files.

In addition to the conversion function, the direction of the magnetic field has to be considered. While the current of a unipolar magnet is handled always as positive, the magnetic field in the GSI follows a convention of direction. Depending on the direction of the beam deflection, the field is marked as positiv or negativ:

• A positiv dipole field deflects the beam to the right (seen in direction of the beam)
• A negativ dipole field deflects the beam to the left (seen in direction of the beam)

Similar rules apply for quadrupoles, sextupoles etc (dont't know them yet).

According to the bending, each magnet is labeled as postiv or negativ.

The field direction is hold in a file, called polarity.lis, which is maintained by the controls department (however, the data is provided by machine physicists).

Data File Handling

Both types of files, field conversion data as well as the definition list of polarity data, have to be stored in the general code management system, which presently is GIT (previously subversion was used).

In the GIT system, the data files are kept in the repository devacc/localdb_polynomials (in subversion, this was part of the project localdb, in the subproject localdb/polynomials). Any change in the input data files (new ore modified files) stringently must be submitted to the GIT repository.

The subdirectory saves contains a snapshop of the database contents as from Mai 2014. From these files, the contents of the database at that time can be reestablished. The reason is: Many polynom data is provided in an outdated file format (stored in the subdirectory saves) which can no longer be interpreted.

Utility mxmd_coeff

The data for conversion functions (fit polynoms) and magnet polarities are stored in files. To be used in the accelerator control system, the data is inserted into the front-end database (accdbp). For insertion into the database, the utility mxmd_coeff is provided.

The utility is used for two purposes:

• Read field conversion (polynom) data and insert into the front-end database
• Read magnet polarity definitions and insert into the front-end database

Polynom data is provided by the department which was formerly called ENMA (Normal Conducting Magnets and Alignment). Data is provided as files of specific structure. The files have to contain either four or six sets of conversion functions (field, field times length of the magnet, and optionally hall probe voltages; each for both directions field -> current/voltage and reverse current/voltage -> field). The control system only needs two of four sets (field times length, for both directions I(Bl) and Bl(I), and if given, also hall prob data for both directions, UNORM(I) and I(UNORM)), and optionally two conversion functions for the hall probe.

The provided files must be tracked in the GIT repository devacc/localdb_polynomials.

The utility mxmd_coeff is provided to extract the relevant polynom data from these files and inserts them into the front-end database accdbp.

The contents of the data beses can be dumped to files with the utility mxmd_extract. The files which are generated by the utility mxmd_extractcan be re-read with the utility mxmd_coeff.

Usage

Usage: mxmd_coeff <input file>

The utility mxmd_coeff reads both types of input data, field conversion polynoms as well as polarity definitions. The type of file is determined automatically but also can be set by options.

Options:

• -x: extend nomenclatures by a leading 'G'
• -nx: no extension of nomenclatures
• -f: interpret input data file as field data (polynoms), overwrites automatic detection
• -p: interpret input data file as polarity data (overwrites automatic detection)

For additional options see mxmd_coeff -h .

The utility parses the given input file and inserts the data into the front-end database. Several consistency checks are performed to detect when data is modified which already exists in the database.

Consistency Checks

Internally in the polynom data base the data sets ared identified by the name of the file in which the polynoms are provided.

The utility mxmd_coeff checks for

• A polynom file contains other (new) data than before
• The assignment of data sets (file name) to a magnet is changed

If the utility detects the above changes, the user has to confirm the modification.

Structure of Polynom Data File

Commands are indicated by the OpenVMS command qualifier indicator "/".

The data files, as provided by the EMNA department, must contain two commands:

/nomen list of nomenclatures

Nomenclatures typically follow in separate lines

/poly=<order> <coefficients>

The order is either 4 or 6 (/poly=4 or /poly=6), indicating 4 or 6 set os fit polynoms. The coefficients comprise , for for each conversion, three polynoms. Each polynom is described by 6 coefficients, the boundaries (start and end) and the constant, linear, quadratic and cubic terms. Typically the files contain one polynom per line.

Commands are supported to generate simple linear fits:

/BLIN <Imin> <Imax> <Bmax>

generate polynoms for linear conversion for B(I) und I(B)

/HLIN <Imin> <Imax> <Bmax> <Umax>

generate polynoms for linear conversion for B(I), I(B), I(U) und U(I)

Special commands are suported, to read data which has been extracted from the front-end database (/fit set name of fit data, /direction set magnet's polarity, /time set time and date of fit data set). If set explicitly, please take great care!

Example of field polynom data, as provided by the ENMA department. The file contains four sets of conversion polynoms, for field and field times length (since the magnets are quadrupoles, not the field B is contained but the quadrupole strength G). Each line in the /poly section contains one polynom, described by the boundaries (lower and upper) and the four polynom coefficients, for the constant, the linear, the quadratic and the cubic term.

/nomen
UL5QD22
UR5QD22
UY5QD11
UY5QD12
UY5QT12
UY2QD11
UY2QD12
/poly=4
  5.400000E-2     7.997300E+1     2.345044E-2     1.322506E-1     3.575164E-5    -6.020921E-7   ! I    FIT G(I)
  7.997300E+1     9.997700E+1     1.177222E+1    -3.124834E-1     5.646901E-3    -2.419859E-5   ! II   FIT G(I)
  9.997700E+1     1.499810E+2    -6.898989E+0     3.396585E-1    -1.794998E-3     3.677422E-6   ! III  FIT G(I)
  5.400000E-2     7.997300E+1     6.336175E-3     3.601067E-2     9.654498E-6    -1.659548E-7   ! I    FIT G*L(I)
  7.997300E+1     9.997700E+1     3.266440E+0    -8.713808E-2     1.560207E-3    -6.673258E-6   ! II   FIT G*L(I)
  9.997700E+1     1.499810E+2    -1.863306E+0     9.213996E-2    -4.865469E-4     9.962219E-7   ! III  FIT G*L(I)
  3.077040E-2     1.052110E+1    -1.809504E-1     7.571324E+0    -1.859138E-2     2.204976E-3   ! I    FIT I(G)
  1.052110E+1     1.279170E+1    -2.454126E+2     7.631884E+1    -6.440863E+0     2.021299E-1   ! II   FIT I(G)
  1.279170E+1     1.607170E+1    -1.643705E+1     1.999862E+1    -1.833229E+0     7.672579E-2   ! III  FIT I(G)
  8.378390E-3     2.863310E+0    -1.797044E-1     2.780719E+1    -2.508057E-1     1.110156E-1   ! I    FIT I(G*L)
  2.863310E+0     3.480820E+0    -2.492573E+2     2.841778E+2    -8.818160E+1     1.016059E+1   ! II   FIT I(G*L)
  3.480820E+0     4.372110E+0    -1.647673E+1     7.354254E+1    -2.479281E+1     3.814913E+0   ! III  FIT I(G*L)

Structure of Polarity Definition Data

Polarity data of the magnets is hold in a file with a simple structure:

• the file must contain the command /orientation, only then the utility for inserting the data into the database (mxmd_coeff) detect the type of data automaticlly
• '+' or '-', indicating the field direction, followed by the nomenclature, all in one line
• comments are indicated by a '!', all text after the '!' indicator is ignored (exclamation marks is a relict from former times, they have been the usual comment signs in OpenVMS)

The polarty information is read by the utility mxmd_coeff,

Usage: mxmd_coeff [options] <input file>

The input data file (or the files) must be tracked in the GIT repositorydevacc/localdb_polynomials . The input data file is named polarity.lis. Only one file for all polarity data is used, containing polarity information for all magnets. When no polarity for a magnet is defined, the magnet is handled as polarity positiv.

The beginning of the source file polarity.lis is given below:

! magnet polarity list
! generated from database instance accdbp
! file created 12. 7.2014-11:11:12
! 
/orientation !   marker for mxmd_coeff
! 
+ GHADKX1    
+ GHADKY1    
+ GHADKY2    
+ GHADKY3    
+ GHADKY4    
- GHADMU1    
- GHADMU2    
+ GHADQD11   
- GHADQD12   
+ GHADQD21   
. . . 

Utility mxmd_extract

Extracts entries from the front-end magnet parameter database ("field polynoms") and generates output files, which can be read and interpreted by the utility mxmd_coeff.

Options:

• -p: Generate polarity data
• none: generate field conversion coefficients
• -n <nomen>: generate field conversion coefficients for nomenclature 'nomen'