API¶

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

scanspec.core: Core classes like Dimension and Path
scanspec.specs: Spec and its subclasses
scanspec.regions: Region and its subclasses
scanspec.plot: plot_spec to visualize a scan

`scanspec.core`¶

scanspec.core.Positions¶

Positions map {key: positions_ndarray} E.g. {xmotor: array([0, 1, 2]), ymotor: array([2, 2, 2])}

alias of Dict[Any, numpy.ndarray]

scanspec.core.T¶

The type of class the function will return

alias of TypeVar(‘T’)

scanspec.core.if_instance_do(x, cls: Type[T], func: Callable[[T], Any])[source]¶: If x is of type cls then return func(x), otherwise return NotImplemented. Used as a helper when implementing operator overloading

class scanspec.core.Dimension(positions: Dict[Any, numpy.ndarray], lower: Dict[Any, numpy.ndarray] = None, upper: Dict[Any, numpy.ndarray] = None, snake: bool = False)[source]¶

Represents a linear stack of positions and bounds. A list of Dimensions is interpreted as nested from slowest moving to fastest moving, so each faster Dimension will iterate once per position of the slower Dimension. When fly-scanning they key will traverse lower-position-upper on the fastest Dimension for each point in the scan.

Parameters

positions – The centre positions of the scan for each key
lower – Lower bounds if different from positions
upper – Upper bounds if different from positions
snake – If True then every other iteration of this Dimension within a slower moving Dimension will be reversed

See also

What are Dimensions?

positions¶: The centre positions of the scan for each key

lower¶: The lower bounds of each scan point for each key for fly-scanning

upper¶: The upper bounds of each scan point for each key for fly-scanning

snake¶: Whether every other iteration of this Dimension within a slower moving Dimension will be reversed

keys() → List[source]¶: The keys that are present in positions, lower and upper which will move during the scan

tile(reps: int) → scanspec.core.Dimension [source]¶

Return a new Dimension that iterates self reps times

>>> dim = Dimension({"x": np.array([1, 2, 3])})
>>> dim.tile(reps=2).positions
{'x': array([1, 2, 3, 1, 2, 3])}

repeat(reps: int) → scanspec.core.Dimension [source]¶

Return a new Dimension that repeats each point in self reps times

>>> dim = Dimension({"x": np.array([1, 2, 3])})
>>> dim.repeat(reps=2).positions
{'x': array([1, 1, 2, 2, 3, 3])}

mask(mask: numpy.ndarray) → scanspec.core.Dimension [source]¶

>>> dim = Dimension({"x": np.array([1, 2, 3])})
>>> dim.mask(np.array([1, 0, 1])).positions
{'x': array([1, 3])}

copy() → scanspec.core.Dimension [source]¶: Return a shallow copy of the current Dimension (dicts copied, arrays within them are not)

concat(other: scanspec.core.Dimension) → scanspec.core.Dimension [source]¶

Return a new Dimension with arrays from self and other concatenated together. Require both Dimensions to have the same keys and snake settings

>>> dim = Dimension({"x": np.array([1, 2, 3])})
>>> dim2 = Dimension({"x": np.array([5, 6, 7])})
>>> dim.concat(dim2).positions
{'x': array([1, 2, 3, 5, 6, 7])}

zip(other: scanspec.core.Dimension) → scanspec.core.Dimension [source]¶

Return a new Dimension with arrays from keys of self and other merged together. Require both Dimensions to not share keys, and to have the snake settings

>>> dimx = Dimension({"x": np.array([1, 2, 3])})
>>> dimy = Dimension({"y": np.array([5, 6, 7])})
>>> dimx.zip(dimy).positions
{'x': array([1, 2, 3]), 'y': array([5, 6, 7])}

scanspec.core.squash_dimensions(dimensions: List[scanspec.core.Dimension], check_path_changes=True) → scanspec.core.Dimension [source]¶

Squash a list of nested Dimensions into a single one.

Parameters

dimensions – The Dimensions to squash, from slowest to fastest moving
check_path_changes – If True then check that nesting the output Dimension within other Dimensions will provide the same path as nesting the input Dimension within other Dimensions

>>> dimx = Dimension({"x": np.array([1, 2])}, snake=True)
>>> dimy = Dimension({"y": np.array([3, 4])})
>>> squash_dimensions([dimy, dimx]).positions
{'y': array([3, 3, 4, 4]), 'x': array([1, 2, 2, 1])}

class scanspec.core.Path(dimensions: List[scanspec.core.Dimension], start: int = 0, num: int = None)[source]¶

Create a consumable Path through a list of Dimensions representing a scan path.

Parameters

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

See also

How to Iterate a Spec

dimensions¶: The Dimensions describing the scan, from slowest to fastest moving

index¶: Index that is next to be consumed

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

consume(num: int = None) → scanspec.core.Dimension [source]¶

Consume at most num points from the Path and return as a Dimension

>>> dimx = Dimension({"x": np.array([1, 2])}, snake=True)
>>> dimy = Dimension({"y": np.array([3, 4])})
>>> path = Path([dimy, dimx])
>>> path.consume(3).positions
{'y': array([3, 3, 4]), 'x': array([1, 2, 2])}
>>> path.consume(3).positions
{'y': array([4]), 'x': array([1])}
>>> path.consume(3).positions
{'y': array([], dtype=int64), 'x': array([], dtype=int64)}

class scanspec.core.SpecPositions(dimensions: List[scanspec.core.Dimension])[source]¶

Convenience iterable that produces the scan positions for each axis. For better performance, consume from a Path instead.

Parameters: dimensions – The Dimensions describing the scan, from slowest to fastest moving

See also

How to Iterate a Spec

>>> dimx = Dimension({"x": np.array([1, 2])}, snake=True)
>>> dimy = Dimension({"y": np.array([3, 4])})
>>> sp = SpecPositions([dimy, dimx])
>>> for p in sp: print(p)
{'y': 3, 'x': 1}
{'y': 3, 'x': 2}
{'y': 4, 'x': 2}
{'y': 4, 'x': 1}

dimensions¶: The Dimensions describing the scan, from slowest to fastest moving

property keys¶: The keys that will be present in each position dictionary

`scanspec.specs`¶

class scanspec.specs.Spec[source]¶

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

*: Outer Product of two Specs, nesting the second within the first
+: Zip two Specs together, iterating in tandem
&: Mask the Spec with a Region, excluding positions outside it
~: Snake the Spec, reversing every other iteration of it

keys() → List[source]¶: Implemented by subclasses to produce the list of keys that are present in the positions, from slowest moving to fastest moving

create_dimensions(bounds=True, nested=False) → List[scanspec.core.Dimension][source]¶: Implemented by subclasses to produce the Dimension list that contribute to positions, from slowest moving to fastest moving

path() → scanspec.core.Path [source]¶: Return a Path through the scan that can be consumed in chunks to give positions and bounds

positions() → scanspec.core.SpecPositions [source]¶: Return a SpecPositions that can be iterated position by position

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

Outer product of two Specs, nesting inner within outer. This means that inner will run in its entirety at each point in outer.

Parameters

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

# 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.core¶

scanspec.specs¶

scanspec.regions¶

scanspec.plot¶

`scanspec.core`¶

`scanspec.specs`¶

`scanspec.regions`¶

`scanspec.plot`¶