API#

`scanspec`#

The top level scanspec module contains a number of packages that can be used from code:

scanspec.core: Core classes like Frames and Path
scanspec.specs: Spec and its subclasses
scanspec.regions: Region and its subclasses
scanspec.plot: plot_spec to visualize a scan
scanspec.service: Defines queries and field structure in graphQL such as PointsResponse

scanspec.__version__: str#: Version number as calculated by dls-controls/versiongit

`scanspec.core`#

scanspec.core.alternative_constructor(f)[source]#

This will be returned as a staticmethod so the signature should not include self/cls.

>>> import dataclasses
>>> @dataclasses.dataclass
... class Foo:
...     a: int
...     @alternative_constructor
...     def doubled(b: int) -> "Foo":
...         return Foo(b * 2)
...
>>> Foo.doubled(2)
Foo(a=4)

scanspec.core.as_tagged_union(cls: Type)[source]#: Used by Spec and Region so they serialize as a tagged union.

scanspec.core.if_instance_do(x: Any, cls: Type, func: Callable)[source]#

If x is of type cls then return func(x), otherwise return NotImplemented.

Used as a helper when implementing operator overloading.

scanspec.core.Axis#

A type variable for an Axis that can be specified for a scan

alias of TypeVar(‘Axis’)

scanspec.core.AxesPoints#

Map of axes to float ndarray of points E.g. {xmotor: array([0, 1, 2]), ymotor: array([2, 2, 2])}

alias of Dict[Axis, ndarray]

class scanspec.core.Frames(midpoints: AxesPoints[Axis], lower: Optional[AxesPoints[Axis]] = None, upper: Optional[AxesPoints[Axis]] = None, gap: Optional[np.ndarray] = None)[source]#

Bases: Generic[Axis]

Represents a series of scan frames along a number of axes.

During a scan each axis will traverse lower-midpoint-upper for each frame.

Parameters:

midpoints – The midpoints of scan frames for each axis
lower – Lower bounds of scan frames if different from midpoints
upper – Upper bounds of scan frames if different from midpoints
gap – If supplied, define if there is a gap between frame and previous otherwise it is calculated by looking at lower and upper bounds

Typically used in two ways:

A list of Frames objects returned from Spec.calculate represents a scan as a linear stack of frames. Interpreted as nested from slowest moving to fastest moving, so each faster Frames object will iterate once per position of the slower Frames object. It is passed to a Path for calculation of the actual scan path.
A single Frames object returned from Path.consume represents a chunk of frames forming part of a scan path, for interpretation by the code that will actually perform the scan.

See also

Technical Terms

midpoints#: The midpoints of scan frames for each axis

lower#: The lower bounds of each scan frame in each axis for fly-scanning

upper#: The upper bounds of each scan frame in each axis for fly-scanning

gap#: Whether there is a gap between this frame and the previous. First element is whether there is a gap between the last frame and the first

axes() → List[Axis][source]#

The axes which will move during the scan.

These will be present in midpoints, lower and upper.

extract(indices: ndarray, calculate_gap=True) → Frames[Axis][source]#

Return a new Frames object restricted to the indices provided.

Parameters:

indices – The indices of the frames to extract, modulo scan length
calculate_gap – If True then recalculate the gap from upper and lower

>>> frames = Frames({"x": np.array([1, 2, 3])})
>>> frames.extract(np.array([1, 0, 1])).midpoints
{'x': array([2, 1, 2])}

concat(other: Frames[Axis], gap: bool = False) → Frames[Axis][source]#

Return a new Frames object concatenating self and other.

Requires both Frames objects to have the same axes, but not necessarily in the same order. The order is inherited from self, so other may be reordered.

Parameters:

other – The Frames to concatenate to self
gap – Whether to force a gap between the two Frames objects

>>> frames = Frames({"x": np.array([1, 2, 3]), "y": np.array([6, 5, 4])})
>>> frames2 = Frames({"y": np.array([3, 2, 1]), "x": np.array([4, 5, 6])})
>>> frames.concat(frames2).midpoints
{'x': array([1, 2, 3, 4, 5, 6]), 'y': array([6, 5, 4, 3, 2, 1])}

zip(other: Frames[Axis]) → Frames[Axis][source]#

Return a new Frames object merging self and other.

Require both Frames objects to not share axes.

>>> fx = Frames({"x": np.array([1, 2, 3])})
>>> fy = Frames({"y": np.array([5, 6, 7])})
>>> fx.zip(fy).midpoints
{'x': array([1, 2, 3]), 'y': array([5, 6, 7])}

class scanspec.core.SnakedFrames(midpoints: AxesPoints[Axis], lower: Optional[AxesPoints[Axis]] = None, upper: Optional[AxesPoints[Axis]] = None, gap: Optional[np.ndarray] = None)[source]#

Bases: Frames[Axis]

Like a Frames object, but each alternate repetition will run in reverse.

classmethod from_frames(frames: Frames[Axis]) → SnakedFrames[Axis][source]#: Create a snaked version of a Frames object.

extract(indices: ndarray, calculate_gap=True) → Frames[Axis][source]#

Return a new Frames object restricted to the indices provided.

Parameters:

indices – The indices of the frames to extract, can extend past len(self)
calculate_gap – If True then recalculate the gap from upper and lower

>>> frames = SnakedFrames({"x": np.array([1, 2, 3])})
>>> frames.extract(np.array([0, 1, 2, 3, 4, 5])).midpoints
{'x': array([1, 2, 3, 3, 2, 1])}

scanspec.core.gap_between_frames(frames1: Frames[Axis], frames2: Frames[Axis]) → bool[source]#: Is there a gap between end of frames1 and start of frames2.

scanspec.core.squash_frames(stack: List[Frames[Axis]], check_path_changes=True) → Frames[Axis][source]#

Squash a stack of nested Frames into a single one.

Parameters:

stack – The Frames stack to squash, from slowest to fastest moving
check_path_changes – If True then check that nesting the output Frames object within others will provide the same path as nesting the input Frames stack within others

>>> fx = SnakedFrames({"x": np.array([1, 2])})
>>> fy = Frames({"y": np.array([3, 4])})
>>> squash_frames([fy, fx]).midpoints
{'y': array([3, 3, 4, 4]), 'x': array([1, 2, 2, 1])}

class scanspec.core.Path(stack: List[Frames[Axis]], start: int = 0, num: Optional[int] = None)[source]#

Bases: Generic[Axis]

A consumable route through a stack of Frames, representing a scan path.

Parameters:

stack – The Frames stack describing the scan, from slowest to fastest moving
start – The index of where in the Path to start
num – The number of scan frames to produce after start. None means up to the end

See also

How to Iterate a Spec

stack#: The Frames stack describing the scan, from slowest to fastest moving

index#: Index that is next to be consumed

lengths#: The lengths of all the stack

end_index#: Index of the end frame, one more than the last index that will be produced

consume(num: Optional[int] = None) → Frames[Axis][source]#

Consume at most num frames from the Path and return as a Frames object.

>>> fx = SnakedFrames({"x": np.array([1, 2])})
>>> fy = Frames({"y": np.array([3, 4])})
>>> path = Path([fy, fx])
>>> path.consume(3).midpoints
{'y': array([3, 3, 4]), 'x': array([1, 2, 2])}
>>> path.consume(3).midpoints
{'y': array([4]), 'x': array([1])}
>>> path.consume(3).midpoints
{'y': array([], dtype=int64), 'x': array([], dtype=int64)}

class scanspec.core.Midpoints(stack: List[Frames[Axis]])[source]#

Bases: Generic[Axis]

Convenience iterable that produces the scan midpoints for each axis.

For better performance, consume from a Path instead.

Parameters:: stack – The stack of Frames describing the scan, from slowest to fastest moving

See also

How to Iterate a Spec

>>> fx = SnakedFrames({"x": np.array([1, 2])})
>>> fy = Frames({"y": np.array([3, 4])})
>>> mp = Midpoints([fy, fx])
>>> for p in mp: print(p)
{'y': 3, 'x': 1}
{'y': 3, 'x': 2}
{'y': 4, 'x': 2}
{'y': 4, 'x': 1}

stack#: The stack of Frames describing the scan, from slowest to fastest moving

property axes: List[Axis]#: The axes that will be present in each points dictionary.

`scanspec.specs`#

scanspec.specs.DURATION = 'DURATION'#: Can be used as a special key to indicate how long each point should be

class scanspec.specs.Spec[source]#

Bases: Generic[Axis]

A serializable representation of the type and parameters of a scan.

Abstract baseclass for the specification of a scan. Supports operators:

*: Outer Product of two Specs, nesting the second within the first. If the first operand is an integer, wrap it in a Repeat
&: Mask the Spec with a Region, excluding midpoints outside of it
~: Snake the Spec, reversing every other iteration of it

axes() → List[Axis][source]#

Return the list of axes that are present in the scan.

Ordered from slowest moving to fastest moving.

calculate(bounds=True, nested=False) → List[Frames[Axis]][source]#

Produce a stack of nested Frames that form the scan.

Ordered from slowest moving to fastest moving.

frames() → Frames[Axis][source]#: Expand all the scan Frames and return them.

midpoints() → Midpoints[Axis][source]#: Return Midpoints that can be iterated point by point.

zip(other: Spec) → Zip[Axis][source]#: Zip the Spec with another, iterating in tandem.

concat(other: Spec) → Concat[Axis][source]#: Concat the Spec with another, iterating one after the other.

serialize() → Mapping[str, Any][source]#: Serialize the spec to a dictionary.

classmethod deserialize(serialized: Mapping[str, Any]) → Spec[Axis][source]#: Deserialize the spec from a dictionary.

to_gql_input() → str[source]#: Convert to the GraphQL input format.

class scanspec.specs.Product(outer, inner)[source]#

Bases: Spec[Axis]

Outer product of two Specs, nesting inner within outer.

Parameters:

outer (Spec) – Will be executed once
inner (Spec) – Will be executed len(outer) times

This means that inner will run in its entirety at each point in outer.

# Example Spec

from scanspec.plot import plot_spec
from scanspec.specs import Line

spec = Line("y", 1, 2, 3) * Line("x", 3, 4, 12)
plot_spec(spec)

API#

scanspec#

scanspec.core#

scanspec.specs#

scanspec.regions#

scanspec.plot#

scanspec.service#

`scanspec`#

`scanspec.core`#

`scanspec.specs`#

`scanspec.regions`#

`scanspec.plot`#

`scanspec.service`#