API: chopcal.lib¶

One disk chopper: how fast it turns, where its openings are, and how far away.

The disk is described the way the NeXus NXdisk_chopper standard and McStas' CollectorDiskChopper describe one. edges are the slit edges in degrees from the disk's own zero mark, two per opening, strictly increasing, opening edge first; beam is the angle from that mark to where the beam crosses the disk. An edge at angle a is on the beam at

t(a) = delay + (beam - a) / (360 * speed)

and every 1/|speed| seconds after that. Only beam - a appears, so a caller can hand over the disk's own numbers with no conversion to do. A negative speed turns the disk the other way, which does not move delay -- a delay is a time, so it means the same thing in either direction -- but does swap which side of it an opening arrives on.

This replaces the angle of chopper-lib 2.x, which could only describe one opening centred on the beam. Chopper.centred still writes one of those.

init(self, speed: float = 0, delay: float = 0, beam: float = 0, edges: collections.abc.Sequence[float] = [], path: float = 0, aperture: float = 0) -> None

Methods:

• __new__ –

  Create and return a new object. See help(type) for accurate signature.

• __repr__ –

  Unambiguous, and in the units the fields are actually stored in.

• __str__ –

  The same disk, said out loud.

• centred –

  centred(speed: float = 0, delay: float = 0, width: float = 0, path: float = 0, aperture: float = 0) -> chopcal._chopper_lib_impl.Chopper

• parked_is_open –

  parked_is_open(self) -> bool

• validate –

  validate(self) -> None

Attributes:

• __doc__ –

  str(object='') -> str

• __module__ –

  str(object='') -> str

• aperture –

  Angular width of the beam where it crosses the disk, in degrees.

• beam –

  From the disk's zero mark to where the beam crosses it, in degrees

• delay –

  When the disk point at angle beam is on the beam path, in seconds

• edges –

  Slit edges in degrees from the zero mark, two per opening, increasing.

• opening –

  Total opening angle in degrees, summed over the openings

• openings –

  The (opening, closing) edge pairs, in degrees from the disk's zero mark.

• path –

  Flight path from the source to the disk, in metres

• quantities –

  The fields as scipp variables, each carrying its own unit.

• speed –

  Rotation frequency in Hz; negative turns the disk the other way

__doc__ = "One disk chopper: how fast it turns, where its openings are, and how far away.\n\nThe disk is described the way the NeXus `NXdisk_chopper` standard and McStas'\n`CollectorDiskChopper` describe one. `edges` are the slit edges in degrees from\nthe disk's own zero mark, two per opening, strictly increasing, opening edge\nfirst; `beam` is the angle from that mark to where the beam crosses the disk.\nAn edge at angle `a` is on the beam at\n\n    t(a) = delay + (beam - a) / (360 * speed)\n\nand every 1/|speed| seconds after that. Only `beam - a` appears, so a caller can\nhand over the disk's own numbers with no conversion to do. A negative `speed`\nturns the disk the other way, which does not move `delay` -- a delay is a time,\nso it means the same thing in either direction -- but does swap which side of it\nan opening arrives on.\n\nThis replaces the `angle` of chopper-lib 2.x, which could only describe one\nopening centred on the beam. `Chopper.centred` still writes one of those."

__module__ = 'chopcal._chopper_lib_impl'

aperture

beam

delay

edges

opening

openings

path

quantities

speed

__new__(*args, **kwargs)

__repr__(chopper)

__str__(chopper)

centred(*args, **kwargs)

parked_is_open()

validate()

Bases: dict

The choppers of an instrument, by name, in beam order.

A dict in every respect -- set['ps1'], set.values(), **set all behave as usual -- that prints itself as a table rather than as six memory addresses.

delay is when the disk point at beam is on the beam path and open how long the openings spend there each turn, so a single-opening disk centred on the beam passes neutrons from delay - open/2 to delay + open/2, and again every 1/speed after that. Both are shown in milliseconds because that is the scale they live on; the attributes themselves are in seconds.

aperture is how wide the beam is on the disk, in degrees about its spindle. It widens every window by half of it at each end, so open understates the time a real beam spends in the openings; zero is a point beam.

Use :attr:quantities to get them as scipp variables instead, which is the safer thing to hand to anything else -- the units come along and cannot be misread.

Attributes:

• quantities –

  Every chopper's fields as scipp variables, by name.

quantities

>>> settings.quantities['ps1']['delay']     # doctest: +SKIP
<scipp.Variable> ()  float64  [s]  0.00595313

The region of (inverse velocity, emission time) a chopper train transmits.

A union of convex polygons, and exact: a neutron emitted at inverse velocity a and time t reaches path L at t + L*a, so a disc open on [lower, upper] accepts lower <= t + L*a <= upper -- a slab between two parallel lines. A train's acceptance is an intersection of unions of such slabs, and intersection distributes over union, so the region is a union of convex pieces: one per choice of which opening and which turn of each disc a neutron goes through.

This is what inverse_velocity_windows and inverse_velocity_time_mask approximate, each in its own direction. The window functions project each disc separately and intersect the projections, which can report a band no single emission time delivers. The mask quantises, losing channels thinner than a bin and keeping partly covered bins whole. This does neither.

Start from Region.rectangle, the region a source draws from, and transmit it through the train.

init(self) -> None

An empty region, transmitting nothing.

Methods:

• __bool__ –

  bool(self) -> bool

• __len__ –

  len(self) -> int

• __new__ –

  Create and return a new object. See help(type) for accurate signature.

• arrival_moments –

  The amount reaching distance in each arrival-time bin, with the mean and spread

• arrivals –

  What a gridded source puts through the region, by arrival time at distance.

• contains –

  contains(self, inverse_velocity: float, time: float) -> bool

• coverage –

  The fraction of each (time, inverse velocity) cell the region covers.

• from_wavelengths –

  A source rectangle given in angstrom rather than in inverse velocity.

• integrate –

  How much of a gridded source the region transmits.

• inverse_velocity_ranges –

  inverse_velocity_ranges(self) -> list[tuple[float, float]]

• rectangle –

  rectangle(inverse_velocity_minimum: float, inverse_velocity_range: float, time_minimum: float, time_range: float) -> chopcal._chopper_lib_impl.Region

• sampler –

  sampler(self, sampled_area: float) -> chopcal._chopper_lib_impl.RegionSampler

• to_dict –

  The region as plain data, in the schema :meth:Region.write_json writes.

• transmit –

  transmit(self, choppers: collections.abc.Sequence[chopcal._chopper_lib_impl.Chopper], path_spreads: collections.abc.Sequence[float] = []) -> chopcal._chopper_lib_impl.Region

• transmit_weighted –

  transmit_weighted(self, choppers: collections.abc.Sequence[chopcal._chopper_lib_impl.Chopper], groups: collections.abc.Sequence[int] = []) -> chopcal._chopper_lib_impl.WeightedRegion

• wavelength_ranges –

  wavelength_ranges(self) -> list[tuple[float, float]]

• write_json –

  Write the region to path as JSON, byte for byte what the McStas component writes.

Attributes:

• __doc__ –

  str(object='') -> str

• __module__ –

  str(object='') -> str

• area –

  Total area in s^2/m. A plain sum: the pieces are disjoint, because

• polygons –

  The convex pieces, as a list

__doc__ = "The region of (inverse velocity, emission time) a chopper train transmits.\n\nA union of convex polygons, and exact: a neutron emitted at inverse velocity `a`\nand time `t` reaches path `L` at `t + L*a`, so a disc open on [lower, upper]\naccepts `lower <= t + L*a <= upper` -- a slab between two parallel lines. A\ntrain's acceptance is an intersection of unions of such slabs, and intersection\ndistributes over union, so the region *is* a union of convex pieces: one per\nchoice of which opening and which turn of each disc a neutron goes through.\n\nThis is what `inverse_velocity_windows` and `inverse_velocity_time_mask`\napproximate, each in its own direction. The window functions project each disc\nseparately and intersect the projections, which can report a band no single\nemission time delivers. The mask quantises, losing channels thinner than a bin\nand keeping partly covered bins whole. This does neither.\n\nStart from `Region.rectangle`, the region a source draws from, and `transmit` it\nthrough the train."

__module__ = 'chopcal._chopper_lib_impl'

area

polygons

__bool__()

__len__()

__new__(*args, **kwargs)

arrival_moments(region, signal, inverse_velocities, times, distance, arrival_times, period=None)

arrivals(region, signal, inverse_velocities, times, distance, arrival_times, period=None)

contains()

coverage(region, inverse_velocities, times)

from_wavelengths(wavelength_min, wavelength_max, time_minimum, time_range)

integrate(region, signal, inverse_velocities, times)

inverse_velocity_ranges()

rectangle(*args, **kwargs)

sampler()

to_dict(region, sampled=None)

transmit()

transmit_weighted()

wavelength_ranges()

write_json(region, path, sampled=None)

One convex piece of a transmitted region, in (inverse velocity, time).

A value, not a handle: it owns nothing and copies freely. Its vertices are the disc edges that bound it, at the precision of a double -- nothing here is sampled onto a grid.

Initialize self. See help(type(self)) for accurate signature.

Methods:

• __len__ –

  len(self) -> int

• __new__ –

  Create and return a new object. See help(type) for accurate signature.

• contains –

  contains(self, inverse_velocity: float, time: float) -> bool

Attributes:

• __doc__ –

  str(object='') -> str

• __module__ –

  str(object='') -> str

• area –

  Area in s^2/m -- phase space, not a count

• vertices –

  (inverse velocity, time) pairs in order, s/m and s

__doc__ = 'One convex piece of a transmitted region, in (inverse velocity, time).\n\nA value, not a handle: it owns nothing and copies freely. Its vertices are the\ndisc edges that bound it, at the precision of a double -- nothing here is sampled\nonto a grid.'

__module__ = 'chopcal._chopper_lib_impl'

area

vertices

__len__()

__new__(*args, **kwargs)

contains()

Draws (inverse velocity, time) pairs uniformly from a transmitted region.

The same job as MaskSampler and the same shape -- three uniform deviates, one binary search, never rejects -- over the exact region rather than a grid approximation of it. Each polygon is fanned into triangles from its first vertex, so count here is triangles, not polygons.

init(self, region: chopcal._chopper_lib_impl.Region, sampled_area: float) -> None

Methods:

• __new__ –

  Create and return a new object. See help(type) for accurate signature.

• draw –

  draw(self, triangle_deviate: float, first_deviate: float, second_deviate: float) -> tuple[float, float]

• draw_many –

  draw_many(self, triangle_deviates: ndarray[dtype=float64, shape=(), order='C', writable=False], first_deviates: ndarray[dtype=float64, shape=(), order='C', writable=False], second_deviates: ndarray[dtype=float64, shape=(*), order='C', writable=False]) -> tuple[list[float], list[float]]

• sample –

  count (inverse_velocity, time) pairs, as two numpy arrays.

Attributes:

• __doc__ –

  str(object='') -> str

• __module__ –

  str(object='') -> str

• acceptance –

  The factor every drawn ray's weight must be multiplied by.

• count –

  Triangles this draws from; 0 means nothing to draw

__doc__ = 'Draws (inverse velocity, time) pairs uniformly from a transmitted region.\n\nThe same job as `MaskSampler` and the same shape -- three uniform deviates, one\nbinary search, never rejects -- over the exact region rather than a grid\napproximation of it. Each polygon is fanned into triangles from its first vertex,\nso `count` here is triangles, not polygons.'

__module__ = 'chopcal._chopper_lib_impl'

acceptance

count

__new__(*args, **kwargs)

draw()

draw_many()

sample(sampler, count, generator=None)

The region a chopper train transmits, weighted by how likely a neutron is to get through.

With a disc aperture, a Region's boundary is where transmission falls to zero. Inside, an edge sweeping a uniformly lit beam ramps the transmission linearly, and this carries that ramp: the same convex polygons, each with a product of affine factors. Discs in one group -- a pair sharing a housing -- are crossed at the same place across the beam, so the group passes the part of the beam open in all of them: the smaller transmission for a co-rotating pair, and for a counter-rotating pair a ramp starting at the half-way time and twice as steep. Different groups multiply. Pieces may overlap where two openings of one disc ramp at once, and their transmissions add.

Make one with Region.transmit_weighted.

Initialize self. See help(type(self)) for accurate signature.

Methods:

• __bool__ –

  bool(self) -> bool

• __len__ –

  len(self) -> int

• __new__ –

  Create and return a new object. See help(type) for accurate signature.

• arrival_moments –

  The amount reaching distance in each arrival-time bin, with the mean and spread

• arrivals –

  What a gridded source puts through the region, by arrival time at distance.

• coverage –

  The fraction of each (time, inverse velocity) cell the region covers.

• integrate –

  How much of a gridded source the region transmits.

• transmission –

  transmission(self, inverse_velocity: float, time: float) -> float

Attributes:

• __doc__ –

  str(object='') -> str

• __module__ –

  str(object='') -> str

• integral –

  The integral of the transmission, s^2/m: the area a uniformly drawn ray

• pieces –

  Each piece as (Polygon, factors), a factor (a, b, c) being

__doc__ = "The region a chopper train transmits, weighted by how likely a neutron is to get\nthrough.\n\nWith a disc `aperture`, a Region's boundary is where transmission falls to zero.\nInside, an edge sweeping a uniformly lit beam ramps the transmission linearly, and\nthis carries that ramp: the same convex polygons, each with a product of affine\nfactors. Discs in one *group* -- a pair sharing a housing -- are crossed at the same\nplace across the beam, so the group passes the part of the beam open in all of\nthem: the smaller transmission for a co-rotating pair, and for a counter-rotating\npair a ramp starting at the half-way time and twice as steep. Different groups\nmultiply. Pieces may overlap where two openings of one disc ramp at once, and their\ntransmissions add.\n\nMake one with `Region.transmit_weighted`."

__module__ = 'chopcal._chopper_lib_impl'

integral

pieces

__bool__()

__len__()

__new__(*args, **kwargs)

arrival_moments(region, signal, inverse_velocities, times, distance, arrival_times, period=None)

arrivals(region, signal, inverse_velocities, times, distance, arrival_times, period=None)

coverage(region, inverse_velocities, times)

integrate(region, signal, inverse_velocities, times)

transmission()

Bases: NamedTuple

What reaches a distance in each arrival-time bin: how much, and at what wavelength.

amount is in the units of the signal; wavelength and sigma are the mean and standard deviation of wavelength over it, in angstrom, NaN where nothing arrives.

Bases: MaskSampler

Draws (inverse velocity, time) pairs from the allowed cells of a finished mask.

Sampling the whole region and discarding what the mask excludes spends the ray budget to keep the fraction the choppers pass, which for a real chopper train is a fraction of a percent. Drawing from the allowed cells keeps all of it and is the same distribution, provided every drawn weight is multiplied by :attr:acceptance.

mask is shaped (time, inverse velocity) and inverse_velocities/times are its bin edges. The four bounds describe the region the caller samples uniformly, which is not in general the region the grid covers -- a grid sized with ceil runs past it in the last row and column, and those cells are clipped before they are weighted so that they do not inflate :attr:acceptance.

Bases: IntEnum

What a cell of an inverse_velocity_time_mask holds.

A finished mask only ever holds EXCLUDED or INCLUDED -- GROWN is the marker the growing pass leaves behind and folds back into INCLUDED before it returns -- but it is written to file as it stands, so a mask read back from one can carry it.