kontrol.sensact
Primary modules
kontrol.sensact.matrix
Base class for matrices, sensing and actuation matices.
- class kontrol.sensact.matrix.Matrix(matrix=None, *args, **kwargs)
Bases:
ndarray
Base class for matrices
- class kontrol.sensact.matrix.SensingMatrix(matrix=None, *args, **kwargs)
Bases:
Matrix
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.
- Returns
The new sensing matrix.
- Return type
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
Optical lever sensing matrix
- class kontrol.sensact.optical_lever.HorizontalOpticalLeverSensingMatrix(r, alpha_h, r_lens=0, f=inf, alpha_v=0, phi_tilt=0, phi_len=0, delta_x=0, delta_y=0, delta_d=0, format='OPLEV2EUL', coupling_matrix=None, *args, **kwargs)
Bases:
OpticalLeverSensingMatrix
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.
- property delta_d
Misplacement of the length-sensing QPD.
- property f
Focal length of the convex lens.
- property r
Lever arm.
- property r_lens
Lever arm from the optics to the convex lens.
- class kontrol.sensact.optical_lever.OpticalLeverSensingMatrix(r_h, r_v, alpha_h, alpha_v, r_lens_h=0, r_lens_v=0, d_h=0, d_v=0, delta_x=0, delta_y=0, phi_tilt=0, phi_len=0, f_h=inf, f_v=inf, format='OPLEV2EUL', coupling_matrix=None, *args, **kwargs)
Bases:
SensingMatrix
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.
- property alpha_h
Angle of incidence on the horizontal plane.
- property alpha_v
Angle of incidence on the vertical plane.
- property d_h
Horizontal distance from the lens to the length-sensing QPD.
- property d_v
Vertical distance from the lens to the length-sensing QPD.
- property delta_x
Horizontal miscentering of the beam spot at the optics plane.
- property delta_y
Horizontal miscentering of the beam spot at the optics plane.
- property f_h
Focal length of the convex lens projected on the horizontal plane.
- property f_v
Focal length of the convex lens projected on the vertical plane.
- property 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.
- property phi_len
Angle from the length-sensing QPD frame to the yaw-pitch frame.
- property phi_tilt
Angle from the tilt-sensing QPD frame to the yaw-pitch frame.
- property r_h
Lever arm from optics to tilt-sensing QPD on the horizontal plane.
- property r_lens_h
Lever arm from optics to the lens on the horizontal plane.
- property r_lens_v
Lever arm from optics to the lens on the vertical plane.
- property 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(r, alpha_v, r_lens=0, f=inf, alpha_h=0, phi_tilt=0, phi_len=0, delta_x=0, delta_y=0, delta_d=0, format='OPLEV2EUL', coupling_matrix=None, *args, **kwargs)
Bases:
OpticalLeverSensingMatrix
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.
- property delta_d
Misplacement of the length-sensing QPD.
- property f
Focal length of the convex lens.
- property r
Lever arm.
- property 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.
- Returns
The aligned optical lever sensing matrix
- Return type
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.
- Returns
The miscentering correction matrix.
- Return type
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.
- Returns
Matrix that transform the QPD frames to the yaw-pitch frame.
- Return type
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
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.
- Returns
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.
- Returns
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.
- Returns
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.