# kontrol.sensact package¶

## Primary modules¶

### kontrol.sensact.matrix module¶

Base class for matrices, sensing and actuation matices.

class kontrol.sensact.matrix.Matrix(*args, **kwargs)

Bases: numpy.ndarray

Base class for matrices

class kontrol.sensact.matrix.SensingMatrix(matrix, coupling_matrix=None, *args, **kwargs)

Base class for sensing matrices

diagonalize(coupling_matrix=None)

Diagonalize the sensing matrix, given a coupling matrix.

Parameters: coupling_matrix (array, optional.) – The coupling matrix. If None, self.coupling_matrix will be used. Default None. The new sensing matrix. array

Notes

The coupling matrix has (i, j) elements as coupling ratios x_i/x_j. For example, consider the 2-sensor configuration: I have a coupled sensing readout $$x_{1,\mathrm{coupled}}$$ that reads $$x_{1,\mathrm{coupled}}=x_1 + 0.1x_2$$. and, I have another coupled sensing readout $$x_{2,\mathrm{coupled}}$$ that reads $$x_{2,\mathrm{coupled}}=-0.2x_1 + x_2$$. Then, the coupling matrix is

$\begin{split}\begin{bmatrix} 1 & 0.1\\ -0.2 & 1 \end{bmatrix}.\end{split}$

### kontrol.sensact.optical_lever module¶

Optical lever sensing matrix

class kontrol.sensact.optical_lever.HorizontalOpticalLeverSensingMatrix(*args, **kwargs)

Horizontal optical lever sensing matrix.

Parameters: r (float) – Lever arm. alpha_h (float) – Angle of incidence on the horizontal plane. r_lens (float, optional) – Lever arm from the optics to the convex lens. Default 0. f (float, optional) – Focal length of the convex lens. Default np.inf. alpha_v (float, optional) – Angle of incidence on the vertical plane. Default 0. phi_tilt (float, optional) – Angle from the tilt-sensing QPD frame to the yaw-pitch frame. Default 0. phi_len (float, optional) – Angle from the length-sensing QPD frame to the yaw-pitch frame. Default 0. delta_x (float, optional) – Horizontal miscentering of the beam spot at the optics plane. Default 0. delta_y (float, optional) – Vertical miscentering of the beam spot at the optics plane. Default 0. delta_d (float, optional) – Misplacement of the length-sensing QPD. Default 0. format (str, optional) – Format of the sensing matrix. Choose from ”OPLEV2EUL”: Default sensing matrix from KAGRA MEDM screen with input (TILT_PIT, TILT_YAW, LEN_PIT, LEN_YAW), and output (longitudinal, pitch and yaw). ”xy”: Matrix as shown in [1]_. coupling_matrix (array, optional) – The coupling matrix. Default None. *args – Variable length arguments passed to OpticalLeverSensingMatrix. **kwargs – Keyword arguments passed to OpticalLeverSensingMatrix.
delta_d

Misplacement of the length-sensing QPD.

f

Focal length of the convex lens.

r

Lever arm.

r_lens

Lever arm from the optics to the convex lens.

class kontrol.sensact.optical_lever.OpticalLeverSensingMatrix(*args, **kwargs)

Optical lever sensing matrix base class.

This is a sensing matrix that maps tilt-sensing QPD and length-sensing QPD (placed behind a lens) readouts to the suspended optics’ longitudinal, pitch, and yaw displacements.

Parameters: r_h (float) – Lever arm from the optics to the tilt-sensing QPD plane on the horizontal plane (amplifying yaw). r_v (float) – Lever arm from the optics to the tilt-sensing QPD plane on the vertical plane (amplifying pitch). alpha_h (float) – Angle of incidence on the horizontal plane. alpha_v (float) – Angle of incidence on the vertical plane. r_lens_h (float, optional) – Lever arm from optics to the lens on the horizontal plane. Defaults None. Specify if it exists. r_lens_v (float, optional) – Lever arm from optics to the lens on the vertical plane. Defaults None. Specify if it exists. d_h (float, optional) – Horizontal distance from the lens to the length-sensing QPD. Defaults None. d_v (float, optional) – Vertical distance from the lens to the length-sensing QPD. Defaults None. delta_x (float, optional) – Horizontal miscentering of the beam spot at the optics plane. delta_y (float, optional) – Vertical miscentering of the beam spot at the optics plane. phi_tilt (float, optional) – Angle from the tilt-sensing QPD frame to the yaw-pitch frame. Defaults None. phi_len (float, optional) – Angle from the length-sensing QPD frame to the yaw-pitch frame. Defaults None. f_h (float, optional,) – Focal length of the lens projected to the horizontal plane. Defaults np.inf (no lens). f_v (float, optional,) – Focal length of the lens projected to the vertical plane. Defaults np.inf (no lens). format (str, optional) – Format of the sensing matrix. Choose from ”OPLEV2EUL”: Default sensing matrix from KAGRA MEDM screen with input (TILT_PIT, TILT_YAW, LEN_PIT, LEN_YAW), and output (longitudinal, pitch and yaw). ”xy”: Matrix as shown in [1]_. coupling_matrix (array, optional) – The coupling matrix. Default None.

Notes

We’re using equation (29) from [1]_.

\begin{split}\begin{pmatrix} x_L\\ \theta_P\\ \theta_Y \end{pmatrix} = \mathbf{C}_\mathrm{miscenter} \mathbf{C}_\mathrm{align} \mathbf{C}_\mathrm{rotation} \begin{pmatrix} x_\mathrm{tilt}\\ y_\mathrm{tilt}\\ x_\mathrm{len}\\ y_\mathrm{len} \end{pmatrix},\end{split}

where $$x_L$$ is the longitudinal displacement of the optics, $$\theta_P$$ is the pitch angular displacement of the optics, $$\theta_Y$$ is the yaw angular displacement of the optics, $$x_\mathrm{tilt}$$ is the horizontal displacement of the beam spot at the tilt-sensing QPD plane, $$y_\mathrm{tilt}$$ is the vertical displacement of the beam spot at the tilt-sensing QPD plane, $$x_\mathrm{len}$$ is the horizontal displacement of the beam spot at the length-sensing QPD plane, $$y_\mathrm{len}$$ is the vertical displacement of the beam spot at the length-sensing QPD plane,

$\begin{split}\mathbf{C}_\mathrm{rotation} = \begin{bmatrix} \cos\phi_\mathrm{tilt} & \sin\phi_\mathrm{tilt} & 0 & 0\\ -\sin\phi_\mathrm{tilt} & \cos\phi_\mathrm{tilt} & 0 & 0\\ 0 & 0 & \cos\phi_\mathrm{len} & \sin\phi_\mathrm{len}\\ 0 & 0 & -\sin\phi_\mathrm{len} & \cos\phi_\mathrm{len} \end{bmatrix},\end{split}$
\begin{split}\mathbf{C}_\mathrm{align} = \begin{bmatrix} 2\sin\alpha_h & 0 & 2r_h\\ 2\sin\alpha_v & 2r_v & 0\\ 2\sin\alpha_h\left(1-\frac{d_h}{f_h}\right) & 0 & 2\left[\left(1-\frac{d_h}{f_h}\right)r_{\mathrm{lens},h} + d_h\right]\\ 2\sin\alpha_v\left(1-\frac{d_v}{f_v}\right) & 2\left[\left(1-\frac{d_v}{f_v}\right)r_{\mathrm{lens},v} + d_v\right] & 0\\ \end{bmatrix}^{+},\end{split}
$\begin{split}\mathbf{C}_\mathrm{miscenter} = \begin{bmatrix} 1 & \delta_y & \delta_x\\ 0 & 1 & 0\\ 0 & 0 & 1 \end{bmatrix}^{-1},\end{split}$

$$\phi_\mathrm{tilt}$$ is the angle between the tilt-sensing QPD and the yaw-pitch frame, $$\phi_\mathrm{len}$$ is the angle between the length-sensing QPD and the yaw-pitch frame, $$r_h$$ is the lever arm on the horzontal plane, $$r_v$$ is the lever arm on the vertical plane, $$\alpha_h$$ is the angle of incidence on the horizontal plane, $$\alpha_v$$ is the angle of incidence on the vertical plane, $$r_{\mathrm{lens}, h}$$ is the lever arm between the optics and the lens on the horizontal plane, $$r_{\mathrm{lens}, v}$$ is the lever arm between the optics and the lens on the vertical plane, $$d_h$$ is the distance between the lens and the length-sensing QPD on the horizontal plane, $$d_v$$ is the distance between lens and the length-sensing QPD on the vertical plane, and $$f$$ is the focal length of the convex lens.

References

 [1] Tsang Terrence Tak Lun, Sensing Matrices for Optical Levers of the KAGRA Main Optics, https://github.com/terrencetec/kagra-optical-lever.
alpha_h

Angle of incidence on the horizontal plane.

alpha_v

Angle of incidence on the vertical plane.

d_h

Horizontal distance from the lens to the length-sensing QPD.

d_v

Vertical distance from the lens to the length-sensing QPD.

delta_x

Horizontal miscentering of the beam spot at the optics plane.

delta_y

Horizontal miscentering of the beam spot at the optics plane.

f_h

Focal length of the convex lens projected on the horizontal plane.

f_v

Focal length of the convex lens projected on the vertical plane.

format

Format of the sensing matrix.

Choose from
“OPLEV2EUL”: Default sensing matrix from KAGRA MEDM screen
with input (TILT_PIT, TILT_YAW, LEN_PIT, LEN_YAW), and output (longitudinal, pitch and yaw).

“xy”: Matrix as shown in [1]_.

References

 [1] Tsang Terrence Tak Lun, Sensing Matrices for Optical Levers of the KAGRA Main Optics, https://github.com/terrencetec/kagra-optical-lever.
phi_len

Angle from the length-sensing QPD frame to the yaw-pitch frame.

phi_tilt

Angle from the tilt-sensing QPD frame to the yaw-pitch frame.

r_h

Lever arm from optics to tilt-sensing QPD on the horizontal plane.

r_lens_h

Lever arm from optics to the lens on the horizontal plane.

r_lens_v

Lever arm from optics to the lens on the vertical plane.

r_v

Lever arm from optics to tilt-sensing QPD on the vertical plane.

update_matrices_decorator()

Update matrices and self upon setting new parameters.

class kontrol.sensact.optical_lever.VerticalOpticalLeverSensingMatrix(*args, **kwargs)

Vertical optical lever sensing matrix.

Parameters: r (float) – Lever arm. alpha_v (float) – Angle of incidence on the vertical plane. r_lens (float, optional) – Lever arm from the optics to the convex lens. Default 0. f (float, optional) – Focal length of the convex lens. Default np.inf. alpha_h (float, optional) – Angle of incidence on the horizontal plane. Default 0. phi_tilt (float, optional) – Angle from the tilt-sensing QPD frame to the yaw-pitch frame. Default 0. phi_len (float, optional) – Angle from the length-sensing QPD frame to the yaw-pitch frame. Default 0. delta_x (float, optional) – Horizontal miscentering of the beam spot at the optics plane. Default 0. delta_y (float, optional) – Vertical miscentering of the beam spot at the optics plane. Default 0. delta_d (float, optional) – Misplacement of the length-sensing QPD. Default 0. format (str, optional) – Format of the sensing matrix. Choose from ”OPLEV2EUL”: Default sensing matrix from KAGRA MEDM screen with input (TILT_PIT, TILT_YAW, LEN_PIT, LEN_YAW), and output (longitudinal, pitch and yaw). ”xy”: Matrix as shown in [1]_. coupling_matrix (array, optional) – The coupling matrix. Default None. *args – Variable length arguments passed to OpticalLeverSensingMatrix. **kwargs – Keyword arguments passed to OpticalLeverSensingMatrix.
delta_d

Misplacement of the length-sensing QPD.

f

Focal length of the convex lens.

r

Lever arm.

r_lens

Lever arm from the optics to the convex lens.

kontrol.sensact.optical_lever.c_align(r_h, r_v, alpha_h, alpha_v, r_lens_h=0, r_lens_v=0, d_h=0, d_v=0, f_h=inf, f_v=inf, roundoff=6)

Return optical lever sensing matrix for a perfectly aligned case.

Parameters: r_h (float) – Lever arm from the optics to the tilt-sensing QPD plane on the horizontal plane (amplifying yaw). r_v (float) – Lever arm from the optics to the tilt-sensing QPD plane on the vertical plane (amplifying pitch). alpha_h (float) – Angle of incidence on the horizontal plane. alpha_v (float) – Angle of incidence on the vertical plane. r_lens_h (float, optional) – Lever arm from optics to the lens on the horizontal plane. Defaults None. Specify if it exists. r_lens_v (float, optional) – Lever arm from optics to the lens on the vertical plane. Defaults None. Specify if it exists. d_h (float, optional) – Horizontal distance from the lens to the length-sensing QPD. Defaults None. d_v (float, optional) – Vertical distance from the lens to the length-sensing QPD. Defaults None. f_h (float, optional,) – Focal length of the lens projected to the horizontal plane. Defaults np.inf (no lens). f_v (float, optional,) – Focal length of the lens projected to the vertical plane. Defaults np.inf (no lens). roundoff (int, optional) – How many decimal places to keep. The aligned optical lever sensing matrix array

Notes

See \mathbf{C}_\mathrm{align} from [1]_.

If f_h or f_v or (d_h and d_v) or (r_lens_h and r_lens_v) are not specified, then we assume no length-sensing QPD so first column, third row, and forth row will be 0. elif f_h and f_v is specified, (d_h or r_lens_h) are not specified, then third row will be 0. elif f_h and f_v is specified, (d_v or r_lens_v) are not specified, then forth row will be 0.

References

 [1] Tsang Terrence Tak Lun, Sensing Matrices for Optical Levers of the KAGRA Main Optics, https://github.com/terrencetec/kagra-optical-lever.
kontrol.sensact.optical_lever.c_miscenter(delta_x, delta_y)

Returns the matrix for correcting miscentered optical lever beam.

Parameters: delta_x (float) – Horizontal miscentering of the beam spot at the optics plane. delta_y (float) – Vertical miscentering of the beam spot at the optics plane. The miscentering correction matrix. array
kontrol.sensact.optical_lever.c_rotation(phi_tilt, phi_len)

Returns the rotation transformation matrix for tilt and length QPDs.

Parameters: phi_tilt (float) – Angle from the tilt-sensing QPD frame to the yaw-pitch frame. phi_len (float) – Angle from the length-sensing QPD frame to the yaw-pitch frame. Matrix that transform the QPD frames to the yaw-pitch frame. array

Notes

See $$\mathbf{C}_\mathrm{rotation}$$ from [1]_

References

 [1] Tsang Terrence Tak Lun, Sensing Matrices for Optical Levers of the KAGRA Main Optics, https://github.com/terrencetec/kagra-optical-lever.

### kontrol.sensact.calibration module¶

Calibration library for calibrating sensors from sensors measurements

kontrol.sensact.calibration.calibrate(xdata, ydata, method='linear', **kwargs)

Fit the measurement data and returns the slope of the fit.

Parameters: xdata (array) – The independent variable, e.g. the displacement of the sensor. ydata (array) – The dependent variable, e.g. the sensor readout. method (str, optional) – The method of the fit. Choose from [“linear”, “erf”]. ”linear”: use kontrol.sensact.calibration.calibrate_linear() ”erf”: use kontrol.sensact.calibration.calibrate_erf() **kwargs – Keyword arguments passed to the calibration methods. slope (float) – The slope of the fitted straight line. intercept (float) – The y-intercept of the fitted straight line. linear_range (float, optional) – The range of y where the sensor considered linear.
kontrol.sensact.calibration.calibrate_erf(xdata, ydata, nonlinearity=5, return_linear_range=False, return_model=False)

Fit an error function and return the 1st-order slope and intercept.

Parameters: xdata (array) – The independent variable, e.g. the displacement of the sensor. ydata (array) – The dependent variable, e.g. the sensor readout. nonlinearity (float, optional) – The specification of non-linearity (%). Defined by the maximum deviation of the full_range. Default 5. return_linear_range (boolean, optional) – If True, return the linear range of ydata. return_model (boolean, optional) – Return a kontrol.curvefit.model.Model object with the fitted parameters. slope (float) – The slope of the fitted straight line. intercept (float) – The $$y$$-intercept of the fitted straight line. linear_range (float, optional) – The range of x where the sensor considered linear.

Notes

Credits to Kouseki Miyo, the inventor of this method.

We fit the following function

$f(x; a, m, x_0, y_0) = a\,\mathrm{erf}(m(x-x_0)) + y_0\,\,$

where $$a, m, x_0, y_0$$ are some parameters to be found. The $$\mathrm{erf}(x)$$ function is defined as

$\mathrm{erf}(x) = \frac{2}{\sqrt{\pi}}\int_0^x\,e^{-x^2}\,dx\,.$

If we taylor expand the exponential function and take the first-order approximation of the $$\mathrm{erf}(x)$$ function, we get

$\mathrm{erf}(x) \approx \frac{2am}{\sqrt{\pi}}(x-x_0) + y_0\,.$

So the (inverse) calibration factor is $$\frac{2am}{\sqrt{\pi}}$$, and the $$y$$-intercept is $$\frac{2am}{\sqrt{\pi}}x_0 + y_0$$.

kontrol.sensact.calibration.calibrate_linear(xdata, ydata, nonlinearity=5, full_range=None, start_index=None, return_linear_range=False, return_model=False)

Fit a straight line to the data and returns the slope and intercept

This functions recursively fits a straight line to chosen data points and terminates when no linear data point remains. It starts from 3 points closest to the middle of the full-range. After fitting a straight line to the 3 points, other data points that are within the linearity specification will be included to the dataset and this dataset will be use for the next fit. The process repeats until no data points can be added anymore.

Parameters: xdata (array) – The independent variable, e.g. the displacement of the sensor. ydata (array) – The dependent variable, e.g. the sensor readout. nonlinearity (float, optional) – The specification of non-linearity (%). Defined by the maximum deviation of the full_range. Default 5. full_range (float, optional) – The full output range of the sensor. If not specified, it will be chosen to be max(ydata) - min(ydata) start_index (int, optional) – The index of the data point to start with. If not specified, it will be chosen to be index of the ydata closest to (max(ydata) + min(ydata))/2. return_linear_range (boolean, optional) – If True, return the linear range of ydata. return_model (boolean, optional) – Return a kontrol.curvefit.model.Model object with the fitted parameters. slope (float) – The slope of the fitted straight line. intercept (float) – The y-intercept of the fitted straight line. linear_range (float, optional) – The range of x where the sensor considered linear. model (kontrol.curvefit.model.Model) – The fitted model.