PMPS Utilities

Calculation utilities related to the LCLS PMPS system.

Here you will find functions related to eV bitmasks.

pcdscalc.pmps.check_actual_range(lower: float, upper: float, allow: bool, line: str, bounds: list[float] | None = None) → tuple[float, float]

Returns the actual effective range given bitmask precision.

Because of the granularity of the bitmask, most range specifications exclude more energy values than requested.

Parameters:

lower: number

The value in eV for the lower bound of the range.

upper: number

The value in eV for the upper bound of the range.

allow: bool

True if we want a bitmask that only includes this range, False if we want a bitmask that only excludes this range.

line: str

String representation of which line’s bitmask to use. If the string begins with “l” or “h” (lfe, hxr), we’ll use the hard-xray bitmask. If the string begins with “k” or “s” (kfe, sxr), we’ll use the soft-xray bitmask.

bounds: list of numbers, optional

Custom boundaries to use instead of the default soft-xray or hard-xray lines. Useful for testing.

Returns:

ranges: tuple

A (lower, upper) pair that represents a range of allowed (or forbidden) energy values. The endpoints of the range are considered unsafe.

pcdscalc.pmps.check_bitmask(energy: float, bitmask: int, line: str, bounds: list[float] | None = None) → bool

Given an energy and a bitmask, tell us if our energy is allowed.

This is the same calculation the PMPS is doing internally to determine if it is safe for beam to proceed.

Parameters:

energy: number

The value in eV for the energy to check.

bitmask: int

The bits to check against. Typically an output of get_bitmask.

line: str

String representation of which line’s bitmask to use. If the string begins with “l” or “h” (lfe, hxr), we’ll use the hard-xray bitmask. If the string begins with “k” or “s” (kfe, sxr), we’ll use the soft-xray bitmask.

bounds: list of numbers, optional

Custom boundaries to use instead of the default soft-xray or hard-xray lines. Useful for testing.

Returns:

energy_allowed: bool

True if the energy is allowed.

pcdscalc.pmps.describe_bitmask(bitmask: int, line: str, bounds: list[float] | None = None) → None

Print a text description of a bitmask.

This will describe what the bitmask means.

Parameters:

bitmaskint

The bits to describe. Typically an output of get_bitmask.

linestr

String representation of which line’s bitmask to use. If the string begins with “l” or “h” (lfe, hxr), we’ll use the hard-xray bitmask. If the string begins with “k” or “s” (kfe, sxr), we’ll use the soft-xray bitmask.

boundslist of numbers, optional

Custom boundaries to use instead of the default soft-xray or hard-xray lines. Useful for testing.

pcdscalc.pmps.get_bitmask(lower: float, upper: float, allow: bool, line: str, bounds: list[float] | None = None) → int

Given a range of eV values, calculate the appropriate pmps bitmask.

This saves you the effort of checking up on the eV ranges and remembering how the bitmask is assembled.

If the lower or upper fall within a range (not on the border), then that range is always considered unsafe.

The rules for the bitmasks are:

• The nth bit of the bitmask represents a range from the n-1th value to the nth value

• If the bit is 1, the range is allowed and is safe.

• If the bit is 0, the range is not allowed and is not safe.

• eVs above the highest boundary are never safe

• negative eVs are never safe

Some examples:

• bitmask 00 -> no beam range is safe

• bitmask 01 -> only the lowest boundary and below are safe

• bitmask 11 -> only the two lowest boundaries and below are safe

• bitmask 10 -> only the space between the lowest and second-lowest

  boundaries are safe.

• bitmask all 1s -> every eV is OK except for above the highest

  boundary and except for negative eV

Parameters:

lower: number

The value in eV for the lower bound of the range.

upper: number

The value in eV for the upper bound of the range.

allow: bool

True if we want a bitmask that only includes this range, False if we want a bitmask that only excludes this range.

line: str

String representation of which line’s bitmask to use. If the string begins with “l” or “h” (lfe, hxr), we’ll use the hard-xray bitmask. If the string begins with “k” or “s” (kfe, sxr), we’ll use the soft-xray bitmask.

bounds: list of numbers, optional

Custom boundaries to use instead of the default soft-xray or hard-xray lines. Useful for testing.

Returns:

bitmask: int

pcdscalc.pmps.get_bitmask_desc(bitmask: int, line: str, bounds: list[float] | None = None) → list[str]

Return a text description of a bitmask.

This will describe what the bitmask means.

Parameters:

bitmaskint

The bits to describe. Typically an output of get_bitmask.

linestr

String representation of which line’s bitmask to use. If the string begins with “l” or “h” (lfe, hxr), we’ll use the hard-xray bitmask. If the string begins with “k” or “s” (kfe, sxr), we’ll use the soft-xray bitmask.

boundslist of numbers, optional

Custom boundaries to use instead of the default soft-xray or hard-xray lines. Useful for testing.

Returns:

desclist of str

Description lines that describe what the bitmask means.

pcdscalc.pmps.select_bitmask_boundaries(line: str) → list[float]

Given a line, select the bitmask boundaries to use.

These are hard-coded for now but in theory this could be loaded from a database, an EPICS PV, or some other source.

Parameters:

line: str

String representation of which line’s bitmask to use. If the string begins with “l” or “h” (lfe, hxr), we’ll use the hard-xray bitmask. If the string begins with “k” or “s” (kfe, sxr), we’ll use the soft-xray bitmask.

Returns:

boundaries: list of floats