ESS Naming convention 20131011 v2 - Lunds universiteteval.esss.lu.se › DocDB › 0000 › 000004...

ESS Naming Convention Naming Convention

Revision: 1.4

Status: Accepted

Project: ESS Naming Convention

Document ID: ESS/AD/0005

File: ESS Naming Convention.doc

Owner: Garry Trahern

Last modification: January 11, 2013

Created: October 26, 2010

Document History

Revision Date Changed/ reviewed

Section(s) Modification

1.0

2010/10/26 Garry Trahern

All Initial version

1.1 2010/11/16 Garry Trahern

All Clarify syntax for system/subsystem instantiation TOC formatting

1.2 2011/03/21 Garry Trahern

All Updated examples, moved reference tables to separate document

1.3 2012/09/26 Karin Rathsman

3 Replaced examples with Implementation-How to name devices

1.4 2013/01/11 Karin Rathsman

3 Updated Implementation.

Confidentiality

This document is classified as a public document. As such, it or parts thereof are openly accessible to anyone listed in the Audience section, either in electronic or in any other form.

Scope

This document represents the basic definitions for the ESS naming convention. It includes the definition of the convention, reference tables and further examples.

Audience

This document is targeted at ESS staff.

Table of Contents

1. Naming convention scope ............................................................................ 4 2. Format and syntax definition ....................................................................... 5 2.1. Syntax rules ............................................................................................................. 6

2.1.1. General guidelines ......................................................................................... 6 2.2. Type reference and attributes .................................................................................. 7

2.2.1. Device type reference .................................................................................... 7 2.2.2. Device attribute .............................................................................................. 7 2.2.3. Example ......................................................................................................... 8

2.3. Conventional facility naming .................................................................................... 8

3. Implementation .............................................................................................. 9 3.1. Terminology ........................................................................................................... 10 3.2. Area Breakdown Structure .................................................................................... 10 3.3. Controls Inventory ................................................................................................. 11 3.4. How to Construct Device Names ........................................................................... 13

3.4.1. Target ........................................................................................................... 13 3.4.2. Accelerator ................................................................................................... 13

3.5. General Rules for Names ...................................................................................... 14 4. References ................................................................................................... 16 Appendix A. Naming convention tools and consistency ............................ 17 A.1. Naming convention tool / software ........................................................................ 17 A.2. IOC variable name checking ................................................................................. 17

Figures

Figure 1. There are four cavities (Cav) inside a cryomodule (Cmd). The hierarchal structure cannot be resolved from the device names. .................................................... 9 Figure 2. The parent-child relation between cavities and cryomodules can be found in structures where the names are used, for example in the device configuration database or in the PBS. ............................................................................................................... 10 Figure 3. Example of the tool to select section-subsection. ......................................... 11 Figure 4. Tool to select a device from the inventory. .................................................... 12 Figure 5. Schematic layout of accelerator sections. ..................................................... 14 Figure 6. The high beta elliptical cavity section is divided into 30 numbered subsections, each containing one cryomodule. ............................................................ 14 Figure 7: A mockup GUI of a naming convention tool .................................................. 17

Tables

Table 1: Naming convention components ...................................................................... 6

Acknowledgement We have created this document after referring to naming conventions adopted at many other facilities: SNS, FRIB, ITER, CEBAF as well as earlier ESS naming conventions studies. In particular the system, subsystem and device identifiers from SNS have been borrowed (with some modifications) in the writing of the supporting documents listed in the references. We gratefully acknowledge the use of ideas and nomenclature as well as conversations with personnel from these institutions.

1. NAMING CONVENTION SCOPE

These requirements apply to all devices (beam instrumentation, sensors, actuators, etc.), equipment (power supplies, magnets, RF cavities, targets, moderators, instruments, etc.) and signals in technical systems and conventional facilities. The naming syntax does not apply to cable or pipe numbering, though cables, pipes and other items may be subsumed in the convention at a later date. The designations listed are to be used on operator screens, in the inventory system, drawings, design schematics, computer software, project databases, equipment name tags, test procedures, and other sources of technical information at ESS. The guiding principle for this document is that a uniform naming convention for ESS will help enforce system integration activities across all divisions.

2. FORMAT AND SYNTAX DEFINITION

The format of names (also called Process Variables in EPICS based Control Systems (CS) for those names which also reside in the CS) shall be as shown below. Further explanations of each component of the naming convention elements are listed in Table 1.

SSSS-BBBB:DDDD-III:TTTIIIXXX

Various examples for system and subsystem components are listed in reference 1. Device identifier examples are listed in reference 2.

This naming convention does not specify minimum or maximum lengths of the name components. However, there is one practical restriction on the overall length of a signal name in the Control System: the current EPICS version can only handle signal names of less than or equal to 28 characters in length. While this restriction will probably be eliminated in a future version, signal names to be implemented in EPICS in the near term should be limited to a length of 28 characters or less. Tests within EPICS are currently being conducted to determine whether this constraint remains necessary. Since the naming convention is a very important part of the over all system integration activities, we feel that this restriction will not present a problem in defining names for ESS.

System and subsystem name

Device identifier and quantifier

Signal type, instance and suffix

Device part Signal part

Table 1: Naming convention components

Naming part Description Requirements Responsible

SSSS System See [1], Section 1 TBD

BBBB Subsystem See [1], Section 2 TBD

DDDD Device identifier See [2] Controls

III Device qualifier and quantifier TBD Controls

TTT Signal type TBD Controls

III Signal instance TBD TBD

XXX Signal suffix TBD TBD

2.1. SYNTAX RULES

This section contains syntax rules that must be followed when naming according to the convention.

1. Allowed characters for names are: upper and lower case alphanumeric characters (a-z, A-Z, 0-9) and the two separator characters (-, :).

a. Avoid using the letter “O” where it can be confused with the number “0”. Avoid using the letter “l” where it can be confused with the letter “I”.

b. Avoid using the letter “I” where it can be confused with the number “1”.

2. The delimiter that separates name elements is “:” (colon). The separator that separates system / subsystem names and device qualifier / quantifier is “-” (dash). No other characters are allowed in names.

3. All three name elements are obligatory for signals. However, device names may omit the signal part when reference is only made to the device. Conventional facility designations may omit device (and signal) parts if reference is only being made to the system level (building) name and not to items or devices within the building.

2.1.1. General guidelines

Some general guidelines for names are listed below.

1. System and subsystem names are obligatory. If a need to omit any of the two elements arises think of a better segmentation for systems and devices.

2. If additional segmentation of the system or subsystem is required or for better clarity, an instance number can be appended to the system and subsystem name.

3. Name elements shall be composed with suitable and logical use of lower and upper case component names.

4. Device identifiers and quantifiers are obligatory unless there is only one instance present. Before the quantifier is omitted it is recommended to analyze the risk of doing so.

5. The number of devices and the scope of the devices should define the instancing (e.g. “-001”, “-A01”, “-1”).

6. The device quantifier can also be descriptive if the scope of the devices allows (e.g. high pressure – “-HP” – instead of “-001”).

7. Signal instance can be omitted if there is only an individual signal present.

8. Vendor specific naming should be avoided; the same goes for funny, contemporary or otherwise “meaningful” names.

9. It is advised to use fixed-width fonts (e.g. Courier New) when using variable names in any documentation, examples …

2.2. TYPE REFERENCE AND ATTRIBUTES

A name is composed of a device part (SSSS-BBBB:DDDD-III) and a signal part (TTTIIIXXX). The signal part is intrinsic to the Control System. The device part, however, can be used as the general designation for any part of the ESS infrastructure whether in controls or other technical systems and conventional facilities. Since the device part is constrained by nature of being a mnemonic, various type reference and attribute information may be required to fully understand the nature of an instantiated device. We explain these in the following two sub-sections.

2.2.1. Device type reference

A device type reference is defined as TTTTTTTTTT and represents a class of objects having the same set of characteristics.

Type references will be used as pointers to drawing schematics as well as purchasing information contained elsewhere in ESS technical information systems. As such the type reference identifier must be defined in co-ordination with the design team in the ESS project office.

2.2.2. Device attribute

A device attribute is defined as EEEEEE and is used to distinguish one instance of the same type reference from another.

Attribute information for a device type reference can be various. It may be stored elsewhere in ESS technical content management systems (TCMS). Consequently such attribute information will also be associated with an identifier (e.g., a web page link is possible) that conveniently allows access to this information.

2.2.3. Example

For example, there may be several types of valves used in ESS.

Valves with similar characteristics (size, shape, and manufacturer) are of the same type reference. This type reference is then used to reference part lists and purchasing information.

Each such valve type can then be distinguished by other attributes such as fluid type, pressure, temperature, etc.

2.3. CONVENTIONAL FACILITY NAMING

As mentioned earlier there are parts of the ESS complex that might escape being named by this convention. Pipes, cables and other structures in conventional facilities are potential examples. However, given that we will have type reference and attribute information available (see section [2.2] above) which link to other technical information systems and can provide additional information, we should try and use the naming syntax for everything in conventional facilities if possible.

3. IMPLEMENTATION

From the ICS point of view, all equipment is modeled as devices. A device name follows the format of signal names, however with the signal part left out:

SSSS-BBBB:DDDD-III

It is likely that the system part (SSSS-BBBB ) of device names will coincide with items in the line or project organization. The primary scope for naming is however for the operations of the facility. Therefore the structure does not necessarily need to follow the PBS, WBS or other project management structures, whose scope is intended mainly for the design and construction phases. The names shall however be used to name or label items in these structures whenever needed.

A device can reside inside another device, as shown in fig. 1. Devices are however not organized hierarchically through the naming convention. The parent-child relation among devices can instead be found in structures where the names are used (fig. 2).

HB-SCRF:Cav-1a

HB-SCRF:Cmd-1

HB-SCRF:Cav-1bHB-SCRF:Cav-1c

HB-SCRF:Cav-1d

Figure 1. There are four cavities (Cav ) inside a cryomodule (Cmd ). The hierarchal structure cannot be resolved from the device names.

The target and accelerator are both complex systems that in most aspects are very different from each other. Logically there are also different requirements from the accelerator and target teams on how to name devices. Therefore it is our belief that if we manage to consistently name devices for both target and accelerator it should be relatively straightforward to name devices in other areas at ESS.

HB-1

HB-SCRF:Cmd-1

HB-SCRF:Cav-1a

HB-SCRF:Cav-1b

HB-SCRF:Cav-1c

HB-SCRF:Cav-1c

Figure 2. The parent-child relation between cavities and cryomodules can be found in structures where the names are used, for example in the device configuration database or in the PBS.

3.1. TERMINOLOGY

The term “system” has different meaning to different people and will therefore be avoided. To be precise we will instead use the following definitions:

Discipline is a branch of knowledge such as RF systems, vacuum systems, cooling systems, controls, conventional facilities, etc.

A Device is the basic unit of granularity of the integrated control system (ICS) and the smallest components that can still be standalone and loosely coupled to other components. It is an abstraction that can represent either single pieces of equipment (low level code for interfacing with the hardware) or higher-level entities of the ICS (e.g., device models, subsystems, instruments etc.)

Super section or zone is an area of the facility restricted to a particular use. Example: Accelerator, Gallery, Target station, Neutron instruments and Utilities.

Sections and subsections are two levels of subareas of a zone. Section and subsection shall be named according to the system hosted in the area. For example there is a High Beta elliptical cavity section (HB ) in both the accelerator and gallery.

3.2. AREA BREAKDOWN STRUCTURE

By making section-subsection part of names and labeling sections and subsections in buildings it will be possible to tell the approximate location of a device from the name.

The terms section, subsection etc. shall not be displayed in the naming tool. When selecting an area the user shall be asked: “Which part of the facility does the device provide service to?” The answer shall be selected from approved lists as shown conceptually in fig. 3.

<Select><Select> ← Select or type convention name← Select or type convention name← Select or type convention name← Select or type convention nameGallery ▶Accelerator ▶Target Station ▶ Active cells ActC ▶Instruments ▶ Active fluids ActF ▶Utilities ▶ Active handling ActH ▶Instruments ▶ Active workshops ActWS ▶

Handling mock-up HMU ▶Intermediate cooling systems Inm ▶Mobile active vacuum ActVM ▶Moderators-Reflector MR ▶Monolith Mnlt ▶ Shielding cooling system ShColProton beam window PBW ▶ Monolith atmosphere system AtmRGEC RGEC ▶ Bulk shielding BlkShShielding TSh ▶ Irradiation plugs IrPlgTarget Tgt ▶ Liner LinTarget safety system TSS ▶ Removable shielding RvShTS storage TSg ▶ Shutter systems ShutTune-up dump TDmp ▶ Neutron beam ports (NBP) NBP

Proton beam diagnostics plug PBDPlgProton beam diagnostics skeleton PBDSInternal supporting structure SpStrTarget diagnostics plug TDPlgTarget diagnostics skeleton TDS

Which part of the facility does the device provide service to?

Section

SubsectionSuper Section

Convention name

Convention name

Figure 3. Example of the tool to select section-subsection.

3.3. CONTROLS INVENTORY

A device name SSSS-BBBB:DDDD-III contains information about the location of the installed device and in which context it is used. As such the device names shall not be confused with inventory identities. When an old device is replaced, the new device inherits the name.

Nevertheless, by linking device names to inventory identifiers (IDs) it will be possible to look up devices in the inventory system using the device name. The other way around, given the inventory identifier, it shall be possible to look up the device name.

The controls inventory will contain useful information for constructing the device names and how devices are configured. Devices in the inventory will be sorted under

• Level 1: Discipline

o Example: Super Conducting RF (SCRF ), Vacuum Systems (Vac ) or water cooling systems (WtrC )

• Level 2: Generic Type

o Two devices of the same generic type provide the same function

o Example: RF cavities (Cav ) accelerate the proton beam.

• Level 3: Control Type

o Two devices of the same control type are identical from a controls perspective and thus have the same set of control signals.

o Example: Elliptical cavities.

• Level 4: Specific Type

o Two devices of the same specific type are interchangeable. I.e., if one device breaks it can be replace by another device of the same specific type.

o Example: High beta elliptical cavities.

To name or to configure a device the user will be asked to select devices from the inventory as shown conceptually in fig. 4. Initially, only the discipline and generic device types will have to be selected in the naming tool. The control type, specific type and inventory identities will be added at later stages.

Both accelerator and target teams prefer to use generic device identifier DDDD in the names. Therefore, until decided otherwise the device names shall be constructed using a device identifier of the generic type.

The discipline that undoubtedly will have the largest number of different devices is the RF system, which therefore should be broken up further, for example, into:

• Super Conducting RF cryomodules and cavities (SCRF )

• RF source (RFS )

• RF distribution (RFD )

• RF cooling (RFC )

• Normal conducting RF (NCRF )

• Low Level RF (LLRF )

<Select><Select><Select>

Controls Ctrl ▶Conventional Facilities CF ▶

Cryogenics Cryo ▶Proton Beam Instrumentation PBI ▶

Proton Beam Optics PBO ▶

Super Conducting RF SCRF ▶ Cavity Cav ▶ Buncher Cavity BCav ▶

Vacuum Vac ▶ Cryomodule CMd ▶ DTL tank DTnk ▶

Water Cooling WtrC ▶ Fast Tuner FTn ▶ Elliptical Cavity ECav ▶ High Beta Cavity HBC ▶ AcDFQR1

Slow Tuner STn ▶ Radio Frequency Quadrupole RFQ ▶ Low Beta

cavity LBC ▶ ADFv3a55

Power Coupler PCp ▶ Spoke

Resonator Spk ▶ caQGERa

ETC ▶ asfz

ETC ▶ 234645y

Specific Type

Discipline

Generic Type

Device Identifier

Convention Name

Select device:

Inventory IDControl Type

Figure 4. Tool to select a device from the inventory.

3.4. HOW TO CONSTRUCT DEVICE NAMES

There are different requirements from the accelerator and target teams on how names are to be constructed, however the same tool and underlying database structure shall be used.

3.4.1. Target

Compared to the accelerator the target has few devices. Many of these are however unique. Target has a plant breakdown structure organized in two levels, which are referred to as system - subsystem by the Target Division. In the context of naming we identify these as sections and subsections of the area breakdown structure.

There is no desire from the Target Division to have the discipline as part of the device names and it is therefore straightforward to name device names according to:

• SSSS = Section Convention Name selected from the area breakdown structure

• BBBB = Subsection Convention Name selected from the area breakdown structure

• DDDD = Device identifier selected from the inventory

• III = Whatever quantifier needed to make the device name unique

3.4.2. Accelerator

There are many devices of the same kind in the accelerator, which creates a repetitive pattern. Each of the 13 accelerator sections shown in fig. 5 have therefore been divided into numbered subsections as showed in fig. 6 for the High Beta section (HB ). Each subsection contains many devices of different disciplines, such as beam optics, superconducting RF, beam instrumentation, vacuum, etc.

When selecting the subsection for the accelerator we use the same tool as for the target, shown in fig 3. However, the accelerator names need to be constructed differently. As an example, the device name of the second cavity in the first high beta cryomodule shall be named HB-SCRF:Cav-1b and not HB-1:Cav-2 . The latter is likely to cause confusion and does not include the discipline as required. Therefore the accelerator device names will be constructed according to

• SSSS = Section Convention Name selected from the area breakdown structure

• BBBB = Discipline Convention Name selected from the inventory

• DDDD = Device identifier selected from the inventory

• First part of quantifier III = Subsection convention name (a number) selected from the area breakdown structure

• Second part of quantifier III = a, b, c, d… or whatever starts with an alphabetic character.

Nr Name SSSS1 Ion Source ISrc2 Low Energy Beam Transport LEBT3 Radio Frequency Quadrupole RFQ4 Medium Energy Beam Transport MEBT5 Drift Tube Linac DTL6 First Beam Extraction FBX7 Spoke Linac SPK8 Medium Beta MB9 Second Beam Extraction SBX10 High Beta HB11 Upgrade (or Upper) High Beta UHB12 High Energy Beam to Target HEBT13 High Energy Beam to Dump HEBD

FDSL_2012_New

352.21 MHz 704.42 MHz

2.4 m

LEBT

3.6 m

MEBT

? m

UHB

? m

SBX

? m

FBX

HEBD

159.8 m

HEBT

32.4 m

DTL

78 MeV

4.0 m

RFQ

3 MeV

ISRC

75 keV

58.5 m

SPK

200 MeV

227.9 m

HB

2500 MeV

113.9 m

MB

628 MeV

Figure 5. Schematic layout of accelerator sections.

BLM

QV BPM

BBX

BCMHalo

BLM

BPM QH

BLM

GV

CMD

CAVH CAVH CAVH CAVHGV

BLM

GV

CMD


BLM

QV BPMHalo

BBX

WS NPM

BLM

BPM QH

BLM

GV

CMD


BLM

GV

CMD


BLM

QV BPMHalo

BBX

WS NPM

BLM

BPM QH

BLM

GV

CMD


BLM

GV

CMD


BLM

QV BPM

BBX

WS NPM

BLM

BPM QH

BLM

GV

CMD


BLM

GV

CMD


BLM

QV BPM

BBX

WS NPM

BLM

BPM QH

BLM

GV

CMD


BLM

GV

CMD


BLM

QV BPM

BBX

BSM

BLM

BPM QH

BLM

GV

CMD


BLM

GV

CMD


BLM

QV BPM

BBX

BSM

BLM

BPM QH

BLM

GV

CMD


BLM

GV

CMD


BLM

QV BPM

BBX

BSM

BLM

BPM QH

BLM

GV

CMD


BLM

GV

CMD


BLM

QV BPM

BBX

Halo

BLM

BPM QH

BLM

GV

CMD


BLM

GV

CMD


BLM

QV BPM

BBX

BLM

BPM QH

BLM

GV

CMD


BLM

GV

CMD


BLM

QV BPM

BBX

BLM

BPM QH

BLM

GV

CMD


BLM

GV

CMD


BLM

QV BPM

BBX

BLM

BPM QH

BLM

GV

CMD


BLM

GV

CMD


BLM

QV BPM

BBX

BLM

BPM QH

BLM

GV

CMD


BLM

GV

CMD


BLM

QV BPM

BBX

BLM

BPM QH

BLM

GV

CMD


BLM

GV

CMD


BLM

QV BPM

BBX

BLM

BPM QH

BLM

GV

CMD


BLM

GV

CMD


HB-03! HB-04!HB-01! HB-02!

HB-07! HB-08!HB-05! HB-06!

HB-23! HB-24!HB-21! HB-22!

HB-15! HB-16!HB-13! HB-14!

HB-19! HB-20!HB-17! HB-18!

HB-11! HB-12!HB-09! HB-10!

HB-27! HB-28!HB-25! HB-26!

HB-29! HB-30!

Figure 6. The high beta elliptical cavity section is divided into 30 numbered subsections, each containing one cryomodule.

3.5. GENERAL RULES FOR NAMES

Name in this section refers to convention names for section, subsection, discipline as well as device identifiers.

1. Names, quantifier and signal part of name shall be alphanumerical.

2. First character of Names, excluding subsection convention name of accelerator systems, shall be alphabetic.

3. For accelerator systems:

a. Subsystem convention name shall be numeric

b. Leading zeros shall be used to ensure that all numbers have the same number of digits.

c. First character of quantifier shall be alphabetic

4. Names shall be unique irrespective of:

a. Letter case;

b. Letters I, l and number 1;

c. Letter O and number 0;

d. Letters V and W;

e. Number 0 immediately following a non-numerical character

5. A section convention name can be identical to another section convention name if they belong to different super sections. For example there are High beta elliptical sections (HB) in both the accelerator and gallery zones.

6. A subsection convention name can be identical to another subsection convention name if they belong to different sections. For example there is a first subsection (01) in all accelerator sections.

7. Device name (SSSS-BBBB:DDDD-III) and signal names shall be unique according to rule 4.

4. REFERENCES

1. ESS Naming Convention reference tables

-- http://eval.esss.lu.se/cgi-bin/public/DocDB/ShowDocument?docid=41

2. ESS device identifiers

-- http://eval.esss.lu.se/cgi-bin/public/DocDB/ShowDocument?docid=42

Appendix A. NAMING CONVENTION TOOLS AND

CONSISTENCY The name format and list of syntax rules do not automatically make a good naming convention. Therefore the most important aspect of the naming convention is enforcement of the rules.

There are many different approaches to enforce the rules of the naming convention. They range from user-friendly (via applications) to very user-hostile (name checking of the signal names in the input output controllers (IOCs) at boot time). In this section we take a look at some of them.

A.1. NAMING CONVENTION TOOL / SOFTWARE

The best way to enforce naming convention rules is by using a tool that takes care of various naming steps. The possible use-cases for such an application are described in a separated document that is under development.

Figure 1 shows a mock graphical interface for such an application that automates most of the steps required to generate a new name. By increasing automation in the process and predefining name elements the scope of possible errors is reduced. We plan to adopt this method at ESS so that names can be created by users that automatically obey the syntax rules.

Figure 7: A mockup GUI of a naming convention tool

A.2. IOC VARIABLE NAME CHECKING

The other approach to enforcing the naming convention is to limit the functionality of hardware in case the variable names are wrong. To achieve this IOCs would check (with regular expressions or a custom parser) the names of the variables and prevent starting the application in case of name errors. An example of such usage can be seen below. As stated above, we are not planning to adopt this method of enforcing the syntax rules currently. We reserve the right to do so in the future, if required for internal consistency and integrity of the Control Systems.

/home/user> ./run_ioc Ø ERROR: PV name ‘Tgt:BullsEye-1:Center’ has no subsystem

defined! Ø The IOC application will now EXIT!

ESS Naming convention 20131011 v2 - Lunds universiteteval.esss.lu.se › DocDB › 0000 › 000004...

Documents

Transcript of ESS Naming convention 20131011 v2 - Lunds universiteteval.esss.lu.se › DocDB › 0000 › 000004...