.. algorithm::

.. summary::

.. relatedalgorithms::

.. properties::

Description
-----------

Algorithm finds the estimate for all incident energies allowed by chopper system of an inelastic instrument and returns a workspace,
with the estimates for positions, heights and width of incident energies provided by the choppers and registered on monitors.
These estimates can be used as guess value for  :ref:`algm-GetEi` algorithm or as inputs for a peak fitting procedure.

Algorithm performs number of steps to identify the values requested:

#. It takes appropriate log names from instrument definition file (IDF), namely chopper-position component and calculates last chopper speed and delay as average
   of the filtered log values. Guess chopper opening times are calculated from chopper speed and delay time. The "chopper-position" component with appropriate properties
   has to be present in IDF for this algorithm to work. See ISIS MARI or MAPS instrument definition files for example of "chopper-position" component.

#. Algorithm uses estimate for the minimal energy resolution of an instrument and searches for real peaks around guess values obtained
   earlier within 4 sigma of this resolution interval.

#. If peaks are found, the algorithm performs running averages over signal in the appropriate time interval until first derivative
   of the signal has only one zero. The position of this zero is returned as the guess energy and the distance between closest to
   the guess energy zeros of the second derivative are returned as the guess values for the peak width. The peak amplitude
   is estimated from the total intensity of the signal within the search interval, assuming that the peak shape is Gaussian.

#. Similar procedure is performed for second monitor. The peak is accepted only if the peak width lies between the minimal and maximal instrument resolution values
   and the distance between peaks positions on two monitors (on energy scale) is smaller then two sigma.

Algorithm returns matrix workspace containing single spectrum, with x-values representing peak positions, y-values: peak heights and the error: peak width. X-values are
sorted according to energy in peaks (peaks with maximal energy are returned first).

Used Subalgorithms
------------------
The algorithm uses :ref:`Unit Factory <Unit Factory>` and :ref:`algm-ConvertUnits` algorithm
to convert units from TOF to energy.


**Example: Find all incident energies for test workspace**

.. testcode:: foundAllEi

    # BUILD SAMPLE WORKSPACE
    # Build sample workspace with chopper and in energy units to
    # have defined peaks in defined energy positions
    wsEn=CreateSampleWorkspace(Function='Multiple Peaks', NumBanks=1, BankPixelWidth=2, NumEvents=10000, XUnit='Energy', XMin=10, XMax=200, BinWidth=0.1)
    # convert units to TOF to simulate real workspace obtained from experiment
    ws = ConvertUnits(InputWorkspace=wsEn, Target='TOF')
    # find chopper log values would be present in real workspace
    l_chop = 7.5  # chopper position build into test workspace
    l_mon1 = 15. # monitor 1 position (detector 1), build into test workspace
    t_mon1 = 3100. # the time of flight defined by incident energy of the peak generated by CreateSampelpWorkspace algorithm.
    t_chop = (l_chop/l_mon1)*t_mon1
    # Add these log values to simulated workspace to represent real sample logs
    AddTimeSeriesLog(ws, Name="fermi_delay", Time="2010-01-01T00:00:00", Value=t_chop ,DeleteExisting=True)
    AddTimeSeriesLog(ws, Name="fermi_delay", Time="2010-01-01T00:30:00", Value=t_chop )
    AddTimeSeriesLog(ws, Name="fermi_speed", Time="2010-01-01T00:00:00", Value=900 ,DeleteExisting=True)
    AddTimeSeriesLog(ws, Name="fermi_speed", Time="2010-01-01T00:30:00", Value=900)
    #-------------------------------------------------------------

    # FIND GUESS PEAKS
    allEiWs=GetAllEi(ws,Monitor1SpecID=1,Monitor2SpecID=2)
    # Analyze results
    allEi = allEiWs.readX(0);
    peakHeight = allEiWs.readY(0);
    peakWidth  = allEiWs.readE(0);

    # Check if peaks positions are indeed correct:
    #-------------------------------------------------------------
    resEi=[]
    for ei_guess in allEi:
       nop,t_peak,monIndex,tZero=GetEi(InputWorkspace=ws, Monitor1Spec=1, Monitor2Spec=2, EnergyEstimate=ei_guess)
       resEi.append((nop,t_peak));
    print("! Guess Ei ! peak TOF ! peak height ! peak width !")
    for ind,val in enumerate(resEi):
       print("!  {0: >6.1f}  !  {1: >6.2f} !   {2: >6.2f}    ! {3: >6.2f}     !".format(allEi[ind],val[1],peakHeight[ind],peakWidth[ind]))
    #
    # NOTE: incident energy of GetEi is calculated from distance between monitor 1 and 2, and this distance is not correct in
    # the test workspace. The tested point is that getEi can find energies from guess values and TOF for peaks is correct.

Output:

.. testoutput:: foundAllEi
    :options: +NORMALIZE_WHITESPACE

    ! Guess Ei ! peak TOF ! peak height ! peak width !
    !    67.0  !  4188.03 !    34.68    !   2.35     !
    !   124.1  !  3079.09 !    14.01    !   4.35     !

.. categories::

.. sourcelink::