Sardana Home Page¶

This chapter provides a quick shortcut to all windows packages which are necessary to run sardana on your windows machine

1. Install all dependencies:

   1. from Python(x,y) (by far the easiest choise)

      1. Download and install a python 2.6/2.7 compatible version of python(x,y) from here

   2. from scratch:

      1. Download and install PyQwt < 6.0 from PyQwt downdoad page

         1. Download and install compatible python from link in the same PyQwt page
         2. Download and install compatible numpy from link in the same PyQwt page.
         3. Download and install compatible PyQt from link in the same PyQwt page.

2. Download and install latest PyTango from PyTango downdoad page

3. Download and install latest taurus from Taurus downdoad page

4. Finally download and install latest sardana from Sardana downdoad page

Sometimes it is convenient to work directly from the git source without installing. To do so, you can clone sardana from our main git repository:

git clone git://git.code.sf.net/p/sardana/sardana.git sardana

And then you can directly execute sardana binaries (Pool, MacroServer, Sardana or spock from the command line):

homer@pc001:~/workspace$ cd sardana
homer@pc001:~/workspace/sardana$ scripts/Sardana

Footnotes

It is possible to separate sardana server into two different servers (in the first sardana versions, this was actually the only way start the sardana system). These servers are called Pool and MacroServer. The Pool server takes care of hardware communication and MacroServer executes procedures (macros) using a connection to Pool(s) server(s).

To start the Pool server just type in the command line:

homer@pc001:~$ Pool lab-01

The first time the server is executed, it will inform you that server lab-01 is not registered and it will offer to register it. Just answer ‘y’. This will register a new instance of Pool called lab-01 and the server will be started. You should get an output like this:

homer@pc001:~$ Pool lab-01
lab-01 does not exist. Do you wish create a new one (Y/n) ? y
DServer/Pool/Lab-01 has no event channel defined in the database - creating it

Next, start the MacroServer server in the command line:

homer@pc001:~$ MacroServer lab-01

The first time the server is executed, it will inform you that server lab-01 is not registered and it will offer to register it. Just answer ‘y’. Next, it will ask you to which Pool(s) you want your MacroServer to communicate with. Select the previously created Pool from the list, press Return once and Return again to finish with Pool selection. This will register a new instance of MacroServer called lab-01 and the server will be started. You should get an output like this:

homer@pc001:~$ MacroServer lab-01
lab-01 does not exist. Do you wish create a new one (Y/n) ?
Pool_lab-01_1 (a.k.a. Pool/lab-01/1) (running)
Please select pool to connect to (return to finish): Pool_lab-01_1
Please select pool to connect to (return to finish):
DServer/MacroServer/lab-01 has no event channel defined in the database - creating it

One of sardana’s goals is to allow you to execute procedures (what we call in sardana macros, hence from here on we will use the term macro). A macro is basically a piece of code. You can write macros using the Python language to do all sorts of things. The sky is the limit here!

Sardana comes with a catalog of macros that help users in a laboratory to run their experiments. Most of these macros involve interaction with sardana elements like motors and experimental channels. Therefore, the first step in a new sardana demo is to populate your system with some elements. Fortunately, sardana comes with a macro called sar_demo that does just that. To execute this macro just type on the command line sar_demo. You should get an output like this:

Door_lab-01_1 [1]: sar_demo

Creating controllers motctrl01, ctctrl01... [DONE]
Creating motors mot01, mot02, mot03, mot04... [DONE]
Creating measurement group mntgrp01... [DONE]

You should now have in your sardana system a set of simulated motors and counters with which you can play.

The next chapter (spock) will give you a complete overview of spock’s interface.

Sardana consists of a software library which contains sardana kernel engine, a server and a client library which allow sardana to run as a client-server based distributed control system. The communication protocols between servers and clients are plug-ins in sardana. At this time, the only implemented protocol is Tango. In earlier versions, sardana was tightly connected to Tango. This documentation, is therefore centered in the Tango server implementation. When other comunication protocols become available, the documentation will be revised.

Client applications (both GUI and CLI) can connect to the sardana server through the high level sardana client API or through the low level pure Tango channels. Client applications can be build with the purpose of operating an existing sardana server or of configuring it.

Sardana server (SDS)¶

The sardana server consists of a sardana tango device server (SDS) running a sardana kernel engine. This server runs as an OS daemon. Once configured, this server acts as a container of device objects which can be accessed by the outside world as tango device objects. Typically, a sardana server will consist of:

• a low level Pool object which manages all the server objects related to motion control and data acquisition (controllers, motors, counters, experiment channels, etc).
• a Macro Server object which manages the execution of macros (procedures) and client connection points (called doors).
• a set of low level objects (controllers, motors, counters, experiment channels, etc) controlled by the Pool object
• a set of Door objects managed by the macro server. A Door is the preferred access point from a client application to the to the sardana server

A diagram representing a sardana server with its objects

A sardana server may contain only a Pool object or a Macro Server object or both. It may NOT contain more than one Pool object or more than one Macro Server object.

If necessary, your sardana system may be splitted into two (or more) sardana servers. A common configuration is to have a sardana server with a Pool (in this case we call the server a Device Pool server) and a second server with a Macro Server (this server is called MacroServer server).

The following figures show some of the possible alternative configurations

1 - Sardana configured to be a single Pool DS (no MacroServer present)

2 - Sardana configured to be a single MacroServer DS (no Pool present)

3 - Sardana configured with a MacroServer DS connecting to an underlying Pool DS

4 - Sardana configured with a Sardna DS connecting to another underlying Pool DS

The following chapters describe each of the Sardana objects in more detail.

A macro in sardana describes a specific procedure that can be executed at any time. Macros run inside the sardana sandbox. This simply means that each time you run a macro, the system makes sure the necessary environment for it to run safely is ready.

Macros can only be written in Python. A macro can be a function or a class. In order for a function to be recognized as a macro, it must be properly labeled as a macro (this is done with a special macro decorator. Details are explaind below). In the same way, for a class to be recognized as a macro, it must inherit from a Macro super-class. Macros are case sensitive. This means that helloworld is a different macro than HelloWorld.

The choice between writing a macro function or a macro class depends not only on the type of procedure you want to write, but also (and probably, most importantly) on the type of programming you are most confortable with.

If you are a scientist, and you have a programming background on a functional language (like fortran, matlab, SPEC), then you might prefer to write macro functions. Computer scientists (young ones, specially), on the other hand, often have a background on object oriented languages (Java, C++, C#) and feel more confortable writing macro classes.

Classes tend to scale better with the size of a program or library. By writing a macro class you can benefit from all advantages of object-oriented programming. This means that, in theory:

• it would reduce the amount of code you need to write
• reduce the complexity of your code y by dividing it into small, reasonably independent and re-usable components, that talk to each other using only well-defined interfaces
• Improvement of productivity by using easily adaptable pre-defined software components

In practice, however, and specially if you don’t come from a programming background, writing classes requires a different way of thinking. It will also require you to extend your knowledge in terms of syntax of a programming language.

Furthermore, most tasks you will probably need to execute as macros, often don’t fit the class paradigm that object-oriented languages offer. If you are writing a sequencial procedure to run an experiment then you are probably better of writing a python function which does the job plain and simple.

One reason to write a macro as a class is if, for example, you want to extend the behaviour of the mv macro. In this case, probably you would want to extend the existing macro by writing your own macro class which inherits from the original macro and this way benefit from most of the functionallity already existing in the original macro.

The idea of a macro is simply a piece of Python code that can be executed from control system interface (GUI/CLI). Therefore, anything that you don’t need to be executed by the interface should NOT be a macro.

When you have a big library of functions and classes, the approach to expose them to sardana should be to first carefully decide which procedures should be invoked by a GUI/CLI (namely the name of the procedure, which parameters it should receive and if it returns any value). Then write the macro(s) which invoke the code of the original library (see Using external python libraries). Avoid the temptation to convert the functions/classes of the original library into macros because:

• This will most certainly break your code (any code that calls a function or class that has been converted to a macro will fail)
• It will excessively polute the macro list (imagine a GUI with a combo box to select which macro to execute. If you have hundreds of macros it will take forever to find the one to execute even if they are in alphabetical order)

Since macros are essencially Python code, they reside inside a Python file. In sardana, we call a Python file which contains macros a macro library.

At the time of writing, the easiest way to create a new macro is from spock (we are currently working on a macro editor GUI).

$ export EDITOR=gedit

LAB-01-D01 [1]: edmac hello_world salute
Opening salute.hello_world...
Editing...

LAB-01-D01 [1]: edmac hello_world salute
Openning salute.hello_world...
Editing...
Do you want to apply the new code on the server? [y] y

As mentioned before, macros are just simple Python functions which have been labeled as macros. In Python, these labels are called decorators. Here is the macro function version of Hello, World!:

1
2
3
4
5
6

from sardana.macroserver.macro import macro

@macro()
def hello_world(self):
    """This is a hello world macro"""
    self.output("Hello, World!")

line 1

imports the macro symbol from the sardana macro package. sardana.macroserver.macro is the package which contains most symbols you will require from sardana to write your macros.

line 3

this line decorates de following function as a macro. It is crucial to use this decorator in order for your function to be recognized by sardana as a valid macro.

line 4

this line contains the hello_world function definition. Every macro needs at least one parameter. The first parameter is the macro execution context. It is usually called self but you can name it anything. This parameter gives you access to the entire context where the macro is being run. Through it, you’ll be able to do all sorts of things, from sending text to the output to ask for motors or even execute other macros.

line 5

Documentation for this macro. You should always document your macro!

line 6

this line will print Hello, World! on your screen.

1
2
3
4
5
6
7
8
9

# mandatory first line in your code if you use Python < 3.0
from __future__ import print_function

from sardana.macroserver.macro import macro

@macro()
def hello_world(self):
    """This is an hello world macro"""
    self.print("Hello, World!")

Remeber that a macro is, for all purposes, a normal Python function. This means you CAN inside a macro write ANY valid Python code. This includes for and while loops, if ... elif ... else conditional execution, etc...

1
2
3
4
5
6
7

import numpy.fft

@macro()
def fft_my_wave(self):
    wave_device = self.getDevice("sys/tg_test/1")
    wave = wave_device.wave
    wave_fft = numpy.fft.fft(wave)

Standard Python allows you to specify parameters to a function by placing comma separated parameter names between the () in the function definition. The macro API, in adition, enforces you to specify some extra parameter information. At first, this may look like a useless complication, but you will apreciate clear benefits soon enough. Here are some of them:

• error prevention: a macro will not be allowed to run if the given parameter if of a wrong type
• CLIs like Spock will be able to offer autocomplete facilities (press <tab> and list of allowed parameters show up)
• GUIs can display list of allowed parameter values in combo boxes which gives increased usability and prevents errors
• Documentation can be generated automatically

So, here is an example on how to define a macro that needs one parameter:

@macro([["moveable", Type.Moveable, None, "moveable to get position"]])
def where_moveable(self, moveable):
    """This macro prints the current moveable position"""
    self.output("%s is now at %s", moveable.getName(), moveable.getPosition())

Here is another example on how to define a macro that needs two parameters:

• Moveable (motor, pseudo motor)
• Float (motor absolute position to go to)

1
2
3
4
5
6
7
8

from sardana.macroserver.macro import macro, Type

@macro([ ["moveable", Type.Moveable, None, "moveable to move"],
         ["position", Type.Float, None, "absolute position"] ])
def move(self, moveable, position):
    """This macro moves a moveable to the specified position"""
    moveable.move(position)
    self.output("%s is now at %s", moveable.getName(), moveable.getPosition())

The parameter information is a list of lists. Each list being a composed of four elements:

• parameter name
• parameter type
• parameter default value (None means no default value)
• parameter description

Here is a list of the most common allowed parameter types:

• Integer: an integer number
• Float: a real number
• Boolean: a boolean True or False
• String: a string
• Moveable: a moveable element (motor, pseudo-motor)
• Motor: a pure motor
• ExpChannel: an experimental channel (counter/timer, 0D, pseudo-counter, ...)
• Controller: a controller
• ControllerClass: an existing controller class plugin
• MacroCode: a macro
• MeasurementGroup: a measurement group
• Any: anything, really

The complete list of types distributed with sardana is made up by these five simple types: Integer, Float, Boolean, String, Any, plus all available sardana interfaces (Interface)

One of the most powerfull features of macros is that the entire context of sardana is at your disposal. Simply put, it means you have access to all sardana elements by means of the first parameter on your macro (you can give this parameter any name but usually, by convention it is called self).

self provides access to an extensive catalog of functions you can use in your macro to do all kinds of things. The complete catalog of functions can be found here.

Let’s say you want to write a macro that explicitly moves a known theta motor to a certain position. You could write a macro which receives the motor as parameter but that would be a little silly since you already know beforehand which motor you will move. Instead, a better solution would be to ask sardana for a motor named “theta” and use it directly. Here is how you can acomplish that:

1
2
3
4
5
6

@macro([["position", Type.Float, None, "absolute position"]])
def move_theta(self, position):
    """This macro moves theta to the specified position"""
    th = self.getMotor("th")
    th.move(position)
    self.output("Motor ended at %s", moveable.getPosition())

One of the functions of the macro decorator is to pass the knowledge of all existing macros to your macro. This way, without any special imports, your macro will know about all other macros on the system even if they have been written in other files.

Lets recreate the two previous macros (where_moveable and move) to execute two of the macros that exist in the standard macro catalog (wm and mv)

Here is the new version of where_moveable

@macro([["moveable", Type.Moveable, None, "moveable to get position"]])
def where_moveable(self, moveable):
    """This macro prints the current moveable position"""
    self.wm(moveable)

... and the new version of move

1
2
3
4
5
6

@macro([ ["moveable", Type.Moveable, None, "moveable to move"],
         ["position", Type.Float, None, "absolute position"] ])
def move(self, moveable, position):
    """This macro moves a moveable to the specified position"""
    self.mv(moveable, position)
    self.output("%s is now at %s", moveable.getName(), moveable.getPosition())

The sardana server provides a global space to store variables, called environment. The environment is a dictionary storing a value for each variable. This environment is stored persistently so if the sardana server is restarted the environment is properly restored.

Variables are case sensitive.

The value of an existing environment variable can be accessed using getEnv(). Setting the value of an environment variable is done with setEnv().

For example, we know the ascan macro increments a ScanID environment variable each time it is executed. The following example executes a scan and outputs the new ScanID value:

@macro([["moveable", Type.Moveable, None, "moveable to get position"]])
def fixed_ascan(self, moveable):
    """This does an ascan starting at 0 ending at 100, in 10 intervals
    with integration time of 0.1s"""

    self.ascan(moveable, 0, 100, 10, 0.1)
    scan_id = self.getEnv('ScanID')
    self.output("ScanID is now %d", scan_id)

The Macro API includes a set of methods that allow you to write log messages with different levels:

As you’ve seen, the special output() function has the same effect as a print statement (with slightly different arguments).

Log messages may have several destinations depending on how your sardana server is configured. At least, one destination of each log message is the client(s) (spock, GUI, other) which are connected to the server. Spock, for example, handles the log messages by printing to the console with different colours. By default, spock prints all log messages with level bigger than debug() (You can change this behaviour by typing debug on in spock). Another typical destination for log messages is a log file.

Here is an example on how to write a logging information message:

1
2
3
4
5

@macro()
def lets_log(self):
    self.info("Starting to execute %s", self.getName())
    self.output("Hello, World!")
    self.info("Finished to executing %s", self.getName())

Once the report facility has been properly configured, report messages can be sent to the previously configured report file.

There are several differences between reporting and logging. The first difference is that log messages may or may not be recorded, depending on the configured filters on the target (example: log file). A report will always be recorded.

Another difference is that report messages are not sent to the clients. The idea of a report is to silently record in a file that something as happened.

A third difference is that unlike logs, reports have no message level associated to them (actually since internally the log library is used to report messages, every report record as the predefined level INFO but this is just an implementation detail).

A report message can be emited at any time in the macro using the report() method:

@macro()
def lets_report(self):
    self.report("this is an official report of macro '%s'", self.getName())

This would generate the following report message in the report file:

INFO 2012-07-18 09:39:34,943: this is an official report of macro ‘lets_report’

As previously explained (see calling macros), you can use the Macro API to call other macros from inside your own macro:

@macro([["moveable", Type.Moveable, None, "moveable to get position"]])
def fixed_ascan(self, moveable):
    """This does an ascan starting at 0 ending at 100, in 10 intervals
    with integration time of 0.1s"""
    self.ascan(moveable, 0, 100, 10, 0.1)

An explicit call to execMacro() would have the same effect:

@macro([["moveable", Type.Moveable, None, "moveable to get position"]])
def fixed_ascan(self, moveable):
    """This does an ascan starting at 0 ending at 100, in 10 intervals
    with integration time of 0.1s"""
    self.execMacro('ascan', moveable, '0', '100', '10', '0.2')

The advantage of using execMacro() is that it supports passing parameters with different flavors:

• parameters as strings:

  self.execMacro('ascan', motor.getName(), '0', '100', '10', '0.2')
  

• parameters as space separated string:

  self.execMacro('ascan %s 0 100 10 0.2' % motor.getName())
  

• parameters as concrete types:

  self.execMacro(['ascan', motor, 0, 100, 10, 0.2])
  

Sometimes it is desirable to access data generated by the macro we just called. For these cases, the Macro API provides a pair of low level methods createMacro() and runMacro() together with data().

Let’s say that you need access to the data generated by an ascan. First you call createMacro() with the same parameter you would give to execMacro(). This will return a tuple composed from a macro object and the result of the prepare() method. Afterward you call runMacro() giving as parameter the macro object returned by createMacro(). In the end, you can access the data generated by the macro using data():

@macro([["moveable", Type.Moveable, None, "moveable to get position"]])
def fixed_ascan(self, moveable):
    """This does an ascan starting at 0 ending at 100, in 10 intervals
    with integration time of 0.1s"""

    ret = self.createMacro('ascan', moveable, '0', '100', '10', '0.2')
    # createMacro returns a tuple composed from a macro object
    # and the result of the Macro.prepare method
    my_scan, _ = ret
    self.runMacro(my_scan)
    print len(my_scan.data)

A set of macro call examples can be found here.

This chapter describes an advanced alternative to writing macros as Python classes. If words like inheritance, polimorphism sound like a lawyer’s horror movie then you probably should only read this if someone expert in sardana already told you that the task you intend to do cannot be accomplished by writing macro functions.

The simplest macro class that you can write MUST obey the following rules:

• Inherit from Macro
• Implement the run() method

The run() method is the place where you write the code of your macro. So, without further delay, here is the Hello, World! example:

1
2
3
4
5
6
7

from sardana.macroserver.macro import Macro

class HelloWorld(Macro):
    """Hello, World! macro"""

    def run(self):
        print "Hello, World!"

Let’s say you want to pass an integer parameter to your macro. All you have to do is declare the parameter by using the param_def Macro member:

1
2
3
4
5
6
7
8
9

from sardana.macroserver.macro import Macro, Type

class twice(Macro):
    """Macro twice. Prints the double of the given value"""

    param_def = [ [ "value", Type.Float, None, "value to be doubled" ] ]

    def run(self, value):
        self.output(2*value)

A set of macro parameter examples can be found here.

import datetime
from sardana.macroserver.macro import Macro

class HelloWorld(Macro):
    """Hello, World! macro"""

    def prepare(self):
        if datetime.datetime.now() < datetime.datetime(1990,01,01):
            raise Exception("HelloWorld can only run after year 1989")

    def run(self):
        print "Hello, World!"

Macro libraries can use code e.g. call functions and instantiate classes defined by external python libraries. In order to import the external libraries inside the macro library, they must be available for the python interpreter running the Sardana/MacroServer server (see Running server).

This could be achieved in two ways:

• Adding the directory containing the external library to the PythonPath property of the MacroServer tango device (path separators can be \n or :).
• Adding the directory containing the external library to the PYTHONPATH OS environment variable of the Sardana/MacroServer process.

The external libraries can be reloaded at Sardana/MacroServer server runtime using the rellib macro.

Remember that your macro will be executed by a Sardana server which may be running in a different computer than the computer you are working on. Executing a normal plot (from matplotlib or guiqwt) would just try to show a plot in the server machine. The macro API provides a way to plot graphics from inside your macro whenver the client that runs the macro understands the plot request (don’t worry, spock does understand!)

The plotting API is the same used by pyplot. The API is accessible through the macro context (self). Here is an example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

import math
from numpy import linspace
from scipy.integrate import quad
from scipy.special import j0

from sardana.macroserver.macro import macro

def j0i(x):
    """Integral form of J_0(x)"""
    def integrand(phi):
        return math.cos(x * math.sin(phi))
    return (1.0/math.pi) * quad(integrand, 0, math.pi)[0]

@macro()
def J0_plot(self):
    """Sample J0 at linspace(0, 20, 200)"""
    x = linspace(0, 20, 200)
    y = j0(x)
    x1 = x[::10]
    y1 = map(j0i, x1)
    self.pyplot.plot(x, y, label=r'$J_0(x)$') #
    self.pyplot.plot(x1, y1, 'ro', label=r'$J_0^{integ}(x)$')
    self.pyplot.title(r'Verify $J_0(x)=\frac{1}{\pi}\int_0^{\pi}\cos(x \sin\phi)\,d\phi$')
    self.pyplot.xlabel('$x$')
    self.pyplot.legend()

Running this macro from spock will result in something like:

Just for fun, the following macro computes a fractal and plots it as an image:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

import numpy

@macro([["interactions", Type.Integer, None, ""],
        ["density", Type.Integer, None, ""]])
def mandelbrot(self, interactions, density):

    x_min, x_max = -2, 1
    y_min, y_max = -1.5, 1.5

    x, y = numpy.meshgrid(numpy.linspace(x_min, x_max, density),
                          numpy.linspace(y_min, y_max, density))

    c = x + 1j * y
    z = c.copy()

    fractal = numpy.zeros(z.shape, dtype=numpy.uint8) + 255

    finteractions = float(interactions)
    for n in range(interactions):
        z *= z
        z += c
        mask = (fractal == 255) & (abs(z) > 10)
        fractal[mask] = 254 * n / finteractions
    self.pyplot.imshow(fractal)

And the resulting image (interactions=20, density=512):

A set of macro plotting examples can be found here.

LAB-01-D01 [1]: line = plot(range(10))[0]

LAB-01-D01 [2]: line.set_linewidth(5)

It is possible to ask for user input inside a macro.

In pure Python, to ask for user input you can use the raw_input() (Python 2) / input() (Python 3)

>>> answer = raw_input('--> ')
--> Monty Python's Flying Circus
>>> answer
"Monty Python's Flying Circus"

The Macro API provides a much more powerful version of input() since it can accept a wide variaty of options.

Similar to what happens with Plotting, when input is requested from inside a macro, the question will be sent to the client (example: spock) which ordered the macro to be executed. At this time the macro is stopped waiting for the client to answer. The client must “ask” the user for a proper value and the answer is sent back to the server which then resumes the macro execution.

Asking for user input is straightforward:

@macro()
def ask_name(self):
    """Macro function version to ask for user name"""

    answer = self.input("What's your name?")
    self.output("So, your name is '%s'", answer)

Executing this macro will make spock popup an Input Dialog Box like this one:

When you type your name and press OK the macro finishes printing the output:

LAB-01-D01 [1]: ask_name
Non interactive macro 'ask_name' is asking for input (please set this macro interactive to True)
So, your name is 'Homer Simpson'

The macro prints a warning message saying that the macro was not declared as interactive. All macros that request user input should be declared as interactive. This is because the sardana server can run a macro in unattended mode. When an interactive macro is run in unattended mode, all input() instructions that have a default value will return automatically the default value without asking the user for input.

To declare a macro as interactive set the interactive keyword argument in the macro decorator to True (default value for interactive is False), like this:

@macro(interactive=True)
def ask_name(self):
    """Macro function version to ask for user name"""

    answer = self.input("What's your name?")
    self.output("So, your name is '%s'", answer)

To declare a macro class as interactive set the interactive member to True (default value for interactive is False), like this:

class ask_name(Macro):
    """Macro class version to ask for user name"""

    interactive = True

    def run(self):
        answer = self.input("What's your name?")
        self.output("So, your name is '%s'", answer)

a helper imacro decorator and a iMacro class exist which can be used instead of the macro decorator and Macro class to transparently declare your macro as interactive:

from sardana.macroserver.macro import imacro, iMacro

# interactive macro function version

@imacro()
def ask_name(self):
    """Macro function version to ask for user name"""

    answer = self.input("What's your name?")
    self.output("So, your name is '%s'", answer)

# interactive macro class version

class ask_name(iMacro):
    """Macro class version to ask for user name"""

    def run(self):
        answer = self.input("What's your name?")
        self.output("So, your name is '%s'", answer)

The following sub-chapters explain the different options available for macro user input.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

from sardana.macroserver.macro import imacro, Type

@imacro()
def ask_number_of_points(self):
    """asks user for the number of points"""

    nb_points = self.input("How many points?", data_type=Type.Integer)
    self.output("You selected %d points", nb_points)

@imacro()
def ask_for_moveable(self):
    """asks user for a motor"""

    moveable = self.input("Which moveable?", data_type=Type.Moveable)
    self.output("You selected %s which is at %f", moveable, moveable.getPosition())

@imacro()
def ask_for_car_brand(self):
    """asks user for a car brand"""

    car_brands = "Mazda", "Citroen", "Renault"
    car_brand = self.input("Which car brand?", data_type=car_brands)
    self.output("You selected %s", car_brand)

@imacro()
def ask_for_multiple_car_brands(self):
    """asks user for several car brands"""

    car_brands = "Mazda", "Citroen", "Renault", "Ferrari", "Porche", "Skoda"
    car_brands = self.input("Which car brand(s)?", data_type=car_brands,
                            allow_multiple=True)
    self.output("You selected %s", ", ".join(car_brands))

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37

from sardana.macroserver.macro import imacro, Type

@imacro()
def ask_number_of_points(self):
    """asks user for the number of points"""

    nb_points = self.input("How many points?", data_type=Type.Integer,
                           default_value=100)
    self.output("You selected %d points", nb_points)

@imacro()
def ask_for_moveable(self):
    """asks user for a motor"""

    moveable = self.input("Which moveable?", data_type=Type.Moveable,
                          default_value="gap01")
    self.output("You selected %s which is at %f", moveable, moveable.getPosition())

@imacro()
def ask_for_car_brand(self):
    """asks user for a car brand"""

    car_brands = "Mazda", "Citroen", "Renault"
    car_brand = self.input("Which car brand?", data_type=car_brands,
                           default_value=car_brands[1])
    self.output("You selected %s", car_brand)

@imacro()
def ask_for_multiple_car_brands(self):
    """asks user for several car brands. Default is every other car brand
    in the list"""

    car_brands = "Mazda", "Citroen", "Renault", "Ferrari", "Porche", "Skoda"
    car_brands = self.input("Which car brand(s)?", data_type=car_brands,
                            allow_multiple=True,
                            default_value=car_brands[::2])
    self.output("You selected %s", ", ".join(car_brands))

1
2
3
4
5
6
7

@imacro()
def ask_peak(self):
    """asks use for peak current of points with a custom title"""

    peak = self.input("What is the peak current?", data_type=Type.Float,
                      title="Peak selection")
    self.output("You selected a peak of %f A", peak)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

@imacro()
def ask_peak_v2(self):
    """asks use for peak current of points with a custom title,
    default value, label and units"""

    label, unit = "peak", "mA"
    peak = self.input("What is the peak current?", data_type=Type.Float,
                      title="Peak selection", key=label, unit=unit,
                      default_value=123.4)
    self.output("You selected a %s of %f %s", label, peak, unit)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

@imacro()
def ask_peak_v3(self):
    """asks use for peak current of points with a custom title,
    default value, label, units and ranges"""

    label, unit = "peak", "mA"
    peak = self.input("What is the peak current?", data_type=Type.Float,
                      title="Peak selection", key=label, unit=unit,
                      default_value=123.4, minimum=0.0, maximum=200.0)
    self.output("You selected a %s of %f %s", label, peak, unit)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

@imacro()
def ask_peak_v4(self):
    """asks use for peak current of points with a custom title,
    default value, label, units, ranges and step size"""

    label, unit = "peak", "mA"
    peak = self.input("What is the peak current?", data_type=Type.Float,
                      title="Peak selection", key=label, unit=unit,
                      default_value=123.4, minimum=0.0, maximum=200.0,
                      step=5)
    self.output("You selected a %s of %f %s", label, peak, unit)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

@imacro()
def ask_peak_v5(self):
    """asks use for peak current of points with a custom title,
    default value, label, units, ranges, step size and decimal places"""

    label, unit = "peak", "mA"
    peak = self.input("What is the peak current?", data_type=Type.Float,
                      title="Peak selection", key=label, unit=unit,
                      default_value=123.4, minimum=0.0, maximum=200.0,
                      step=5, decimals=2)
    self.output("You selected a %s of %f %s", label, peak, unit)

Some of the macros you write may take a long time to execute. It could be useful to provide frequent feedback on the current progress of your macro to prevent users from thinking the system is blocked. The way to do this is by yielding a new progress number in the ode everytime you want to send a progress.

The following code shows an example:

import time

@macro([["duration", Type.Integer, 1, "time to sleep (s)"]])
def nap(self, duration):

    fduration = float(duration)
    for i in range(duration):
        time.sleep(1)
        yield (i+1) / fduration * 100

The important code here is line 9. Everytime the macro execution reaches this line of code, basically it tells sardana to send a progress with the desired value. By default, the value is interpreted has a percentage and should have the range between 0.0 and 100.0.

Actually, even if your macro doesn’t explicitly send macro progress reports, sardana always generates a 0.0 progress at the beginning of the macro and a last 100.0 progress at the end so for example, in a GUI, the progress bar showing the macro progress will always reach the end (unless an error occurs) no matter how you program the progress.

It is possible to generate a progress that doesn’t fit the 0 - 100.0 range. The above macro has been modified to send a progress with a customized range:

import time

@macro([["duration", Type.Integer, 1, "time to sleep (s)"]])
def nap(self, duration):

    status = { 'range' : [0, duration] }

    fduration = float(duration)
    for i in range(duration):
        time.sleep(1)
        status['step'] = i+1
        yield status

You may notice that this way, the range can be changed dynamically. A progress bar in a GUI is programmed to adjust not only the current progress value but also the ranges so it is safe to change them if necessary.

Footnotes

Step scans are built using an instance of the SScan class, which requires a step generator that defines the path for the motion. Since in a step scan the data is acquired at each step, the generator controls both the motion and the acquisition.

Note that in general, the generator does not need to generate a determinate (or even finite) number of steps. Also note that it is possible to write generators that vary their current step based on the acquired values (e.g., changing step sizes as a function of some counter reading).

The ascan_demo macro illustrates the most basic features of a step scan:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49

class ascan_demo(Macro):
    """
    This is a basic reimplementation of the ascan` macro for demonstration
    purposes of the Generic Scan framework. The "real" implementation of
    :class:`sardana.macroserver.macros.ascan` derives from
    :class:`sardana.macroserver.macros.aNscan` and provides some extra features.
    """

    hints = { 'scan' : 'ascan_demo'} #this is used to indicate other codes that the macro is a scan
    env = ('ActiveMntGrp',) #this hints that the macro requires the ActiveMntGrp environment variable to be set

    param_def = [
       ['motor',      Type.Moveable, None, 'Motor to move'],
       ['start_pos',  Type.Float,    None, 'Scan start position'],
       ['final_pos',  Type.Float,    None, 'Scan final position'],
       ['nr_interv',  Type.Integer,  None, 'Number of scan intervals'],
       ['integ_time', Type.Float,    None, 'Integration time']
    ]

    def prepare(self, motor, start_pos, final_pos, nr_interv, integ_time, **opts):
        #parse the user parameters
        self.start = numpy.array([start_pos], dtype='d')
        self.final = numpy.array([final_pos], dtype='d')
        self.integ_time = integ_time

        self.nr_points = nr_interv+1
        self.interv_size = ( self.final - self.start) / nr_interv
        self.name='ascan_demo'
        env = opts.get('env',{}) #the "env" dictionary may be passed as an option

        #create an instance of GScan (in this case, of its child, SScan
        self._gScan=SScan(self, generator=self._generator, moveables=[motor], env=env)


    def _generator(self):
        step = {}
        step["integ_time"] =  self.integ_time #integ_time is the same for all steps
        for point_no in xrange(self.nr_points):
            step["positions"] = self.start + point_no * self.interv_size #note that this is a numpy array
            step["point_id"] = point_no
            yield step

    def run(self,*args):
        for step in self._gScan.step_scan(): #just go through the steps
            yield step

    @property
    def data(self):
        return self._gScan.data #the GScan provides scan data

The ascan_demo shows only basic features of the scan framework, but it already shows that writing a step scan macro is mostly just a matter of writing a generator function.

It also shows that the scan.gscan.GScan.data() method can be used to provide the needed return value of data()

Continuous scans are built using an instance of the CScan class. Since in the continuous scans the acquisition and motion are decoupled, CScan requires two independent generators:

• a waypoint generator: which defines the path for the motion in a very similar way as the step generator does for a continuous scan. The steps generated by this generator are also called “waypoints”.
• a period generator which controls the data acquisition steps.

Essentially, CScan implements the continuous scan as an acquisition loop (controlled by the period generator) nested within a motion loop (controlled by the waypoint generator). Note that each loop is run on an independent thread, and only limited communication occurs between the two (basically the acquisition starts at the beginning of each movement and ends when a waypoint is reached).

The ascanc_demo macro illustrates the most basic features of a continuous scan::

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51

class ascanc_demo(Macro):
    """
    This is a basic reimplementation of the ascanc` macro for demonstration
    purposes of the Generic Scan framework. The "real" implementation of
    :class:`sardana.macroserver.macros.ascanc` derives from
    :class:`sardana.macroserver.macros.aNscan` and provides some extra features.
    """

    hints = { 'scan' : 'ascanc_demo'} #this is used to indicate other codes that the macro is a scan
    env = ('ActiveMntGrp',) #this hints that the macro requires the ActiveMntGrp environment variable to be set

    param_def = [
       ['motor',      Type.Moveable, None, 'Motor to move'],
       ['start_pos',  Type.Float,    None, 'Scan start position'],
       ['final_pos',  Type.Float,    None, 'Scan final position'],
       ['integ_time', Type.Float,    None, 'Integration time']
    ]

    def prepare(self, motor, start_pos, final_pos, integ_time, **opts):
        self.name='ascanc_demo'
        #parse the user parameters
        self.start = numpy.array([start_pos], dtype='d')
        self.final = numpy.array([final_pos], dtype='d')
        self.integ_time = integ_time
        env = opts.get('env',{}) #the "env" dictionary may be passed as an option

        #create an instance of GScan (in this case, of its child, CScan
        self._gScan = CScan(self,
                            waypointGenerator=self._waypoint_generator,
                            periodGenerator=self._period_generator,
                            moveables=[motor],
                            env=env)

    def _waypoint_generator(self):
        #a very simple waypoint generator! only start and stop points!
        yield {"positions":self.start, "waypoint_id": 0}
        yield {"positions":self.final, "waypoint_id": 1}


    def _period_generator(self):
        step = {}
        step["integ_time"] =  self.integ_time
        point_no = 0
        while(True): #infinite generator. The acquisition loop is started/stopped at begin and end of each waypoint
            point_no += 1
            step["point_id"] = point_no
            yield step

    def run(self,*args):
        for step in self._gScan.step_scan():
            yield step

In general, the Hooks API provided by the Hookable base class allows a macro to run other code (the hook callable) at certain points of its execution. The hooks use a “hints” mechanism to pass the receiving macro some extra information on how/when they should be executed. The hints are strings, and its content is not fixed by the API, being up to each macro to identify, use and/or ignore them.

You can find some examples of the use of hooks in the hooks module.

In the case of the scan macros, the hooks can be either registered directly via the Hooks API or passed as key:values of the “step” dictionary returned by the scan generator() (see GScan for more details).

The hints for a given hook are used by the scan framework to select the moment of the scan execution that the given hook is run. The following is a list of hint strings that scan macros support (other hints are ignored):

• ‘pre-scan-hooks’ : before starting the scan.
• ‘pre-move-hooks’ : for steps: before starting to move.
• ‘post-move-hooks’: for steps: after finishing the move.
• ‘pre-acq-hooks’ : for steps: before starting to acquire.
• ‘post-acq-hooks’ : for steps: after finishing acquisition but before recording the step.
• ‘post-step-hooks’ : for steps: after finishing recording the step.
• ‘post-scan-hooks’ : after finishing the scan

See the code of hooked_scan for a macro that demonstrates the use of the hook points of a scan.

Other examples of the hooks module can be illustrative.

Also, note that the Taurus MacroExecutor widget allows the user to dynamically add hooks to existing macros before execution.

Other macros in the examples module illustrate more features of the scan framework.

See also the code of the standard scan macros in the scan module.

Finally, the documentation and code of GScan, SScan and CScan may be helpful.

The first thing to do is to import the necessary symbols from sardana library. As you will see, most symbols can be imported through the sardana.pool.controller module:

import springfieldlib

from sardana.pool.controller import MotorController

class SpringfieldMotorController(MotorController):
    """A motor controller intended from demonstration purposes only"""
    pass

The common API to all low level controllers includes the set of methods to:

1. construct the controller
2. add/delete a controller element [1]
3. obtain the state of controller element(s) [2]
4. define, set and get extra axis attributes
5. define, set and get extra controller attributes
6. define, set and get extra controller properties

In the following chapters the examples will be based on a motor controller scenario.

The examples use a springfieldlib module which emulates a motor hardware access library.

The springfieldlib can be downloaded from here.

The Springfield motor controller can be downloaded from here.

class SpringfieldMotorController(MotorController):

    def __init__(self, inst, props, *args, **kwargs):
        super(SpringfieldMotorController, self).__init__(inst, props, *args, **kwargs)

        # initialize hardware communication
        self.springfield = springfieldlib.SpringfieldMotorHW()

        # do some initialization
        self._motors = {}

class SpringfieldMotorController(MotorController):

    def AddDevice(self, axis):
        self._motors[axis] = True

    def DeleteDevice(self, axis):
        del self._motor[axis]

from sardana import State

class SpringfieldMotorController(MotorController):

    StateMap = {
        1 : State.On,
        2 : State.Moving,
        3 : State.Fault,
    }

    def StateOne(self, axis):
        springfield = self.springfield
        state = self.StateMap[ springfield.getState(axis) ]
        status = springfield.getStatus(axis)
        return state, status

from sardana import DataAccess
from sardana.pool.controller import Type, Description, DefaultValue, Access, FGet, FSet

class SpringfieldMotorController(MotorController):

    axis_attributes = {
        "CloseLoop" : {
                Type         : bool,
                Description  : "(de)activates the motor close loop algorithm",
                DefaultValue : False,
            },
    }

    def getCloseLoop(self, axis):
        return self.springfield.isCloseLoopActive(axis)

    def setCloseLoop(self, axis, value):
        self.springfield.setCloseLoop(axis, value)

from sardana import DataAccess
from sardana.pool.controller import Type, Description, DefaultValue, Access, FGet, FSet

class SpringfieldMotorController(MotorController):

    axis_attributes = {
        "CloseLoop" : {
                Type         : bool,
                Description  : "(de)activates the motor close loop algorithm",
                DefaultValue : False,
            },
    }

    def GetAxisExtraPar(self, axis, parameter):
        if parameter == 'CloseLoop':
            return self.springfield.isCloseLoopActive(axis)

    def SetAxisExtraPar(self, axis, parameter, value):
        if parameter == 'CloseLoop':
             self.springfield.setCloseLoop(axis, value)

class SpringfieldMotorController(MotorController):

    ctrl_attributes = {
        "ReflectionMatrix" : {
                Type         : ( (float,), ),
                Description  : "The reflection matrix",
                Access : DataAccess.ReadOnly,
            },
    }

    def getReflectionMatrix(self):
        return ( (1.0, 0.0), (0.0, 1.0) )

class SpringfieldMotorController(MotorController):

    ctrl_attributes = \
    {
        "ReflectionMatrix" : {
                Type         : ( (float,), ),
                Description  : "The reflection matrix",
                Access : DataAccess.ReadOnly,
            },
    }

    def GetCtrlPar(self, name):
        if name == "ReflectionMatrix":
            return ( (1.0, 0.0), (0.0, 1.0) )