# devices.oxford:MercuryIPS


Driver for multi-axis Mercury IPS.


Usage

``` python
devices.oxford:MercuryIPS(
    interface,
    **kwargs,
)
```


dataDict contains the commands (keys) and also the response from the IPS (values).

Mode of operation: 1. Querry dicts you want to read - results are written to dictionarys 2. Results can now be read with the given functions

Dicts for functions: confDictX/Y/Z for magnetic field status (to Setpoint etc.) dataDictX/Y/Z for magnetic field functions confDictLevel for Helium Fast/Slow dataDictLevel for Helium/Nitrogen Levels

Usually all relevant parameters for operation can be found in the workingDict.


## Methods

| Name | Description |
|----|----|
| [__init__()](#__init__) | Initialize the Mercury multi-axis IPS device. |
| [checkFields()](#checkFields) | Check field boundaries and return valid field values. |
| [getDictValue()](#getDictValue) | Get a value from the working dictionary. |
| [getFastRate()](#getFastRate) | Get the helium level meter mode. |
| [getLevels()](#getLevels) | Get the liquid nitrogen and helium levels. |
| [getMagnetStatus()](#getMagnetStatus) | Get the status of the magnet(s). |
| [getMagneticFieldRate()](#getMagneticFieldRate) | Get rates of change for magnetic field axes. |
| [getMagneticFields()](#getMagneticFields) | Get the current magnetic field values. |
| [logAllDicts()](#logAllDicts) | Log the contents of all dictionaries for debugging. |
| [queryAllDicts()](#queryAllDicts) | Query all dictionaries to update their values. |
| [queryDict()](#queryDict) | Query all entries in a dictionary. |
| [queryID()](#queryID) | Query the device ID. |
| [queryLevelMeter()](#queryLevelMeter) | Query the level meter configuration. |
| [queryLevelMeterStatus()](#queryLevelMeterStatus) | Query the level meter status. |
| [queryMagnetConf()](#queryMagnetConf) | Query the magnet configuration for all axes. |
| [queryMagnetStatus()](#queryMagnetStatus) | Query the magnet status for all axes. |
| [querySysConf()](#querySysConf) | Query the system configuration. |
| [queryWorkingDict()](#queryWorkingDict) | Query all entries in the working dictionary. |
| [query_merc()](#query_merc) | Query a value from the device. |
| [setFastRate()](#setFastRate) | Set the helium level meter to fast or slow mode. |
| [setMagnetStatus()](#setMagnetStatus) | Set the status of the magnet(s). |
| [setMagneticFieldRate()](#setMagneticFieldRate) | Set rates of change for all magnetic field axes. |
| [setMagneticFields()](#setMagneticFields) | Set the magnetic field on all three axes. |
| [setVal()](#setVal) | Set a value on the device. |

------------------------------------------------------------------------


### \_\_init\_\_()


Initialize the Mercury multi-axis IPS device.


Usage

``` python
__init__(
    interface,
    **kwargs,
)
```


#### Parameters


`interface: str`  
VISA resource name

`**kwargs: dict`  
Additional arguments passed to the parent class


------------------------------------------------------------------------


### checkFields()


Check field boundaries and return valid field values.


Usage

``` python
checkFields(
    xval,
    yval,
    zval,
    tolerance=0.0,
)
```


#### Parameters


`xval: float`  
X-axis field value

`yval: float`  
Y-axis field value

`zval: float`  
Z-axis field value

`tolerance: float = ``0.0`  
Tolerance to apply to limits, by default 0.0


#### Returns


`tuple`  
(valid, (xval, yval, zval)) where valid is a boolean indicating if the original values were within limits, and the tuple contains the adjusted values


------------------------------------------------------------------------


### getDictValue()


Get a value from the working dictionary.


Usage

``` python
getDictValue(key)
```


#### Parameters


`key: str`  
Key in the working dictionary


#### Returns


`float or bool`  
Value from the working dictionary


------------------------------------------------------------------------


### getFastRate()


Get the helium level meter mode.


Usage

``` python
getFastRate()
```


#### Returns


`bool`  
True if in slow mode, False if in fast mode


------------------------------------------------------------------------


### getLevels()


Get the liquid nitrogen and helium levels.


Usage

``` python
getLevels()
```


#### Returns


`tuple`  
(LN2 level, LHe level) as percentage values


------------------------------------------------------------------------


### getMagnetStatus()


Get the status of the magnet(s).


Usage

``` python
getMagnetStatus(axis=-1)
```


#### Parameters


`axis: int = ``-1`  
Axis to query: 0=x, 1=y, 2=z, -1=all axes, by default -1


#### Returns


`int or list`  
Status of the magnet(s): 0 - HOLD 1 - RTOS (Ramp to setpoint) 2 - RTOZ (Ramp to zero) 3 - CLMP (Clamped, when current is 0) If axis is -1, returns a list of statuses for all three axes.


------------------------------------------------------------------------


### getMagneticFieldRate()


Get rates of change for magnetic field axes.


Usage

``` python
getMagneticFieldRate(
    axis=-1,
    setp=False,
)
```


#### Parameters


`axis: int = ``-1`  
Axis to query: 0=x, 1=y, 2=z, -1=all axes, by default -1

`setp: bool = ``False`  
If True, also return the setpoints, by default False


#### Returns


`float or tuple or list`  
If axis is -1, returns list of rates \[x, y, z\] (and setpoints if requested) If axis is 0, 1, or 2, returns rate for that axis (and setpoint if requested)


------------------------------------------------------------------------


### getMagneticFields()


Get the current magnetic field values.


Usage

``` python
getMagneticFields(setp=False)
```


#### Parameters


`setp: bool = ``False`  
If True, also return the setpoints, by default False


#### Returns


`tuple`  
If setp is False, returns (x_field, y_field, z_field) If setp is True, returns (x_field, y_field, z_field, x_setpoint, y_setpoint, z_setpoint)


------------------------------------------------------------------------


### logAllDicts()


Log the contents of all dictionaries for debugging.


Usage

``` python
logAllDicts()
```


------------------------------------------------------------------------


### queryAllDicts()


Query all dictionaries to update their values.


Usage

``` python
queryAllDicts()
```


------------------------------------------------------------------------


### queryDict()


Query all entries in a dictionary.


Usage

``` python
queryDict(
    queryDict,
    address="",
    signal=False,
)
```


#### Parameters


`queryDict: dict`  
Dictionary containing commands as keys

`address: str = ``""`  
Device address, by default ""

`signal: bool = ``False`  
Whether to use the signal variant of the command, by default False


------------------------------------------------------------------------


### queryID()


Query the device ID.


Usage

``` python
queryID()
```


------------------------------------------------------------------------


### queryLevelMeter()


Query the level meter configuration.


Usage

``` python
queryLevelMeter()
```


------------------------------------------------------------------------


### queryLevelMeterStatus()


Query the level meter status.


Usage

``` python
queryLevelMeterStatus()
```


------------------------------------------------------------------------


### queryMagnetConf()


Query the magnet configuration for all axes.


Usage

``` python
queryMagnetConf()
```


------------------------------------------------------------------------


### queryMagnetStatus()


Query the magnet status for all axes.


Usage

``` python
queryMagnetStatus()
```


------------------------------------------------------------------------


### querySysConf()


Query the system configuration.


Usage

``` python
querySysConf()
```


------------------------------------------------------------------------


### queryWorkingDict()


Query all entries in the working dictionary.


Usage

``` python
queryWorkingDict()
```


Updates the values in the working dictionary with current device values.


------------------------------------------------------------------------


### query_merc()


Query a value from the device.


Usage

``` python
query_merc(
    command,
    address="",
    signal=False,
)
```


#### Parameters


`command: str`  
Command to send

`address: str = ``""`  
Device address, by default ""

`signal: bool = ``False`  
Whether to use the signal variant of the command, by default False


#### Returns


`str`  
Response from the device


------------------------------------------------------------------------


### setFastRate()


Set the helium level meter to fast or slow mode.


Usage

``` python
setFastRate(slow=True)
```


#### Parameters


`slow: bool = ``True`  
True for slow mode, False for fast mode, by default True


------------------------------------------------------------------------


### setMagnetStatus()


Set the status of the magnet(s).


Usage

``` python
setMagnetStatus(
    state,
    axis=-1,
)
```


#### Parameters


`state: int or list`  
Status to set: 0 - HOLD 1 - RTOS (Ramp to setpoint) 2 - RTOZ (Ramp to zero) 3 - CLMP (Clamped, when current is 0) - disallowed If axis is -1, state should be a list of 3 integers for each axis.

`axis: int = ``-1`  
Axis to set: 0=x, 1=y, 2=z, -1=all axes (using state as list), by default -1


#### Notes

Status 3 (CLMP) is disallowed as it could damage the magnet.

------------------------------------------------------------------------


### setMagneticFieldRate()


Set rates of change for all magnetic field axes.


Usage

``` python
setMagneticFieldRate(values)
```


#### Parameters


`values: list`  
List of 3 floats specifying rates for \[x, y, z\] axes in T/min. Values are clamped to valid ranges:

- x, y axes: 0 to 0.5 T/min
- z axis: 0 to 1 T/min


------------------------------------------------------------------------


### setMagneticFields()


Set the magnetic field on all three axes.


Usage

``` python
setMagneticFields(fields)
```


#### Parameters


`fields: list`  
List with three entries containing field values \[x, y, z\] in Tesla. Values exceeding the boundaries will be clamped.


------------------------------------------------------------------------


### setVal()


Set a value on the device.


Usage

``` python
setVal(
    setpoint,
    command,
    address="",
    signal=False,
)
```


#### Parameters


`setpoint: float or str`  
Value to set

`command: str`  
Command to use

`address: str = ``""`  
Device address, by default ""

`signal: bool = ``False`  
Whether to use the signal variant of the command, by default False


#### Returns


`str`  
Response from the device