Reference

This is the auto-generated reference from the doc strings in the source code.

Scans.Defaults

This module holds the base class for the instrument defaults. This is an abstract class which will need to be overwritten for each beamline. This design was chosen because the subclass cannot be instantiated unless all of the abstract methods have been implemented. This means that we detect mistakes in the subclass the moment that the Defaults object is created, instead of in the middle of a user run when a missing method is called.

class Scans.Defaults.Defaults

A defaults object to store the correct functions for this instrument

static detector(**kwargs)

The default function for pulling a count off the detector. Takes the standard time settings (e.g. seconds, frames, uamps) as keyword arguments.

static log_file()

Returns the name of a unique log file where the scan data can be saved.

Scans.Fit

The Fit module holds the Fit class, which defines common parameters for fitting routines. It also contains implementations of some common fits (i.e. Linear and Gaussian).

class Scans.Fit.PolyFit(degree, title=None)

A fitting class for polynomials

fit(x, y)

The fit function takes arrays of independent and depedentend variables. It returns a set of parameters in a format that is convenient for this specific object.

get_y(x, fit)

get_y takes an array of independent variables and a set of model parameters and returns the expected dependent variables for those parameters

readable(fit)

Readable turns the implementation specific set of fit parameters into a human readable dictionary.

title(params)

Give the title of the fit.

Parameters:params – The list of fit method parameters

Scans.Fit.Linear = <Scans.Fit.PolyFit object>

A linear regression

Scans.Fit.Gaussian = <Scans.Fit.GaussianFit object>

A gaussian fit

class Scans.Fit.PeakFit(window=None)

A simple peak-finding fitter.

This is a simple class that finds the highest point in the data set. It will not find secondary peaks. It also requires a width parameter to give the size of the peak. For example,

>>> scan(TRANSLATION, start=-20, stop=20, step=1).Fit(PeakFit(5), uamps=1)

Will use all of the points within 5 mm of the peak when fitting the quadratic.

fit(x, y)

The fit function takes arrays of independent and depedentend variables. It returns a set of parameters in a format that is convenient for this specific object.

get_y(x, fit)

get_y takes an array of independent variables and a set of model parameters and returns the expected dependent variables for those parameters

readable(fit)

Readable turns the implementation specific set of fit parameters into a human readable dictionary.

title(center)

Give the title of the fit.

Parameters:params – The list of fit method parameters

Scans.Instrument

Instrument is an example module of an instrument setup.

The motion commands simply adjust a global variable and the measurement commands just print some information. It should never be used in production, but allows us to perform unit tests of the remaining code without needing a full instrument for the testing environment.

class Scans.Instrument.MockInstrument

This class represents a fake instrument that can be used for testing purposes.

log_file()

Returns the name of a unique log file where the scan data can be saved.

Scans.Monoid

The module defines a series of Monoid classes for handlings measurements. For the unfamiliar, a monoid is just a type that A) has a zero value and B) can be combined with other values of the same type to produce new monoids. For example, Sum is a monoid because Sum(a) + Sum(b) = Sum(a+b) and Sum(a) + Sum(0) = Sum(a).

Putting the incoming data into amonoid makes it easier to get the information out of a combined measuremnts.

class Scans.Monoid.Average(x, count=1)

This monoid calculates the average of its values.

err()

Return the uncertainty of the current value

class Scans.Monoid.ListOfMonoids(*args)

A modified list class with special helpers for handlings lists of Monoids

err()

Get the uncertainty values from the List

max()

Find the largest value in the list, including for uncertainty

min()

Find the smallest value in the list, including for uncertainty

plot(axis, xs)

Make an errorbar plot of a monoid onto an axis at a given set of x coordinates

values()

Get the numerical values from the List

class Scans.Monoid.Monoid

The Monoid base class enforces the two laws: There must be a zero operation and a combining function (add).

err()

Return the uncertainty of the current value

pure(x)

Turn a number into a member of this monoid

upgrade(x)

Ensure that a value is a member of this monoid

static zero()

The zero element of the monoid. This element obeys the law that

x + x.zero() == x

class Scans.Monoid.MonoidList(values)

This class turns a collection of Monoids into its own Monoid.

err()

Return the uncertainty of the current value

max()

Return the largest value

min()

Return the smallest value

zero()

The zero element of the monoid. This element obeys the law that

x + x.zero() == x

class Scans.Monoid.Polarisation(ups, downs=0)

This monoid calculates the polarisation from the total of all of the up and down counts.

err()

Return the uncertainty of the current value

class Scans.Monoid.StdDev(x, count=1, avg=None)

This monoid calculates the standard deviation of values presented.

err()

Return the uncertainty of the current value

class Scans.Monoid.Sum(x)

This monoid calculates the sum total of the values presented

err()

Return the uncertainty of the current value

Scans.Motion

This module contains helper classes for controlling motions on the beamline

There’s three levels of depth to this module. At the simplest level, merely import and call populate(). This create motion object for every block currently registered on the instrument.

The next level down is the BlockMotion class, which allows for creating single objects that correspond to single IBEX blocks.

Finally, at the bottom, BlockMotion derives from the Motion object, which gives a simple framework for all physical parameters that can be controlled by an instrument. Although it is called Motion, it will also handle temperatures, currents, and other physical properties.

class Scans.Motion.BlockMotion(block)

A helper class for creating motion objects from Ibex blocks

Parameters:block – A string containing the name of the ibex block to control

class Scans.Motion.Motion(getter, setter, title, low=None, high=None)

A Motion object largely acts like a function to control and interrogate a single axis of motion. When called without a parameter, it returns the current position. Being called with a parameter causes the position to update.

Example: Assume that we have some motion object Foo

>>> Foo()
7
>>> Foo(5)
>>> Foo()
5

accessible(x)

Determines whether a motor can reach the desired position.

Parameters:x – The desired position for the motor Returns:

• Tuple (Bool, Str)
• The boolean represents whether the possition can be reached
• The string is an error message explaining why the position is
• unreachable.

high

The motion’s uppder limit

low

The motion’s lower limit

require(x)

Requires that the given position is accessible. If not, an exception is thrown

Scans.Motion.populate()

Create Motion objects in the GLOBAL namespace for each block registered with IBEX.

Scans.multiplot

A demo of proper multiprocessing matplotlib

class Scans.multiplot.NBPlot(**kwargs)

A non-blocking plot to get around the threading limitations of matplotlib.

join()

Close the plot and get the results from it

class Scans.multiplot.ProcessPlotter(rehome=False)

This object maintains a separate a separate process at the OS level which manages a matplotlib plot. This is an incredibly stupid way to get around the threading limitations of matplotlib, but it’s also the best that we’ve found.

Parameters:rehome (bool) – If true, the graph will recenter itself every time a new point is added. Otherwise, the plot will remain where the user left it, but the home functionality will not be updated after the user moves the graph.

poll_draw()

Update the graph with the latest commands off the process channel

Scans.Scans

The Scans module holds the base classes for scan objects. These objects reify the steps an instrument takes in a scan and allow us to have single place where all of the various scanning methods can be condensed.

The only export of this module that should ever need to be directly accessed by other modules is SimpleScan. Everything else should be treated as private.

class Scans.Scans.ForeverScan(scan)

ForeverScan repeats the same scan over and over again to improve the statistics until the user manually halts the scan.

map(func)

The map function returns a modified scan that performs the given function on all of the original positions to return the new positions.

max()

Find the largest point in a scan

min()

Find the smallest point in a scan

class Scans.Scans.ParallelScan(first, second)

ParallelScan runs two scans alongside each other, performing both sets of position adjustments before each step of the scan.

map(func)

The map function returns a modified scan that performs the given function on all of the original positions to return the new positions.

max()

Find the largest point in a scan

min()

Find the smallest point in a scan

reverse

Creates a new scan that runs in the opposite direction

class Scans.Scans.ProductScan(outer, inner)

ProductScan performs every possible combination of the positions of its two constituent scans.

map(func)

The map function returns a modified scan that performs the given function on all of the original positions to return the new positions.

max()

Find the largest point in a scan

min()

Find the smallest point in a scan

plot(detector=None, save=None, action=None, **kwargs)

An overloading of Scan.plot to handle multidimensional scans.

reverse

Creates a new scan that runs in the opposite direction

class Scans.Scans.Scan

The virtual class that represents all controlled scans. This class should never be instantiated directly, but rather by one of its subclasses.

and_back

Run then scan both forwards and in reverse. This can help minimise motor movement.

calculate(time=False, pad=0, **kwargs)

Calculate the expected time needed to perform a scan. Additionally, print the expected time of completion.

Beyond accepting the default arguments for setting a measurement time (e.g uamps, minutes, frames), this method accept two other keywords. The pad argument is an extra time, in seconds, to add to each measurement to account for motor movements, file saving, and other such effects. The quiet keyword, if set to true, prevents the printing of the expected time of completion.

fit(fit, **kwargs)

The fit method performs the scan, plotting the points as they are taken. Once the scan is completed, a fit is then plotted over the scan and the fitting parameters are returned.

forever

Create a scan that will cycle until stopped by the user.

map(func)

The map function returns a modified scan that performs the given function on all of the original positions to return the new positions.

max()

Find the largest point in a scan

measure(title, measure=None, **kwargs)

Perform a full measurement at each position indicated by the scan. The title parameter gives the run’s title and allows for values to be interpolated into it. For instance, the string “{theta}” will include the current value of the theta motor if it is being iterated over.

WARNING: This function is deprecated and will be removed in the next release.

min()

Find the smallest point in a scan

plot(detector=None, save=None, action=None, **kwargs)

Run over the scan an perform a simple measurement at each position. The measurement parameter can be used to set what type of measurement is to be taken. If the save parameter is set to a file name, then the plot will be saved in that file.

reverse

Create a new scan that runs in the opposite direction

class Scans.Scans.SimpleScan(action, values, defaults)

SimpleScan is a scan along a single axis for a fixed set of values

map(func)

The map function returns a modified scan that performs the given function on all of the original positions to return the new positions.

max()

Find the largest point in a scan

min()

Find the smallest point in a scan

reverse

Create a new scan that runs in the opposite direction

class Scans.Scans.SumScan(first, second)

The SumScan performs two separate scans sequentially

map(func)

The map function returns a modified scan that performs the given function on all of the original positions to return the new positions.

max()

Find the largest point in a scan

min()

Find the smallest point in a scan

reverse

Creates a new scan that runs in the opposite direction

Scans.Scans.estimate(seconds=None, minutes=None, hours=None, uamps=None, frames=None, **_)

Estimate takes a measurement specification and predicts how long the measurement will take in seconds.

Scans.Scans.just_times(kwargs)

Filter a dict down to just the waitfor members

Scans.Scans.merge_dicts(x, y)

Given two dicts, merge them into a new dict as a shallow copy.

Scans.Spec

The Spec module implements a couple of commond commands from SPEC.

Scans.Spec.ascan(motor, start, end, intervals, time)

A reimplementations of ascan from spec

Example

>>> ascan(COARSEZ, -20, 20, 40, -50)

Scan the CoarseZ motor from position -20 to position 20 (inclusive) in 1 mm steps. At each point, take measure for 50 frames (about five seconds). After the plot, the CoarseZ motor will be at position 20.

Parameters:

• motor – The axis to scan
• start – The initial position
• stop – The final position
• intervals – How many steps to take between the initial and final position
• time – If positive, the measurement time at each point in seconds. If negative, the measurement frames at each point.

Scans.Spec.dscan(motor, start, end, intervals, time)

A reimplementations of dscan from spec

Example

>>> dscan(COARSEZ, -20, 20, 40, -50)

Scan the CoarseZ motor from 20 mm below the current position to position 20 mm above the current position (inclusive) in 1 mm steps. At each point, take measure for 50 frames (about five seconds). After the plot, the CoarseZ motor will move back to its original position.

Parameters:

• motor – The axis to scan
• start – The initial position as an offset from the current position
• stop – The final position as an offset from the current position
• intervals – How many steps to take between the initial and final position
• time – If positive, the measurement time at each point in seconds. If negative, the measurement frames at each point.

Scans.Spec.rscan(motor, before=None, after=None, step=None, frames=None, **kwargs)

An ISIS specific relative scan function

This function is identical to the normal scan function, but it defaults to using relative positions, instead of absolute.

Example

>>> rscan(coarsez, -20, 20, 1, 50)

Scan the CoarseZ motor from 20 mm below the current position to position 20 mm above the current position (exclusive) in 1 mm steps. At each point, take measure for 50 frames (about five seconds). After the plot, the CoarseZ motor will move back to its original position.

Parameters:

• motor – The axis to scan
• before – The initial position as an offset from the current position
• after – The ending position as an offset from the current position
• step – The absolute step size
• frames – The number of pulse frames to measure at each point

Scans.Util

The Util module contains functions which are useful for the instrument scientist in defining their beamline. Nothing in this module should ever need to be called by the end user.

Scans.Util.get_points(current, start=None, stop=None, step=None, stride=None, count=None, gaps=None, before=None, after=None, **_)

This function takes a dictionary of keyword arguments for a scan and returns the points at which the scan should be measured.

This function provides many ways to define a scan

• start point, stop point, and number of points
• start point, stop point, and spacing
• start point, spacing, and number of points

Parameters:

• current (float) – The present position of the motor. This is needed to relative scans.
• start (float) – The absolute first position in the scan. This is a valid start point.
• stop (float) – The absolute final position in the scan. This is a valid stop point.
• before (float) – The relative first position in the scan. If the motor is currently at 3 and before is set to -5, then the first scan point will be -2. This is a valid start point.
• after (float) – The relative final position in the scan. If the motor is currently at 3 and before is set to 5, then the last scan point will be 8. This is a valid stop point.
• step (float) – The fixed distance between points. If the distance between the beginning and end aren’t an exact multiple of this step size, then the end point will not be included. This is a valid spacing.
• stride (float) – The approximate distance between points. In order to ensure that the start and stop points are included in the scan, a finer resolution scan will be called for if the stride is not an exact multiple of the distance. This is a valid spacing.
• count (float) – The number of measurements to perform. A scan with a count of 2 would measure at only the beginning and the end. This is a valid number of points.
• gaps (float) – The number of steps that the motor will take. A scan with a gaps of 1 would measure at only the beginning and the end. This is a valid number of points.

Returns:

The positions for the scan.

Return type:

Array of Floats

Raises:

RuntimeError – If the supplied parameters cannot be combined into a coherent scan.

Scans.Util.make_scan(defaults)

This is a helper function to be used by the instrument scientist. Given a defaults class that holds the default values needed for scans, it creates a scan function that uses those default values.

The basic usage is that the instrument science will have some module for setting up their instrument, which will include

>>> scan = make_scan(my_defaults)

The main python environment will then import scan from that module