LSA Database Import (Model)

1. Updating ring accelerator entries in LSA data base

This wiki page explains how the data required for the machine models can be imported into the LSA data base. This procedure is based on scripts which are stored in GSI’s LSA svn repository.

1.1 Deleting data base entries (optional)

If data base entries for a given accelerator ring exist already and one needs to replace a large number of these entries, it might be efficient to delete this information in the data base and newly fill it thereafter.

For deleting, Raphael Mueller created a compilation of (PL)SQL commands lsa-db-scripts 2013/sis100_delete_devices.sql, that act directly on the data base content of specified accelerator zones. Out of the compilation of commands , the information to be deleted can be chosen, however, it is recommended to delete neither the device types nor the logical devices such as the beam device.

1.2 Importing elements and devices

Devices and elements are imported from a csv file containing the following information:

• Devices
• Elements
• Element-to-device mapping
• Corresponding accelerator zones
• Element description
• Element plane information (H/V/undefined)
• Element multipole information (‘MAD parent’)

The columns of the table represented by the CSV file must be ordered like this:

Element

Device

Accelerator zone

Description

Plane

Mad parent

Element Type

e.g.: "YRT1LD21A;YRT1LD21A;YRLE;el.stat. quad. doublet, 1st lens, asymmetry knob;;K1L;QUADRUPOLE"

The actual import is done via the Java de.gsi.cs.co.ap.lsa.setup.dbimport.devices.DeviceImport in lsa-db-import maintained by J. Fitzek and R. Müller.

For the SIS100, the csv file is presently generated from the official nomenclature Excel sheet using a python script sis100_devices.pywritten by D. Ondreka (not yet available in the repository, please ask the author directly in case you're interested). Up to now, only elements that act on the beam are used, i.e. the elements are magnets and rf cavities, the devices are their power supplies and amplifiers; not included are beam diagnostics, vacuum installations, etc. This selection is part of the python script.

1.3 Defining the parameters and introducing the hierarchy of parameters

Parameters can either describe physics quantities (e.g. beam energy) or hardware settings (e.g. current for a power supply). The hierarchy provides the parent-child relation between these parameters, i.e. the link from the source parameter to the dependent parameter representing the derived quantity. The definition of logical devices within this script is under preparation.

For any given ring, a python script lsa-hierarchy-gsi/Generator_SIS100is used for this step. It defines:

1. The devices pertaining to the ring
2. All parameters except for hardware parameters
3. All parameter relations, i.e. the complete parameter hierarchy

The definition of parameters and relations contains a generic part, which is identical for any ring. Additional parameters may be added for features specific to the given ring. These scripts are presently maintained by H. Liebermann.

The scripts use a python interface maintained by R. Müller to create the parameters and relations. The original process needs a python script that generates a (JSON) file containing the data that is imported. This script is located in the lsa-py project. It is installed by default for members of the lsa linux group.
After the generation the file needs to be imported into the LSA database. A tool will be provided to do this, for the moment a Java class that provides the import features exists in the project lsa-hierachy-gsi.

1.4 Updating the element's information and importing the beam optics

This import to the data base consists of two steps:

1. The database table ELEMENTS is updated to add layout information for the elements, i.e. length, position, element type. This information is independent of a particular optics. (Note that this information is required to create the parameters systems, see below).
2. All optics dependent data is imported. This step consists again of two separate steps:
   1. Import of the theory optics. This step requires for each optic to be imported a MADX style twiss file with the following naming convention: <PARTICLE_TRANSFER>_<PREFIX>_<INDEX>. The file must be located in the following standard place: /common/usr/lsa/opt/optics/lsa/twiss/RING/<PARTICLE_TRANSFER>/. Any program can be used to create this twiss file. The import creates entries in the following database tables:
      1. OPTICS For each optic to be imported, basic information is stored in this table (e.g. optic name, creation date, lattice file, twiss file)
      2. TWISS_OUTPUTS For each element, integral strengths(KnL, KnSL) as well as optical functions (twiss parameters, dispersion, etc.) are stored.
      3. OPTIC_STRENGTHS For each magnet device, the unique integral strength in the given optic is stored.
      4. OPTIC_PARAMETERS For each global optics parameter of a ring (tunes, chromaticities, momentum compaction), the value in the given optic is stored.
   2. Calculation of knobs, i.e. linear approximation of deviations from the theory optics (e.g. tune and chromaticity variation, local orbit bumps). This step is presently based exclusively on calculations using MIRKO. Therefore, it requires a standardized MIRKO lattice and, for each optic type, a number of standardized makro files. The import creates entries in the database table KNOBS.

The first step is performed using the Java program lsa-mirko-optic-import-gsi/ElementUpdatePerformer maintained by D. Ondreka. The second step is performed by the Java program lsa-mirko-optic-import-gsi/LSAOpticsCreatormaintained by D. Ondreka.

1.5 Finalising the devices' parameters

This step can be performed before or after the optics import. Here, the information of the devices is completed: calibration curves and upper and lower limits are given to each device. This information is stored in xml files that contain the calibration curves (listed in tables) and minimum and maximum values for each device. The import of the device data from the xml sources is performed by a Java program sy-app-dmgen/FSyDataApp maintained by H. Liebermann.