Power converter control software

2024-12-20

The magnet power converters at the test station are controlled by a software package, which enables the user to steer it by:

• configuring the parameters of the load of the power converter
• its setup information describing the gain factors and other internal parameters
• and then to configure the ramp it should do.
• Then the power converter is commanded to execute the ramp.

The details of this interface are given in 20kAPowerSupplyEnglish. This document here focuses on describing what the software has to do, to control the power converter and the organisation of the software itself.

Excursus: A small description of the power converter functionality

Current control

Here only the part is covered which is necessary for understanding the functioning of the software. Further details can be obtained by the BELab or power converter group. The power converters considered here are current controlled and the voltage is pre-steered. This means that

• The power converter regulation loop will follow the reference value
• To limit the regulation range it as to cover, a second reference value is given, which describes the voltage that the power converter will roughly need to drive the given load.

This approach lowers the total regulation band the regulation loop has to cover.

Function generator

The power converter contains 1 or 2 function generators in its control unit called (ACU). The software described here will always addresses both function generators.The first function generator is used to generate the reference value of the current, while the second one is used to generate a reference value for the voltage presteering.

These are rather straight forward in their implementation.

• The function generator is given some start value
• Then it gets increments, which it will add to its start value internally data_point_count times.
• The internal value is the reference value for the power converter, which it will try to follow.
• During the time it adds up data_point_count times, it must receive the next increment.
• If the increment is not received it will stop operation

So the function generator will only make linear ramps. The steepness of the ramps can be changed accordingly by using appropriate increments. The task of the software is thus to:

• parameterise the power converter's function generators
• check the start value using the power converter's ADC's and
• check that the ramp specified by the user is followed within certain limits reading back the ADC's.

Please be aware, that the interface of the software to the power converter are

• 32 bit integers for the set values
• 16 bit integers for the increments and
• 16 bit integers for the actual value

This implies that the software has to convert physical parameters to appropriate integers. This is realised using the configuration parameters.

The software has no access to the value the power converter uses for displaying the current on the ACU. Misconfiguration will still allow ramping the power converter, but it can act totally inconsistently for the user.

Some points were omitted above to aid the understanding. So now a more detailed explanation process follows. When the function generator is initialised it requires

• To be set to some start value
• How often to repeat the increments. The software package here only uses 256 repetitions. Other descriptions at GSI call that parameter data_point_count.
• It requires to be told at which frequency to execute the function generator (16 kHz, 32 kHz, 64 kHz, 128 kHz, 256 kHz, 512 kHz)
• They are initialised to some set value. The power converter will immediately set the output to this value! ​Therefore the software should check the status of the power converter.
• Then when the ramp should start, a broadcast command is set to both function generators to tell them that these should start to ramp.
• As long as the increments are timely supplied the function generators are incrementing it status.
• These are handed over directly to the power converter output. Be aware that the ADC, which to power converter uses in its control loop is acurrate to 16 --18 bits.
• The function generators stop if they do not receive the increments timely.
• It is best praxis to supply them with an increment of zero when the ramp stops

Hardware package

Within a power converter a SCU and a ACU (XXX) is installed next to all outer power converter equipment.

• SCU: The SCU is a linux computer, which boots over the network,. This is the standard controller which is foreseen for controlling power converters etc. for the FAIR machines. This is supplied by the BELab.
• ACU: This is the control unit of the power converter. This is supplied by the power converter group.

Software package structure

The power converter control software is split up in the following packages:

• The fmtlib library, which wraps C-library functions,
• The power converter program. It is split up in * Libraries which abstract the hardware access and a library to generate the required ramp values. * The main program, which is started from the command line. It will initialise the memory, execute the relevant hardware initialisation. If requested it will open a server or execute the ramp defined on the command line. For details on the server interface or the command line see 20kAPowerSupplyEnglish.

The software package is described in detail below.

fmtlib library

Convention

The fmtlib library wraps standard c library functions and provides some simple tools. It builds on a consistent API.

• It is implemented in C
• Its return value is typically an integer and reports the error status
  • FMT_SUCCESS no error
  • negative values: These are considered to typically reported to the user, but can be ignored: e.g. power converter does not need to execute a ramp
  • positive values: These are considered as more serve ones.
• Input arguments come first, while output arguments make the end
• Objects are implemented as c - structure with access methods.
  • The object (c++ "this-pointer", python "self" variable) is the first argument.
  • The structure of the object is not allocated. A method is provided which will initialise a provided structure. This permits the user to combine different objects in a common structure.

The fmtlib library contains the following packages:

• utils: provides wrappers over various functions for converting strings to double and long, environement variable access, select, atexit, memory lock
• signals: simplifed unix signal interface, which is sufficient for the intended power converter. It provides a simple function, which stores the send signal in a static variable and a function to poll this variable.
• some math functions: interpolation, solving quadratic equations, linear, quadratic and cubic interpolation
• a network handler: allows opening a single port and reading and writing to this port. It will automatically close the network connection, when the program is closed. (it uses atexit).
• parser: provides definitions to set up a tree of nodes. Each node can contain get and set callbacks.
• priority: sets the real time scheduler and provides two priority levels: the standard operation level (0 on rt linux) and a measurment operation level (typically 49 or 99 on realtime unix). It stores these levels in global variables. The modes are then set using the functions fmt_measurement_priority and fmt_normal_priority
• server: allows opening a single port. It will wait for commands. The protocol is described in 20kAPowerSupplyEnglish.
• simple integer matrix access:
  • block data: safe access to matrix elements
  • ring buffer: wraps over to row 0 after all rows are filled
  • mask data: provides a vector of integers. It provides a set method which will check if the value is still zero.
• timer object: A maximum time span can be defined. Then one can check if the timeout was already reached.
  • The timer object itself does is ment to be implemented using some hardware timer
  • posix_timer is such an implementation. It uses clock_get_time_absolute wrapped in rt_clock_linux  * rt_clock_linux wrapper for the clock_nanosleep function calls.

Tree structure

Configuration directory config/ :

configuration files for the build process. For the different configuration targets configuration files exist. The file default.cfg should be linked to the target build for (here linux.cfg). In this file the c-compiler, c++-compiler, linker and their flags are defined.

The following extra files are found there:

• host.cfg standard posix command line tools. Normally editing this file should not be necessary.
• arch.cfg determines the architecture name using uname as output. Normally this file does not need to be edited on posix systems.
• libinfo.cfg variables defining the library target names

Include directory:

The include directory only includes a single entry: the directory fmt. All header files exporting functions of the library are collected in this directory. These files should be included using the fmt/ prefix e.g. the miscancelllous utilities as

 <fmt/util.h> 

The lib directory:

The source files are collected in the sub directory src. The default build process will build the object files in a separate directory. Make should be started in the lib directory. First execute

$ make archmake

This will create the architecture and processor dependant directory. The target library name contains the name of the architecture and of the processor. It is given by $LIBRARY variable. The default.cfg file provides this information. Programs using the library should include default.cfg in the build process.

The test directory

Many different simple command test line programs exist which allow testing the different library functions. These are found in the test directory. Their sources are found in the subdirectory src. The test programs are built in the architecture/processor directory.

Comments to some objects

Net state

Net state allows collecting input from the network in a buffer reading speficing a timeout. Furthermore it handles accepting a client, or reacting to a disconnect from the client side. It is used by the server. fmt_net_state_iterate should be called iteratively.

Server

The server accepts commands which are similiar to xml from the network and processes them. A user_server_t object is linked to the server during initialisation. This allows reusing the server for different applications. The user server has to implement different call backs. Please consult the user_server_t description in fmt/server.h. The server can poll the network and acquire the commands, while evaluating the user check function during the time it is waiting for the network.

Power converter software

The power converter software splits in libraries as described below and the main program. Furthermore simple test programs for testing various aspects are found in the test_acu directory.

Tree structure

• Libraries
  • The libraries include files are found in the directory include.
  • The libraries source files are found in the directory lib.
  • Each library consists of two parts. One directory is found in the lib, while an other directory is found in the include directory.
  • The functionality of some module (e.g. function generator card) is split over two files. The name of one of the files contains the part loop in it. This part is considered as used by the real time part of the power converter code. The build process will put these in a dedicated library. The linker of the main program is first given the files describing the real time part and then the non realtime part.
• Tests: test programs are found in the directory test_acu
• Main program: the main program files are found in the directory pc

Libraries

• ramp generator: This packages implements a ramp generator, which calculates a ramp with a constant ramp rate and provides an object which will deliver the required increments of current and voltage to feed to the power converter.
• pcimil: This package contains type definitions for various. It ows its names to historical heritage.
• bel_hw: This package handles the function generators and exposes a interface in physical constants (SI units). Originally these were implemented as dedicated hardware cards supplied by the BELab (BEschleuniger Labor). Now these function generators are implemented in the FPGA found in the ACU.
  • The integer access to the function generator is handled in the function_generator_card_* files. This includes serving the function generator and book keeping of the state it was set to. It also provides a function to serve two generators with two increment values.
  • Interface using physical parameters as double values and book keeping of the internal value of the function generator are found in the function_generator_* files (without the files containing "card" in them).
• acu: This package abstracts the interface to the SCU. This package should be obsolete.
• scu: This packages contains wrapprers for the C++ classes of libfesl which are required to access the required SCU and ACU parts.

Ramp generator

The ramp generator currently only implements a linear curent ramp. It uses the standard inductance model is described in 20kAPowerSupplyEnglish. This part assumes that at the start and the end of the ramp dI/dt = 0. Furthermore it assumes that the current ramp has to be increased in a continuous function from 0 to the requested ramp rate (rounding part).

It consists of:

• load description: set/get methods for the load description members. Furthermore it calculates the maximum voltage that has to be supplied on the ramp
• calculate round ramp: using the different configuration parameters it calculates the start of the ramp, the end of the ramp and the ramp rate. The interpolation coefficients are stored in round_ramp_values_t.
• follow round ramp: The ramp is assumed to start at t=0. With t equal to the current time the next current to execute will be returned. The power converter main program uses the methods:
  • total steps: how many steps have to be executed?
  • step start: initalises the internal stepper
  • step next: retrieves the next current to ramp to. Internally it evaluates which part (ramp from 0 to target current, linear part, or end ramp part) are to be used.
  • In case of failure step_stop is executed: if this called values will be provided so that dI/dt is continuously changed to 0.

Two test programs are in the tests/ directory: load_test and round_ramp_test

Main program

The main program initialises itself.

1. At first all memory is claimed and locked into memory
2. Signal handlers set (see fmtlib signals)
3. Error handler is installed
4. Environment variables are read and the hardware is initialised. All required environment variables must be defined.
5. Then the command lines options are evaluated.
6. Depending on the command line options it will open a server or execute the commands given on the command line. See 20kAPowerSupplyEnglish for details on the command line options.

In the following text the suffix of the file name is omitted if both the header and source file are.

The power converter program contains a failure mode: This will read the actual status of the power converter (i.e the current it operates on the load) and then run the power converter down slowly slowly decrementing the set value of the function generators. Any not handled error within the power converter program will trigger the failure mode. It is implemented in the files power_converter_failure.h and power_converter_failure.c. failure_stop_calculate_delay must be called in the beginning of the main program (and it is called). It will calculate the appropriate delay to wait for before the next set is to be made.The function failure_stop then executes the failure run down carefully avoiding not to use not initialised function generators.

A large part of the main program is dedicated to executing ramps:

• power_converter_ramp_loop ramp from one current to the next current. During this operation the ramp values are calculated using the ramp_generator library. Then the ramp is executed by the function power_converter_ramp_to_value_round. The individual steps are made by power_converter_ramp_to_value_linear. When this function returns the power converter shall have reached the final current value. If not it should return an error. Typically (or even most probably) the power converter must be sent to failure state. This is not a safety function. Safety must be provided by the power converter or additional hardware e.g. quench detection magnet protection. During the ramps the actual value of the current is read back. It is checked if it matches the set value within limits. If not the power converter will enter error mode. Then it tries to finish the ramp adding a round so that the ramp rate is decreased within normal limits. Then it will finish the ramp.
• power_converter_cycle The function power_converter_cycleis the typical entry point. It will execute the cycles given by the user (stored in the ramp data).
  • Each cycle is handled by _power_converter_single_cycle_round. This function handles:
  • It waits for the start trigger if required.
  • Then it executes the request ramp step by step:
  • It checks if the user required a delay. If so it will wait for the specified time.
  • It will check if the requested start and end current justify a ramp: i.e the values are so close that they can not be resolved by the ADC. Currently a minimum of 1 bit of a 16 bit ADC is deemed as a minimum step. 16/2 bits are equivalent to the maximum current that is set for the ADC
  • For each step this function will put the proper data into the data structure required for the round ramps. It writes the ramp rate, date etc to the SCU display. It will calculate the round ramp parameters using calculate_round_ramp of the ramp_generator library. Furthermore it will set the function generators to the appropriate frequency. Then it calculates the integer values for the given following limits. This is required as the same integer increment values yield different ramp rates for the different function generator frequencies. The same applies to the maximum allowed ramp rates. These integer values are then used during the ramp to see if the "measured ramp value" are within the boundaries.
  • At the end of the ramp it checks if the power converter reached the demanded current
• power_converter_ramp Provides the memory for the required objects, sets the pointers in the structure and so forth. It also provides set/get methods for different members of the power_converter_ramp structure.

The remaining files provide:

• power_converter.c contains the main program and handles log file generation. Log files are written when the power converter program stops
• ui.c command line arguments (uses getopt)
• pc_server implements callbacks etc. so that the server provided by the fmtlib can be used for the power converter. The required parser tree is defined in pc_server_parser_tree.c
• power_converter_failure Handles the run down of the power converter using only the set values of the function generators. In a first step it reads back the status of the power converter using the actual status and then slowly running down the powerconverter setting smaller and smaller set values.
• power_converter_timer object for using the timer on the SCU hardware to detect timeouts. Not used in the current code as it blocks the bus so much that the OS will starve.
• power_converter_trigger_lines wrapper for the different lemo inputs on the SCU

Missing hardware implementation

Currently the actual value of the voltage can not be read back.

A short historical description

Details of the power converter control units by power converter group.

The code is based on information of belab members. It is based on code of Martin Kumm, Marcus Zweig, Matthias Wiebel, Nikolaus Kurz. It was first made to control the hardware function generator cards, which were connected using GSI milbus. The hardware was a x86 pc running LynxOS. It used the pcimil card as hardware interface to the milbus.

When the power converter was upgraded from 11 kA to 20 kA an ACU was added. The communication was made using a milbus and an interface card.

The power converters at the STF were the first foreseen to be operated using a SCU.

The code shows its age as abstractions had to be added later on. Using appropriate defines a single code base could be used to provide binaries for the different hardware/OS platforms.

-- PierreSchnizer - 2016-11-04