Lakeshore 336

The Lakeshore 336 Agent interfaces with the Lakeshore 336 (LS336) hardware to perform temperature monitoring and servoing on the LS336’s four channels. This setup is currently primarily being used for controlling a cold load. Basic functionality to interface with and control an LS336 is provided by the Supporting APIs.

usage: python3 agent.py [-h] [--serial-number SERIAL_NUMBER]
                        [--ip-address IP_ADDRESS] [--f-sample F_SAMPLE]
                        [--threshold THRESHOLD] [--window WINDOW]
                        [--auto-acquire AUTO_ACQUIRE]

Agent Options

--serial-number

--ip-address

IP address for the lakeshore

--f-sample

The frequency of data acquisition

Default: 0.1

--threshold

The upper bound on temperature differences for stability check

Default: 0.1

--window

The lookback time on temperature differences for stability check

Default: 900.0

--auto-acquire

Automatically start data acquisition on startup

Default: True

Configuration File Examples

Below are some configuration files for the OCS config file and for running the Agent in a Docker container.

OCS Site Config

To configure your Lakeshore 336 for use with OCS, you need to add a Lakeshore336Agent block to your OCS configuration file. Here is an example configuration block:

{'agent-class': 'Lakeshore336Agent',
 'instance-id': 'LSA2833',
 'arguments': [['--serial-number', 'LSA2833'],
               ['--ip-address', '10.10.10.2'],
               ['--f-sample', 0.1],
               ['--threshold', 0.05],
               ['--window', 600],
               ['--auto-acquire']]},

Each device requires configuration under ‘agent-instances’. See the OCS site configs documentation for more details.

Docker Compose

The Lakeshore 336 agent should be configured to run in a Docker container. An example configuration is:

ocs-LSA2833:
  image: simonsobs/socs:latest
  hostname: ocs-docker
  network_mode: "host"
  environment:
    - INSTANCE_ID=LSA2833
    - SITE_HUB=ws://127.0.0.1:8001/ws
    - SITE_HTTP=http://127.0.0.1:8001/call
  volumes:
    - ${OCS_CONFIG_DIR}:/config:ro

Note

Since the 336 Agent container needs network_mode: "host", it must be configured to connect to the crossbar server as if it was on the host system. In this example the crossbar server is running on localhost, 127.0.0.1, but on your network this may be different.

Note

The serial numbers here will need to be updated for your device.

Description

Like the Lakeshore 372, direct communication via ethernet is possible with the Lakeshore 336. Please see the Lakeshore 372 Agent documentation for more information about direct communication and the following APIs to see which methods are available in the agent and the underlying Lakeshore336.py script.

Agent API

class socs.agents.lakeshore336.agent.LS336_Agent(agent, sn, ip, f_sample=0.1, threshold=0.1, window=900)

Agent to connect to a single Lakeshore 336 device. Supports channels ‘A’,’B’,’C’, and ‘D’ for Lakeshore 336s that do not have the extra Lakeshore 3062 scanner installed. Also has channels ‘D2’,’D3’,’D4’, and ‘D5’ for 336s that have the extra scanner. Currently only supports heaters ‘1’ and ‘2’.

Parameters:

• sn (str) – Serial number of the LS336

• ip (str) – IP Address for the 336 device

• f_sample (float, optional (default 0.1)) – The frequency of sampling for acquiring data (in Hz)

• threshold (float, optional (default 0.1)) – The max difference (in K) between the setpoint and current temperature that will be considered stable

• window (int, optional (default 900)) – The amount of time (in s) over which the difference between the setpoint and the current temperature must not exceed threshold while checking for temperature stability.

sn

Serial number of the LS336

Type:

str

ip

IP Address for the 336 device

Type:

str

module

Driver object

Type:

LS336 object

module.channels

The available channels in the LS336 object

Type:

dict

module.heaters

The available heaters in the LS336 object

Type:

dict

f_sample

The frequency of sampling for acquiring data (in Hz)

Type:

float

t_sample

The time between each sample (inverse of f_sample - 0.01)

Type:

float

threshold

The max difference (in K) between the setpoint and current temperature that will be considered stable

Type:

float

window

The amount of time (in s) over which the difference between the setpoint and the current temperature must not exceed threshold while checking for temperature stability.

Type:

int

_recent_temps

Array of recent temperatures for checking temperature stability

Type:

numpy array, protected

_static_setpoint

The final setpoint value to avoid issues when the setpoint is ramping to a new value. Used in checking temperature stability

Type:

float, protected

init_lakeshore(auto_acquire=False)

Task - Perform first time setup of the Lakeshore 336 communication

Parameters:

auto_acquire (bool, optional) – Default is False. Starts data acquisition after initialization if True.

acq(f_sample=0.1)

Process - Begins recording data from thermometers and heaters.

Parameters:

f_sample (float, optional) – Default is 0.1. Sets the sampling rate in Hz.

Notes

The most recent data collected is stored in session.data in the structure:

>>> response.session['data']
{"ls336_fields":
    {"timestamp": 1921920543,
     "block_name": "temperatures"
     "data": {"Channel_A_T": (some value)
              "Channel_A_V": (some value)
              "Channel_B_T": (some value)
              "Channel_B_V": (some value)
              "Channel_C_T": (some value)
              "Channel_C_V": (some value)
              "Channel_D_T": (some value)
              "Channel_D_V": (some value)
             }
    }
}

stop_acq()

Task - Stops acq process.

set_heater_range(range=None, heater='2')

Task - Adjusts the heater range for servoing the load.

Parameters:

• range (str) – Sets the range of the chosen heater. Must be one of ‘off’, ‘low’, ‘medium’, and ‘high’.

• heater (str, optional) – default ‘2’. Chooses which heater’s range to change. Must be ‘1’ or ‘2’.

Notes

The range setting has no effect if an output is in the Off mode, and it does not apply to an output in Monitor Out mode. An output in Monitor Out mode is always on.

set_pid(P=None, I=None, D=None, heater='2')

Task - Set the PID parameters for servoing the load.

Parameters:

• P (float) – Proportional term for PID loop (must be between 0.1 and 1000)

• I (float) – Integral term for PID loop (must be between 0.1 and 1000)

• D (float) – Derivative term for PID loop (must be between 0 and 200)

• heater (str, optional) – Selects the heater on which to change the PID settings. Must be ‘1’ or ‘2’.

set_mode(mode=None, heater='2')

Task - Sets the output mode of the heater.

Parameters:

• mode (str) – Selects the output mode for the heater. Accepts four options: ‘off’, ‘closed loop’, ‘zone’, and ‘open loop’. for restrictions based on the selected heater.

• heater (str, optional) – Default ‘2’. Selects the heater on which to change the mode. Must be ‘1’ or ‘2’.

Notes

Does not support the options ‘monitor out’ and ‘warm up’, which only work for the unsupported analog outputs (heaters 3 and 4).

set_heater_resistance(resistance=None, heater='2')

Task - Sets the heater resistance and resistance setting of the heater. The associated ‘get’ function in the Heater class is get_heater_resistance_setting().

Parameters:

• resistance (float) – The actual resistance of the load

• heater (str, optional) – Default ‘2’. Selects the heater on which to set the resistance. Must be ‘1’ or ‘2’.

set_max_current(current=None, heater='2')

Task - Sets the maximum current that can pass through a heater.

Parameters:

• current (float) – The desired max current. Must be between 0 and 2 A.

• heater (str, optional) – Default ‘2’. Selects the heater on which to set the max current. Must be ‘1’ or ‘2’.

set_manual_out(percent=None, heater='2')

Task - Sets the manual output of the heater as a percentage of the full current or power depending on which display the heater is set to use.

Parameters:

• percent (float) – Percent of full current or power to set on the heater. Must have 2 or fewer decimal places.

• heater (str, optional) – Default ‘2’. Selects the heater on which to set the manual output. Must be ‘1’ or ‘2’.

set_input_channel(input=None, heater='2')

Task - Sets the input channel of the heater control loop.

Parameters:

• input (str) – The name of the heater to use as the input channel. Must be one of ‘none’,’A’,’B’,’C’, or ‘D’. Can also be ‘D2’,’D3’,’D4’, or ‘D5’ if the extra Lakeshore 3062 Scanner is installed in your LS336.

• heater (str, optional) – Default ‘2’. Selects the heater for which to set the input channel. Must be ‘1’ or ‘2’.

set_setpoint(setpoint=None, heater='2')

Task - Sets the setpoint of the heater control loop, after first turning ramp off. May be a limit to how high the setpoint can go based on your system parameters.

Parameters:

• setpoint (float) – The setpoint for the control loop. Units depend on the preferred sensor units (Kelvin, Celsius, or Sensor).

• heater (str, optional) – Default ‘2’. Selects the heater for which to set the input channel. Must be ‘1’ or ‘2’.

set_T_limit(T_limit=None, channel='A')

Task - Sets the temperature limit above which the control

output assigned to the selected channel shut off.

Parameters:

• T_limit (int) – The temperature limit in Kelvin. Note that a limit of 0 K turns off this feature for the given channel.

• channel (str, optional) – Default ‘A’. Selects which channel to use for controlling the temperature. Options are ‘A’,’B’,’C’, and ‘D’. Can also be ‘D2’,’D3’,’D4’, or ‘D5’ if the extra Lakeshore 3062 Scanner is installed in your LS336.

servo_to_temperature(temperature=None, ramp=0.1, heater='2', transport=False, transport_offset=0)

Task - A wrapper for setting the heater setpoint. Performs sanity checks on heater configuration before publishing setpoint:

1. checks control mode of heater (closed loop)

2. checks units of input channel (kelvin)

3. resets setpoint to current temperature with ramp off

4. sets ramp on to specified rate

5. checks setpoint does not exceed input channel T_limit

6. sets setpoint to commanded value

Note that this function does NOT turn on the heater if it is off. You must use set_heater_range() to pick a range first.

Parameters:

• temperature (float) – The new setpoint in Kelvin. Make sure there is is a control input set to the heater and its units are Kelvin.

• ramp (float, optional) – Default 0.1. The rate for how quickly the setpoint ramps to new value. Units of K/min.

• heater (str, optional) – Default ‘2’. The heater to use for servoing. Must be ‘1’ or ‘2’.

• transport (bool, optional) – Default False. See Notes for description.

• transport_offset (float, optional) – Default 0. In Kelvin. See Notes.

Notes: If param ‘transport’ is provided and True, the control loop restarts when the setpoint is first reached. This is useful for loads with long cooling times or time constant to help minimize over/undershoot.

If param ‘transport’ is provided and True, and ‘transport_offset’ is provided and positive, and the setpoint is higher than the current temperature, then the control loop will restart when the setpoint - transport_offset is first reached. This is useful to avoid a “false positive” temperature stability check too shortly after transport completes.

check_temperature_stability(threshold=0.1, window=900, heater='2')

Task - Assesses whether the load is stable around the setpoint to within some threshold.

Parameters:

• threshold (float, optional) – Default 0.1. See notes.

• window (int, optional) – Default 900. See notes.

• heater (str, optional) – Default ‘2’. Selects the heater for which to set the input channel. Must be ‘1’ or ‘2’.

Notes

Param ‘threshold’ sets the upper bound on the absolute temperature difference between the setpoint and any temperature from the input channel in the last ‘window’ seconds.

Param ‘window’ sets the lookback time into the most recent temperature data, in seconds. Note that this function grabs the most recent data in one window-length of time; it does not take new data.

If you want to use the result of this task for making logical decisions in a client (e.g. waiting longer before starting a process if the temperature is not yet stable), use the session[‘success’] key. It will be True if the temperature is stable and False if not. Example: >>> response = ls336.check_temperature_stability() >>> response.session[‘success’] True

get_channel_attribute(attribute=None, channel='A')

Task - Gets an arbitrary channel attribute and stores it in the session.data dict. Attribute must be the name of a method in the namespace of the Lakeshore336 Channel class, with a leading “get_” removed (see example).

Parameters:

• attribute (str) – The name of the channel attribute to get. See the Lakeshore 336 Channel class API for all options.

• channel (str, optional) – Default ‘A’. Selects which channel for which to get the attribute. Options are ‘A’,’B’,’C’, and ‘D’. Can also be ‘D2’,’D3’,’D4’, or ‘D5’ if the extra Lakeshore 3062 Scanner is installed in your LS336.

Example: >>> ls.get_channel_attribute(attribute = ‘T_limit’).session[‘data’] {‘T_limit’: 30.0}

get_heater_attribute(attribute=None, heater='2')

Task - Gets an arbitrary heater attribute and stores it in the session.data dict. Attribute must be the name of a method in the namespace of the Lakeshore336 Heater class, with a leading “get_” removed (see example).

Parameters:

• attribute (str) – The name of the channel attribute to get. See the Lakeshore 336 Heater class API for all options.

• heater (str, optional) – Default ‘2’. Selects the heater for which to get the heater attribute. Must be ‘1’ or ‘2’.

Examples

>>> ls.get_heater_attribute(attribute = 'heater_range').session['data']
{'heater_range': 'off'}

Supporting APIs

class socs.Lakeshore.Lakeshore336.LS336(ip, timeout=10)

Implements a lakeshore 336 box to interface with client scripts. Only contains locally relevant information; namely, port parameters. The state of the device is not stored locally to avoid the potential for inconsistent information. Device status can always be accessed (accurately) through a msg.

msg(message)

Send message to the Lakeshore 336 over ethernet.

If we’re asking for something from the Lakeshore (indicated by a ? in the message string), then we will attempt to ask twice before giving up due to potential communication timeouts.

Parameters:

message (str) – Message string as described in the Lakeshore 336 manual.

Returns:

Response string from the Lakeshore, if any. Else, an empty string.

Return type:

str

get_id()

Get identification information of the Lakeshore module

get_kelvin(inp)

Return a temperature reading of the specified input (‘A’, ‘B’, ‘C’, or ‘D’) or ‘0’ for all inputs. If the extra 3062 scanner is installed, possible options are (‘A’, ‘B’, ‘C’, ‘D’, ‘D1’, ‘D2’, ‘D3’, ‘D4, and ‘D5’). Note that D and D1 refer to the same channel!

Parameters:

inp (str) – channel to query

Returns:

array of four (or eight) floats if input is ‘0’, float otherwise of temperature reading

Return type:

array or float

Raises:

ValueError – Invalid input channel arguments

get_sensor(inp)

Return a sensor reading of the specified input (‘A’, ‘B’, ‘C’, or ‘D’) or ‘0’ for all inputs. If the extra 3062 scanner is installed, possible options are (‘A’, ‘B’, ‘C’, ‘D’, ‘D1’, ‘D2’, ‘D3’, ‘D4, and ‘D5’). Note that D and D1 refer to the same channel!

Parameters:

inp (str) – channel to query

Returns:

array of four (or eight) floats if input is ‘0’, float otherwise of sensor reading

Return type:

array or float

Raises:

ValueError – Invalid input channel arguments

class socs.Lakeshore.Lakeshore336.Channel(ls, inp)

Channel class for LS336

Parameters:

• ls (LS336 object) – The parent LS336 device

• inp (str) – The channel we are building (‘A’, ‘B’, ‘C’, or ‘D’) Could also be ‘D1’,’D2’,’D3’,’D4’, or ‘D5’ if the extra Lakeshore 3062 scanner is installed on the LS336. D and D1 refer to the same channel!

get_input_type()

Return sensor metadata, <sensor type>, <autorange>, <range>, <compensation>, and <units>. For diodes, only sensor type and units are relevant.

Returns:

<sensor type>, <autorange>, <range>, <compensation>, and <units>

Return type:

list

get_sensor_type()

Get the sensor type of the channel in plain text

set_sensor_type(type)

Set the sensor type on the channel

Parameters:

type (str) – Sensor type must be in ‘Disabled’, ‘Diode’, ‘Platinum RTD’, ‘NTC RTD’, ‘Thermocouple’, ‘Capacitance’

get_units()

Get the channel preferred units as plain text

set_units(units)

Set the channel preferred units

Parameters:

unit (str) – Channel preferred units must be in ‘Kelvin’, ‘Celsius, ‘Sensor

get_input_name()

Get the name of the channel shown on front display

Returns:

The channel name for display purposes

Return type:

str

set_input_name(name)

Set the name of the channel shown on front display

Parameters:

name (str) – The channel name for display purposes. Only send the first 15 characters

get_input_curve()

Return the curve number of the curve assigned to this channel

set_input_curve(curve_num)

Set the curve number of the curve assigned to this channel

get_T_limit()

Return the temperature limit above which control outputs assigned this channel shut off

set_T_limit(limit)

Set the temperature limit above which control outputs assigned this channel shut off

class socs.Lakeshore.Lakeshore336.Curve(ls, curve_num)

Calibration Curve class for the LS336.

get_header()

Get curve header description.

Returns:

response from CRVHDR? in list

Return type:

list

get_name()

Get the curve name with the CRVHDR? command.

Returns:

The curve name

Return type:

str

set_name(name)

Set the curve name with the CRVHDR command.

Parameters:

name (str) – The curve name, limit of 15 characters, longer names get truncated

Returns:

the response from the CRVHDR command

Return type:

str

get_serial_number()

Get the curve serial number with the CRVHDR? command.”

Returns:

The curve serial number

Return type:

str

set_serial_number(serial_number)

Set the curve serial number with the CRVHDR command.

Parameters:

serial_number (str) – The curve serial number, limit of 10 characters, longer serials get truncated

Returns:

the response from the CRVHDR command

Return type:

str

get_format()

Get the curve data format with the CRVHDR? command.”

Returns:

The curve data format

Return type:

str

set_format(_format)

Set the curve format with the CRVHDR command.

Parameters:

_format (str) – The curve format, valid formats are: “mV/K (linear)”, “V/K (linear)”, “Ohm/K (linear)”, and “log Ohm/K (linear)”

Returns:

the response from the CRVHDR command

Return type:

str

get_limit()

Get the curve temperature limit with the CRVHDR? command.

Returns:

The curve temperature limit

Return type:

str

set_limit(limit)

Set the curve temperature limit with the CRVHDR command.

Parameters:

limit (float) – The curve temperature limit

Returns:

the response from the CRVHDR command

Return type:

str

get_coefficient()

Get the curve temperature coefficient with the CRVHDR? command.

Returns:

The curve temperature coefficient

Return type:

str

set_coefficient(coefficient)

Set the curve temperature coefficient with the CRVHDR command.

Parameters:

coefficient (str) – The curve temperature coefficient, either ‘positive’ or ‘negative’

Returns:

the response from the CRVHDR command

Return type:

str

get_data_point(index)

Get a single data point from a curve, given the index, using the CRVPT? command.

Parameters:

index (int) – index of breakpoint to msg

Returns:

(units, tempertaure, curvature) values for the given breakpoint

The format for the return value, a 2-tuple of floats, is chosen to work with how the get_curve() method later stores the entire curve in a numpy structured array.

Return type:

tuple

get_curve(_file=None)

Get a calibration curve from the LS336. If _file is not None, save to file location.

set_curve(_file)

Set a calibration curve, loading it from the file.

Parameters:

_file (str) – the file to load the calibration curve from

Returns:

return the new curve header, refreshing the attributes

Return type:

list

delete_curve()

Delete the curve using the CRVDEL command.

Returns:

the response from the CRVDEL command

Return type:

str

soft_cal(std, points, delay=1)

Executes SCAL command using the data in points_str. Note this overwrites the current breakpoints!

Parameters:

• std (int) – Standard curve number to base the SoftCal on

• points (list) – List of T1,U1,T2,U2,T3,U3 values

class socs.Lakeshore.Lakeshore336.Heater(ls, output)

Heater class for LS336 control

Parameters:

• ls (Lakeshore336.LS336) – the lakeshore object we’re controlling

• output (int) – the heater output we want to control, 1 = 100W, 2 = 50W

get_output_mode()

msg the heater mode using the OUTMODE? command.

Returns:

3-tuple with output mode, input, and whether powerup is enabled

Return type:

tuple

get_mode()

Set output mode with OUTMODE? commnd.

Returns:

The output mode

Return type:

str

set_mode(mode)

Set output mode with OUTMODE commnd.

Parameters:

mode (str) – control mode for heater

Returns:

the response from the OUTMODE command

Return type:

str

get_input_channel()

Get the control channel with the OUTMODE? command.

Returns:

The control channel

Return type:

str

set_input_channel(inp)

Set the control channel with the OUTMODE command.

Parameters:

inp (str or int) – specifies which input or channel to control from

get_powerup()

Get the powerup state with the OUTMODE? command.

Returns:

The powerup state

Return type:

str

set_powerup(powerup)

Parameters:

powerup (bool) – specifies whether the output remains on or shuts off after power cycle. True for on after powerup

get_heater_setup()

Gets Heater setup params with the HTRSET? command.

Returns:

List of values that have been returned from the Lakeshore.

Return type:

list

get_heater_resistance_setting()

Get the “setting” of the heater resistance, which can only be 25 or 50 Ohms

set_heater_resistance(res)

Sets the correct heater setting depending on the actual load resistance

Parameters:

res (int or float) – Actual resistance of load being powered

get_max_current()

Get the limiting current of the heater. Either set by “max current” if user max current not on, or user max current if user max current on.

Returns:

Limiting heater current

Return type:

float

get_heater_display()

Get whether heater displays in % of full current or power

Returns:

Display unit (% of current or % of power)

Return type:

str

set_heater_display(display)

Change the display of the heater

Parameters:

display (str) – Display mode for heater. Can either be ‘current’ or ‘power’.

get_manual_out()

Return the % of full current or power depending on heater display, if set by MOUT

Returns:

the % of full current or power depending on heater display

Return type:

float

set_manual_out(percent)

Set the % of full current or power depending on heater display, with MOUT

Parameters:

percent (int or float) – the % of full current or power depending on heater display

get_heater_range()

Get heater range with RANGE? command.

Returns:

heater range by decade in total available power/current

Return type:

float

set_heater_range(rng)

Set heater range with RANGE command.

Parameters:

rng (str) – heater range, either ‘Off’,’Low’,’Medium’, or ‘High’

get_setpoint()

Return the setpoint in control loop sensor units

set_setpoint(value)

Set the setpoint of the control loop in sensor units

Parameters:

value (int or float) – The setpoint. Units depend on the preferred sensor units.

get_pid()

Get PID parameters with PID? command.

Returns:

(p, i, d)

Return type:

tuple

set_pid(p, i, d)

Set PID parameters for closed loop control.

Parameters:

• p (float) – proportional term in PID loop

• i (float) – integral term in PID loop

• d (float) – derivative term in PID loop

Returns:

response from PID command

Return type:

str

get_ramp()

Return list of params <on/off>, <rate value> for RAMP? msg

Returns:

<on/off>, <rate value> for RAMP? msg

Return type:

list

get_ramp_on_off()

Get string indicating ramp ‘on’ or ‘off’

set_ramp_on_off(on_off)

Turn ramp on or off

Parameters:

on_off (str) – Either ‘on’ to enable ramp or ‘off’ to disable ramp

get_ramp_rate()

Returns ramp rate in K/min

set_ramp_rate(rate)

Set ramp rate of changes in setpoint, in K/min

Parameters:

rate (int or float) – Absolute value of setpoint rate of change, from 0.1 to 100 K/min

get_ramp_status()

Return a string indicating whether or not the setpoint is currently ramping

get_heater_percent()

Return the current heater output level in %