Scan Functions

So far Py4Syn can handle three scan types:

• Scan

  • All devices must have the same number of steps and they will step toguether. You can specify as many devices as you want, there’s no limitation with this.
  • The only restriction is that the used devices must implement the IScannable interface. For more information about IScannable Interface please check py4syn.epics.IScannable.

• Mesh

  • No concern about devices number of steps. You can specify as many devices as you want.
  • The only restriction is that the used device must implement the IScannable interface. For more information about IScannable Interface please check py4syn.epics.IScannable.

• Time

  • No devices, scan runs over time. User specify the counting time and delay time in seconds, both default to 1.

Handling the Data

At Py4Syn all the scan data is stored in a memory dictionary in order to ensure great speed. Data inside the SCAN_DATA dictionary is organized as follows:

Index	Content
‘points’	Array of points, [0, 1, 2, 3…N]
‘scan_object’	Reference to the Scan object
devices mnemonic	For each device used in the scan an entry to store this device value across the scan is created, e.g. SCAN_DATA[‘tth’] represents the array of tth positions
counters mnemonic	For each counter registered an entry to store this device value across the scan is created, e.g. SCAN_DATA[‘mon’] represents the array of mon values
‘scan_start’	Timestamp of scan start
‘scan_end’	Timestamp of scan end
‘scan_duration’	Scan duration. (‘scan_end’ - ‘scan_start’)
Any other user data	Any value you want, but beware that this values must be created using the py4syn.utils.scan.createUserDefinedDataField() method in order to be saved in the file.

Callbacks

There are 7 callbacks available:

• Pre Scan Callback

  • This callback is executed at the beginning of the scan

• Pre Point Callback

  • This callback is executed before the point (before motors movement, or any other device setup)

• Pre Operation Callback

  • This callback is executed before the operation, before launching the counters

• Operation Callback

  • This is the main callback, it’s executed while the counters are running

• Post Operation Callback

  • This callback is executed after the operation, after the counters stop and before the plot and screen update

• Post Point Callback

  • This callback is executed right after the operation callback and before a new movement

• Post Scan Callback

  • This callback is executed at the end of the scan

If one wants to define specific callbacks it’s possible by following the recipe below:

# Creating my function that will be executed in the choosen callback
# This function needs to receive a parameter **kwargs
def myCallback(**kwargs):
   scanObject = kwargs['scan']
   indexArray = kwargs['idx']
   positionArray = kwargs['pos']
   print('Message from my callback')

# This shows how to move back to the default callback from py4syn
setPreScanCallback(defaultPreScanCallback)

# Set my function to the operation callback
setOperationCallback(mycallback)

# Run the scan with the new configurations
scan('m1', 0, 180, 10, 1)

Attention

By overwriting an existing callback you assume that you will handle all the operations that you have overwritten. Also, user is responsible by the dead-time generated by the custom callbacks.

Special variables in the Scan module

In the Scan module there are some GLOBAL variables that can be read and configured. To access this variables you can either use the scan module or the appropriate getter and setter methods.

Variable	Content	Getter	Setter
SCAN_DATA	Ordered Dictionary that contains all scan related data	getScanData()
SCAN_CMD	String with the last scan command executed	getScanCommand()
SCAN_COMMENT	String with a comment to be added to the scan file	getScanComment()	setScanComment()
SCAN_PLOTTER	Scan Object to be used when plotting data	getScanPlotter()	setScanPlotter()
SCAN_PLOTTER_AXIS	Axis index to be used in the plotter	getScanPlotterAxis()	setScanPlotterAxis()
FILENAME	String that represents the filename to be used, if None stores only in memory. See setOutput for more information.	getOutput()	setOutput()
XFIELD	String that represents the Mnemonic of the X axis. See setX for more information.	getX()	setX()
YFIELD	String that represents the Mnemonic of the Y axis. See setY for more information.	getY()	setY()
FWHM	Double that represents the FWHM value.	getFwhm()
FWHM_AT	Double that represents the FWHM position.	getFwhmAt()
COM	Double that represents the COM (Center of Mass) value.	getCom()
PEAK	Double that represents the Peak value.	getPeak()
PEAK_AT	Double that represents the Peak position.	getPeakAt()
MIN	Double that represents the Minimum value.	getMin()
MIN_AT	Double that represents the Minimum value position.	getMinAt()
FITTED_DATA	Array that represents the best fit values.	getFittedData()
FIT_RESULT	ModelFit with fit result information.	getFitResult()
FIT_SCAN	Boolean that represents if we should or not fit the scan data at end. Default is True	getFitScan()	setFitScan()
PRINT_SCAN	Boolean that represents if we should or not print to the terminal the scan information. Default is True	getPrintScan()	setPrintScan()
PLOT_GRAPH	Boolean that represents if we should or not create the real-time plot. Default is True	getPlotGraph()	setPlotGraph()
PRE_SCAN_CALLBACK	Function pointer for the Pre Scan Callback. Default is defaultPreScanCallback.	getPreScanCallback()	setPreScanCallback()
PRE_POINT_CALLBACK	Function pointer for the Pre Point Callback. Default is None.	getPrePointCallback()	setPrePointCallback()
PRE_OPERATION_CALLBACK	Function pointer for the Pre Operation Callback. Default is None.	getPreOperationCallback()	setPreOperationCallback()
OPERATION_CALLBACK	Function pointer for the Operation Callback. Default is defaultOperationCallback.	getOperationCallback()	setOperationCallback()
POST_OPERATION_CALLBACK	Function pointer for the Post Operation Callback. Default is None.	getPostOperationCallback()	setPostOperationCallback()
POST_POINT_CALLBACK	Function pointer for the Post Point Callback. Default is None.	getPostPointCallback()	setPostPointCallback()
POST_SCAN_CALLBACK	Function pointer for the Post Scan Callback. Default is defaultPostScanCallback	getPostScanCallback()	setPostScanCallback()

Functions from the Scan module

exception py4syn.utils.scan.ScanInterruptedException

Scan was interrupted

class py4syn.utils.scan.ScanStateEnum

An enumeration.

class py4syn.utils.scan.ScanType

An enumeration.

py4syn.utils.scan.clearUserDefinedDataField()

Remove all user defined fields

Examples

>>> clearUserDefinedDataField()

py4syn.utils.scan.createUserDefinedDataField(field_name)

Create an user defined field in the SCAN_DATA dictionary

Parameters:

field_name : string

Field name

Examples

>>> createUserDefinedDataField("norm")

py4syn.utils.scan.fitData(x, y)

Try to fit a Gaussian to data and calculate the MAX, FWHM and COM (Center of Mass)

Parameters:

x : array

X data

y : array

Y data

Examples

>>> fitData(myDataX, myDataY)
>>> print("Peak ", PEAK, " at ", PEAK_AT)
>>> print("Fwhm ", FWHM, " at ", FWHM_AT)
>>> print("COM = ", COM)

py4syn.utils.scan.getCom()

Get the Center Of Mass of Fit (COM)

Returns:

`double`

py4syn.utils.scan.getFileWriter()

Get the current File Writer. See py4syn.writing.FileWriter

Returns:

`FileWriter`

py4syn.utils.scan.getFitResult()

Get the fit results.

Returns:

`ModelFit`

py4syn.utils.scan.getFitScan()

Get the global variable FIT_SCAN to enable or disable the scan fit at end

Returns:

`bool`

py4syn.utils.scan.getFitValues()

Get the Fit values (Peak value, Peak Position, FWHM, FWHM Position and Center of Mass)

Returns:

`list`

py4syn.utils.scan.getFittedData()

Get the best fit data.

Returns:

`array`

py4syn.utils.scan.getFwhm()

Get the FWHM value of Fit

Returns:

`double`

py4syn.utils.scan.getFwhmAt()

Get the FWHM position of Fit

Returns:

`double`

py4syn.utils.scan.getMin()

Get the Min value of Fit

Returns:

`double`

py4syn.utils.scan.getMinAt()

Get the Min position of Fit

Returns:

`double`

py4syn.utils.scan.getOperationCallback(c)

Get the operation callback.

Returns:

`function`

py4syn.utils.scan.getOutput()

Get the Output, if output is set to None then the data is only stored in the SCAN_DATA dictionary.

Returns:

`string`

py4syn.utils.scan.getPartialWrite()

Check if Partial write is enable.

Returns:

`bool`

py4syn.utils.scan.getPeak()

Get the Peak value of Fit

Returns:

`double`

py4syn.utils.scan.getPeakAt()

Get the Peak position of Fit

Returns:

`double`

py4syn.utils.scan.getPlotGraph()

Get the global variable PLOT_GRAPH value

Returns:

`bool`

py4syn.utils.scan.getPostOperationCallback(c)

Get the post operation callback.

Returns:

`function`

py4syn.utils.scan.getPostPointCallback(c)

Get the post point callback.

Returns:

`function`

py4syn.utils.scan.getPostScanCallback(c)

Get the post scan callback.

Returns:

`function`

py4syn.utils.scan.getPreOperationCallback(c)

Get the pre operation callback.

Returns:

`function`

py4syn.utils.scan.getPrePointCallback(c)

Get the pre point callback.

Returns:

`function`

py4syn.utils.scan.getPreScanCallback(c)

Get the pre scan callback.

Returns:

`function`

py4syn.utils.scan.getPrintScan()

Get the global variable PRINT_SCAN value

Returns:

`bool`

py4syn.utils.scan.getScanCommand()

Get the last scan command executed

Returns:

`string`

py4syn.utils.scan.getScanComment()

Get the custom comment

Returns:

`string`

The comment to be inserted

Examples

>>> print(getScanComment())

py4syn.utils.scan.getScanData()

Get the SCAN_DATA dictionary

Returns:

`dictionary`

py4syn.utils.scan.getScanPlotter()

Get the current plotter

Returns:

`Plotter`

The current plotter

Examples

>>> p = getScanPlotter()

py4syn.utils.scan.getScanPlotterAxis()

Get the current plotter axis

Returns:

`int`

The current axis

Examples

>>> p = getScanPlotterAxis()

py4syn.utils.scan.getX()

Get which field will be used to plot in the X axis

Returns:

`string`

py4syn.utils.scan.getY()

Get which field will be used to plot in the X axis

Returns:

`string`

py4syn.utils.scan.mesh(*kwargs)

Run a mesh scan with the given parameters

Parameters:

kwargs : *

List of parameters in the following order: device, start, end, points, device2, start2, end2, points2, …, deviceN, startN, endN, pointsN, time, delay.

Note

To use variable time for each point instead of an value user should pass an array with the time to count in each point.

Note

Instead of the common use of start and end, one can use an array of points. Beware that the array length cannot be different of points parameter.

Note

To use delay between points one can use a scalar value representing the number of seconds to wait until acquire next point, for variable delay time instead of an value user should pass an array.

Examples

>>> createMotor('m1', 'SOL:DMC1:m1')
>>> createMotor('m2', 'SOL:DMC1:m2')
>>> scalerSOL = Scaler("SOL2:SCALER", 10, "scalerSOL")
>>> createCounter("seconds", scalerSOL, 1, factor=1e+7)
>>> createCounter("S10", scalerSOL, 10, monitor=True)
>>> setX("points")
>>> setY("S10")
>>> setOutput("/home/ABTLUS/hugo.slepicka/mesh1.txt")
>>> mesh('m1', 0, 1, 15, 'm2', 0, 180, 1001, 0.01)
>>> print("Scan Ended")
>>> print("Time elapsed: ", SCAN_DATA['scan_duration'])

py4syn.utils.scan.plot()

Plot a graph using the fields set in XFIELD and YFIELD.

Examples

>>> setX("m1")
>>> setY("det")
>>> plot()

py4syn.utils.scan.removeUserDefinedDataField(field_name)

Remove an user defined field in the SCAN_DATA dictionary

Parameters:

field_name : string

Field name

Examples

>>> removeUserDefinedDataField("norm")

py4syn.utils.scan.scan(*args, **kwargs)

Run a scan with the given parameters

Parameters:

args : *

List of parameters in the following order: device, start, end, points, time or device, start, end, device2, start2, end2,…, deviceN, startN, endN, points, time, delay.

Note

To use variable time for each point instead of an value user should pass an array with the time to count in each point.

Note

Instead of the common use of start and end, one can use an array of points. Beware that the array length cannot be different of points parameter.

Note

To use delay between points one can use a scalar value representing the number of seconds to wait until acquire next point, for variable delay time instead of an value user should pass an array.

Examples

>>> createMotor('m1', 'SOL:DMC1:m1')
>>> createMotor('m2', 'SOL:DMC1:m2')
>>> scalerSOL = Scaler("SOL2:SCALER", 10, "scalerSOL")
>>> createCounter("seconds", scalerSOL, 1, factor=1e+7)
>>> createCounter("S10", scalerSOL, 10, monitor=True)
>>> setX("points")
>>> setY("S10")
>>> setOutput("/home/ABTLUS/hugo.slepicka/scan1.txt")
>>> scan('m1', 0, 1, 15, 0.01)
>>> print("Scan Ended")
>>> print("Time elapsed: ", SCAN_DATA['scan_duration'])

py4syn.utils.scan.setFileWriter(writer)

Set the file writer to be used in order to save the data. If None is informed the DefaultWriter is used, generating a PyMCA-like file.

Parameters:

writer : FileWriter

Examples

>>> writer = DefaultWriter("/tmp/test.txt")
>>> setFileWrite(writer)

py4syn.utils.scan.setFitScan(b)

Set the global variable FIT_SCAN to enable or disable the scan fit at end

Parameters:

b : bool

py4syn.utils.scan.setOperationCallback(c)

Set the operation callback.

Parameters:

c : function

A function to be executed

Note

This function must receive an argument **kwargs

Examples

>>> def myCallback(**kwargs):
>>>     print("Print from my callback")
>>>
>>> setOperationCallback(myCallback)
>>>

py4syn.utils.scan.setOutput(out)

Set the Output, if output is set to None then the data is only stored in the SCAN_DATA dictionary.

Parameters:

out : string

The complete filename.

Note

The files will be renamed to fit the format: filename_000N.ext.

Each file represents one scan and they are automatically incremented.

Examples

>>> setOutput("/home/user/teste.txt")

py4syn.utils.scan.setPartialWrite(partial)

Set enable or disable the Partial Write, if partial is set to True then the data written every iteration, otherwise data is only saved at the end.

Parameters:

partial : bool

Examples

>>> setPartialWrite(True)

py4syn.utils.scan.setPlotDaemon(b)

Configure if the scan plot should or not be daemon

Parameters:

b : bool

True of False indicating if should be daemon

Examples

>>> setPlotDaemon(True)

py4syn.utils.scan.setPlotGraph(b)

Set the global variable PLOT_GRAPH to enable or disable the live plot

Parameters:

b : bool

py4syn.utils.scan.setPostOperationCallback(c)

Set the post operation callback.

Parameters:

c : function

A function to be executed

Note

This function must receive an argument **kwargs

Examples

>>> def myCallback(**kwargs):
>>>     print("Print from my callback")
>>>
>>> setPostOperationCallback(myCallback)
>>>

py4syn.utils.scan.setPostPointCallback(c)

Set the post point callback.

Parameters:

c : function

A function to be executed

Note

This function must receive an argument **kwargs

Examples

>>> def myCallback(**kwargs):
>>>     print("Print from my callback")
>>>
>>> setPostPointCallback(myCallback)
>>>

py4syn.utils.scan.setPostScanCallback(c)

Set the post scan callback.

Parameters:

c : function

A function to be executed

Note

This function must receive an argument **kwargs

Examples

>>> def myCallback(**kwargs):
>>>     print("Print from my callback")
>>>
>>> setPostScanCallback(myCallback)
>>>

py4syn.utils.scan.setPreOperationCallback(c)

Set the pre operation callback.

Parameters:

c : function

A function to be executed

Note

This function must receive an argument **kwargs

Examples

>>> def myCallback(**kwargs):
>>>     print("Print from my callback")
>>>
>>> setPreOperationCallback(myCallback)
>>>

py4syn.utils.scan.setPrePointCallback(c)

Set the pre point callback.

Parameters:

c : function

A function to be executed

Note

This function must receive an argument **kwargs

Examples

>>> def myCallback(**kwargs):
>>>     print("Print from my callback")
>>>
>>> setPrePointCallback(myCallback)
>>>

py4syn.utils.scan.setPreScanCallback(c)

Set the pre scan callback.

Parameters:

c : function

A function to be executed

Note

This function must receive an argument **kwargs

Examples

>>> def myCallback(**kwargs):
>>>     print("Print from my callback")
>>>
>>> setPreScanCallback(myCallback)
>>>

py4syn.utils.scan.setPrintScan(b)

Set the global variable PRINT_SCAN to enable or disable the scan print on terminal

Parameters:

b : bool

py4syn.utils.scan.setScanComment(c)

Insert a custom comment in the scan file

Parameters:

c : string

The comment to be inserted

Examples

>>> setScanComment("Scan of sample X, using Y")

py4syn.utils.scan.setScanPlotter(p)

Define the Plotter to be used in the scan

Parameters:

p : Plotter

The plotter to be used

Examples

>>> p = Plotter("My Plotter ", daemon=False)
>>> setScanPlotter(p)

py4syn.utils.scan.setScanPlotterAxis(ax)

Define the axis index to be used when plotting

Parameters:

ax : int

The axis index to be used when plotting

Examples

>>> p = Plotter("My Plotter ", daemon=False)
>>> p.createAxis("", label="Data label", xlabel="Energy", ylabel="I0",
>>> grid=True, line_style="-", line_marker=".", line_color="blue")
>>> setScanPlotter(p)
>>> setScanPlotterAxis(1)

py4syn.utils.scan.setX(x)

Set which field will be used to plot in the X axis

Parameters:

x : string

Mneumonic of the data, e.g. “m1”, “tth”, “det”, “mon”

Examples

>>> setX("tth")

py4syn.utils.scan.setY(y)

Set which field will be used to plot in the Y axis

Parameters:

y : string

Mneumonic of the data, e.g. “m1”, “tth”, “det”, “mon”

Examples

>>> setY("mon")

py4syn.utils.scan.timescan(t=1, delay=1, repeat=-1)

Executes a scan in time.

Parameters:

t : double

Time in seconds to count

delay : double

Time to wait before new count

repeat : int

Number of repeats to acquire (default is infinity), if repeat = 1 it will run 2 times an acquire