Solaris Project Document No.
CS-003
Control Group
Solaris Project Document No.
Version no.
Created: 14.06.2012
CS- 003
1.0
Modified: 14.06.2012
The Virtual Accelerator for the Tango CS
Abstract
This document is due to updates. Please contact the authors, or check the Alfresco for the
most recent revision.
Prepared by:
P. Goryl
Checked by:
Authorship:
P. Goryl
Distribution list:
Approved by:
Solaris Project Document No.
Record of Changes
Rev. No.
Data
Pages
Descriptions of changes
CS-003
Solaris Project Document No.
CS-003
Table of Contents
Introduction............................................................................................................................................. 4
The Model Server ................................................................................................................................ 5
2.1.
The ModelServer usage ....................................................................................................... 5
2.2.
The ModelServer deployment ............................................................................................. 6
2.3. The ModelServer device properties ........................................................................................ 8
The Online Model ................................................................................................................................ 9
simple-tango ...................................................................................................................................... 10
4.1.
Reading attributes’ values ................................................................................................. 10
4.2.
Writing attributes’ values .................................................................................................. 10
4.3.
Calling command ............................................................................................................... 11
4.4.
Installing simple-tango ...................................................................................................... 11
tango2elegant ................................................................................................................................... 12
5.1.
Installing tango2elegant .................................................................................................... 12
5.2.
Usage of tango2elegant..................................................................................................... 12
5.3.
The elegant input file processing ...................................................................................... 12
Solaris Project Document No.
CS-003
Introduction
The Tango control system implements an objective approach to interface controlled devices. It
provides an interface giving an access to so called attributes, representing PVs or state values and to
commands representing operations one can invoke on a particular device. Each device is in fact
represented as an object of a certain class as it is in Object Oriented Programming (OOP).
The OOP introduce a mechanism called the polymorphism. This provides a way to abstract from what
is behind an interface. As an example, all power supplies integrated in a control system (cs) could
expose the same interface to users regardless of a fieldbus the cs is using for communicate with a
particular equipment. This also means that it is possible to use the same interface to a model of a
controlled system as to the real one. With some assumptions actors interacting with the cs will not
be able to distinguish if they work with a real or a modeled system.
The Virtual Accelerator is a concept of integrating and interfacing different simulation and/or
computation codes into the control system. Implementation of the Virtual Accelerator for the Tango
CS has the following goals:

Standardize a way to starting and stopping computations from the control system

Simplify data exchange between the control system and the simulation code

Provides a standard interfaces to different kind of equipment (classes of devices)

Provides central point for storing the calculated machine parameters within the control
system architecture thus making these directly available for all control system applications
All above take advantages of the existing tools of the control system. The integration could improve
the system diagnostic as well as simplify applying to the machine a calculated machine’s parameters
like operating points. Making the model being available through the control system will enable online
comparison of the real machine with the virtual one. Providing a way of distributing machine’s
parameters through the Tango control system will prevent from clutter caused by usage of different
data exchange protocols.
The Virtual Accelerator for the Tango Project provides the following components:



The ModelServer device class and server. It is a device that standardizes and simplifies
invoking of computation from the Tango cs.
The simple-tango API. This is C/C++ library enabling an access to Tango cs in ‘one line in code’
hiding all Tango complexity and providing seamless typecasting of Tango data types into
standard C types.
The tango2elegant script interfacing the Elegant tool with the Tango
Solaris Project Document No.
CS-003
The Model Server
The Model Server is a tool to run the simulation inside the control system. This project implements
this as a tango device of the class ModelServer.
The ModelServer device enables to run any arbitrary program, script or operating system command.
All what is supposed to be run is called a Job. ModelServer device is an interface to run and control
Jobs.
Each Job has its name and a defined disk location. Due to security reasons all executable for Jobs
should be placed in and run from a disk folder specified by the JobsPath device property (see below).
The same reason is for that the jobs are executed with a system credentials provided by the
SystemUser and the SystemGroup properties. Details on how to deploy and configure the
ModelServer are embraced later in this section.
2.1. The ModelServer usage
Let assume that the system user that is running jobs is a jobuser. His home folder is /home/jobuser .
There is a folder for keeping jobs: /home/jobuser/jobs. The file structure may look like this:
/home/jobuser/jobs/
#folder for jobs
/home/jobuser/jobs/m4-cod/
#a m4-cod job
/home/jobuser/jobs/m4-cod/init
#initialization script for the m4-cod
/home/jobuser/jobs/m4-cod/m4-cod
#executable to run this job
/home/jobuser/jobs/m4-cod/m4-cod.cc
/home/jobuser/jobs/m4-spf/ a m4-spf job
/home/jobuser/jobs/m4-spf/files/
#files used by the m4-spf job
/home/jobuser/jobs/m4-spf/files/in/
/home/jobuser/jobs/m4-spf/files/in/m4lin.lat #some file used by the job
/home/jobuser/jobs/m4-spf/files/in/m4li.w
#some file used by the
job
/home/jobuser/jobs/m4-spf/files/out/
#some folder to be used by the job
/home/jobuser/jobs/m4-spf/m4-spf
#script that do the m4-spf job
/home/jobuser/jobs/lattice.lat
# lattice file to be provided to jobs
The ModelServer provides four main commands related to starting simulations:




On(string job_name) – to init a job job_name.
Off() – to clean after a job
Start(int no_iterations) – to start an initiated job for no_iterations iterations. If no_iterations
is -1 it runs infinitive loop.
Stop(bool kill) – stop executing the job. The parameter kill states weather to wait for current
iteration to finish or to kill the job process.
Solaris Project Document No.
CS-003
2.2. The ModelServer deployment
Assumptions






To run the ModelServer device server you need a working installation of the Tango CS,
PyTango and Fandango.
The operating system should have sudo tool installed to let ModelServer run a job as a
different user
System user for running Jobs is named jobuser, its primary group is jobuser and home folder
/home/jobuser – adjust it to meet your environment
User who run ModeServer device server is tangosys and its main group is tangosys – adjust
it to meet your settings
ModelServer device will have name virt/models/maxiv
Job name is m4-cod
Following steps let you run a ModelServer:



If a user jobuser does not exist on your system create it
In the jobuser’s home directory create a folder for keeping Jobs. Let name it jobs.
Enable tangosys user (thus ModelServer device) run jobs. To achieve this modify file
/etc/sudoers adding a line:
tangosys
ALL=(jobuser:tangosys) NOPASSWD: ALL
# The above line enable run any commands that jobuser could run with
# credentials (jobuser:tangosys) without providing password

Download ModelServer device server from SVN repository.
svn co \
https://goryl.cps.uj.edu.pl/svn/projects/VirtualAccelerator/ModelServer/

Go to the downloaded folder
cd ModelServer

Install Model server, using easy_install
easy_install


.
Now you could start device server from a command line or using the Astor. For details howto start a device server look into the Tango manual.
Use the following properties to configure the device:
Property name
Value
jobuser
JobSystemUser
JobSystemGroup
tangosys
JobsPath
/home/jobuser/jobs
LatticeFileName
lattice.lte
OmmitLatticeFileName
False
JobStarterCommand
sudo –H –u $RUN_AS_USER –g $RUN_AS_GROUP
Solaris Project Document No.
JobKillerCommand

CS-003
sudo –H –u $KILL_AS_USER kill -9 $KILL_AS_PROCESS
Make in the home folder a folder for jobs:
mkdir /home/jobuser/jobs


Upload your lattice file into /home/jobusr/jobs
Upload your jobs to this folder as subfolders.
Running a model

Start the AtkPanel for your configured ModelServer device:
AtkPanel virt/models/maxiv

Invoke command On providing as a parameter m4-cod
o This will initialize the m4-cod job. If it finds the
executable
file
/home/jobuser/jobs/m4-cod/init
it
will
run it.

Now, to start a model use a command Start providing it with an argument denoting number
of iteration to be done. Providing value -1 will make an infinity loop.
o For each iteration it will run a file /home/jobuser/jobs/m4-cod/m4-cod

Solaris Project Document No.
CS-003
2.3. The ModelServer device properties
Property
Example value
Description
JobsPath
/home/jobuser/jobs
Path to the folder where jobs are stored
JobSystemGroup
Tangosys
System group upon which jobs will be runned. It should be the same
as the device server’s one to let it control the job execution.
JobSystemUser
Jobuser
System user upon which jobs will be runned.
LatticeFileName
lattice.lat
Lattice file name to be provided to a job. You should upload this file to
folder specified in the JobsPath property.
OmmitLaticeFileExtension
True
State if the job will be provided with the file name without its
extension. Useful for tracy.
DynamicAttributes
Optional. Dynamic attributes that will be created for this device. Since
the job will be provided with the ModelServer device name it could
use this attributes as input or output. Format of this property is the
same as for PySimulator.
DefaultJob
Optional. It states the name of job to be initialized by default when
device is run.
JobKillerCommand
sudo
–H
–u
$KILL_AS_USER
kill -9 $KILL_AS_PROCESS
Command called to kill the job process. Enviromental variables
available:
$KILL_AS_USER is set to a value of the JobSystemUser property
$KILL_AS_PROCESS is set to a PID number of th job process to be
killed
JobStarterCommand
sudo –H –u $RUN_AS_USER –g
Command called to start a job. Job name is added as the last
$RUN_AS_GROUP
argument. Enviromental variables available:
$RUN_AS_USER is set to a value of the JobSystemUser property
$RUN_AS_GROUP is set to a value of the JobSystemGroup property
Solaris Project Document No.
CS-003
The Online Model
The online model is a model available through the control system. It could be a simulation of the
machine as well as a computation job to calculate some machine properties or parameters to be
used by the rest of the control system (i.e. orbit correction). In this project, the online model is
realized with the ModelServer running a job in the loop. Typical job for providing the online model
consists of two modules:
1) The init script for preparation to the job. It is executed once when the job is switched on
by the ModelServer device’s On command. It is an executable with name “init” or
“init.py” located in the job’s folder.
2) The exact job doing useful computations. It is run repeatedly by the ModelServer. It is an
executable named as the name of job. Typically, it is acting like the following:
a. Do some “per iteration” initialization – for example read the lattice file
b. Read required values from the control system
c. Apply the values to the model
d. Do the computation
e. Read results from the model
f. Poke the results to the control system
Example:
If we have the property JobsPath set to “/home/jobuser/jobs” and consider a job named “m4-cod”,
we could end up with files like this for the m4-cod job:

/home/jobuser/jobs/
 m4-cod/
 init
 m4-cod
 m4-cod.cc
where:
 init – is a scritp that starts a compilation of m4-cod.cc
 m4-cod – is an executable produced by the compilation
 m4-cod.cc – is the source file.
Of course, it is possible to omit the init phase. If there is no file called init or init.py in the job’s folder
the ModelServer device will not call it. It is also ok to put a job already compiled into the job’s folder.
Solaris Project Document No.
CS-003
simple-tango
Simple-tango is a C/C++ library that simplifies access to the Tango control system from within the
program. It is a set of functions for reading and writing devices’ attributes using standard C/C++ data
types. The library provides proper type casting doing real conversion form Tango datatypes to
standard C/C++ types like double or long. It hides most of the Tango complexity (even it is not very
complex) from the code’s writer. It is not intended to replace the Tango API. For some complex usage,
one will need to use the Tango API anyway.
Simple-tango provides two header files: stango.h, stangoimpl.h and library libstango.so, which you
have to use for linking (i.e. gcc option -lstango).
The stango.h contains main simple-tango API and it is the one you should use with pure C programs.
In C++ code you can use the stangoimpl.h that provides generic functions. Not described here. Please
look into its contents.
Below the API provided by stango.h is described:
4.1. Reading attributes’ values
For value reading use the following functions

int tango_read_scalar_{type}(char *_deviceName, char *_attributeName,
{type} *_value);
 int
tango_read_spectrum_{type}(char
*_deviceName,
char
*_attributeName, {type} *_value, unsigned int *_size);
 int tango_read_image_{type}(char *_deviceName, char *_attributeName,
{type} *_value, unsigned int *_dimX, unsigned int *_dimY);
where:






{type} is one of: double, float, short, unsigned short, int,
unsigned int,
_deviceName is the name of the device to access
_attributeName is the name of the attribute
_value is a pointer to a buffer where the red value should be
stored
_size, _dimX, _dimY are pointers to values stating the size of the
provided _value buffer. Upon function return these will be filled
with the actual sizes (the sizes really written to _value). If
_value==NULL, the *_size, *_dimX, *_dimY will contains information
that could be used to allocate memory.
Return 0 if there is no error and -1 if there is an error during
reading. The error description is sent to stderr.
4.2. Writing attributes’ values
For value writing use the function like the following:
Solaris Project Document No.
CS-003

int tango_write_scalar_{type}(char *_deviceName, char *_attributeName,
{type} _value);
 int
tango_write_spectrum_{type}(char
*_deviceName,
char
*_attributeName, {type} *_value, unsigned int _size);
 int tango_write_image_{type}(char *_deviceName, char *_attributeName,
{type} *_value, unsigned int _dimX, unsigned int _dimY);
where:






{type} is one of: double, float, short, unsigned short, int,
unsigned int,
_deviceName is the name of the device to access
_attributeName is the name of the attribute
_value is a value (for the scalar) or a pointer (for the spectrum
or the image) with data
_size, _dimX, _dimY denotes size of the provided _value buffer.
Return 0 if there is no error and -1 if there is an error during
reading. The error description is sent to stderr.
4.3. Calling command
You can also call argument-less commands using the simple-tango:
int tango_run_command(const char *_deviceName, const char *_command);
4.4. Installing simple-tango
To install the simple-tango you need to have the Tango installed first. See www.tango-controls.org.
Then you have to download and compile source:

Download the simple-tango from the SVN repository.
svn co \
https://goryl.cps.uj.edu.pl/svn/projects/VirtualAccelerator/simple-tango/
 Go to the downloaded folder
cd simple-tango
 Adjust the Makefile to conform your environment if necessary.
 Compile:
make
 Install (You need to be a root user to do this, usually.):
make install
Solaris Project Document No.
CS-003
tango2elegant
The tango2elegant is a program that reads the Elegant input file and parse it to find tango related
commands (&tango_input, &tango_output, see below). It processes these and then filters out to
provide the elegant with modified file.
5.1. Installing tango2elegant
To install the tango2elegant you need to have the SDDS tools installed along with its Python library.
See SDDS documentation. Then you should follow steps:

Download the tango2elegant from the SVN repository:
svn co \
https://goryl.cps.uj.edu.pl/svn/projects/VirtualAccelerator/tango2elegant/
 Go to the downloaded folder
cd tango2elegant
 Install Model server, using easy_install
easy_install .
And now, tango2elegant is installed
5.2. Usage of tango2elegant
There are two methods of calling the tango2elegant:
 Providing the tango2elegant with an input file and piping the output to the elegant:
tango2elegant input.ele | elegant –pipe=in,out

Providing an input file name and an output file name. Then calling the Elegant against the
output file. This may be the only possibility for the pelegant, to ensure that the output is
processed after the results are valid.
tango2elegant
–-no-tango-out
input.ele
tmp.ele
#this
process
only
&tango_input
pelegant tmp.ele
tango2elegant --no-tango-in input.ele #this process only &tango_output
5.3. Processing of the elegant input file
The tango2elegant is used with an elegant input file that contains additional commands:
 &tango_input – to let modify the lattice according to control system
 &tango_output – to modify values in control system according to output file
 &tango_global_subst – to set global substitutions parameters
The file is read line by line and parsed. If one of these commands is found it is processed. If not, the
line is sent to the output file or piped to elegant.
Solaris Project Document No.
CS-003
Additionally it could substitute the values in commands when entered as %subst_name%
(substitution name between the percent signs).
5.3.1. &tango_input command
In &tango_input the additional commands (&alter_elements, or other required) are created by
tango2elegant. So, it is only necessary to add &tango_input commands and then tango2elegant will
generate necessary commands according to the input from the control system.
This command is defined as the following:
&tango_input
STRING tango_device or tango_path = NULL;
STRING tango_attribute = NULL;
long tango_index
= NULL;
STRING command_name = &alter_elements;
STRING tango_input_mode = [one | spectrum];
other parameters to be passed to generated command(s), for example: element,
item, start_occurence, end_occurence, value
&end
Where:
 tango_device or tango_path - The tango device name
 tango_attribute – The name of the attribute to be used as a source of the value
 tango_index – The index in used with a Tango spectrum attribute when the input_mode is set to one, see
below.
 command_name - The name of the elegant command(s) to be generated
 input_mode - The input processing mode:
 one - will generate only one command
 spectrum - will generate list of commands, each for one element of a provided spectrum attribute
In this command the following substitution strings can be used:
 %device% - the device name actually processed
 %attribute% - the current attribute processed. Useful with element and/or item when in tree or device
mode. See the input_mode, above.
 %index% - the current index in the spectrum attribute
 %index+1% - the current index plus 1 in the spectrum attribute. Since the Tango spectrum is indexed from 0
but the elegant elements from 1 it could be used for the start_occurence and end_occurence
 %value% - the current value read from the control system (the attribute value)
5.3.2. &tango_output command
This command read the specified SDDS file and set the Tango attribute(s) value(s).
&tango_output
STRING tango_device or tango_path = NULL;
STRING tango_attribute = NULL;
long tango_index = NULL;
STRING tango_output_mode = [one | spectrum];
Solaris Project Document No.
CS-003
STRING file = NONE;
long page = 0;
STRING column = NULL;
STRING element_name = NULL;
STRING element_type = NULL;
long start_occurence = -1;
long end_occurence = -1;
STRING parameter = NULL;
STRING element_column = ElementName;
STRING occurrence_column = Occurrence;
STRING type_column = ElementType;
&end
Where:








tango_path or tango_device – The device(s) to be modified
tango_attribute – The attribute(s) to be modified
tango_output_mode – The way of processing
file – The name of an output sdds elegant file to use
page – The page in the sdds file
element_name – The element selection by its name
element_type – The element selection by its type
start_occurence, end_occurence – The indexes to select values for a spectrum attribute