API

This page contains the auto-generated documentation for the sorunlib package.

sorunlib

sorunlib.__init__.initialize(test_mode=False)[source]

Initialize global clients list.

Parameters:: test_mode (bool) – Operate in ‘test mode’. Use this to find Agents that are meant to stand in for real agents while testing, i.e. SmurfFileEmulators instead of PysmurfControllers.

sorunlib.acu

sorunlib.acu.move_to(az, el)[source]

Move telescope to specified coordinates.

Parameters:

az (float) – destination angle for the azimuthal axis
el (float) – destination angle for the elevation axis

sorunlib.acu.move_to_target(az, el, start_time, stop_time, drift)[source]

Move telescope to a given drifting target.

Parameters:

az (float) – Destination angle for the azimuthal axis.
el (float) – Destination angle for the elevation axis.
start_time (str) – Time in ISO format that target is at the given coordinates, i.e. “2024-09-22T07:13:34.416664+00:00”.
stop_time (str) – Time in ISO format that the target is no longer available to scan, i.e. “2024-09-22T08:42:16.343049+00:00”.
drift (float) – Azimuthal drift rate of the target in degrees per second. Used to adjust az if the move occurs after start_time but before stop_time.

sorunlib.acu.set_boresight(target)[source]

Move the third axis to a specific target angle.

Parameters:: target (float) – destination angle for boresight rotation

sorunlib.acu.set_scan_params(az_speed, az_accel, el_freq=None, reset=False, **kwargs)[source]

Update the default scan parameters, used during sorunlib.seq.scan().

Parameters:

az_speed (float) – The azimuth scan speed.
az_accel (float) – The (average) azimuth acceleration at turn-around.
el_freq (float, optional) – The frequency of elevation nods in type 3 scans.
reset (bool, optional) – If True, reset all params to default values before applying any updates passed explicitly here.

Any additional arguments are passed through, as well.

sorunlib.acu.set_shutter(action)[source]

Control the LAT shutter.

Parameters:: action (str) – Shutter action, either ‘open’ or ‘close’.

sorunlib.commands

sorunlib.commands.wait_until(timestamp, tolerance=None)[source]

Wait until a specified time.

Parameters:

timestamp (str) – Time in ISO format and in UTC timezone to wait until. If UTC (“+00:00”) is not explicitly used in the timestamp it is assumed.
tolerance (int, float, or str) –
Tolerance on the difference between the time when the function is evaluated and timestamp. Can be specified as a ISO formatted timestamp (str) or in number of seconds (int, float).

When evaluated, if tolerance (str) is in the past or if the difference between the current time and timestamp is greater than this tolerance (int, float), then an error is raised. If None, an error will not be raised. Default is None.

Raises:

ValueError – If timestamp has an unsupported timezone, tolerance is an unsupported type, or if the current time at evaluation is past the threshold set by the tolerance.

Examples

>>> wait_until("2015-10-21T07:28:00")
>>> wait_until("2015-10-21T07:28:00+00:00")
>>> wait_until("2015-10-21T07:28:00+00:00", 60)
>>> wait_until("2015-10-21T07:28:00+00:00", "2015-10-21T07:29:00+00:00")

sorunlib.hwp

sorunlib.hwp.set_freq(freq, timeout=None)[source]

Set the rotational frequency of the HWP.

Parameters:

freq (float) – Target frequency to rotate the HWP in Hz. This is a signed float, the meaning of which depends on the OCS site configuration. For details see the documentation for the HWP Supervisor Agent.
timeout (float, optional) – Duration, in seconds, to wait for the operation to complete. An exception will be raised if this timeout is exceeded.

sorunlib.hwp.spin_down(active=True, brake_voltage=None)[source]

Spin down the HWP while streaming data.

Parameters:

active (bool, optional) – If True, actively try to stop the HWP by applying the brake. If False, simply turn off the PMX power and wait for it to spin down on its own. Defaults to True.
brake_voltage (float, optional) – Voltage used when actively stopping the HWP. Only considered when active is True.

sorunlib.hwp.spin_up(freq)[source]

Spin up the HWP while streaming data.

Parameters:: freq (float) – Target frequency to rotate the HWP in Hz. This is a signed float, the meaning of which depends on the OCS site configuration. For details see the documentation for the HWP Supervisor Agent.

sorunlib.hwp.stop(active=True, brake_voltage=None)[source]

Stop the HWP.

Parameters:

active (bool, optional) – If True, actively try to stop the HWP by applying the brake. If False, simply turn off the PMX power and wait for it to spin down on its own. Defaults to True.
brake_voltage (float, optional) – Voltage used when actively stopping the HWP. Only considered when active is True.

sorunlib.seq

sorunlib.seq.el_nod(el1, el2, num=5, pause=5)[source]

Perform a set of elevation nods.

Elevation nods will be peformed at the current azimuth, and will start from and return to the current elevation. The nod first moves to el1, pauses, then moves to el2, pauses, and then repeats for the specified number of iterations.

Parameters:

el1 (float) – First elevation to move to during the nod.
el2 (float) – Second elevation to move to during the nod.
num (int) – Number of nods to peform. Defaults to 5.
pause (float) – Length of pause, in seconds, at each elevation. Defaults to 5 seconds.

sorunlib.seq.scan(description, stop_time, width, az_drift=0, scan_type=1, el_amp=None, tag=None, subtype=None, min_duration=None, **kwargs)[source]

Run a constant elevation scan, collecting detector data.

Parameters:

description (str) – Description of the field/object being scanned.
stop_time (str) – Time in ISO format to scan until, i.e. “2022-06-21T15:58:00”
width (float) – Scan width in azimuth. The scan will start at the current position and move in the positive azimuth direction.
az_drift (float) – Drift velocity in deg/s, causing scan extrema to move accordingly.
scan_type (int) – Scan type. Possible values are 1, 2, or 3.
el_amp (float) – For type 3 scans, the amplitude (half peak-to-peak) for the elevation oscillation, in degrees. Must be specified if scan_type=3 (but can be zero).
tag (str, optional) – Tag or comma-separated listed of tags to attach to the operation. Passed through to the smurf stream command.
subtype (str, optional) – Operation subtype used to tag the stream.
min_duration (float, optional) – Minimum duration required to scan, specified in seconds. If not enough time exists between now and the stop_time the scan is not executed. Defaults to None.

Any additional arguments are passed through to generate_scan.

sorunlib.smurf

This module is responsible for commanding all active pysmurf-controller agents.

If a SMuRF fails to perform an operation it will be dropped from the global CLIENTS list, removing it from further use during that schedule. If the number of active SMuRFs falls below the configured smurf_failure_threshold an exception will be raised, halting observations.

initialize() must be run to re-add previously failed SMuRFs to the CLIENTS list.

sorunlib.smurf.bias_dets(rfrac=None, concurrent=True, settling_time=0)[source]

Bias the detectors on all SMuRF Controllers.

Parameters:

rfrac (float, tuple, optional) – Target rfrac to aim for. If a float is provided, bias voltages will be chosen such that the median rfrac of each bias group is as close as possible to this value. If a tuple is provided, bias voltages will be chosen to maximize the number of channels within the given range. If None, the agent defaults are used. Defaults to None.
concurrent (bool, optional) – A bool which determines how the operation is run across the active SMuRF controllers. It runs in parallel if True, and in series if False.
settling_time (float, optional) – Time in seconds to wait between operation runs across the active SMuRF controllers if not running concurrently. If running concurrently this is ignored. Defaults to 0 seconds.

sorunlib.smurf.bias_step(tag=None, concurrent=True, settling_time=None)[source]

Perform a bias step on all SMuRF Controllers.

Parameters:

tag (str, optional) – Tag or comma-separated listed of tags to attach to the operation.
concurrent (bool, optional) – A bool which determines how the operation is run across the active SMuRF controllers. It runs in parallel if True, and in series if False.
settling_time (float, optional) – Time in seconds to wait between operation runs across the active SMuRF controllers if not running concurrently. If running concurrently this is ignored. If None, defaults to a fixed wait time of 120 seconds.

sorunlib.smurf.iv_curve(tag=None, iv_kwargs=None, concurrent=True, settling_time=None)[source]

Perform an iv curve on all SMuRF Controllers.

Parameters:

tag (str, optional) – Tag or comma-separated listed of tags to attach to the operation.
iv_kwargs (dict, optional) – Additional keyword arguments to pass to take_iv.
concurrent (bool, optional) – A bool which determines how the operation is run across the active SMuRF controllers. It runs in parallel if True, and in series if False.
settling_time (float, optional) – Time in seconds to wait between operation runs across the active SMuRF controllers if not running concurrently. If running concurrently this is ignored. If None, defaults to a fixed wait time of 120 seconds.

sorunlib.smurf.set_biases(bias, bias_group=None, concurrent=True, settling_time=0)[source]

Set the detector biases on all SMuRF Controllers.

Parameters:

bias – (int, float, list) Biases to set. If a float is passed, this will be used for all specified bias groups. If a list of floats is passed, it must be the same size of the list of bias groups.
bias_group – (int, list, optional) Bias group or list of bias groups to set. If None, will set all bias groups. Defaults to None.
concurrent (bool, optional) – A bool which determines how the operation is run across the active SMuRF controllers. It runs in parallel if True, and in series if False.
settling_time (float, optional) – Time in seconds to wait between operation runs across the active SMuRF controlls if not running concurrently. If running concurrently this is ignored. Defaults to 0 seconds.

sorunlib.smurf.set_targets(targets)[source]

Set the target pysmurf-controller Agents that sorunlib will command.

Parameters:: targets (list) – List of pysmurf-controller instance-ids to send future commands to. This must be a subset of the currently active clients list.

Notes

This modifies the global sorunlib.CLIENTS list.

sorunlib.smurf.shutdown(concurrent=True, settling_time=0)[source]

Safely shutdown the SMuRFs.

This turns off tones, flux-ramp voltage and amplifier biases on all SMuRF Controllers.

Parameters:

concurrent (bool, optional) – A bool which determines how the operation is run across the active SMuRF controllers. It runs in parallel if True, and in series if False.
settling_time (float, optional) – Time in seconds to wait between operation runs across the active SMuRF controllers if not running concurrently. If running concurrently this is ignored. Defaults to 0 seconds.

sorunlib.smurf.stream(state, tag=None, subtype=None, wait_for_stream=True, **kwargs)[source]

Stream data on all SMuRF Controllers.

Parameters:

state (str) – Streaming state, either ‘on’ or ‘off’.
tag (str, optional) – Tag or comma-separated listed of tags to attach to the operation.
subtype (str, optional) – Operation subtype used to tag the stream.
wait_for_stream (bool, optional) – If True, block until the streams are all enabled. If False, check that the client call goes through, but do not wait. Defaults to True.
**kwargs – Additional keyword arguments. Passed through to the SMuRF controller unmodified. See the controller documentation.

sorunlib.smurf.take_bgmap(tag=None, concurrent=True, settling_time=0)[source]

Take a bgmap on all SMuRF Controllers.

Parameters:

tag (str, optional) – Tag or comma-separated listed of tags to attach to the operation.
concurrent (bool, optional) – A bool which determines how the operation is run across the active SMuRF controllers. It runs in parallel if True, and in series if False.
settling_time (float, optional) – Time in seconds to wait between operation runs across the active SMuRF controllers if not running concurrently. If running concurrently this is ignored. Defaults to 0 seconds.

sorunlib.smurf.take_noise(tag=None, concurrent=True, settling_time=0)[source]

Measure noise statistics from a short, 30 second, timestream.

Parameters:

tag (str, optional) – Tag or comma-separated listed of tags to attach to the operation.
concurrent (bool, optional) – A bool which determines how the operation is run across the active SMuRF controllers. It runs in parallel if True, and in series if False.
settling_time (float, optional) – Time in seconds to wait between operation runs across the active SMuRF controllers if not running concurrently. If running concurrently this is ignored. Defaults to 0 seconds.

sorunlib.smurf.uxm_relock(test_mode=False, concurrent=True, settling_time=0)[source]

Relocks detectors to existing tune if setup has already been run.

Parameters:

test_mode (bool) – Run uxm_setup() task in test_mode, removing emulated wait times.
concurrent (bool, optional) – A bool which determines how the operation is run across the active SMuRF controllers. It runs in parallel if True, and in series if False.
settling_time (float, optional) – Time in seconds to wait between operation runs across the active SMuRF controllers if not running concurrently. If running concurrently this is ignored. Defaults to 0 seconds.

sorunlib.smurf.uxm_setup(concurrent=True, settling_time=0)[source]

Perform first-time setup procedure for a UXM.

Parameters:

concurrent (bool, optional) – A bool which determines how the operation is run across the active SMuRF controllers. It runs in parallel if True, and in series if False.
settling_time (float, optional) – Time in seconds to wait between operation runs across the active SMuRF controllers if not running concurrently. If running concurrently this is ignored. Defaults to 0 seconds.

sorunlib.smurf.zero_biases(bias_group=None, concurrent=True, settling_time=0)[source]

Set the detector biases on all SMuRF Controllers.

Parameters:

bias_group – (int, list, optional) Bias group or list of bias groups to set. If None, will zero all bias groups. Defaults to None.
concurrent (bool, optional) – A bool which determines how the operation is run across the active SMuRF controllers. It runs in parallel if True, and in series if False.
settling_time (float, optional) – Time in seconds to wait between operation runs across the active SMuRF controlls if not running concurrently. If running concurrently this is ignored. Defaults to 0 seconds.

sorunlib.stimulator

sorunlib.stimulator.calibrate_gain(duration=60, speed_rpm=90, forward=True, do_setup=True, stop=True, downsample_factor=8, filter_disable=False, filter_order=None, filter_cutoff=None)[source]

Gain calibration with the stimulator

Parameters:

duration (float, optional) – Duration of the gain calibration in sec, default to 60 sec.
speed_rpm (float, optional) – Rotation speed of the chopper wheel in RPM, default to 90 RPM.
forward (bool, optional) – Chopper rotation direction. If True, the chopper rotates clockwise when viewed from the receiver toward the stimulator. Defaults to True.
do_setup (bool, optional) – Do initial setup (i.e. open shutter, set acceleration, start rotation) if True. Defaults to True.
stop (bool, optional) – Stop the rotation and close the shutter if True. Defaults to True.
downsample_factor (int, optional) – Downsample factor for SMuRF. Defaults to 8.
filter_disable (bool, optional) – If True, will disable the downsample filter before streaming. Defaults to False.
filter_order (int, optional) – Order of the downsample filter for SMuRF. Defaults to None. If None is passed, the pysmurf default(normally 4) will be used.
filter_cutoff (float, optional) – The cutoff frequency in Hz for the downsample filter for SMuRF. Defaults to None. If None is passed, will be (63/200)*sampling_rate.

sorunlib.stimulator.calibrate_gain_tau(duration_gain=60, duration_tau=10, duration_stabilization=10, speed_rpm_gain=90, speeds_rpm_tau=[225, 495, 945, 1395, 1845, 2205], forward=True, downsample_factor=8, filter_disable=False, filter_order=None, filter_cutoff=None)[source]

Gain and time-constant calibration at the same time

Parameters:

duration_gain (float, optional) – Duration of the gain calibration in sec, default to 60 sec.
duration_tau (float, optional) – Duration of each step of time constant measurement in sec, default to 10 sec.
duration_stabilization (float, optional) – Duration to stabilize the chopper wheel speed in sec, default to 10 sec.
speed_rpm_gain (float, optional) – Rotation speed of the chopper wheel in RPM for gain calibration, default to 90 RPM.
speeds_rpm_tau (list of float, optional) – List of chopper rotation speed in RPM for each step for time-constant calibration. Defaults to [225, 495, 945, 1395, 1845, 2205].
forward (bool, optional) – Chopper rotation direction. If True, the chopper rotates clockwise when viewed from the receiver toward the stimulator. Defaults to True.
downsample_factor (int, optional) – Downsample factor for SMuRF. Defaults to 8.
filter_disable (bool, optional) – If True, will disable the downsample filter before streaming. Defaults to False.
filter_order (int, optional) – Order of the downsample filter for SMuRF. Defaults to None. If None is passed, the pysmurf default(normally 4) will be used.
filter_cutoff (float, optional) – The cutoff frequency in Hz for the downsample filter for SMuRF. Defaults to None. If None is passed, will be (63/200)*sampling_rate.

sorunlib.stimulator.calibrate_tau(duration_step=20, speeds_rpm=[225, 495, 945, 1395, 1845, 2205], forward=True, do_setup=True, stop=True, downsample_factor=8, filter_disable=False, filter_order=None, filter_cutoff=None)[source]

Time constant calibration using the stimulator.

Parameters:

duration_step (float, optional) – Duration of each step of time constant measurement in sec, default to 20 sec.
speeds_rpm (list of float, optional) – List of chopper rotation speed in RPM for each step. Defaults to [225, 495, 945, 1395, 1845, 2205].
forward (bool, optional) – Chopper rotation direction. If True, the chopper rotates clockwise when viewed from the receiver toward the stimulator. Defaults to True.
do_setup (bool, optional) – Do initial setup (i.e. open shutter, set acceleration, start rotation) if True. Defaults to True.
stop (bool, optional) – Stop the rotation and close the shutter if True. Defaults to True.
downsample_factor (int, optional) – Downsample factor for SMuRF. Defaults to 8.
filter_disable (bool, optional) – If True, will disable the downsample filter before streaming. Defaults to False.
filter_order (int, optional) – Order of the downsample filter for SMuRF. Defaults to None. If None is passed, the pysmurf default(normally 4) will be used.
filter_cutoff (float, optional) – The cutoff frequency in Hz for the downsample filter for SMuRF. Defaults to None. If None is passed, will be (63/200)*sampling_rate.

sorunlib.util

exception sorunlib.util.CrossbarConnectionError[source]: Bases: Exception

sorunlib.util.create_clients(config=None, sorunlib_config=None, test_mode=False)[source]

Create all clients needed for commanding a single platform.

Parameters:

config (str) – Path to the OCS Site Config File. If None the default file in OCS_CONFIG_DIR will be used.
sorunlib_config (str) – Path to sorunlib config file. If None the path from environment variable SORUNLIB_CONFIG is used.
test_mode (bool) – Operate in ‘test mode’. Use this to find Agents that are meant to stand in for real agents while testing, i.e. SmurfFileEmulators instead of PysmurfControllers.

Returns:

Dictionary with the ACU and SMuRF clients needed for commanding in the format:

clients = {'acu': acu_client,
           'hwp': hwp_supervisor_client,
           'smurf': [smurf_client1, smurf_client2, smurf_client3],
           'wiregrid': {'actuator': actuator_client,
                        'encoder': encoder_client,
                        'kikusui': kikusui_client,
                        'labjack': labjack_client}}

Return type:

dict

sorunlib.wiregrid

sorunlib.wiregrid.calibrate(continuous=False, elevation_check=True, boresight_check=True, temperature_check=True, bias_step_before=True, bias_step_after=False)[source]

Run a wiregrid calibration.

Parameters:

continuous (bool) – Calibration by continuous rotation or not. Default is False, in which the wiregrid rotates step-wisely.
elevation_check (bool) – Check the elevation angle is in an appropriate range before the calibration or not. Default is True.
boresight_check (bool) – Check the boresight angle is in an appropriate range before the calibration or not. Default is True.
temperature_check (bool) – Check the temperature of various components are within operational limits before the calibration or not. Default is True.
bias_step_before (bool) – Perform detector bias step with and without wiregrid before the calibration.
bias_step_after (bool) – Perform detector bias step with and without wiregrid after the calibration.

sorunlib.wiregrid.eject()[source]: Eject the wiregrid.

sorunlib.wiregrid.insert()[source]: Insert the wiregrid.

sorunlib.wiregrid.rotate(continuous, duration=30, num_laps=1, stopped_time=10.0)[source]

Rotate the wiregrid.

Rotation is either continuously for duration seconds or stepwise for num_laps, stopping every 22.5 degrees for stopped_time seconds.

This function sets the Kikusui power settings appropriately based on the rotation type.

Parameters:

continuous (bool) – Rotate the grid continuously if True or not if False.
duration (int, float) – Amount of time in seconds to rotate if rotating continuously. Defaults to 30 seconds.
num_laps (int) – Number of revolutions if rotating stepwise (i.e. continuous = False). Defaults to 1.
stopped_time (float) – Duration of each 22.5 deg step in seconds if rotating stepwise. Defaults to 10 seconds.

sorunlib.wiregrid.time_constant(num_repeats=1)[source]

Run a wiregrid time constant measurement.

Parameters:: num_repeats (int) – Number of repeats. Default is 1. If this is odd, the HWP direction will be changed to the opposite of the initial direction. If this is even, the HWP direction will be the same as the initial direction.