Examples

This chapter gathers a series of macro examples distributed with Sardana. The example modules shown below can be found in the sardana.macroserver.macros.examples package.

Macro examples

Macro parameter examples

The following examples demonstrate how to declare macros which receive parameter(s). See Adding parameters to your macro for a tutorial on macro parameters.

##############################################################################
##
# This file is part of Sardana
##
# http://www.sardana-controls.org/
##
# Copyright 2011 CELLS / ALBA Synchrotron, Bellaterra, Spain
##
# Sardana is free software: you can redistribute it and/or modify
# it under the terms of the GNU Lesser General Public License as published by
# the Free Software Foundation, either version 3 of the License, or
# (at your option) any later version.
##
# Sardana is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU Lesser General Public License for more details.
##
# You should have received a copy of the GNU Lesser General Public License
# along with Sardana.  If not, see <http://www.gnu.org/licenses/>.
##
##############################################################################

"""This module contains macros that demonstrate the usage of macro parameters"""

from sardana.macroserver.macro import Macro, Type

__all__ = [
    "pt0",
    "pt1",
    "pt2",
    "pt3",
    "pt3d",
    "pt4",
    "pt5",
    "pt6",
    "pt7",
    "pt7d1",
    "pt7d2",
    "pt8",
    "pt9",
    "pt10",
    "pt11",
    "pt12",
    "pt13",
    "pt14",
    "pt14d",
    "twice",
]


class pt0(Macro):
    """Macro without parameters. Pretty dull.
    Usage from Spock, ex.:
    pt0
    """

    param_def = []

    def run(self):
        pass


class pt1(Macro):
    """Macro with one float parameter: Each parameter is described in the
    param_def sequence as being a sequence of four elements: name, type,
    default value and description.
    Usage from Spock, ex.:
    pt1 1
    """

    param_def = [["value", Type.Float, None, "some bloody float"]]

    def run(self, f):
        pass


class pt1d(Macro):
    """Macro with one float parameter with default value..
    Usage from Spock, ex.:
    pt1d 1
    pt1d
    """

    param_def = [["value", Type.Float, None, "some bloody float"]]

    def run(self, f):
        pass


class pt2(Macro):
    """Macro with one Motor parameter: Each parameter is described in the
    param_def sequence as being a sequence of four elements: name, type,
    default value and description.
    Usage from Spock, ex.
    pt2 mot1
    """

    param_def = [["motor", Type.Motor, None, "some bloody motor"]]

    def run(self, m):
        pass


class pt3(Macro):
    """Macro with a list of numbers as parameter: the type is a sequence of
    parameter types which is repeated. In this case it is a repetition of a
    float so only one parameter is defined.
    By default the repetition as a semantics of 'at least one'
    Usages from Spock, ex.:
    pt3 [1 34 15]
    pt3 1 34 15
    """

    param_def = [
        ["numb_list", [["pos", Type.Float, None, "value"]], None, "List of values"],
    ]

    def run(self, *args, **kwargs):
        pass


class pt3d(Macro):
    """Macro with a list of numbers as parameter: the type is a sequence of
    parameter types which is repeated. In this case it is a repetition of a
    float so only one parameter is defined. The parameter has a default value.
    By default the repetition as a semantics of 'at least one'
    Usages from Spock, ex.:
    pt3d [1 34 15]
    pt3d 1 34 15
    Usage taken the default value, ex.:
    pt3d [1 [] 15]
    """

    param_def = [
        ["numb_list", [["pos", Type.Float, 21, "value"]], None, "List of values"],
    ]

    def run(self, *args, **kwargs):
        pass


class pt4(Macro):
    """Macro with a list of motors as parameter: the type is a sequence of
    parameter types which is repeated. In this case it is a repetition of a
    motor so only one parameter is defined.
    By default the repetition as a semantics of 'at least one'.
    Usages from Spock, ex.:
    pt4 [mot1 mot2 mot3]
    pt4 mot1 mot2 mot3
    """

    param_def = [
        [
            "motor_list",
            [["motor", Type.Motor, None, "motor name"]],
            None,
            "List of motors",
        ],
    ]

    def run(self, *args, **kwargs):
        pass


class pt5(Macro):
    """Macro with a motor parameter followed by a list of numbers.
    Usages from Spock, ex.:
    pt5 mot1 [1 3]
    pt5 mot1 1 3
    """

    param_def = [
        ["motor", Type.Motor, None, "Motor to move"],
        ["numb_list", [["pos", Type.Float, None, "value"]], None, "List of values"],
    ]

    def run(self, *args, **kwargs):
        pass


class pt6(Macro):
    """Macro with a motor parameter followed by a list of numbers. The list as
    explicitly stated an optional last element which is a dictionary that defines the
    min and max values for repetitions.
    Usages from Spock, ex.:
    pt6 mot1 [1 34 1]
    pt6 mot1 1 34 1
    """

    param_def = [
        ["motor", Type.Motor, None, "Motor to move"],
        [
            "numb_list",
            [["pos", Type.Float, None, "value"], {"min": 1, "max": None}],
            None,
            "List of values",
        ],
    ]

    def run(self, *args, **kwargs):
        pass


class pt7(Macro):
    """Macro with a list of pair Motor,Float.
    Usages from Spock, ex.:
    pt7 [[mot1 1] [mot2 3]]
    pt7 mot1 1 mot2 3
    """

    param_def = [
        [
            "m_p_pair",
            [
                ["motor", Type.Motor, None, "Motor to move"],
                ["pos", Type.Float, None, "Position to move to"],
            ],
            None,
            "List of motor/position pairs",
        ]
    ]

    def run(self, *args, **kwargs):
        pass


class pt7d1(Macro):
    """Macro with a list of pair Motor,Float. Default value for last
    repeat parameter element.
    Usages from Spock, ex.:
    pt7d1 [[mot1 1] [mot2 3]]
    pt7d1 mot1 1 mot2 3
    Using default value, ex.:
    pt7d1 [[mot1] [mot2 3]] # at any repetition
    pt7d1 mot1 # if only one repetition

    """

    param_def = [
        [
            "m_p_pair",
            [
                ["motor", Type.Motor, None, "Motor to move"],
                ["pos", Type.Float, 2, "Position to move to"],
            ],
            None,
            "List of motor/position pairs",
        ]
    ]

    def run(self, *args, **kwargs):
        pass


class pt7d2(Macro):
    """Macro with a list of pair Motor,Float. Default value for both
    repeat parameters elements.
    Usages from Spock, ex.:
    pt7d2 [[mot1 1] [mot2 3]]
    pt7d2 mot1 1 mot2 3
    Using both default values, ex.:
    pt7d2 [[] [mot2 3] []] # at any repetition
    """

    param_def = [
        [
            "m_p_pair",
            [
                ["motor", Type.Motor, "mot1", "Motor to move"],
                ["pos", Type.Float, 2, "Position to move to"],
            ],
            None,
            "List of motor/position pairs",
        ]
    ]

    def run(self, *args, **kwargs):
        pass


class pt8(Macro):
    """Macro with a list of pair Motor,Float. The min and max elements have been
    explicitly stated.
    Usages from Spock, ex.:
    pt8 [[mot1 1] [mot2 3]]
    pt8 mot1 1 mot2 3
    """

    param_def = [
        [
            "m_p_pair",
            [
                ["motor", Type.Motor, None, "Motor to move"],
                ["pos", Type.Float, None, "Position to move to"],
                {"min": 1, "max": 2},
            ],
            None,
            "List of motor/position pairs",
        ]
    ]

    def run(self, *args, **kwargs):
        pass


class pt9(Macro):
    """Same as macro pt7 but with min and max number of repetitions of the
    repeat parameter.
    Usages from Spock, ex.:
    pt9 [[mot1 1][mot2 3]]
    pt9 mot1 1 mot2 3
    """

    param_def = [
        [
            "m_p_pair",
            [
                ["motor", Type.Motor, None, "Motor to move"],
                ["pos", Type.Float, None, "Position to move to"],
                {"min": 1, "max": 2},
            ],
            None,
            "List of motor/position pairs",
        ],
    ]

    def run(self, *args, **kwargs):
        pass


class pt10(Macro):
    """Macro with list of numbers followed by a motor parameter. The repeat
    parameter may be defined as first one.
    Usage from Spock, ex.:
    pt10 [1 3] mot1
    pt10 1 mot1 # if only one repetition
    """

    param_def = [
        ["numb_list", [["pos", Type.Float, None, "value"]], None, "List of values"],
        ["motor", Type.Motor, None, "Motor to move"],
    ]

    def run(self, *args, **kwargs):
        pass


class pt11(Macro):
    """Macro with counter parameter followed by a list of numbers, followed by
    a motor parameter. The repeat parameter may be defined in between other
    parameters.
    Usages from Spock, ex.:
    pt11 ct1 [1 3] mot1
    pt11 ct1 1 mot1 # if only one repetition
    """

    param_def = [
        ["counter", Type.ExpChannel, None, "Counter to count"],
        ["numb_list", [["pos", Type.Float, None, "value"]], None, "List of values"],
        ["motor", Type.Motor, None, "Motor to move"],
    ]

    def run(self, *args, **kwargs):
        pass


class pt12(Macro):
    """Macro with list of motors followed by list of numbers. Two repeat
    parameters may defined.
    Usage from Spock, ex.:
    pt12 [1 3 4] [mot1 mot2]
    pt12 1 mot1 # if only one repetition for each repeat parameter
    """

    param_def = [
        ["numb_list", [["pos", Type.Float, None, "value"]], None, "List of values"],
        [
            "motor_list",
            [["motor", Type.Motor, None, "Motor to move"]],
            None,
            "List of motors",
        ],
    ]

    def run(self, *args, **kwargs):
        pass


class pt13(Macro):
    """Macro with list of motors groups, where each motor group is a list of
    motors. Repeat parameters may be defined as nested.
    Usage from Spock, ex.:
    pt13 [[mot1 mot2] [mot3 mot4]]
    """

    param_def = [
        [
            "motor_group_list",
            [
                [
                    "motor_list",
                    [["motor", Type.Motor, None, "Motor to move"]],
                    None,
                    "List of motors",
                ]
            ],
            None,
            "Motor groups",
        ]
    ]

    def run(self, *args, **kwargs):
        pass


class pt14(Macro):
    """Macro with list of motors groups, where each motor group is a list of
    motors and a float. Repeat parameters may be defined as nested.
    Usage from Spock, ex.:
    pt14 [[[mot1 mot2] 3] [[mot3] 5]]
    """

    param_def = [
        [
            "motor_group_list",
            [
                [
                    "motor_list",
                    [["motor", Type.Motor, None, "Motor to move"]],
                    None,
                    "List of motors",
                ],
                ["float", Type.Float, None, "Number"],
            ],
            None,
            "Motor groups",
        ]
    ]

    def run(self, *args, **kwargs):
        pass


class pt14d(Macro):
    """Macro with list of motors groups, where each motor group is a list of
    motors and a float. Repeat parameters may be defined as nested.
    Default values can be used.
    Usages taken default values, ex.:
    pt14d [[[mot1 mot2] 3] [[mot3] []]]
    pt14d [[[mot1 []] 3] [[mot3] []]]
    pt14d [[[[]] 3] [[mot3] []]]
    """

    param_def = [
        [
            "motor_group_list",
            [
                [
                    "motor_list",
                    [["motor", Type.Motor, "mot1", "Motor to move"]],
                    None,
                    "List of motors",
                ],
                ["float", Type.Float, 33, "Number"],
            ],
            None,
            "Motor groups",
        ]
    ]

    def run(self, *args, **kwargs):
        pass


class twice(Macro):
    """A macro that returns a float that is twice its input. It also sets its
    data to be a dictionary with 'in','out' as keys and value,result
    as values, respectively"""

    # uncomment the following lines as necessary. Otherwise you may delete them
    param_def = [["value", Type.Float, 23, "value to be doubled"]]
    result_def = [["result", Type.Float, None, "the double of the given value"]]
    # hints = {}
    # env = (,)

    # uncomment the following lines if need prepare. Otherwise you may delete them
    # def prepare(self):
    #    pass

    def run(self, n):
        ret = 2 * n
        self.setData({"in": n, "out": ret})
        return ret

Macro call examples

The following examples demonstrate how to call macros from inside a macro. See Calling other macros from inside your macro for a tutorial on calling macros.

##############################################################################
##
# This file is part of Sardana
##
# http://www.sardana-controls.org/
##
# Copyright 2011 CELLS / ALBA Synchrotron, Bellaterra, Spain
##
# Sardana is free software: you can redistribute it and/or modify
# it under the terms of the GNU Lesser General Public License as published by
# the Free Software Foundation, either version 3 of the License, or
# (at your option) any later version.
##
# Sardana is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU Lesser General Public License for more details.
##
# You should have received a copy of the GNU Lesser General Public License
# along with Sardana.  If not, see <http://www.gnu.org/licenses/>.
##
##############################################################################

"""
A macro package to show examples on how to run a macro from inside another macro
"""

__all__ = ["call_wa", "call_wm", "subsubm", "subm", "mainmacro", "runsubs"]

__docformat__ = "restructuredtext"

from sardana.macroserver.macro import Macro, Type

# -~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-
# First example:
# A 'mainmacro' that executes a 'subm' that in turn executes a 'subsubm'.
# The 'subsubm' macro itself calls a short ascan macro
# -~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~--~-~-


class call_wa(Macro):
    def run(self):
        self.macros.wa()


class call_wm(Macro):
    param_def = [
        [
            "motor_list",
            [["motor", Type.Motor, None, "Motor to move"]],
            None,
            "List of motor to show",
        ],
    ]

    def run(self, m):
        self.macros.wm(m)


class subsubm(Macro):
    """this macro just calls the 'subm' macro
    This macro is part of the examples package. It was written for demonstration purposes"""

    def run(self):
        self.output("Starting %s" % self.getName())
        m = self.macros
        motors = self.getObjs(".*", type_class=Type.Motor)
        m.ascan(motors[0], 0, 100, 10, 0.2)
        self.output("Finished %s" % self.getName())


class subm(Macro):
    """this macro just calls the 'subsubm' macro
    This macro is part of the examples package. It was written for demonstration purposes"""

    def run(self):
        self.output("Starting %s" % self.getName())
        self.macros.subsubm()
        self.output("Finished %s" % self.getName())


class mainmacro(Macro):
    """this macro just calls the 'subm' macro
    This macro is part of the examples package. It was written for demonstration purposes"""

    def run(self):
        self.output("Starting %s" % self.getName())
        self.macros.subm()
        self.output("Finished %s" % self.getName())


# -~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-
# Second example:
# a 'runsubs' macro that shows the different ways to call a macro from inside
# another macro
# -~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~--~-~-


class runsubs(Macro):
    """A macro that calls a ascan macro using the motor given as first parameter.

    This macro is part of the examples package. It was written for demonstration purposes

    Call type will allow to choose to format in which the ascan macro is called
    from this macro:
    1 - m.ascan(motor.getName(), '0', '10', '4', '0.2')
    2 - m.ascan(motor, 0, 10, 4, 0.2)
    3 - self.execMacro('ascan', motor.getName(), '0', '10', '4', '0.2')
    4 - self.execMacro(['ascan', motor, 0, 10, 4, 0.2])
    5 - params = 'ascan', motor, 0, 10, 4, 0.2
        self.execMacro(params)
    6 - self.execMacro("ascan %s 0 10 4 0.2" % motor.getName())
    7 - macro, prep = self.createMacro("ascan %s 0 10 4 0.2" % motor.getName())
        macro.hooks = [ self.hook ]
        self.runMacro(macro)
    8 - macro, prep = self.createMacro('ascan', motor, 0, 10, 4, 0.2)
        macro.hooks = [ self.hook ]
        self.runMacro(macro)
    9 - params = 'ascan', motor, 0, 10, 4, 0.2
        macro, prep = self.createMacro(params)
        macro.hooks = [ self.hook ]
        self.runMacro(macro)

        Options 7,8 and 9 use the lower level macro API in order to be able to
        attach hooks to the ascan macro."""

    param_def = [
        ["motor", Type.Motor, None, "Motor to move"],
        ["call_type", Type.Integer, 2, "type of run to execute internally"],
    ]

    def hook(self):
        self.info("executing hook in a step of a scan...")

    def run(self, motor, call_type):
        m = self.macros
        self.output("Using type %d" % call_type)
        if call_type == 1:
            m.ascan(motor.getName(), "0", "10", "4", "0.2")
        elif call_type == 2:
            m.ascan(motor, 0, 10, 4, 0.2)
        elif call_type == 3:
            self.execMacro("ascan", motor.getName(), "0", "10", "4", "0.2")
        elif call_type == 4:
            self.execMacro("ascan", motor, 0, 10, 4, 0.2)
        elif call_type == 5:
            params = "ascan", motor, 0, 10, 4, 0.2
            self.execMacro(params)
        elif call_type == 6:
            self.execMacro("ascan %s 0 10 4 0.2" % motor.getName())
        elif call_type == 7:
            macro, prep = self.createMacro("ascan %s 0 10 4 0.2" % motor.getName())
            macro.hooks = [self.hook]
            self.runMacro(macro)
        elif call_type == 8:
            macro, prep = self.createMacro("ascan", motor, 0, 10, 4, 0.2)
            macro.hooks = [self.hook]
            self.runMacro(macro)
        elif call_type == 9:
            params = "ascan", motor, 0, 10, 4, 0.2
            macro, prep = self.createMacro(params)
            macro.hooks = [self.hook]
            self.runMacro(macro)


class get_data(Macro):
    """A macro that executes another macro from within it, get its data,
    and calculates a result using this data.

    This macro is part of the examples package. It was written for
    demonstration purposes"""

    param_def = [["mot", Type.Moveable, None, "moveable to be moved"]]
    result_def = [["middle", Type.Float, None, "the middle motor position"]]

    def run(self, mot):
        start = 0
        end = 2
        intervals = 2
        integtime = 0.1
        positions = []
        dscan, _ = self.createMacro("dscan", mot, start, end, intervals, integtime)
        self.runMacro(dscan)

        data = dscan.data
        len_data = len(data)
        for point_nb in range(len_data):
            position = data[point_nb].data[mot.getName()]
            positions.append(position)

        middle_pos = max(positions) - min(positions) / len_data
        return middle_pos

Macro hooks examples

The following examples demonstrate how to define hookable macros and how to programmatically attach hooks to macros. See Macro Hooks and Adding hooks support for more information.

##############################################################################
##
# This file is part of Sardana
##
# http://www.sardana-controls.org/
##
# Copyright 2011 CELLS / ALBA Synchrotron, Bellaterra, Spain
##
# Sardana is free software: you can redistribute it and/or modify
# it under the terms of the GNU Lesser General Public License as published by
# the Free Software Foundation, either version 3 of the License, or
# (at your option) any later version.
##
# Sardana is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU Lesser General Public License for more details.
##
# You should have received a copy of the GNU Lesser General Public License
# along with Sardana.  If not, see <http://www.gnu.org/licenses/>.
##
##############################################################################

"""This module contains macros that demonstrate the usage of hooks"""

__all__ = ["captain_hook", "captain_hook2", "loop", "hooked_scan", "hooked_dummyscan"]

__docformat__ = "restructuredtext"

from sardana.macroserver.macro import ExecMacroHook, Hookable, Macro, Type


class loop(Macro, Hookable):
    """A macro that executes a for loop. It accepts hooks.
    This macro is part of the examples package. It was written for
    demonstration purposes"""

    hints = {"allowsHooks": ("pre-move", "post-move", "pre-acq", "post-acq")}

    param_def = [
        ["start", Type.Integer, None, "start point"],
        ["stop", Type.Integer, None, "end point"],
        ["step", Type.Integer, 1, "step"],
    ]

    def run(self, start, stop, step):
        self.info("Starting loop")
        for i in range(start, stop, step):
            self.output("At step %d" % i)
            self.flushOutput()
            for hook, hints in self.hooks:
                self.info("running hook with hints=" + repr(hints))
                hook()
        self.info("Finished loop")


class captain_hook(Macro):
    """A macro that executes a loop macro. A hook was attached so that in each
    step of the loop this hook is executed.
    This macro is part of the examples package. It was written for
    demonstration purposes"""

    param_def = [
        ["start", Type.Integer, None, "start point"],
        ["stop", Type.Integer, None, "end point"],
        ["step", Type.Integer, 1, "step"],
    ]

    def hook(self):
        self.info("\thook execution")

    def run(self, start, stop, step):
        loop_macro, _ = self.createMacro("loop", start, stop, step)
        loop_macro.hooks = [(self.hook, ["pre-acq"])]
        self.runMacro(loop_macro)


class captain_hook2(Macro):
    """A macro that executes a loop macro. A hook was attached so that in each
    step of the loop this hook is executed.
    This macro is part of the examples package. It was written for
    demonstration purposes"""

    param_def = [
        ["start", Type.Integer, None, "start point"],
        ["stop", Type.Integer, None, "end point"],
        ["step", Type.Integer, 1, "step"],
    ]

    def hook(self):
        self.execMacroStr(["lsm"])

    def run(self, start, stop, step):
        loop_macro, _ = self.createMacro("loop", start, stop, step)
        # h = self.createExecMacroHook(["lsm"])
        # it gives the "pre-acq" hint to the hook
        loop_macro.hooks = [self.hook]
        self.runMacro(loop_macro)


class hooked_scan(Macro):
    """An example on how to attach hooks to the various hook points of a scan.
    This macro is part of the examples package. It was written for
    demonstration purposes"""

    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 hook1(self):
        self.info("\thook1 execution")

    def hook2(self):
        self.info("\thook2 execution")

    def hook3(self):
        self.info("\thook3 execution")

    def hook4(self):
        self.info("\thook4 execution")

    def hook5(self):
        self.info("\thook5 execution")

    def hook6(self):
        self.info("\thook6 execution")

    def run(self, motor, start_pos, final_pos, nr_interv, integ_time):
        ascan, pars = self.createMacro(
            "ascan", motor, start_pos, final_pos, nr_interv, integ_time
        )
        ascan.hooks = [
            (self.hook1, ["pre-acq"]),
            (self.hook2, ["pre-acq", "post-acq", "pre-move", "post-move", "aaaa"]),
            self.hook3,
            (self.hook4, ["pre-scan"]),
            (self.hook5, ["pre-scan", "post-scan"]),
            (self.hook6, ["post-step"]),
        ]
        self.runMacro(ascan)


class hooked_scan_with_macro(Macro):
    """An example on how to attach macro (in this case without parameters)
    as a hook to the various hook points of a scan.

    This macro is part of the examples package. It was written for
    demonstration purposes"""

    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"],
        ["macro", Type.Macro, None, "Macro to be used as hook"],
        [
            "hook_places",
            [["hook_place", Type.String, None, "Hook place"]],
            None,
            "Hook places where macro will be called",
        ],
    ]

    def run(
        self, motor, start_pos, final_pos, nr_interv, integ_time, macro, hook_places
    ):
        ascan, _ = self.createMacro(
            "ascan", motor, start_pos, final_pos, nr_interv, integ_time
        )
        macro_hook = ExecMacroHook(self, "umv", [["mot01", 1]])
        ascan.hooks = [(macro_hook, hook_places)]
        self.runMacro(ascan)


class hooked_dummyscan(Macro):
    """An example on how to attach hooks to the various hook points of a scan.
    This macro is part of the examples package. It was written for
    demonstration purposes"""

    param_def = [
        ["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 hook1(self):
        self.info("\thook1 execution")

    def hook2(self):
        self.info("\thook2 execution")

    def hook3(self):
        self.info("\thook3 execution")

    def run(self, start_pos, final_pos, nr_interv, integ_time):
        dummyscan, pars = self.createMacro(
            "dummyscan", start_pos, final_pos, nr_interv, integ_time
        )
        dummyscan.hooks = [
            (self.hook1, ["pre-scan"]),
            (self.hook2, ["pre-acq", "post-acq", "pre-move", "post-move", "aaaa"]),
            (self.hook3, ["post-scan"]),
        ]
        self.runMacro(dummyscan)

Macro scans examples

The following examples demonstrate specific features or tricks for programming custom scan macros using the Sardana scan framework.

##############################################################################
##
# This file is part of Sardana
##
# http://www.sardana-controls.org/
##
# Copyright 2011 CELLS / ALBA Synchrotron, Bellaterra, Spain
##
# Sardana is free software: you can redistribute it and/or modify
# it under the terms of the GNU Lesser General Public License as published by
# the Free Software Foundation, either version 3 of the License, or
# (at your option) any later version.
##
# Sardana is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU Lesser General Public License for more details.
##
# You should have received a copy of the GNU Lesser General Public License
# along with Sardana.  If not, see <http://www.gnu.org/licenses/>.
##
##############################################################################

"""
 Macro library containning examples demonstrating specific features or tricks
 for programming macros for Sardana.

Available Macros are:
  ascanr
  toothedtriangle

"""

__all__ = ["ascan_demo", "ascanr", "toothedtriangle", "a2scan_mod"]

__docformat__ = "restructuredtext"

import numpy

from sardana.macroserver.macro import Hookable, Macro, Type
from sardana.macroserver.scan import ColumnDesc, CScan, MoveableDesc, SScan


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.
    """

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

    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.nb_points = nr_interv + 1
        if nr_interv:
            self.interv_size = (self.final - self.start) / nr_interv
        else:
            self.interv_size = self.final - self.start
        self.name = "ascan_demo"
        # the "env" dictionary may be passed as an option
        env = opts.get("env", {})

        # 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 = {}
        # integ_time is the same for all steps
        step["integ_time"] = self.integ_time
        for point_no in range(self.nb_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

    def _get_nr_points(self):
        msg = "nr_points is deprecated since version 3.0.3. Use nb_points instead."
        self.warning(msg)
        return self.nb_points

    nr_points = property(_get_nr_points)


class ascanr(Macro, Hookable):
    """This is an example of how to handle adding extra info columns in a scan.
    Does the same than ascan but repeats the acquisitions "repeat" times for each step.
    It could be implemented deriving from aNscan, but I do it like this for clarity.
    Look for the comments with "!!!" for tips specific to the extra info columns
    I do not support constrains in this one for simplicity (see ascan for that)

    Do an absolute scan of the specified motor, repeating measurements in each step.
    ascanr scans one motor, as specified by motor. The motor starts at the
    position given by start_pos and ends at the position given by final_pos.
    At each step, the acquisition will be repeated "repeat" times
    The step size is (start_pos-final_pos)/nr_interv. The number of data points collected
    will be (nr_interv+1)*repeat. Count time for each acquisition is given by time which if positive,
    specifies seconds and if negative, specifies monitor counts."""

    hints = {
        "scan": "ascanr",
        "allowsHooks": ("pre-move", "post-move", "pre-acq", "post-acq", "post-step"),
    }
    env = ("ActiveMntGrp",)

    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"],
        ["repeat", Type.Integer, None, "Number of Repetitions"],
    ]

    def prepare(
        self, motor, start_pos, final_pos, nr_interv, integ_time, repeat, **opts
    ):
        self.starts = numpy.array([start_pos], dtype="d")
        self.finals = numpy.array([final_pos], dtype="d")
        self.nr_interv = nr_interv
        self.integ_time = integ_time
        self.repeat = repeat
        self.opts = opts

        self.nb_points = (nr_interv + 1) * repeat
        if nr_interv:
            self.interv_sizes = (self.finals - self.starts) / nr_interv
        else:
            self.interv_sizes = self.finals - self.starts
        self.name = "ascanr"

        generator = self._generator
        moveables = [motor]
        env = opts.get("env", {})
        constrains = []
        extrainfodesc = [ColumnDesc(name="repetition", dtype="int64", shape=())]  # !!!

        self._gScan = SScan(
            self, generator, moveables, env, constrains, extrainfodesc
        )  # !!!

    def _generator(self):
        step = {}
        step["integ_time"] = self.integ_time
        step["pre-move-hooks"] = self.getHooks("pre-move")
        step["post-move-hooks"] = self.getHooks("post-move")
        step["pre-acq-hooks"] = self.getHooks("pre-acq")
        step["post-acq-hooks"] = self.getHooks("post-acq") + self.getHooks("_NOHINTS_")
        step["post-step-hooks"] = self.getHooks("post-step")
        step["check_func"] = []
        for point_no in range(self.nb_points // self.repeat):
            extrainfo = {"repetition": 0}  # !!!
            step["extrainfo"] = extrainfo  # !!!
            step["positions"] = self.starts + point_no * self.interv_sizes
            step["point_id"] = point_no
            yield step
            for i in range(1, self.repeat):
                extrainfo["repetition"] = i  # !!!
                step["positions"] = [None]
                yield step

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

    @property
    def data(self):
        return self._gScan.data

    def _get_nr_points(self):
        msg = "nr_points is deprecated since version 3.0.3. Use nb_points instead."
        self.warning(msg)
        return self.nb_points

    nr_points = property(_get_nr_points)


class toothedtriangle(Macro, Hookable):
    """toothedtriangle macro implemented with the gscan framework.
    It performs nr_cycles cycles, each consisting of two stages: the first half
    of the cycle it behaves like the ascan macro (from start_pos to stop_pos in
    nr_interv+1 steps).For the second half of the cycle it steps back until
    it undoes the first half and is ready for the next cycle.
    At each step, nr_samples acquisitions are performed.
    The total number of points in the scan is nr_interv*2*nr_cycles*nr_samples+1"""

    hints = {
        "scan": "toothedtriangle",
        "allowsHooks": (
            "pre-scan",
            "pre-move",
            "post-move",
            "pre-acq",
            "post-acq",
            "post-step",
            "post-scan",
        ),
    }
    env = ("ActiveMntGrp",)

    param_def = [
        ["motor", Type.Moveable, None, "Motor to move"],
        ["start_pos", Type.Float, None, "start position"],
        ["final_pos", Type.Float, None, "position after half cycle"],
        ["nr_interv", Type.Integer, None, "Number of intervals in half cycle"],
        ["integ_time", Type.Float, None, "Integration time"],
        ["nr_cycles", Type.Integer, None, "Number of cycles"],
        ["nr_samples", Type.Integer, 1, "Number of samples at each point"],
    ]

    def prepare(
        self,
        motor,
        start_pos,
        final_pos,
        nr_interv,
        integ_time,
        nr_cycles,
        nr_samples,
        **opts,
    ):
        self.start_pos = start_pos
        self.final_pos = final_pos
        self.nr_interv = nr_interv
        self.integ_time = integ_time
        self.nr_cycles = nr_cycles
        self.nr_samples = nr_samples
        self.opts = opts
        cycle_nb_points = self.nr_interv + 1 + (self.nr_interv + 1) - 2
        self.nb_points = cycle_nb_points * nr_samples * nr_cycles + nr_samples

        self.interv_size = (self.final_pos - self.start_pos) / nr_interv
        self.name = "toothedtriangle"

        generator = self._generator
        moveables = []
        moveable = MoveableDesc(
            moveable=motor,
            is_reference=True,
            min_value=min(start_pos, final_pos),
            max_value=max(start_pos, final_pos),
        )
        moveables = [moveable]
        env = opts.get("env", {})
        constrains = []
        extrainfodesc = [
            ColumnDesc(name="cycle", dtype="int64", shape=()),
            ColumnDesc(name="interval", dtype="int64", shape=()),
            ColumnDesc(name="sample", dtype="int64", shape=()),
        ]  # !!!

        self._gScan = SScan(
            self, generator, moveables, env, constrains, extrainfodesc
        )  # !!!

    def _generator(self):
        step = {}
        step["integ_time"] = self.integ_time
        step["pre-move-hooks"] = self.getHooks("pre-move")
        step["post-move-hooks"] = self.getHooks("post-move")
        step["pre-acq-hooks"] = self.getHooks("pre-acq")
        step["post-acq-hooks"] = self.getHooks("post-acq") + self.getHooks("_NOHINT_")
        step["post-step-hooks"] = self.getHooks("post-step")
        step["check_func"] = []
        extrainfo = {
            "cycle": None,
            "interval": None,
            "sample": None,
        }
        step["extrainfo"] = extrainfo
        halfcycle1 = list(range(self.nr_interv + 1))
        halfcycle2 = halfcycle1[1:-1]
        halfcycle2.reverse()
        intervallist = halfcycle1 + halfcycle2
        point_no = 0
        for cycle in range(self.nr_cycles):
            extrainfo["cycle"] = cycle
            for interval in intervallist:
                extrainfo["interval"] = interval
                step["positions"] = numpy.array(
                    [self.start_pos + (interval) * self.interv_size], dtype="d"
                )
                for sample in range(self.nr_samples):
                    extrainfo["sample"] = sample
                    step["point_id"] = point_no
                    yield step
                    point_no += 1

        # last step for closing the loop
        extrainfo["interval"] = 0
        step["positions"] = numpy.array([self.start_pos], dtype="d")
        for sample in range(self.nr_samples):
            extrainfo["sample"] = sample
            step["point_id"] = point_no
            yield step
            point_no += 1

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

    @property
    def data(self):
        return self._gScan.data

    def _get_nr_points(self):
        msg = "nr_points is deprecated since version 3.0.3. Use nb_points instead."
        self.warning(msg)
        return self.nb_points

    nr_points = property(_get_nr_points)


class a2scan_mod(Macro):
    """a2scan_mod.
    Do an a2scan with the particularity of different intervals per motor: int_mot1, int_mot2.
    If int_mot2 < int_mot1, mot2 will change position every int(int_mot1/int_mot2) steps of mot1.
    It uses the gscan framework.
    """

    hints = {"scan": "a2scan_mod"}
    env = ("ActiveMntGrp",)

    param_def = [
        ["motor1", Type.Moveable, None, "Motor 1 to move"],
        ["start_pos1", Type.Float, None, "Scan start position 1"],
        ["final_pos1", Type.Float, None, "Scan final position 1"],
        ["nr_interv1", Type.Integer, None, "Number of scan intervals of Motor 1"],
        ["motor2", Type.Moveable, None, "Motor 2 to move"],
        ["start_pos2", Type.Float, None, "Scan start position 2"],
        ["final_pos2", Type.Float, None, "Scan final position 2"],
        ["nr_interv2", Type.Integer, None, "Number of scan intervals of Motor 2"],
        ["integ_time", Type.Float, None, "Integration time"],
    ]

    def prepare(
        self,
        motor1,
        start_pos1,
        final_pos1,
        nr_interv1,
        motor2,
        start_pos2,
        final_pos2,
        nr_interv2,
        integ_time,
        **opts,
    ):
        self.name = "a2scan_mod"
        self.integ_time = integ_time
        self.start_pos1 = start_pos1
        self.final_pos1 = final_pos1
        self.nr_interv1 = nr_interv1
        self.start_pos2 = start_pos2
        self.final_pos2 = final_pos2
        self.nr_interv2 = nr_interv2

        generator = self._generator
        moveables = [motor1, motor2]
        env = opts.get("env", {})
        constraints = []
        self._gScan = SScan(self, generator, moveables, env, constraints)

    def _generator(self):
        step = {}
        step["integ_time"] = self.integ_time

        start1, end1, interv1 = self.start_pos1, self.final_pos1, self.nr_interv1
        start2, end2, interv2 = self.start_pos2, self.final_pos2, self.nr_interv2

        # Prepare the positions
        positions_m1 = numpy.linspace(start1, end1, interv1 + 1)
        positions_m2 = numpy.linspace(start2, end2, interv2 + 1)

        if interv1 > interv2:
            positions_m2 = start2 + ((end2 - start2) / interv2) * (
                numpy.arange(interv1 + 1) // (interv1 / interv2)
            )
        elif interv2 > interv1:
            positions_m1 = start1 + ((end1 - start1) / interv1) * (
                numpy.arange(interv2 + 1) // (interv2 / interv1)
            )

        point_id = 0
        for pos1, pos2 in zip(positions_m1, positions_m2):
            step["point_id"] = point_id
            step["positions"] = [pos1, pos2]
            yield step
            point_id += 1

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


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.
    """

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

    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
        # the "env" dictionary may be passed as an option
        env = opts.get("env", {})

        # 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


class ascan_with_addcustomdata(ascan_demo):
    """
    example of an ascan-like macro where we demonstrate how to pass custom data to the data handler.
    This is an extension of the ascan_demo macro. Wemake several calls to `:meth:DataHandler.addCustomData`
    exemplifying different features.
    At least the following recorders will act on custom data:
      - OutputRecorder (this will ignore array data)
      - NXscan_FileRecorder
      - SPEC_FileRecorder (this will ignore array data)
    """

    def run(self, motor, start_pos, final_pos, nr_interv, integ_time, **opts):
        # we get the datahandler
        dh = self._gScan._data_handler
        # at this point the entry name is not yet set, so we give it explicitly
        # (otherwise it would default to "entry")
        dh.addCustomData(
            "Hello world1",
            "dummyChar1",
            nxpath="/custom_entry:NXentry/customdata:NXcollection",
        )
        # this is the normal scan loop
        for step in self._gScan.step_scan():
            yield step
        # the entry number is known and the default nxpath is used
        # "/<currententry>/custom_data") if none given
        dh.addCustomData("Hello world1", "dummyChar1")
        # you can pass arrays (but not all recorders will handle them)
        dh.addCustomData(list(range(10)), "dummyArray1")
        # you can pass a custom nxpath *relative* to the current entry
        dh.addCustomData("Hello world2", "dummyChar2", nxpath="sample:NXsample")

        # calculate a linear fit to the timestamps VS motor positions and store
        # it
        x = [r.data[motor.getName()] for r in self.data.records]
        y = [r.data["timestamp"] for r in self.data.records]
        fitted_y = numpy.polyval(numpy.polyfit(x, y, 1), x)
        dh.addCustomData(fitted_y, "fittedtime", nxpath="measurement:NXcollection")

        # as a bonus, plot the fit
        self.pyplot.plot(x, y, "ro")
        self.pyplot.plot(x, fitted_y, "b-")
        self.pyplot.draw()


class ascanct_midtrigger(Macro):
    """This macro demonstrates how to add an extra scan column with
    the shifted positions of the motor corresponding to the middle of the
    space interval. Be aware that the space interval does not
    necessarily correspond to the middle of the acquisition interval
    (remember about the latency time).

    This macro does not export all the ascanct features e.g. hooks.
    """

    param_def = [
        ["motor", Type.Moveable, None, "Moveable name"],
        ["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"],
        ["latency_time", Type.Float, 0, "Latency time"],
    ]

    def run(self, *args, **kwargs):
        motor = args[0]
        scan_macro = self.execMacro("ascanct", *args, **kwargs)
        # we get the datahandler
        # TODO: use public api to GScan object whenever
        # https://gitlab.com/sardana-org/sardana/-/issues/784 gets solved
        dh = scan_macro._gScan.data_handler
        # calculate position corresponding to the middle space interval
        positions = [r.data[motor.getName()] for r in scan_macro.data.records]
        first_position = positions[0]
        second_position = positions[1]
        positive_direction = second_position > first_position
        shift = abs(second_position - first_position) / 2
        if positive_direction:
            mid_positions = positions + shift
        else:
            mid_positions = positions - shift
        # add custom data column to the measurement HDF5 group with the
        # <motor_name>_mid name
        dh.addCustomData(
            mid_positions, motor.getName() + "_mid", nxpath="measurement:NXcollection"
        )

Macro plotting examples

The following examples demonstrate how to plot graphics from inside a macro. See Plotting for a tutorial on macro plotting. The complete set of pyplot examples can be found in the matplotlib gallery.

import math

import numpy
from numpy import linspace, random
from scipy.integrate import quad
from scipy.special import j0

from sardana.macroserver.macro import Type, macro


def j0i(x):
    """Integral form of J_0(x)"""

    def integrand(phi):
        return math.cos(x * math.sin(phi))

    return (1 / 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 = list(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()
    self.pyplot.draw()


@macro()
def random_image(self):
    """Shows a random image 32x32"""
    img = random.random((32, 32))
    self.pyplot.matshow(img)
    self.pyplot.draw()


@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

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

Macro input examples

The following examples demonstrate how to ask for user input inside macros.

A tutorial on macro input parameter can be found here. The API documentation: input().

from sardana.macroserver.macro import Type, imacro


@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.input("How many points?", data_type=Type.Integer)
    self.output("Points: %i", 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,
        title="Favorites",
    )
    self.output("You selected %s", ", ".join(car_brands))


@imacro()
def ask_peak(self):
    """asks user 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)


@imacro()
def ask_peak_v2(self):
    """asks user 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)


@imacro()
def ask_peak_v3(self):
    """asks user 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)


@imacro()
def ask_peak_v4(self):
    """asks user 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)


@imacro()
def ask_peak_v5(self):
    """asks user 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)

Controller examples

Controller examples are discussed together with each controller type in the Writing controllers guides. The Springfield example controllers used throughout those guides can be found next to the guide sources.