register_bpms help copy from SCregisterBPMs.m

pySC/core/simulated_commissioning.py

@@ -43,6 +43,85 @@ def __init__(self, ring: Lattice):
         self.plot: bool = False
 
     def register_bpms(self, ords: ndarray, **kwargs):
+        """
+        register_bpms - Registers BPMs in SC
+
+        SYNOPSIS
+        --------
+        'SC.register_BPMs(BPM_ords [, sigmas])`
+
+
+        DESCRIPTION
+        -----------
+        Registers BPMs specified by `BPMords` in the `SC` structure and initializes all required fields
+        in the lattice elements. The ordinates of all registered BPMs are stored in `SC.ORD.BPM`. The
+        BPM realated fields in the lattice elements are:
+
+
+        `Noise`:: [1 x 2] array of hor./ver. turn-by-turn BPM noise
+
+        `NoiseCO`:: [1 x 2] array of hor./ver. orbit BPM noise
+
+        `CalError`:: [1 x 2] array of hor./ver. BPM calibration errors
+
+        `Offset`:: [1 x 2] array of individual hor./ver. BPM offsets
+        `SupportOffset`:: [1 x 2] array of hor./ver. BPM offsets which result from the corresponding girder offset at the location of the BPMs, see *SCupdateSupport*.
+
+        `Roll`:: BPM roll around z-axis w.r.t. the support structure
+
+        `SupportRoll`:: BPM roll around z-axis which results from the corresponding support structure roll at the location of the BPMs, see *SCupdateSupport*.
+
+        `SumError`:: Calibration error of the sum signal. The sum signal is used to determine the beam loss location with a cutoff as defined `SC.INJ.beamLostAt`.
+
+        INPUTS
+        ------
+        `SC`::       SC base structure.
+
+        `BPMords`::  BPM ordinates in the lattice structure.
+
+        UNCERTAINTIES
+        -------------
+        Additional name/vale-pairs are interpreted as uncertainties and passed to the sigma structure
+        `SC.SIG` for the corresponding BPM. The function *SCapplyErrors* uses the fields of `SC.SIG` to
+        randomly generate errors and applies them to the corresponding fields in `SC.RING`.
+        By default a 2 sigma cutoff is applied. The user can specify a different cutoff by giving the
+        uncertainty as a cell structure, e.g. {[1x2],nSig}, with nSig being the cutoff (see examples
+        below).
+
+        RETURN VALUE
+        ------------
+        `SC`::
+            The base structure containing required information of all BPMs.
+
+        EXAMPLES
+        --------
+        Identify the ordinates of all elements named `BPM` and registers them as BPMs in `SC`::
+
+            ords = SCgetOrds(SC.RING,'BPM');
+            SC = SCregisterBPMs(SC,ords);
+
+
+        Register the BPMs specified in `ords` in `SC` and set the uncertanty of the offset to `500um` in
+        both planes. A subsequent call of *SCapplyErrors* would generate a random BPM offset errors with
+        `sigma=500um`::
+
+            SC = SCregisterBPMs(SC,ords,'Offset',500E-6*[1 1]);
+
+        Register the BPMs specified in `ords` in `SC` and set the uncertanty of the offset to `500um` in
+        both planes and a calibration error of the sum signal of 20%::
+
+            SC = SCregisterBPMs(SC,ords,'Offset',500E-6*[1 1],'SumError',0.2);
+
+        Register the BPMs specified in `ords` in `SC` and set the uncertanty of the offset to `500um` in
+        both planes. A subsequent call of *SCapplyErrors* would generate a random BPM offset errors with
+        `sigma=500um` with a 3 sigma cutoff::
+
+            SC = SCregisterBPMs(SC,ords,'Offset',{500E-6*[1 1],3});
+
+        SEE ALSO
+        --------
+        *SCgetBPMreading*, *SCgetOrds*, *SCsanityCheck*, *SCapplyErrors*, *SCregisterSupport*, *SCupdateSupport*
+        """
         self._check_kwargs(kwargs, BPM_ERROR_FIELDS)
         self.ORD.BPM = np.unique(np.concatenate((self.ORD.BPM, ords)))
         for ind in np.unique(ords):