Software Requirements Specification for LLRF Applications at FLASH Version 1.0 Prepared by Zheqiao Geng MSK, DESY Nov. 06, 2009

Transcription

1 Software Specification for LLRF Applications at FLASH Version 1.0 Prepared by Zheqiao Geng MSK, DESY Nov. 06, 2009 Copyright 2009 by Zheqiao Geng. Any change of this document should be agreed by the development team.

2 Software Specification for LLRF Applications at FLASH Page ii Table of Contents 1. Introduction Purpose Document Conventions Intended Audience and Reading Suggestions Product Scope References Overall Description Product Perspective Product Functions User Classes and Characteristics Operating Environment Design and Implementation Constraints User Documentation Assumptions and Dependencies External Interface User Interfaces Hardware Interfaces Software Interfaces Communications Interfaces Use Cases Use Case List Use Case Description Other Additional Functional Additional Non-Functional External Glossary To Be Determined List...24

3 Software Specification for LLRF Applications at FLASH Page iii Revision History Version Reason For Changes Date 1.0 Zheqiao Geng Initial Revision Nov. 06, 2009 Approved By Signature Department Date

4 Software Specification for LLRF Applications at FLASH Page 1 1. Introduction 1.1 Purpose This document is to present the software requirements specification for the LLRF Applications at FLASH, which is part of the LLRF upgrade for the FLASH upgrade program started from September of In this document, the goals, constrains, use cases and non-functional requirements will be presented for the LLRF Applications at FLASH. 1.2 Document Conventions To be worked out later. 1.3 Intended Audience and Reading Suggestions FLASH Managers : can only read Chapter 1 and 2 for the system goals, scope and constraints FLASH Operators : can read Chapter 1 for the overview of this document, and then directly read Chapter 3 and 4 to verify the user interfaces and use cases Involved in : can read Chapter 1 for the overview of this document, and then directly read Chapter 3 and 4 to verify the user interfaces and use cases Algorithm Developers : can read Chapter 1 for the overview of this document, and then directly read the Chapter 4 and 5 for use cases and other requirements to find out what algorithms need to be worked out, and the performance for each algorithm Software Developers : should read the whole document to verify that the software under development is oriented to the system goals, within the system scope, follow the constraints, realize the use cases and satisfy the non-functional requirements Software Testers : should read the whole document to test if the interface requirements, use cases and non-functional requirements are satisfied or not 1.4 Product Scope LLRF Applications are a group of algorithms and software to support the configuration, optimization and operation of the LLRF system. For the FLASH upgrade, the LLRF Applications will try to facilitate to Improve the RF field stabilities by optimizing the parameters of the RF field controller Improve the robustness and availability of the LLRF system by system diagnostics, exception detection and handling Support automation for easy operation The goals of the LLRF Applications at FLASH:

5 Software Specification for LLRF Applications at FLASH Page 2 Support commissioning and operation of FLASH after upgrade Implement robust algorithms for LLRF in DOOCS servers Realize basic automation of the LLRF Applications and procedures Validate the concepts of applications development for the European XFEL LLRF system 1.5 References 1). For FLASH upgrade information, 2). Software Design Specification for LLRF Applications at FLASH, v Overall Description 2.1 Product Perspective LLRF Applications are a part of the LLRF system of FLASH. It is based on the hardware and basic software (such as field controller and communication links), and provides support to the operation of the whole LLRF system, helping the system to reach its performance specification, improve the system robustness and availability, and also support the operator for easy operation. The context of the LLRF Applications in the LLRF system is shown in Figure 1. Figure 1: Context of the LLRF Applications The main input of the LLRF Applications will be Initial measurements of the cavity RF signals, including probe, forward and reflected signals Intermediate data from the field controller, such as DAC output and vector sum errors

6 Software Specification for LLRF Applications at FLASH Page 3 Initial measurements of the high power RF signals, including the klystron and preamplifier output signals Data from other systems, such as the klystron high voltage and beam current The main output of the LLRF Applications will be System characteristics, such as the system dynamic model, loaded Q and detuning of the cavity Calibration coefficients, such as the vector sum calibration coefficients Optimized parameters for field controller, such as the optimized feedback gain and feed forward tables Optimized settings for other systems, such as the setting of the loaded Q and detuning of the cavity System status reports Before FLASH upgrade, most of the applications were realized in matlab, and there were no automatic procedures in use. The software described in this specification is to replace the matlab applications and realize them in DOOCS framework in order to provide a set of more robust and more automatic tools for the operation of the LLRF system. 2.2 Product Functions The LLRF Applications at FLASH will perform the functions of System identification : identify the dynamical model of the RF control system, and measure the characteristic parameters of the system, which provide input to all other applications System calibration : vector sum calibration, cavity gradient and phase calibration, cavity forward and reflected power calibration Parameters optimization Diagnostics support Exception detection Exception handling 2.3 User Classes and Characteristics FLASH Operators : use the LLRF Applications to set the vector sum voltage and phase of each RF station, switch on/off the feedback, and view the status report (simplified) of the LLRF system Involved in Daily : use all functions of the LLRF Applications and view the detailed status report of the LLRF system (frequently) for Machine Study and Maintenance : use all functions of the LLRF Applications and view the detailed status report of the LLRF system (time to time) FLASH Manager : view the status report (simplified) and failure statistics of the LLRF system

7 Software Specification for LLRF Applications at FLASH Page Operating Environment The LLRF Applications at FLASH will be designed for the platform of SIMCON DSP installed at VME crates and the 250 khz IF scheme. The software will be operated at VME CPU (for applications in the front-end DOOCS servers) and Sun servers (for applications in the middle-layer DOOCS servers). The software will be operated in the operating system of Sun Solaris2 and Linux. The software will be embedded into the DOOCS servers. The software will coexist with the Client Applications. 2.5 Design and Implementation Constraints This project is for FLASH Applications should be implemented in DOOCS Computation rate should be larger than 1Hz, but do not need to response from pulse to pulse (for some applications, 5 to 10 Hz is possible, but may have several pulses latency) Follow the nomenclature of LLRF and DOOCS in source code (location name follow the DOOCS nomenclature, and property name follow the LLRF nomenclature) All the initial data required by the applications should be taken from the DAQ system Applications should be implemented in C/C++ language Software implementation should be open source and follow the GNU standard (binary for Solaris Debian differently, releasing the source code we follow the tar package defined by GNU) Source code should be saved in Subversion (SVN) (CVS!) 2.6 User Documentation The documents below will be delivered to the users with the software: User s manual On-line help Tutorials LLRF matlab library manual LLRF C library manual 2.7 Assumptions and Dependencies Assumptions: Assume the database for firmware and run-time parameters are available (To be decided!) Assume it is promised to upgrade the VME computers and Sun servers to have enough computation power and memory for the software if necessary Assume FLASH can provide moderate beam (3nC and 30 bunches) for calibration

8 Software Specification for LLRF Applications at FLASH Page 5 3. External Interface 3.1 User Interfaces The user interfaces should use the existing FLASH LLRF user interfaces as reference. The user interfaces of the LLRF Applications should have two parts, one for FLASH Operators and another for, which are shown in the tables below. Table 1: User interfaces for FLASH Operators Interface Input / Output Signal Type Unit Note 3.2 Hardware Interfaces To be worked out later. 3.3 Software Interfaces To be worked out later. 3.4 Communications Interfaces To be worked out later.

9 Software Specification for LLRF Applications at FLASH Page 6 4. Use Cases Here collect the main functional requirements to the LLRF Applications at FLASH in the format of use cases, which will correspond to the relative independent tasks and procedures that the operator may use the LLRF Applications to perform. Other functional requirements and non-functional requirements that are not suitable to be presented in use cases will be presented in next Chapter. 4.1 Use Case List Here give a brief list of the use cases of the LLRF Applications at FLASH: LLRF_UC01: Configure the LLRF firmware LLRF_UC02: Set the vector sum voltage and phase for each RF station LLRF_UC03: Set the fill and flattop duration of the RF pulse, and set the basic feed forward parameters LLRF_UC04: Calibrate the vector sum LLRF_UC05: Close the RF feedback loop LLRF_UC06: Optimize the LO generation tables LLRF_UC07: Correct the DAC offset of the field controller LLRF_UC08: Tune the cavity resonance frequency LLRF_UC09: Adjust the cavity incident phase automatically LLRF_UC10: Adjust the cavity loaded Q automatically LLRF_UC11: Sweep the feedback gain for correlation study LLRF_UC12: Optimize the feed forward tables LLRF_UC13: Measure the system status LLRF_UC14: Start up and calibrate the RF gun LLRF_UC15: Recover the beam parameters after interlock trip LLRF_UC16: Save/restore machine settings LLRF_UC17: Check/set the timing of klystron, LLRF and other components LLRF_UC18: Support the beam based feedback 4.2 Use Case Description LLRF_UC01: Configure the LLRF firmware LLRF_UC01 Configure the LLRF firmware Basic Enable the to configure the SIMCON DSP with proper firmware for the RF field controller. Automatic configuration during the start up of the DOOCS front-end servers should be also supported. SIMCON DSP boards for each RF station have been powered up and the

10 Software Specification for LLRF Applications at FLASH Page 7 Basic Flow Alternative Exceptions Post-conditions Internal Interface FPGAs have been properly configured DOOCS front-end servers have been started up Proper firmware for the RF field controller are available RF gate of the RF station to be configured has been switched off Settings of the controller parameters have been saved Only authorized can perform the operation 1. start the operation with parameters of: 1). Destination of the SIMCON DSP (RF station number, bus address of the SIMCON DSP boards) 2). Location of the firmware 3). Version of the firmware 2. LLRF Applications check the status of feedback, feed forward and RF gate 3. LLRF Applications load the proper firmware and download it to the FPGA of the SIMCON DSP 4. LLRF Applications read the firmware ID and version information from the configured FPGA 5. LLRF Applications report the configuration status to 6. record the successful new configuration in logbook, including the firmware version, purpose and description In Step 1, the operation can also be started automatically when the DOOCS front-end server starts up, and then follow the Step 2 In Step2, if the field controller is in operation before starting this use case, follow the steps of 2.a.1. Check the status of feedback, feed forward and RF gate 2.a.2. If the feedback or feed forward is enabled, or the RF gate is switched on, jump to Step 5 and generate alarm to the user. And if not, continue to Step 3 And if the use case is performed just after the DOOCS front-end server starts up (field controller is not in use), follow the steps of 2.b.1. Check the status RF gate 2.b.2. If the RF gate is switched on, jump to Step 5 and generate alarm to the user. And if not, continue to Step 3 If the input parameters of step 1 is wrong, such as the wrong station number, bus address or wrong firmware version, jump to Step 5 and generate alarm to the user If the feedback, feed forward and RF gate status are not measurable in Step 2, jump to Step 5 and generate alarm to the user If there is mismatch between the firmware and FPGA type or the firmware does not exist in step 3, jump to Step 5 and generate alarm to the user If the firmware configuration is failed in step 3, jump to Step 5 and generate alarm to the user The new firmware of the field controller is configured to the FPGA of SIMCON DSP Configure a single FPGA (one SIMCON DSP board) Configure the FPGAs of one RF station (one or two SIMCON DSP boards)

11 Software Specification for LLRF Applications at FLASH Page 8 Configure all/several RF stations Provide a central location to store the firmware, such as database Provide a graphical user interface for the firmware configuration with clear guide information LLRF_UC02: Set the vector sum voltage and phase for each RF station Basic Flow Alternative LLRF_UC02 Set the vector sum voltage and phase for each RF station Basic Enable the FLASH Operators to set the vector sum voltage and phase of each RF station, and this is the most basic function that the LLRF system should provide to the FLASH Operators Enable the LLRF Applications and Client Applications to set the set point table and feed forward table directly FLASH Operators LLRF front-end server for the field controller is working properly Vector sum has been well calibrated, including the absolute calibration of the cavity gradient to the physical unit of MV/m When the beam is on, confirm to the beam orbit before making large range change of the vector sum voltage and phase The vector sum voltage should not be set larger than the limitations decided by the cavity quench, klystron power and coupler sparks Do not change the tables in the field controller in case of exceptions 1. FLASH Operators input the new vector sum voltage and phase in physical units from the user interface 2. LLRF Applications validate the input values to be sure they do not exceed the limitations 3. LLRF Applications convert the input values from physical units to digital values 4. LLRF Applications generate new set point table and feed forward table based on the input values 5. LLRF Applications validate the set point table and feed forward table 6. LLRF Applications download the new tables to the field controller 7. FLASH Operators confirm the new settings from the vector sum display in the user interface In Step 1, the parameters can also be set by LLRF Applications or Client Applications via the DOOCS interface, and then follow the Step 2 In Step 2, if the input values do not exceed the limitations, follow the Step 3, or follow the steps of 2.a.1. Stop the use case and generate alarm to the FLASH Operators 2.a.2. Provide suggestions of the ranges of the input values in the GUI In Step 4, the new set point table and feed forward table can also be set directly by the LLRF Applications and Client Applications through DOOCS (skip Step 1 to 3), then follow the Step 5

12 Software Specification for LLRF Applications at FLASH Page 9 Exceptions Post-conditions Non-Functional In Step 5, if the set point table and feed forward table are valid, follow the Step 6, or follow the steps of 5.a.1. Stop the use case and generate alarm to the FLASH Operators 5.a.2. Provide suggestions of the ranges of the set point table and feed forward table In Step 2, if the limitations (thresholds) do not exist, use the default values In Step 3, if the calibration coefficients between the values in physical units and digital values do not exist, stop the use case and generate alarm to the FLASH Operators In Step 5, if the limitations (thresholds) do not exist, use the default values In Step 6, if fail to download the new tables, stop the use case and generate alarm to the FLASH Operators The vector sum voltage and phase are adjusted and feedback control is stable with the new setting Small change of the vector sum voltage or phase during beam operation for beam parameters adjustment Large scale change of the vector sum voltage or phase for working point adjustment or calibration (like the gradient calibration with energy maximizing method) [Functionality :: Interoperability] User input should be converted to the format, structure and scale demanded by the controller [Efficiency :: Time Behavior] The operation should be finished within 100 ms; tables downloading to the controller should be finished during the gap between RF pulses The limitations of the vector sum voltage and phase should be able to be set through the user interface Provide management (such as database) of the parameters like vector sum voltage limitations and calibration coefficients between values in physical units and digital values LLRF_UC03: Set the fill and flattop duration of the RF pulse, and set the basic feed forward parameters Basic Flow LLRF_UC03 Set the fill and flattop duration of the RF pulse, and set the basic feed forward parameters Basic Enable the to change the RF pulse shape and adjust the feed forward table shape Refer to LLRF_UC02 Refer to LLRF_UC02 1. input the parameters of the fill and flattop duration of the RF pulse, or the feed forward parameters such as the ratio of the fill and flattop amplitudes

13 Software Specification for LLRF Applications at FLASH Page 10 Alternative Exceptions Post-conditions Non-Functional Note 2. Follow the Step 2 to 7 of LLRF_UC02 Refer to LLRF_UC02 Refer to LLRF_UC02 The new set point table and feed forward table are set to the field controller and feedback control is stable with the new setting Set the fill and flattop duration of the RF pulse for working point adjustment or calibration Refer to LLRF_UC02 Refer to LLRF_UC02 This use case will be valid for many parameters setting, such as feedback gain LLRF_UC04: Calibrate the vector sum Basic Flow LLRF_UC04 Calibrate the vector sum Basic Enable the to calibrate the vector sum, including the calibration of the vector sum measurement and the absolute calibration of the cavity gradient to the physical unit of MV/m Measurement of the probe signal of individual cavity is available The resonance frequency of all cavities have been well tuned Moderate beam (such as 3nC, 30 bunches) can pass through the accelerating modules belongs to the vector sum to be calibrated Cavity is working at 100% of the full gradient The field controller is working at open loop operation Never submit the calibration coefficients in case of exception Calculate several times and take average Only authorized can perform the operation 1. start the operation with the parameters of: bunch charge, bunch number, beam timing information (beam on and beam off time), average number, and so on 2. LLRF Applications set up the beam for calibration 3. LLRF Applications measure the beam transient signal in each cavity and then switch off the beam 4. LLRF Applications calculate the vector sum calibration coefficients (rotation matrices) for each cavity 5. LLRF Applications read the beam current information from the proper DOOCS property and calculate the real beam induced voltage 6. LLRF Applications calculate the gradient in physical unit of MV/m for each cavity 7. LLRF Applications save the vector sum calibration coefficients to the field

14 Software Specification for LLRF Applications at FLASH Page 11 Alternative controller and database; save the cavity gradient calibration coefficients to the proper DOOCS servers and database; report the calibration results to the 8. confirm the calibration results and record to the logbook The poor man s calibration method as alternative choice: a.1. start the poor man s calibration a.2. LLRF Applications measure the probe signal of each cavity a.3. LLRF Applications calculate the rotation matrices for each cavity to rotate and scale the probe signals of other cavities to be same as the first one a.4. LLRF Applications save the vector sum calibration coefficients to the field controller and database Exceptions In Step 2, if the beam can not be set up or the beam current is unstable or the beam loss is large, stop the use case and generate alarm to the In Step 3, if the beam transient signal is too small or the cavity gradient is too small or not available or not stable, stop the use case and generate alarm to the In Step 5, if the beam current information is not available, stop the use case and generate alarm to the In Step 7, if the vector sum calibration coefficients and cavity gradient calibration coefficients exceed the thresholds, stop the use case and generate alarm to the Post-conditions The new vector sum calibration coefficients and cavity gradient calibration coefficients are calculated and saved to the RF field controller, proper DOOCS servers and database Vector sum calibration executed by the Non-Functional [Functionality :: Accuracy]: The calibration error for each cavity should be less than 0.5 degree in phase and 1% in amplitude [Functionality :: Interoperability]: All data transferred in/out of the software for the use case should be converted to be consistent with the format, structure and scale of the interfaces with field controller and other DOOCS servers [Reliability :: Fault tolerance]: The calibration procedure should distinguish and discard abnormal RF pulses with big fluctuations [Reliability :: Recoverability]: Before setting the calibration coefficients, the old values should be saved for backup [Efficiency :: Time behavior]: The use case should be completed in 60 seconds [t < 60s] The r/q values of each cavity should be known The beam should be injected at the middle of the RF pulse LLRF_UC0 5: Close the RF feedback loop LLRF_UC05

15 Software Specification for LLRF Applications at FLASH Page 12 Close the RF feedback loop Basic Enable the FLASH Operators to close the feedback loop for vector sum control FLASH Operators Vector sum calibration has been well done Klystron high voltage is set properly Never close the feedback loop if the conditions below are not satisfied 1). Loop phase is adjusted within 10 degree 2). Loop gain is calibrated and corrected Basic Flow 1. FLASH Operators send command to closed the feedback loop 2. LLRF Applications adjust the loop phase and correct the loop gain 3. LLRF Applications set the field controller for closing the feedback loop 4. FLASH Operators confirm the settings from the vector sum display at GUI Alternative In Step 1, the command can also be set by the LLRF Applications and Client Applications Exceptions TBD Post-conditions The feedback loop is closed and works stably Initially close the feedback loop during start up of the LLRF system Close the feedback loop after small adjustment of the controller parameters Close the feedback loop after adjusting the klystron high voltage Non-Functional [Efficiency :: Time behavior]: The use case should be completed in 100 ms TBD LLRF_UC06: Optimize the LO generation tables Basic Flow LLRF_UC06 Optimize the LO generation tables Basic Optimize the switched LO generation tables for the 250kHz IF scheme, in order to remove the RF input phase dependant errors in amplitude and phase measurement RF signal measurement are enabled Signal generator is available for calibration and its signal is measured by the RF measurement channel with the same type as cavity probe signals Open loop operation Only authorized can perform the operation Should not be done during normal operation, because it will influence the RF field measurement significantly 1. start the operation 2. LLRF Applications measure the signal (with frequency of 1.3GHz + 500Hz to 2kHz) of the signal generator in I/Q format

16 Software Specification for LLRF Applications at FLASH Page 13 Alternative Exceptions Post-conditions Non-Functional 3. LLRF Applications measure the amplitude and phase imbalance of the I and Q channels by Fourier fitting 4. LLRF Applications calculate the new tables for LO generation to compensate the imbalance 5. LLRF Applications download the new tables to the DAC board for LO generation 6. confirm the calibration effect by calibration signal measurement and real cavity probe signal measurement TBD In Step 3, if the imbalance exceed the thresholds, stop the use case and generate alarm to the In Step 4, if the new tables for LO generation have too large errors compared to the prediction, stop the use case and generate alarm to the New LO generation tables are decided and downloaded to the DAC board TBD TBD Provide a signal generator for calibration Provide extra RF measurement channel for calibration LLRF_UC0 7: Correct the DAC offset of the field controller Nam e Basic Flow LLRF_UC07 Correct the DAC offset of the field controller Advanced Provide an automatic method to correct the DAC offset of the field controller for zero power settings RF signal measurement of the output from the vector modulator or the pre- enabled amplifiers are Open loop operation Only authorized can perform the operation Do not submit the results to the field controller in case of exceptions 1. start the operation with the parameters of: point number for calibration, set point of the vector sum voltage 2. LLRF Applications save the current settings of vector sum voltage and phase for backup 3. LLRF Applications change the amplitude and phase of the controller output and measure the output from the vector modulator or pre-amplifiers 4. LLRF Applications calculate the DAC offset 5. LLRF Applications confirm the results and save to the field controller and database 6. LLRF Applications restore the settings of vector sum voltage and phase

17 Software Specification for LLRF Applications at FLASH Page confirm the results from the display of vector sum in GUI, and make fine adjustment by hand if necessary Alternative In Step 1, the operation can also be started by the LLRF Applications and Client Applications, and follow Step 2 In Step 3, if the klystron output is available, it can also be measured, and follow Step 4 An alternative method for DAC offset correction during closed loop operation (without interrupt the normal operation) a.1. Same as the Step 1 a.2. LLRF Applications introduce a secondary pulse after the working pulse with the feed forward tables, during which the feedback is off a.3. LLRF Applications change the phase of the secondary pulse and measure the output from the vector modulator, pre-amplifiers or klystron a.4. Follow the Step 4, 5 and 7 Exceptions In Step 1, if the point number for calibration is less than 8, or the set point voltage is larger than the limitations, stop the use case and generate alarm to the In Step 3, if the measurement of the output from the vector modulator, preamplifiers or klystron is not available or is unstable, stop the use case and generate alarm to the In Step 5, if the calculation results exceed the thresholds, stop the use case and generate alarm to the Post-conditions The DAC offset is corrected Non-Functional Correct the DAC offset at start up of the system (klystron should not be activated for safety) Correct the DAC offset during calibration stage with open loop operation (the whole feed forward table can be changed) Correct the DAC offset during closed loop operation (introduce secondary pulse) [Functionality :: Accuracy] The DC offset should be calibrated to the level of less than 0.1% of the driving signal for normal operation gradient (so for 10MV/m gradient, the offset will generate a gradient of 0.01MV/m, which is acceptable) TBD LLRF_UC08: Tune the cavity resonance frequency LLRF_UC08 Tune the cavity resonance frequency Advanced Provide an automatic method for slow resonance control Frequency motor tuner control of each cavity is available Cavity is working in normal gradient

18 Software Specification for LLRF Applications at FLASH Page 15 Open loop operation Only authorized can perform the operation Do not change the cavity detuning in case of exceptions Basic Flow Th e basic flow for adjusting the cavity detuning to a defined destination: 1. input the destination detuning of the cavity to be tuned 2. LLRF Applications measure the cavity detuning as average of the detuning during RF flattop and record the current position of the motor tuner 3. LLRF Applications calculate the steps of the motor to reach the destination detuning and move the motor tuner by the steps calculated 4. LLRF Applications repeat Step 2 5. LLRF Applications repeat Step 3 and 4 (at most 3 times) until the error of the cavity detuning against the destination is smaller than a defined value 6. confirm the settings from the GUI Alternative The detuning can also be calculated during RF decay if the cavity driving signal is not available The alternative flow for the scenario of Bypass the cavity Additional : The cavity to be bypassed is in-operation Flow: a.1. input the command to bypass the specified cavity a.2. Same as Step 2 of basic flow a.3. Same as Step 3 of basic flow, the destination is 10 times of the cavity half bandwidth a.4. LLRF Applications save the current position of the motor tuner a.5. Same as Step 6 of basic flow The alternative flow for the scenario of Un-bypass the cavity Additional : The cavity to be un-bypassed is in bypassed state; the motor position of the cavity in-operation state has been recorded Flow: b.1. input the command to un-bypass the specified cavity b.2. LLRF Applications move the motor to the position saved during in- operation state b.3. Same as Step 6 of basic flow The alternative flow for scenario of Optimize the pre-detuning Exceptions Additional : The cavity is in-operation; there is no Piezo tuner working Flow: c.1. input the command to optimize the pre-detuning c.2. Set the destination to zero and follow Step 2 to 6 of basic flow In Step 1, if the detuning destination exceed the limitations of the motor tuner, stop the use case and generate alarm to the In Step 2, if the detuning measurement fails (such as by too mall cavity gradient), stop the use case and generate alarm to the In Step 3, if the motor tuner is not available or reaches to its terminals, s top the use case and generate alarm to the In Step 3, if the calibration coefficients between the motor steps and detuning

19 Software Specification for LLRF Applications at FLASH Page 16 Post-conditions Non-Functional does not exist, stop the use case and generate alarm to the The cavity is tuned Tune a single cavity Tune a group of cavities at the same time [Functionality :: Accuracy] The detuning should be controlled in the accuracy of 20 Hz Provide functions to measure the cavity detuning during RF pulse The calibration coefficients between the motor steps and detuning should be known LLRF_UC0 9: Adjust the cavity incident phase automatically To be work out later. (Nice to Have) LLRF_UC10: Adjust the cavity loaded Q automatically To be work out later. (Nice to Have) LLRF_UC11: Sweep the feedback gain for correlation study Basic Flow Alternative Exceptions Post-conditions LLRF_UC11 Sweep the feedback gain for correlation study Advanced Enable the to determine the optimized gain for RF stability or beam stability RF control loop is closed Beam stability (beam energy, beam current and beam arrival time) measurement is available Only authorized can perform the operation 1. input the feedback gain sweep range 2. LLRF Applications save the current feedback gain for backup 3. LLRF Applications change the feedback gain and measure the RF stability or beam stability 4. LLRF Applications restore the feedback gain 5. LLRF Applications calculate the optimized feedback gain 6. LLRF Applications return the results to the and display on GUI In Step 1, the operation can also be started by the LLRF Applications or Client Applications In Step 1, if the gain sweep range exceeds the threshold, stop the use case and generate alarm to the In Step 2, if the RF error or beam parameters error is too large (and the gain does not reach the sweep range), stop the gain sweep and jump to Step 3 The system state is recovered to be same as before the operation This use case is mainly for calibration and machine study

20 Software Specification for LLRF Applications at FLASH Page 17 Non-Functional TBD TBD LLRF_UC12: Optimize the feed forward tables Basic Flow Alternative Exceptions Post-conditions Non-Functional LLRF_UC12 Optimize the feed forward tables Basic Optimize the feed forward tables for repetitive error correction including beam loading compensation Iterative learning control will be used The cavity is running at the normal operation gradient The vector sum calibration has been performed The loop phase and loop gain has been set properly The system model has been identified Only authorized can perform the operation Do not refresh the feed forward tables in case of exceptions 1. start the iterative learning control with the parameters of adaption range and adaption gain 2. LLRF Applications load the RF system model and necessary parameters 3. LLRF Applications calculate the feed forward correction table based on the system model and vector sum error 4. LLRF Applications validate the new feed forward table 5. LLRF Applications download new feed forward table to the field controller 6. LLRF Applications repeat Step 3 to 5 until the vector sum error becomes stable (the algorithm convergent) or the push the stop button In Step 1, the operation can also be started by the LLRF Applications or Client Applications In Step 1, if the adaption range or adaption gain exceed the thresholds, stop the use case and generate alarm to the In Step 2, if the RF system model does not exist, stop the use case and generate alarm to the In Step 2, if the RF system model is too old, generate warning to the LLRF Experts In Step 4, if the predicted system performance degrades, skip the current iteration and generate warning to the Th e repetitive error is compensated When the system working point (such as cavity gradient, RF pulse shape and beam loading) changes, adapt the feed forward table for new settings [Functionality :: Accuracy] The steady state error of the RF flattop should meet the RF phase and amplitude stability requirements for each section of

21 Software Specification for LLRF Applications at FLASH Page 18 the accelerator [Functionality :: Interoperability] The output of AFF should be converted to the same scale with the working feed forward tables [Reliability :: Fault Tolerance] Detect the wrong klystron high voltage or power; detect the wrong cavity gradient; detect the wrong beam loading (such as beam inhibition interlock, the AFF tables should be adapt for it) [Efficiency :: Time Behavior] The algorithm should convergent within 20 iterations Provide Client Applications for black box model identification LLRF_UC 13 : Measure the system status Basic Flow LLRF_UC13 Measure the system status Basic Measure and report the system status Detect system performance and failures and generate warnings and alarms to the FLASH Operators Automatic activate when system start up (or provide on/off button for FLASH Operators) Work for all conditions The report should have two versions: v1: for FLASH Operators, only with abstract information of the system health v2: for, should have detailed information for system hardware, software and analysis of the failure source The basic flow works for each RF station 1. LLRF Applications read the following data from the field controller or other DOOCS properties or the DAQ system Probe signal in I/Q format for each cavity High power chain RF signals in I/Q format (vector modulator, preamplifiers and klystron output) Toroid signal Vector sum in I/Q format 2. LLRF Applications measure the system parameters of Loaded Q and detuning of each cavity RMS error of the cavity RF amplitude and phase, including intra-pulse and pulse to pulse error RMS error of the high power chain RF amplitude and phase, including intra-pulse and pulse to pulse error RMS error of the vector sum amplitude and phase, including intra-pulse and pulse to pulse error Loop phase and loop gain 3. LLRF Applications provide status report to the FLASH Operators

22 Software Specification for LLRF Applications at FLASH Page 19 RF measurement channel input power too small or saturation Vector sum error large Loop phase and loop gain error LLRF components failure ( MO, frequency distribution, vector modulator, LO, down converter, vector sum calibration, RF gate, SIMCON DSP, communication links) Saturation of vector modulator, pre-amplifiers and klystron High power chain RF signal unstable High power chain RF component failure (pre-amplifiers, klystron) Cavity RF signal unstable Cavity gradient exceeds limitations Cavity phase or gradient slope large Cavity quench Cavity detuning large Cavity motor tuner failure Cavity incident phase error Relative timing error (RF gate, klystron, RF pulse, beam) DOOCS server failure VME computer failure Network failure Alternative No Exceptions No Post-conditions System status is reported No Non-Functional No No LLRF_UC14: Start up and calibrate the RF gun Basic Flow 1. Alternative Exceptions LLRF_UC14 Start up and calibrate the RF gun Basic Accelerate the start up of the RF gun Calibrate the RF gun field measurement

23 Software Specification for LLRF Applications at FLASH Page 20 Post-conditions Non-Functional LLRF_UC 15 : Recover the beam parameters after interlock trip Basic Flow 1. Alternative Exceptions Post-conditions Non-Functional LLR F_UC15 Recover the beam parameters after interlock trip Advanced (to be decided! May bre nice to have) Recover the beam energy, beam current and beam arrival time after interlock trip to improve the availability of the system LLRF_UC 16 : Save/restore machine settings Basic Flow LLRF_UC16 Sav e/restore machine settings Basic Save the machine settings for backup so that the machine state can be recovered easily after some special operations Restore the machine state to the saved settings No Only authorized can perform the operation Basic flow for saving the machine settings 1. push the button to save the machine settings of specified RF stations 2. LLRF Applications record the system parameters of

24 Software Specification for LLRF Applications at FLASH Page 21 * The list should be worked out later! Alternative Exceptions Post-conditions Non-Functional Basic flow for restoring the machine settings 1. select the saved machine settings to be restored 2. LLRF Applications disable the feedback feed forward for safety 3. LLRF Applications compare the current settings and the settings to be restored, and only change the different items of the current system settings. (Please note the sequence of the restore, the feed forward and feedback enable signal should be restored at last!) 4. confirm the machine restore from the display of GUI The use case can also be started by the LLRF Applications and Client Applications In Step 1 of basic flow for restoring the machine settings, if the saved machine settings selected by the is too old, generate warning to the In Step 3 of basic flow for restoring the machine settings, if there is failure to restore the machine settings, undo all the changes which have been done and generate alarm to the The machine settings (mainly for LLRF settings) are saved or restored Save the machine settings before doing calibrations or machine studies and restore the settings afterward Save the machine settings that make the system work well for some conditions as references [Efficiency :: Time Behavior] The machine restore should be finished within 10 s TBD LLRF_UC17: Check/set the timing of klystron, LLRF and other components LLRF_UC17 Check/set the timing of klystron, LLRF and other components Basic Check and set the timing relations between klystron pulse, RF pulse and beam. The timings should be consistent, such as the RF pulse should be located at the middle of the klystron high voltage pulse for best phase flatness; the beam should be located around the middle of the RF pulse flattop to avoid the influence by the overshot and rings of the RF pulse rising edge, see the figure below

25 Software Specification for LLRF Applications at FLASH Page 22 If the bunch train is short, put the beam around the middle of the RF flattop! (Proposed by Christian Schmidt) Basic Flow Alternative Exceptions Post-conditions Non-Functional Measurement of the klystron high voltage pulse is available Measurement of the klystron RF output is available Timing settings is available Only authorized can perform the operation Setting of the timing should be done by hand, no automation is needed Basic flow for checking the timing automatically 1. LLRF Applications measure the phase difference between the klystron output and DAC output during the start up (first 200 μs) of the RF pulse, if the phase difference changes larger than the defined threshold, the RF pulse timing may be too early 2. LLRF Applications measure the beam transient on the RF pulse to check the beam timing 3. LLRF Applications report the abnormal timing to the FLASH Operators and TBD TBD The timing relations between klystron, RF pulse and other components are properly set Set the timing when system start up TBD Provide GUI to display the waveforms of klystron high voltage, klystron RF pulse, cavity RF pulse and beam pulse to reflect their timing relations LLRF_UC18: Support the beam based feedback (To be decided with Hoger) LLRF_UC18 Support the beam based feedback Basic

26 Software Specification for LLRF Applications at FLASH Page 23 LLR F Experts Pre-con ditions Basic Flow 1. Alternative Exceptions Post-conditions Non-Functional 5. Other 5.1 Additional Functional Here list the functional requirements to the LLRF Applications at FLASH that is not suitable to be presented as use cases. The requirements here together with the use cases describe the functions that the LLRF Applications should provide. FUN_REQ01: LLRF Applications should provide slow feedback to correct the phase and gain drift of the high power chain FUN_REQ02: LLRF Applications should provide operation mode to bypass the exceptions in the use cases (for most exceptions, the use cases will be stopped, see the use case description in Chapter 4, this is to enable the to perform the use cases even some exceptions happen for some special test, but BE CAREFULL, IT IS DANGER!) 5.2 Additional Non-Functional Here list the non-functional requirements to the LLRF Applications at FLASH additional to the non-functional requirements presented in each use case. NFUN_REQ01: [Usability :: Understandability] Provide manual and online help to the use cases, and training to the users. The results under deferent input should be understood by the users NFUN_REQ02: [Usability :: Operability] Provide error message to guide the user to recover the mistakes; provide simple, clear and self described GUI NFUN_REQ03: [Maintainability :: Analyzability] Provide activity logging to the use cases, should be able to analyze the failure time and failure source NFUN_REQ04: [Maintainability :: Testability] The use case should be able to be tested with build-in test module, and the test results should be displayed completely

27 Software Specification for LLRF Applications at FLASH Page External Here list the requirements to the external systems from the LLRF Applications. EXT_REQ01: [to Control System] Provide database for firmware and run-time parameters management EXT_REQ02: [to Control System] Provide name service, when one application is moved to another location, other applications that use its data should not need to be changed in source code (use an address configuration file is alternative solution!) EXT_REQ03: [to Accelerating Module] Provide limitations and characteristics of the motor frequency tuner EXT_REQ04: [to Accelerating Module] Provide quench limitations in gradient for each cavity EXT_REQ05: [to High Power RF System] Provide saturation curve of the input/output power for each klystron under different high voltage settings EXT_REQ06: [to High Power RF System] Provide klystron high voltage and peak power information through DOOCS EXT_REQ07: [to Beam Diagnostic System] Provide calibrated toroid data for each pulse through DOOCS EXT_REQ08: [to Beam Diagnostic System] Provide beam current measurement results through DOOCS EXT_REQ09: [to Machine Interlock System] Provide beam inhibition signal to LLRF through physical links EXT_REQ10: [to LLRF Field Controller] Insert loop phase and loop gain correction module in both driving chain and measurement chain EXT_REQ11: [to LLRF Field Controller] Provide exception handling for adaptive feed forward in case of beam inhibition interlocks 7. Glossary FLASH Operators: the operators of the FLASH accelerators except the LLRF experts : the persons from LLRF group involved in daily operation of FLASH, or perform maintenance of the LLRF system and machine studies Client Applications: software running in clients, mainly written in matlab has three level: 1. Basic necessary for FLASH commissioning 2. Advanced essential for FLASH operation 3. Nice to Have can be worked out later, if manpower and resources permit 8. To Be Determined List