<?xml version="1.0" encoding="UTF-8"?>
<sect2 id="ekos-focus">
  <title>Focus</title>

  <indexterm>
    <primary>Tools</primary>

    <secondary>Ekos</secondary>

    <tertiary>Focus</tertiary>
  </indexterm>

  <sect3 id="focus-theory">
    <title>Theory Of Operation</title>

    <screenshot>
      <screeninfo> Ekos Focus </screeninfo>

      <mediaobject>
        <imageobject>
          <imagedata fileref="ekos_focus.png" format="PNG" width="75%"/>
        </imageobject>

        <textobject>
          <phrase>Ekos Focus</phrase>
        </textobject>
      </mediaobject>
    </screenshot>

    <para> In order to focus an image, Ekos needs to establish a numerical
    method for gauging how <emphasis>good</emphasis> your focus is. It's easy
    when you look at an image and can see it as
    <emphasis>unfocused</emphasis>, as the human eye is very good at detecting
    that, but <emphasis>how</emphasis> can Ekos possibly know that? </para>

    <para> The most tried and tested method is Half-Flux-Radius (HFR), which is a
    measure of the width in pixels counting from the center of the star until
    the accumulated intensity is half of the total flux of the star. As you move
    closer to the point of optimum focus, so the HFR gets smaller, reaching a
    minimum at the point of focus before increasing as you start to move away
    from focus. HFR has been used on lots of different types of equipment and has
    proved to be stable in a wide range of circumstances. </para>

    <para> In addition to HFR, Ekos supports other focus measures, including
    an adjusted HFR measure, FWHM, Number of Stars and Fourier Power. It is
    recommended to start with HFR and when the user has become proficient in
    focusing their equipment, to try the other measures. </para>

    <para> After Ekos processes an image, it selects either a single star and
    starts measuring its HFR, or it selects a set of stars matching the
    criteria that have been set and calculates an average HFR. It can
    automatically select stars, or you can select a single star manually. It
    is recommended to allow Ekos to select a set of stars. </para>

    <para> Ekos supports 4 different focus algorithms: Linear 1 Pass, Linear,
    Iterative, Polynomial. Linear 1 Pass is the recommended algorithm. </para>

    <itemizedlist>
      <listitem>
        <para> <emphasis role="bold">Linear 1 Pass</emphasis>: In the Linear 1
        Pass algorithm, Ekos establishes a V-Curve and fits a curve to the data
        to find the focus solution. It then moves to the calculated minimum.
        Key features include: </para>

        <itemizedlist>
          <listitem>
            <para> The algorithm compensates for focuser backlash. </para>
          </listitem>

          <listitem>
            <para> The algorithm is fast, taking 1 pass to identify optimum
            focus. </para>
          </listitem>

          <listitem>
            <para> The algorithm uses more sophisticated curve fitting to
            pinpoint the optimum focus position. </para>
          </listitem>

          <listitem>
            <para> The algorithm is highly configurable with user control over
            many parameters like step size, number of steps and how to deal with
            outliers in the datapoints. </para>
          </listitem>
        </itemizedlist>
      <para> Providing the focuser behaves in a repeatable way, i.e. when commanded
      to go to position X, it always goes to the same position, then this algorithm
      will be the best to use.</para>
      </listitem>

      <listitem>
        <para> <emphasis role="bold">Linear</emphasis>: In the Linear
        algorithm, Ekos steps outward from its starting point then moves
        inward taking regular datapoints through the point of optimum focus
        and then further inward, to draw a V-Curve. It then fits a quadratic
        curve to the datapoints and calculates the point of optimum focus. It
        then moves out again past the point of optimum focus, halves the
        stepsize and moves in again for a second pass. It looks to follow the
        curve from the first pass and find the minimum HFR. Due to randomness
        in the HFR measurements it uses the % tolerance to help decide when it
        has found a solution. Key features include: </para>

        <itemizedlist>
          <listitem>
            <para> The algorithm compensates for focuser backlash. </para>
          </listitem>

          <listitem>
            <para> The algorithm is slow, taking 2 passes to identify optimum
            focus. </para>
          </listitem>

          <listitem>
            <para> The algorithm uses curve fitting to pinpoint the optimum
            focus position in pass 1, but then uses % Tolerance to try to stop
            as close as possible to this HFR on pass 2. </para>
          </listitem>

          <listitem>
            <para> The algorithm is highly configurable with user control over
            many parameters like step size and number of steps. </para>
          </listitem>
        </itemizedlist>
        <para> If the focuser behaves in an inconsistent way, i.e. when commanded
        to go to position X, there is variability in the position it goes to, then
        this algorithm will be the best to use as it has some built in tolerance
        for this variability.</para>
      </listitem>

      <listitem>
        <para> <emphasis role="bold">Iterative</emphasis>: In the Iterative
        algorithm, Ekos operates iteratively by moving in discrete steps,
        decided initially by the user-configurable step size and later by the
        slope of the V-Curve, to get closer to the optimal focus position
        where it then changes gears and performs smaller, finer moves to reach
        the optimal focus. The focus process stops when the measured HFR is
        within the configurable tolerance of the minimum recorded HFR in the
        process. In other words, whenever the process starts searching for a
        solution within a narrowly limited range, it checks if the current HFR
        is within % difference compared to the minimum HFR recorded, and if
        this condition is met then the Autofocus process is considered
        successful. The default value is set to 1% and is sufficient for most
        situations. The Step options specify the number of initial ticks the
        focuser has to move. If the image is severely out of focus, we set the
        step size high (i.e. greater than 250). On the other hand, if the
        focus is close to optimal focus, we set the step size to a more
        reasonable range (less than 50). It takes trial and error to find the
        best starting tick, but Ekos only uses that for the first focus
        motion, as all subsequent motions depend on the V-Curve slope
        calculations. Key features include:</para>

        <itemizedlist>
          <listitem>
            <para> The algorithm relies on the focuser having well controlled
            backlash. </para>
          </listitem>

          <listitem>
            <para> The algorithm can be fast using a minimum number of steps.
            </para>
          </listitem>

          <listitem>
            <para> The algorithm works on a "good enough" paradigm whereby it
            stops when the HFR is within % Tolerance of the perceived minimum.
            </para>
          </listitem>
        </itemizedlist>
      </listitem>

      <listitem>
        <para> <emphasis role="bold">Polynomial</emphasis>: In the Polynomial
        algorithm, the process starts off in Iterative mode, but once we cross
        to the other side of the V-Curve (once HFR values start increasing
        again after decreasing for a while), then Ekos performs quadratic
        curve fitting to find a solution that predicts the minimum possible
        HFR position. Key features include:</para>

        <itemizedlist>
          <listitem>
            <para> The algorithm relies on the focuser having well controlled
            backlash. </para>
          </listitem>

          <listitem>
            <para> The algorithm can be fast using a minimum number of steps.
            </para>
          </listitem>

          <listitem>
            <para> The algorithm uses curve fitting to pinpoint the optimum
            focus position. </para>
          </listitem>
        </itemizedlist>
      </listitem>
    </itemizedlist>
  </sect3>

  <sect3 id="optical-train-group">
    <title>Optical Train Group</title>

    <screenshot>
      <screeninfo> Optical Train </screeninfo>

      <mediaobject>
        <imageobject>
          <imagedata fileref="optical_train_group.png" format="PNG"
                     width="50%"/>
        </imageobject>

        <textobject>
          <phrase>Optical Train Settings</phrase>
        </textobject>
      </mediaobject>
    </screenshot>

    <para> The Optical Train group displays the currently selected Optical
    Train. By default this will be the primary imaging train, but other trains
    can be selected. The group consists of:</para>

    <itemizedlist>
      <listitem>
        <para> <guibutton>Train</guibutton>: The Optical Train currently in
        use by the Focus tab. Hover the mouse over this field for a more
        detailed description of the selected train.</para>
      </listitem>

      <listitem>
        <para> <guibutton>Edit Button</guibutton>: Brings up the Optical Train
        dialog to view and potentially change the optical trains.</para>
      </listitem>
    </itemizedlist>

    <para> Focus parameters are saved per Optical Train automatically.</para>
  </sect3>

  <sect3 id="focus-focuser-group">
    <title>Focuser Group</title>

    <screenshot>
      <screeninfo> Focuser Settings </screeninfo>

      <mediaobject>
        <imageobject>
          <imagedata fileref="focuser_group.png" format="PNG" width="50%"/>
        </imageobject>

        <textobject>
          <phrase>Focuser Settings</phrase>
        </textobject>
      </mediaobject>
    </screenshot>

    <para> All INDI-compatible focusers are supported. It is recommended to
    use <emphasis role="bold">absolute</emphasis> focusers for the best
    results since their absolute position is known on power up. In INDI, the
    focuser <emphasis>zero</emphasis> position is when the drawtube is
    <emphasis role="bold">fully retracted</emphasis>. When focusing
    <emphasis>outwards</emphasis>, the focuser position increases, while it
    decreases when focusing <emphasis>inwards</emphasis>. The following
    focuser types are supported: </para>

    <itemizedlist>
      <listitem>
        <para> <emphasis role="bold">Absolute</emphasis>: Absolute Position
        Focusers such as RoboFocus, MoonLite, ASI ZWO </para>
      </listitem>

      <listitem>
        <para> <emphasis role="bold">Relative</emphasis>: Relative Position
        Focusers. </para>
      </listitem>

      <listitem>
        <para> <emphasis role="bold">Time Based</emphasis>: Time based
        focusers with no position feedback that adjust focus position by
        moving for a certain amount of time. </para>
      </listitem>
    </itemizedlist>

    <para> The <guibutton>Focuser</guibutton> field contains the focuser in the
    attached Optical Train. </para>

    <para> For absolute and relative focusers, the step size is in units of
    <emphasis>ticks</emphasis> and for simple, or time based, focusers, the
    step size is in <emphasis>milliseconds</emphasis>. The
    <guibutton>In</guibutton> and <guibutton>Out</guibutton> buttons can then
    be used to move the focuser by the number of ticks defined in the
    <guibutton>Initial Step Size</guibutton> field in the
    <link linkend="focus-mechanics">Mechanics</link> tab.</para>

    <para> The Steps fields has 2 parts:</para>
    <itemizedlist>
      <listitem>
        <para> <emphasis role="bold">Left Hand Steps</emphasis>: Current focuser position. This is
        output only and is updated as the focuser moves to reflect the current position.</para>
      </listitem>

      <listitem>
        <para> <emphasis role="bold">Right Hand Steps</emphasis>: This is input and allows the user
        to enter a desired position. When the <guibutton>Goto</guibutton> button is pressed, the
        focuser is moved from its current position to the position indicated in this field. </para>
      </listitem>
    </itemizedlist>

    <para> On startup, the Left Hand Steps will show the current focuser position. The Right Hand Steps
    field is defaulted from the Optical Train saved settings. This is useful, for example, if
    you have several Optical Trains that use the same focuser but solve at different positions. In
    this case, the Right Hand Steps will contain the last persisted value for this field for
    the selected Optical Train. So, after swapping equipment and selecting the Optical Train, if the
    user presses the <guibutton>Goto</guibutton> button then the focuser will be moved to a
    good place to start focusing from.</para>

    <para> The <guibutton>Goto Focus Position</guibutton> button moves the
    focuser to the position in the righthand Steps field. </para>

    <para> The <guibutton>Stop Focuser Motion</guibutton> button stops the
    in-progress focuser motion. </para>

    <para> The <guibutton>Auto Focus</guibutton> button starts an Autofocus
    run. The <guibutton>Stop</guibutton> button is used to stop the run.
    </para>

    <para> The <guibutton>Capture Image</guibutton> button will take a frame
    based on the current settings in the <link linkend="focus-ccd-filter-wheel">
    Camera &amp; Filter Wheel Group</link>. The <guibutton>Start Framing</guibutton>
    button will start repeatedly capturing frames until the
    <guibutton>Stop</guibutton> button is pressed. </para>

    <para> Some of the focus algorithms will attempt to cope with being
    started away from the point of optimum focus, but for predictable results,
    it is best to start from a position of being approximately in focus. For
    first time setup, <guibutton>Start Framing</guibutton> can be used along
    with the <guibutton>In</guibutton> and <guibutton>Out</guibutton> buttons
    to adjust the focus position to roughly minimize the HFR of the stars in
    the captured images. When Framing is used in this way, the <link
    linkend="focus-v-curve">V-Curve</link> graph changes to show a time series
    of frames and their associated HFRs. This makes the framing process much
    easier to perform.</para>

    <para> If you are completely new to astronomy, it is always a good idea to
    get familiar with your equipment in daylight. This includes getting the
    approximate focus position on a distant object. This will provide a good
    starting position for focusing on stars when nighttime comes.</para>
  </sect3>

  <sect3 id="focus-ccd-filter-wheel">
    <title>Camera &amp; Filter Wheel Group</title>

    <screenshot>
      <screeninfo> Focus Camera &amp; Filter Wheel Group </screeninfo>

      <mediaobject>
        <imageobject>
          <imagedata fileref="focus_ccdfw_group.png" format="PNG" width="50%"/>
        </imageobject>

        <textobject>
          <phrase>Focus Camera &amp; Filter Wheel Group</phrase>
        </textobject>
      </mediaobject>
    </screenshot>

    <para> This section of parameters deals with the Camera and Filter
    settings to use when focusing.</para>

    <para> The top row of controls allows CCD parameters to be set.</para>

    <itemizedlist>
      <listitem>
        <para> <guilabel>Exp</guilabel>: The exposure time in seconds.</para>
      </listitem>

      <listitem>
        <para> The <guibutton>Toggle Full Screen</guibutton> button pops the
        window displaying the focus frame out to a separate window. Pressing
        it again returns it within the focus window.</para>
      </listitem>

      <listitem>
        <para> The <guibutton>Show in FITS Viewer</guibutton> button pops-up a
        separate FITS Viewer window to display the focus frame, in addition to
        the focus frame displayed within the focus window.</para>
      </listitem>

      <listitem>
        <para> The <guibutton>Live Video</guibutton> button brings up the
        associated popup.</para>
      </listitem>
    </itemizedlist>

    <para> The next row of controls allows Camera parameters to be set. Choose
    a value from the binning dropdown and then set either the camera gain or
    ISO.</para>

    <itemizedlist>
      <listitem>
        <para> <guilabel>Binning</guilabel>: Increasing the binning will
        change the image scale as well as resulting in brighter pixels. It is
        generally only worth binning above 1x1 if your image scale is oversampled
        where the increase in image scale does not lead to a loss of resolution.
        If you wish to increase star brightness try increasing the exposure
        and / or gain. If you are unsure bin 1x1.</para>
      </listitem>

      <listitem>
        <para> <guilabel>Gain</guilabel>: Set the Gain for the Camera being
        used to focus. The value needs to be high enough to give a clear star
        pattern but not so high as to create too much noise to interfere with
        the focus operation. Some experimentation will be required to find an
        optimum value. If you are unsure where to start try unity gain for
        your camera and adjust from there.</para>
      </listitem>

      <listitem>
        <para> <guilabel>ISO</guilabel>: Set the ISO for the Camera being used
        to focus. Some experimentation will be required to find an optimum
        value.</para>
      </listitem>
    </itemizedlist>

    <para> The third row of controls deals with the Temperature Source and
    Filter, if there is one:</para>

    <itemizedlist>
      <listitem>
        <para> <guilabel>TS</guilabel>: Select the temperature source from the
        dropdown. Underneath are displayed the current temperature from the
        selected temperature source and the change in temperature between when
        the last successful Autofocus run completed and the current
        temperature. It is common practice to redo focus after significant
        temperature changes that alter the telescope's focus point.</para>
      </listitem>

      <listitem>
        <para> <guilabel>Filter</guilabel>: Select the filter to use.</para>

        <para>To start focusing it will probably be easier to select the
        filter that allows the most light through, for example the Lum filter.
        Click the filter icon <inlinemediaobject><imageobject><imagedata
        fileref="view-filter.png" format="PNG"/></imageobject></inlinemediaobject>
        to launch the <link linkend="focus-filter-settings">Filter Settings</link>
        popup. This allows a number of parameters to be set per filter to be used during
        an Autofocus run.</para>
      </listitem>

      <listitem>
        <para> <guibutton>Reset</guibutton> button will reset the focusing
        subframe to full frame.</para>
      </listitem>
    </itemizedlist>
  </sect3>

  <sect3 id="focus-settings">
    <title>Focus Settings</title>

    <screenshot>
      <screeninfo> Focus Settings </screeninfo>

      <mediaobject>
        <imageobject>
          <imagedata fileref="focus_settings.png" format="PNG" width="50%"/>
        </imageobject>

        <textobject>
          <phrase>Focus Settings</phrase>
        </textobject>
      </mediaobject>
    </screenshot>

    <para> Next are 5 tabbed panes of parameters. These parameters are
    retained between sessions. First up is the Settings pane.</para>

    <itemizedlist>
      <listitem>
        <para> <guilabel>Auto Select Star</guilabel>: This setting is only relevant if
        <guilabel>Sub Frame</guilabel> is selected. In this case if <guilabel>Auto Select Star</guilabel>
        is selected then Ekos will select the star to use for focus; otherwise
        the user will have to manually select the star using FitsViewer.</para>
      </listitem>

      <listitem>
        <para> <guilabel>Suspend Guiding</guilabel>: Set this option to
        suspend guiding during an Autofocus run. The purpose of this
        is to prevent guiding from having problems with defocused stars during
        the focus process where, for example, the guide scope is attached to the
        main telescope using an OAG.</para>
      </listitem>

      <listitem>
        <para> <guilabel>Dark Frame</guilabel>: Check this option to perform
        dark-frame subtraction. This option can be useful in noisy images,
        where a pretaken dark is subtracted from the focus image before
        further processing.</para>

        <para> If hot pixels are causing problems with focus, select Dark Frames and
        either setup a regular Master Dark frame or a Defect Map.</para>

        <para> Dark frames are used by Focus, Alignment and Guiding. See the
        Dark Library feature within the <link linkend="ekos-capture">Capture
        Module</link> for more details on how to setup Dark Frames.</para>
      </listitem>

      <listitem>
        <para> <guilabel>Full Field</guilabel>: Select to use the full field of
        the camera. In this mode, focus will automatically select multiple stars for
        use in an Autofocus run. The alternative to this is <guilabel>Sub Frame</guilabel>.</para>
        </listitem>

      <listitem>
        <para> <guilabel>Sub Frame</guilabel>: Select to use a single star for the
        Autofocus process. The alternative to this is <guilabel>Full Field</guilabel> where
        multiple stars will be used by Autofocus. Depending on the setting of
        <guilabel>Auto Select Star</guilabel> either the user or Ekos will select the star.</para>
      </listitem>

      <listitem>
        <para> <guilabel>Box</guilabel>: Sets the box size used to enclose the
        focus star when using <emphasis role="bold">Sub Frame</emphasis>.
        Increase if you have very large stars. For Bahtinov focus the box size
        can be increased even more to better enclose the Bahtinov diffraction
        pattern.</para>
      </listitem>

      <listitem>
        <para> <guilabel>Display Units</guilabel>: Select the units for display on the Autofocus V-Curve
        when HFR or FWHM is selected. <emphasis role="bold">Pixels</emphasis>
        and <emphasis role="bold">Arc Seconds</emphasis> are supported.</para>
      </listitem>

      <listitem>
        <para> <guilabel>Guide Settle</guilabel>: This option is used in conjunction
        with <guilabel>Suspend Guiding</guilabel>. It allows any vibrations in
        the optical train to settle by waiting this many seconds after the
        Autofocus process has completed, before restarting guiding.</para>
      </listitem>

      <listitem>
        <para> The next set of radio button controls relate to <emphasis role="bold">Masking Options</emphasis>
        to be used when in <guilabel>Full Field</guilabel> mode.</para>
        <para> The effect of Masking Options can be seen on the <link linkend="focus-display">FITS Viewer</link>.</para>
	  <itemizedlist>
	    <listitem>
	      <para> <guilabel>Use all stars for focusing</guilabel>: Select this option
		if all stars of the field should be considered for focusing.</para>
	    </listitem>
	    
	    <listitem>
              <para> <guilabel>Ring Mask</guilabel>: This option provides two input fields
                that together define a doughnut over the FOV of the camera. Stars falling
                outside of the doughnut are discounted from processing. Setting an inner
                value above 0% causes stars in the centre of the FOV to be discarded. This
                could be useful to avoid using stars in the target of the image (for example
		a galaxy) for focusing purposes. Setting an outer value below 100%
		causes stars in the edges of the FOV to be discarded during focusing.
		This could be useful if you do not have a flat field out to the edges
		of your FOV.</para>
	    </listitem>

	    <listitem>
	      <para> <guilabel>Mosaic Mask</guilabel>: A 3x3 mosaic is composed with tiles
		from the image center, its corners and from the edges. This option is useful
		if you want to inspect the optics performance - you might know this from the
		PixInsight Aberration Inspector script. The tile size can be configured in
                percent of the frame width, with the spacer value specifying the space between
                the tiles.</para>
                <para> There are three use-cases for the Mosaic Mask:
                <itemizedlist>
                  <listitem>
                    <para> Checking focus in all parts of the sensor: The mask allows an easy
                    visual inspection and comparisons of stars in the center, corners and edges
                      of the sensor. This is especially useful for optics that show aberration if
		      the focus is not 100% met.</para>
                  </listitem>
                  <listitem>
		    <para>Correcting image tilt: especially large sensors are very sensitive to
		      incorrect distance and tilting of the sensor. In such cases, the image
		      shows aberration, especially in the image corners. If all corners show the same
		      effect, the distance needs to be corrected. If the aberrations in the corners
		    differ, this is typically the result of a tilted sensor.</para>
                  </listitem>
                  <listitem>
                    <para>Collimating Newtonians: inspecting frames in a defocused state is typically
		      used for collimating Newtonians. See, for example, Tommy Nawratil's
		      <ulink url="https://teleskop-austria.at/information/pdf/JUS_Photonewton_Collimation_Primer_EN.pdf">
                        The Photonewton Collimation Primer</ulink> for more details.</para>
                  </listitem>
                </itemizedlist></para>
	    </listitem>	    
	  </itemizedlist>
      </listitem>

      <listitem>
        <para> The next set of controls relate to <emphasis role="bold">Adaptive Focus</emphasis>.
        This is an experimental feature in Ekos. The idea here is to keep the telescope focused by
        adapting the focuser position based on changes in environmental conditions without having to
        perform a full Autofocus run. See the <link linkend="focus-adaptive">Adaptive Focus</link> section
        for more details.</para>

        <para> For example, as temperature changes during an imaging session so the focus
        point will change. By sampling the temperature between subframes it is possible to
        firstly calculate the change in temperature and then to convert this to a number of
        ticks of focuser movement to apply between subframes.</para>

        <para> In order to use <emphasis role="bold">Adaptive Focus</emphasis> it is necessary
        to setup some data for your system. In particular you need to tell Ekos how many ticks (and
        in which direction) to move the focuser when the environmental conditions change. This is
        covered in the <link linkend="focus-filter-settings">Filter Settings</link> popup. The
        popup is launched by clicking the filter icon <inlinemediaobject><imageobject><imagedata
        fileref="view-filter.png" format="PNG"/></imageobject></inlinemediaobject>.</para>

        <para> The following controls are available:
          <itemizedlist>
            <listitem>
              <para> <guilabel>Adaptive Focus</guilabel>: Select this option to activate
              <emphasis role="bold">Adaptive Focus</emphasis>.</para>
            </listitem>

            <listitem>
              <para> <guilabel>Min Move</guilabel>: The minimum Adaptive Focus movement allowed.</para>
            </listitem>

            <listitem>
              <para> <guilabel>Adapt Start Pos</guilabel>: Check to allow Adaptive Focus to calculate the
              start position for an Autofocus run. The starting position is the last good solve position for
              the selected filter, adapted for environmental changes.</para>

              <para> For example, if the current focuser position is 1000, temperature = 4C, and if the Red
              filter is selected (last good focus position for Red is 990 @ 5C and Ekos is configured to move
              +3 <guilabel>Ticks / °C</guilabel>). Then, if Adapt Start Pos is off,
              Autofocus will start at 1000. If Adapt Start Pos is on, Autofocus will start at 990 + (5 - 4) * 3
              = 993.</para>

              <para> This feature is useful to ensure that Autofocus starts from close to the focus point
              which will mean a more symmetric V-curve. It is particularly useful when changing between filters
              which have large differences in focus points.</para>

              <para> It is possible to use this feature on its own without Adaptive Focus. Just set the checkbox
              and leave the ticks per degree C set to zero. This way the Autofocus start position will be
              filter dependent and will start each Autofocus run at the focus point of the last successful
              Autofocus run for that filter.</para>
            </listitem>

            <listitem>
              <para> <guilabel>Max Total Move</guilabel>: The maximum total focuser movement that
              Adaptive Focus is allowed in the observing session. The purpose of this is as a "dead man's
              handle" on Adaptive Focus in case it runs away. For example, if the temperature source fails
              and returns bad temperature readings whilst the equipment is unattended, this could result in
              Adaptive Focus attempting to make large focuser movements.</para>

              <para> If the Max Total Move is reached then <guilabel>Adaptive Focus</guilabel> is unchecked
              until manually re-checked by the user.</para>
            </listitem>
          </itemizedlist>
        </para>
      </listitem>
    </itemizedlist>
  </sect3>

  <sect3 id="focus-process">
    <title>Focus Process</title>

    <screenshot>
      <screeninfo> Focus Process </screeninfo>

      <mediaobject>
        <imageobject>
          <imagedata fileref="focus_process.png" format="PNG" width="50%"/>
        </imageobject>

        <textobject>
          <phrase>Focus Process</phrase>
        </textobject>
      </mediaobject>
    </screenshot>

    <para> This is the Focus Process parameters pane. Widgets are only displayed if they are relevant to
    the selections made.</para>

    <itemizedlist>
      <listitem>
        <para> <guilabel>Detection</guilabel>: Select star detection
        algorithm. Each algorithm has its strengths and weaknesses. It is
        recommended to use SEP, unless you have a specialized
        use. The following are available:</para>

        <itemizedlist>
          <listitem>
            <para> <emphasis role="bold">SEP</emphasis>: Source Extraction and
            Photometry built in library. This is the default value.</para>
          </listitem>

          <listitem>
            <para> <emphasis role="bold">Centroid</emphasis>: An extraction
            method based on estimating star mass around signal peaks.</para>
          </listitem>

          <listitem>
            <para> <emphasis role="bold">Gradient</emphasis>: A single source
            extraction model based on the Sobel filter. </para>
          </listitem>

          <listitem>
            <para> <emphasis role="bold">Threshold</emphasis>: A single source
            detection algorithm based on pixel values. </para>
          </listitem>

          <listitem>
            <para> <emphasis role="bold">Bahtinov</emphasis>: This detection
            method can be used when using a Bahtinov mask for focusing. First
            take an image, then select the star to focus on. A new image will
            be taken and the diffraction pattern will be analysed. Three lines
            will be displayed on the diffraction pattern showing how well the
            pattern is recognized and how good the image is in focus. When the
            pattern is not well recognized, the <emphasis>Num. of
            rows</emphasis> parameter can be adjusted to improve recognition.
            The line with the circles at each end is a magnified indicator for
            the focus. The shorter the line, the better the image is in
            focus.</para>
          </listitem>
        </itemizedlist>
      </listitem>

      <listitem>
        <para> <guilabel>SEP Profile</guilabel>: If the star detection
        algorithm is set to <emphasis>SEP</emphasis>, then choose a parameter
        profile to use with the algorithm. It is recommended to use the
        default 1-Focus-Default profile as a starting point.</para>
      </listitem>

      <listitem>
        <para> <guilabel>Algorithm</guilabel>: Select the Autofocus process
        algorithm: </para>

        <itemizedlist>
        <listitem>
          <para> <emphasis role="bold">Linear 1 Pass</emphasis>: This is the
          recommended algorithm. In this algorithm, Ekos establishes a V-Curve
          and fits a curve to the data to find the focus solution. It then moves
          to the calculated solution.</para>

          <para> This algorithm supports the older style Quadratic curve
          type as well as the newer <link
          linkend="Levenberg-Marquardt">Levenberg-Marquardt Solver</link>
          for Hyperbolic and Parabolic curves. It will also weight the
          datapoints in the curve fitting process if <guilabel>Use Weights</guilabel>
          is checked and run a refinement process if <guilabel>Refine Curve Fit
          </guilabel> is selected.</para>
        </listitem>

        <listitem>
          <para> <emphasis role="bold">Linear</emphasis>: This algorithm
          builds a V-Curve with approximately <emphasis role="bold">Out step
          Multiple</emphasis> steps on each side of the minimum. Having
          built the V-Curve it then fits a quadratic equation to the curve
          (parabolic shape) and uses this to calculate the focuser position
          giving the minimum HFR. Having identified the minimum it then
          performs a 2nd pass halving the step size, recreating the curve
          from the 1st pass. It attempts to stop within <emphasis
          role="bold">Tolerance</emphasis> of the minimum HFR calculated
          during the 1st pass.</para>
        </listitem>

        <listitem>
          <para> <emphasis role="bold">Iterative</emphasis>: Moves focuser
          by discreet steps initially decided by the step size. Once a curve
          slope is calculated, further step sizes are calculated to reach an
          optimal solution. The algorithm stops when the measured HFR is
          within <emphasis role="bold">Tolerance</emphasis> of the minimum
          HFR recorded in the procedure.</para>
        </listitem>

        <listitem>
          <para> <emphasis role="bold">Polynomial</emphasis>: Starts with
          the iterative method. Upon crossing to the other side of the
          V-Curve, polynomial fitting coefficients along with possible
          minimum solution are calculated. This algorithm can be faster than
          a purely iterative approach given a good data set.</para>
        </listitem>
      </itemizedlist>
    </listitem>

    <listitem>
      <para> <guilabel>Curve Fit</guilabel>: The type of curve to fit to the datapoints. </para>
      <itemizedlist>
        <listitem>
          <para> <emphasis role="bold">Hyperbola</emphasis>: Fits a Hyperbola using a non-linear least squares
          algorithm supplied by GSL (GNU Science Library). See <link
          linkend="Levenberg-Marquardt">Levenberg-Marquardt Solver</link> for more details.</para>

          <para> This is the recommended option.</para>
        </listitem>

        <listitem>
          <para> <emphasis role="bold">Parabola</emphasis>: Fits a Parabola using a non-linear least squares
          algorithm supplied by GSL (GNU Science Library). See <link
          linkend="Levenberg-Marquardt">Levenberg-Marquardt Solver</link> for more details.</para>
        </listitem>

        <listitem>
          <para> <emphasis role="bold">Quadratic</emphasis>: Uses a quadratic equation using a linear style least
          squares algorithm supplied by GSL (GNU Science Library). This is, in effect, a parabolic curve.</para>

          <para> It is no longer recommended to use this curve.</para>
        </listitem>
      </itemizedlist>
    </listitem>

    <listitem>
    <para> <guilabel>Measure</guilabel>: Select Measure to use in the focus process.
    The following are available:</para>

    <itemizedlist>
      <listitem>
        <para> <emphasis role="bold">HFR</emphasis>: Half Flux Radius (HFR) is the
        recommended measure. When a star is detected, Ekos will calculate the HFR for
        the star. This is the radius of an imaginary circle, centered on the star
        center, that encloses half the star's total flux.</para>

        <para>The point of best focus corresponds to the minimum HFR.</para>
      </listitem>

      <listitem>
        <para> <emphasis role="bold">HFR Adj</emphasis>: This is an experimental feature that
        uses a brightness adjusted HFR calculation to take account of the fact that the HFR for
        brighter stars is larger than for smaller stars.</para>

        <para> The algorithm adjusts the value of the measured HFR, usually upwards, so the HFRs obtained
        by the HFR Adj method will be higher than the measured HFR values. This does not mean that you are
        getting worse results by using HFR Adj, simply that the measure is different.</para>

        <para> When using this Measure it is usual to get smaller error bars on the datapoints when
        <guilabel>Use Weights</guilabel> is selected.</para>

        <para>The point of best focus corresponds to the minimum adjusted HFR.</para>
      </listitem>

      <listitem>
        <para> <emphasis role="bold">FWHM</emphasis>: This is an experimental feature that fits
        a Gaussian surface to each star and uses that to calculate the Full Width Half Maximum
        (FWHM) of the star. The FWHM is the width of an circle (or ellipse) centered on the star center
        reaching the edge of the star at half its maximum intensity.</para>

        <para>The point of best focus corresponds to the minimum FWHM.</para>

        <para>Expect the FWHM to be approximately twice the HFR of a star.</para>
      </listitem>

      <listitem>
        <para> <emphasis role="bold"># Stars</emphasis>: This is an experimental feature that
        calculates the number of stars in the image and uses this number as the focus measure.
        The idea is that as you move nearer focus so more stars become detectable.</para>

        <para> The advantage of this Measure is that it is very simple and does not require
        algorithms to calculate HFRs or FWHMs.</para>

        <para>The point of best focus corresponds to a maximum number of stars.</para>
      </listitem>

      <listitem>
        <para> <emphasis role="bold">Fourier</emphasis>: Fourier takes a Fourier transform of the
        image and calculates the image power in frequency space. The assumption is that for an astronomical
        image of stars and background, the stars will be gaussians. Under a Fourier
        transform, a gaussian transforms to another gaussian; but wider stars transform to narrower
        gaussians in frequency space, and vice-versa. So, at focus, summing up the contents in
        frequency space, which is in effect a measure of power, will be a maximum.</para>

        <para>This follows the main idea suggested by Tan and Schulz in their paper:
        <ulink url="https://arxiv.org/pdf/2201.12466.pdf">A Fourier method for the determination of focus
            for telescopes with stars</ulink>. Please note that this paper makes other processing suggestions
            beyond the idea of using Fourier Transforms that are not included within Ekos</para>

        <para> This is a relatively new method in the Astro Community, and does not require star detection.
        Tan and Schulz report good results with both amateur and professional telescopes.</para>
      </listitem>
    </itemizedlist>
    </listitem>

    <listitem>
      <para> <guilabel>PSF</guilabel>: If <guilabel>Measure</guilabel> is set to FWHM, then the PSF
      widget can be selected for use in fitting a surface to the star. At present just Gaussian is
      supported.</para>
    </listitem>

    <listitem>
      <para> <guilabel>Use Weights</guilabel>: This is only available with the Linear 1 Pass focus algorithm
      and Curve Fits of Hyperbola and Parabola. It requires Full Field to be selected. The option calculates
      the standard deviation of star Measure and uses the square of this (mathematically the variance) as a
      weighting in the curve fitting process. The advantage of this is that datapoints with less reliable data
      and therefore larger HFR standard deviations will be given less weight than more reliable datapoints. If
      this option is unchecked, and for all other curve fitting where the option is not allowed, all datapoints
      are given equal weight in the curve fitting process.</para>

      <para> The standard deviation is drawn on the V-Curve for each datapoint as an error bar.</para>

      <para> It is recommended to check this option.</para>

      <para> See the <link linkend="Levenberg-Marquardt">Levenberg-Marquardt Solver</link> for more details.</para>
    </listitem>

    <listitem>
      <para> <guilabel>R² Limit</guilabel>: This is only available with the Linear 1 Pass focus algorithm
      and Curve Fits of Hyperbola and Parabola. As part of the Linear 1 Pass algorithm, the degree to which the
      curve fits the datapoints, or <link linkend="Coefficient_of_Determination">Coefficient of Determination,
      R²</link>, is calculated. This option allows a minimum acceptable value of R² to be defined that is compared
      to the value obtained from the curve fitting process. If the minimum value has not been achieved then
      Autofocus will rerun. Only one rerun will be performed and even if the minimum R² has not been met the
      second time, the Autofocus run will still be deemed successful.</para>

      <para> Experiment to find an appropriate value but a good starting point would be 0.8 or 0.9</para>
    </listitem>

    <listitem>
      <para> <guilabel>Refine Curve Fit</guilabel>: This is an experimental option only available with the Linear
      1 Pass focus algorithm and Curve Fits of Hyperbola and Parabola. If this option is checked then at the end
      of the sweep of datapoints, Ekos fits a curve and measures the R². It then applies Peirce's Criterion
      based on Gould's methodology for outlier identification. See <ulink
      url="https://en.wikipedia.org/wiki/Peirce%27s_criterion">Peirce's Criterion</ulink> for details incl
      Peirce's original paper and Gould's paper which are both referenced in the notes. If Peirce's Criterion
      detects 1 or more outliers then another curve fit is attempted with the outliers removed. Again the R²
      is calculated and compared with the original curve fit R². If the R² is better, then the latest run is used,
      if not, the original curve fit (with the outliers included) is used.</para>

      <para> Outliers are clearly marked on the V-Curve with an X through the datapoint.</para>
      </listitem>

      <listitem>
        <para> <guilabel>Average over</guilabel>: Number of frames to capture at each datapoint. It is usually
        sensible to start with 1 but increasing this will result in an averaging process for the star Measure
        selected.</para>
      </listitem>

      <listitem>
        <para> If <guilabel>Detection</guilabel> is set to Threshold then the following additional field is
        available:</para>
        <itemizedlist>
          <listitem>
            <para> <guilabel>Threshold</guilabel>: This contains a percentage value used for star detection using the
            <emphasis>Threshold</emphasis> detection algorithm. Increase to restrict the centroid to bright
            cores. Decrease to enclose fuzzy stars.</para>
          </listitem>
        </itemizedlist>
      </listitem>

      <listitem>
        <para>  If <guilabel>Detection</guilabel> is set to Bahtinov then the following additional widgets are
        available:</para>
        <itemizedlist>
          <listitem>
            <para> <guilabel>Num. of rows</guilabel>: The number of lines displayed on screen when using a
            Bahtinov mask.</para>
          </listitem>

          <listitem>
            <para> <guilabel>Sigma</guilabel>: The sigma of the gaussian blur applied to the image before applying
            Bahtinov edge detection.</para>
          </listitem>

          <listitem>
            <para> <guilabel>Kernel Size</guilabel>: The kernel size of the gaussian blur applied to the image
            before applying Bahtinov edge detection.</para>
          </listitem>
        </itemizedlist>
      </listitem>

      <listitem>
        <para> If <guilabel>Algorithm</guilabel> is set to Linear or Iterative then the following additional widget is
        available:</para>
        <itemizedlist>
          <listitem>
          <para> <guilabel>Tolerance</guilabel>: The tolerance percentage value is used to help decide when the
          Autofocus process stops. During the Autofocus process, HFR values are recorded, and once the focuser is close to an
          optimal position, it starts measuring HFRs against the minimum recorded HFR in the session and stops
          whenever a measured HFR value is within % difference of the minimum recorded HFR. Decrease the value to
          narrow the optimal focus point solution radius. Increase to expand solution radius. </para>

          <warning>
          <para> Setting the Tolerance value too low might result in a repetitive loop and would most likely result in a
          failed Autofocus process. </para>
          </warning>
          </listitem>
        </itemizedlist>
      </listitem>
    </itemizedlist>
  </sect3>

  <sect3 id="focus-mechanics">
    <title>Focus Mechanics</title>

    <screenshot>
      <screeninfo> Focus Mechanics </screeninfo>

      <mediaobject>
        <imageobject>
          <imagedata fileref="focus_mechanics.png" format="PNG" width="50%"/>
        </imageobject>

        <textobject>
          <phrase>Focus Mechanics</phrase>
        </textobject>
      </mediaobject>
    </screenshot>

    <para> This is the Focus Mechanics parameters pane.</para>

  <itemizedlist>
  <listitem>
    <para> <guilabel>Walk</guilabel>: This specifies the way Autofocus will "walk" inwards through its
    sweep to produce the V-Curve from which the focus solution will be calculated.</para>

    <para> The following are available:
    <itemizedlist>
      <listitem>
        <para> <emphasis role="bold">Classic</emphasis>: This is the recommended setting. The inward sweep
        follows a series of steps of equal size (<guilabel>Initial Step Size</guilabel>). The algorithm includes
        logic to determine when to stop that makes the exact number of steps unpredictable but it will be about
        2 * (<guilabel>Out Step Multiple</guilabel>) + 1.</para>
        <para> This Walk is tolerant of curve fitting failures in the last step where it will take a further
        step and try again to solve. It is also somewhat tolerant of not being started near to focus so is a good
        choice for the initial Autofocus run.</para>
        <para> Because of the "tolerance" of this Walk to less than perfect setup it is a conservative option
        to chose, but comes at the expense of extra steps and therefore extra time in the Autofocus process.</para>
      </listitem>

      <listitem>
        <para> <emphasis role="bold">Fixed Steps</emphasis>: This experimental option is available in the Linear 1 Pass
        <guilabel>Algorithm</guilabel>. It is quite similar to Classic but <guilabel>Fixed Steps</guilabel>
        is used to control the total number of steps taken.</para>
        <para> This algorithm is more predicable than Classic in that it takes a definite number of steps (so
        will be faster), but is less tolerant of issues curve fitting the last data point and needs to be
        started near to focus.</para>
        <para> When selected, the <guilabel>Out Steps Multiple</guilabel> is replaced by
        <guilabel>Fixed Steps:</guilabel>
        <screenshot>
          <screeninfo> Focus Mechanics </screeninfo>
          <mediaobject> <imageobject> <imagedata fileref="focus_mechanics1.png" format="PNG" width="50%"/>
            </imageobject><textobject><phrase>Focus Mechanics</phrase></textobject></mediaobject>
        </screenshot>
        </para>
      </listitem>
      <listitem>
        <para> <emphasis role="bold">CFZ Shuffle</emphasis>: This experimental option is available in the Linear 1 Pass
        <guilabel>Algorithm</guilabel>. It is a variation on Fixed Steps so the comments on that Walk are
        applicable here as well.</para>

        <para> The difference between CFZ Shuffle and Fixed Steps is that near the center of the sweep (which
        should be around the Critical Focus Zone (CFZ)) the algorithm takes steps of half the specified size.</para>
      </listitem>
    </itemizedlist>
    </para>
  </listitem>

  <listitem>
    <para> <guilabel>Focuser Settle</guilabel>: The number of seconds to wait, after moving the focuser, before
    starting the next capture. The purpose is to stop any vibrations in the optical train from affecting
    the next frame.</para>
  </listitem>

  <listitem>
    <para> <guilabel>Initial Step size</guilabel>: This sets the step size to be used by various focus algorithms.
    For absolute and relative focusers this is the number of ticks; for timer based focusers this is the number of
    milliseconds.</para>
  </listitem>

  <listitem>
    <para> <guilabel>Out Step Multiple</guilabel>: Used by the Linear and Linear 1 Pass focus algorithms in the
    Classic walk, this parameter specifies the initial number of outward steps the focuser takes at the start of
    an Autofocus run.</para>
  </listitem>

  <listitem>
    <para> <guilabel>Number Steps</guilabel>: Used by the Linear 1 Pass algorithm in the Fixed Steps and CFZ
    Shuffle walks, this parameter specifies the total number of steps the focuser takes to create the V-Curve in
    an Autofocus run.</para>
  </listitem>

  <listitem>
    <para> <guilabel>Max Travel</guilabel>: Puts bounds on the amount of travel from the current focuser position
    that is permitted by the Autofocus algorithms. The purpose is to protect the focuser from travelling too far
    and potentially damaging itself. On the other hand, the value needs to be big enough to allow sufficient focuser
    motion to permit the auto focus runs to complete.</para>
  </listitem>

  <listitem>
    <para> <guilabel>Max Step Size</guilabel>: Used by the Iterative algorithm to limit the maximum step size that
    can be used.</para>
  </listitem>

  <listitem>
    <para> <guilabel>Driver Backlash</guilabel>: See the section on <link linkend="focus-backlash">Backlash</link>.</para>

    <para>There are 2 schemes that can be used:</para>

    <itemizedlist>
      <listitem>
        <para>Set <guilabel>Driver Backlash</guilabel> to 0 to switch it off and deal with Backlash elsewhere.</para>
      </listitem>

      <listitem>
        <para>Set <guilabel>Driver Backlash</guilabel> &gt; 0 to use Driver Backlash to manage Backlash in the device driver. Note
        that this field is only editable if the device driver supports Backlash.</para>
        <para>This is the same data field that is displayed in the Indi Control Panel for the focuser device. It can be set
        in either place.</para>
      </listitem>
    </itemizedlist>
  </listitem>

  <listitem>
    <para> <guilabel>AF Overscan</guilabel>: See the section on <link linkend="focus-backlash">Backlash</link>.</para>

    <para> There are 2 schemes that can be used:</para>
    <itemizedlist>
      <listitem>
        <para> Set <guilabel>AF Overscan</guilabel> to 0 to switch it off and deal with Backlash elsewhere.</para>
      </listitem>

      <listitem>
        <para> Set <guilabel>AF Overscan</guilabel> &gt; 0 to have the Focus module manage Backlash.</para>
      </listitem>
    </itemizedlist>
  </listitem>

  <listitem>
    <para> <guilabel>Capture Timeout</guilabel>: The amount of time in seconds to wait for a captured image to be received before
    declaring a timeout. This should only be triggered if there are problems with the camera during the Focus process so set this
    to a high enough value that it will not occur during normal operation.</para>
  </listitem>

  <listitem>
    <para> <guilabel>Motion Timeout</guilabel>: The amount of time in seconds to wait for the focuser to move to the requested position
    before declaring a timeout. This should only be triggered if there are problems with the focuser during the Focus process so set this
    to a high enough value that it will not occur during normal operation.</para>
  </listitem>
  </itemizedlist>
  </sect3>

  <sect3 id="focus-cfz">
    <title>Focus Critical Focus Zone (CFZ)</title>

    <screenshot>
      <screeninfo> Focus CFZ </screeninfo>

      <mediaobject>
        <imageobject>
          <imagedata fileref="focus_cfz_classic.png" format="PNG" width="50%"/>
        </imageobject>

        <textobject>
          <phrase>Focus CFZ</phrase>
        </textobject>
      </mediaobject>
    </screenshot>

    <para> This is the Focus CFZ parameters pane.</para>

  <itemizedlist>
  <listitem>
    <para> <guilabel>Algorithm</guilabel>: This specifies the Critical Focus Zone (CFZ) algorithm. The purpose of this is
    to calculate the CFZ for the equipment attached in the Optical Train. It is not necessary to use this functionality
    in order to successfully focus, but it provides useful information if correctly configured.</para>

    <para> It requires some knowledge to configure it correctly. There is plenty of information available on the internet.</para>

    <para> The idea of the CFZ tab is that it starts with data from the Optical Train used in the Focus tab and uses that to
    calculate the CFZ. The user can adjust parameters to do "what-if" scenarios to see how it affects the CFZ. Clicking the
    <guilabel>Reset to OT</guilabel> button resets any adjusted parameters to the Optical Train values.</para>

    <para> If the <guilabel>Display</guilabel> box is checked then the CFZ is drawn on the V-Curve after Autofocus
    successfully completes.
    <screenshot>
      <screeninfo> Focus Mechanics </screeninfo>
      <mediaobject> <imageobject> <imagedata fileref="focus_cfz_moustache.png" format="PNG" width="75%"/>
        </imageobject><textobject><phrase>Focus Mechanics</phrase></textobject></mediaobject>
    </screenshot></para>
    <para> It is necessary to specify the <guilabel>Step Size</guilabel> parameter which specifies in microns how far one tick
    moves the focuser.</para>

    <para> The following algorithms are available:
    <itemizedlist>
      <listitem>
        <para> <emphasis role="bold">Classic</emphasis>: This is the recommended setting. The equation used is displayed
        in the top right of the panel and is the equation most commonly seen on the internet. The equation comes from a
        linear optics treatment using the Airy Disc and is acknowledged to have limitations. For this reason it includes
        a "tolerance" factor that can be adjusted by the user. For example, in the often quoted “In Perfect Focus” article
        by Don Goldman and Barry Megdal in Sky &amp; Telescope 2010 they suggest setting t=1/3.</para>
      </listitem>

      <listitem>
        <para> <emphasis role="bold">Wavefront</emphasis>: The equation used is displayed in the top right of the panel.
        The equation comes from a wavefront approach to the CFZ. Again, it has limitations and again, for this reason it
        includes a "tolerance" factor that can be adjusted by the user.
        <screenshot>
          <screeninfo> Focus Mechanics </screeninfo>
          <mediaobject> <imageobject> <imagedata fileref="focus_cfz_wavefront.png" format="PNG" width="50%"/>
            </imageobject><textobject><phrase>Focus Mechanics</phrase></textobject></mediaobject>
        </screenshot>
        </para>
      </listitem>

      <listitem>
        <para> <emphasis role="bold">Gold</emphasis>: This method is based on work done by Gold Astro and presented
        <ulink url="https://www.goldastro.com/goldfocus/ncfz.php">here</ulink>.</para>
        <screenshot>
          <screeninfo> Focus Mechanics </screeninfo>
          <mediaobject> <imageobject> <imagedata fileref="focus_cfz_gold.png" format="PNG" width="50%"/>
            </imageobject><textobject><phrase>Focus Mechanics</phrase></textobject></mediaobject>
        </screenshot>
      </listitem>
    </itemizedlist>
    </para>
  </listitem>

  <listitem>
    <para> <guilabel>Tolerance</guilabel>: This is used by Classic and Wavefront algorithms and is a scaling factor
    between 0 and 1.</para>
    <para> For the Classic algorithm, Goldman and Megdal suggest 1/3.</para>
    <para> For the Wavefront algorithm, some have suggested 1/3 or even 1/10.</para>
  </listitem>

  <listitem>
    <para> <guilabel>Tolerance (τ)</guilabel>: This is used by the Gold algorithm and is a focus tolerance as a percentage of
    total seeing. The Gold website suggests 3-5% for a good focuser or 1-2% for a top quality focuser. See the
    <ulink url="https://www.goldastro.com/goldfocus/ncfz.php">Gold Astro website</ulink> for more details.</para>
  </listitem>

  <listitem>
    <para> <guilabel>Display</guilabel>: Check this box to display the calculated CFZ on the V-Curve after a
    successful Autofocus run. It is displayed as a yellow moustache.</para>
  </listitem>

  <listitem>
    <para> <guilabel>Reset to OT</guilabel>: Press this button to reset any parameters to values defaulted from the
    currently connected Optical Train.</para>
  </listitem>

  <listitem>
    <para> <guilabel>Wavelength (λ)</guilabel>: This is the light wavelength to use. It is defaulted from the currently used
    filter. Remember to set this up in <link linkend="focus-filter-settings">Filter Settings</link> for your filters.</para>
  </listitem>

  <listitem>
    <para> <guilabel>Aperture (A)</guilabel>: This is the aperture of the telescope in mm. It is defaulted from the
    currently connected Optical Train.</para>
  </listitem>

  <listitem>
    <para> <guilabel>Focal Ratio (f)</guilabel>: This is the focal ratio of the telescope. It is defaulted from the
    currently connected Optical Train.</para>
  </listitem>

  <listitem>
    <para> <guilabel>FWHM (θ)</guilabel>: This is used by the Gold Algorithm and is the total seeing. This is the combined
    contribution of the diffraction limit of your telescope and the astronomical seeing. The
    <ulink url="https://www.goldastro.com/goldfocus/ncfz.php">Gold Astro website</ulink> describes how you might approximate
    the total once you have values for the individual contributions.</para>
  </listitem>

  <listitem>
    <para> <guilabel>CFZ</guilabel>: This is calculated CFZ in microns and in ticks.</para>
  </listitem>

  <listitem>
    <para> <guilabel>Step Size</guilabel>: This must be input by the user (as it cannot be calculated by Ekos). It relates how far
    1 tick moves the focal plane in microns. </para>
    <para> For a refractor this is how far the drawtube moves when the focuser is moved by 1 tick. You might be able to get this
    value from the specification of your focuser (how many ticks for a complete revolution of your focuser) and the thread pitch of
    your telescope drawtube along with any gearing involved.</para>
    <para> Alternatively, you can measure how far the drawtube moves from end to end (be careful not to force the drawtube) with
    a set of calipers or a ruler. By subtracting the furthest "in" position (in ticks) from the furthest "out" position (in ticks) you
    have how many ticks moved the drawtube the distance you measured. From this you can calculate the distance in microns a single
    tick moves the drawtube.</para>
    <para> Other types of telescope will have other ways to adjust the focal plane, for example, by moving the primary or
    secondary mirrors. You will need to either get the Step Size from the documentation for your equipment or work out how to
    measure it in a way that are consistent with that described above.</para>
  </listitem>

  <listitem>
    <para> <guilabel>CFZ Camera</guilabel>: The pixel size of the camera attached via the Optical Train may have a limiting
    effect on the CFZ. So an equivalent CFZ for the attached camera is calculated assuming a Nyquist 2* limit.</para>
  </listitem>

  <listitem>
    <para> <guilabel>Final CFZ</guilabel>: This is the larger of the CFZ calculated using the selected algorithm for the specified
    parameter and the <guilabel>CFZ Camera</guilabel>. It is the display value and is, in effect, the CFZ of your equipment.</para>
  </listitem>

  </itemizedlist>
  </sect3>


  <sect3 id="focus-advisor">
    <title>Focus Advisor</title>

    <screenshot>
      <screeninfo> Focus Advisor </screeninfo>

      <mediaobject>
        <imageobject>
          <imagedata fileref="focus_advisor.png" format="PNG" width="50%"/>
        </imageobject>

        <textobject>
          <phrase>Focus Advisor</phrase>
        </textobject>
      </mediaobject>
    </screenshot>

    <para> This is the Focus Advisor pane. It is an experimental feature to assist with management of focus parameters.</para>

    <para> The purpose of Focus Advisor is to help people struggling to use the Focus module within Ekos. The Focus module is
    functionally rich and contains a lot of parameters that need to be set self-consistently to achieve good results. Focus
    Advisor is designed to help with basic parameter setup that should achieve focus. It is not designed to achieve the best possible
    focus for your equipment; you will have to experiment with your setup to achieve that. But Focus Advisor provides a place to
    start that experimentation.</para>

    <para> So Focus Advisor is aimed towards the less experienced users.</para>
    <para> If Focus Advisor does not appear to give good results on your setup why not start a discussion on the forum so it can
    be enhanced to give better results in the future. This way it will build over time to be more useful.</para>
    <para> When you click on the Focus Advisor pane it works out a series of parameter recommendations based on the Optical
    Train you are using in Focus.</para>
    <para> At the top of the pane it displays information about the connected Optical Train. Then it displays 6 lines relating
    to various sets of parameters used within Focus. Against each line is a checkbox to update the associated Focus fields
    with Focus Advisor's recommendations.</para>
    <para> Focus parameters are broken into the following groupings:</para>

    <itemizedlist>
    <listitem>
    <para> <guilabel>Step Size</guilabel>: This is the suggested focus step size to use. This is a critical parameter. It is
    defaulted from the Critical Focus Zone (CFZ) pane. So the first thing to do is set this panel up and get a reasonable value
    for the CFZ. Alternatively, if you know a reasonable value for your equipment from other sources you can just enter that.</para>
    </listitem>

    <listitem>
    <para> <guilabel>Out Step Multiple</guilabel>: This is the suggested outward step multiple to use.</para>
    </listitem>

    <listitem>
    <para> <guilabel>Camera &amp; Filter Wheel Parameters</guilabel>: This sets the parameters in the
    <link linkend="focus-ccd-filter-wheel">CCD &amp; Filter Wheel</link> section of the Focus screen. By hovering the mouse over this
    label you can see in the tooltip what values Focus Advisor is recommending.</para>
    </listitem>

    <listitem>
    <para> <guilabel>Settings Tab Parameters</guilabel>: This sets the parameters in the
    <link linkend="focus-settings">Focus Settings</link> pane of the Focus screen. By hovering the mouse over this
    label you can see in the tooltip what values Focus Advisor is recommending.</para>
    </listitem>

    <listitem>
    <para> <guilabel>Process Tab Parameters</guilabel>: This sets the parameters in the
    <link linkend="focus-process">Focus Process</link> pane of the Focus screen. By hovering the mouse over this
    label you can see in the tooltip what values Focus Advisor is recommending.</para>
    </listitem>

    <listitem>
    <para> <guilabel>Mechanics Tab Parameters</guilabel>: This sets the parameters in the
    <link linkend="focus-mechanics">Focus Mechanics</link> pane of the Focus screen. By hovering the mouse over this
    label you can see in the tooltip what values Focus Advisor is recommending.</para>
    </listitem>

    <listitem>
    <para> <guilabel>Help</guilabel>: Press this button to get help on using Focus Advisor.</para>
    </listitem>

    <listitem>
    <para> <guilabel>Update Params</guilabel>: Press this button to accept the Focus Advisor recommendations and update
    the Focus parameters where the associated <guilabel>Update</guilabel> checkbox is checked..</para>
    </listitem>

  </itemizedlist>
  </sect3>

  <sect3 id="focus-filter-settings">
      <title>Filter Settings</title>

      <screenshot>
          <screeninfo>
              Filter Queue
          </screeninfo>
          <mediaobject>
              <imageobject>
                  <imagedata fileref="filter_settings.png" format="PNG" width="50%"/>
              </imageobject>
              <textobject>
                  <phrase>Filter Queue</phrase>
              </textobject>
          </mediaobject>
      </screenshot>

      <para> Click the filter icon <inlinemediaobject><imageobject><imagedata fileref="view-filter.png" format="PNG"/></imageobject>
          </inlinemediaobject> from either Capture or Focus to open the filter settings dialog. This popup allows the user to
          configure data associated with each filter, and used for various functions within the system.</para>

      <para> Focusing with different filters can be done in one of three ways within Ekos.</para>

      <itemizedlist>
        <listitem>
          <para> <emphasis role="bold">Direct Autofocus</emphasis>: When Capture changes to this filter it is possible to automatically
          refocus this filter. The exposure to use for the selected filter is taken from the <guilabel>Exposure</guilabel> field. This
          allows, for example, narrowband filters to use a longer exposure than broadband filters during Autofocus.</para>

          <para> Check <guilabel>Auto Focus</guilabel> to use the filter in this way.</para>
        </listitem>

        <listitem>
          <para> <emphasis role="bold">Autofocus on Lock Filter</emphasis>: It is possible to specify a Lock filter to use when it is
          required to focus this filter. For example, if the Ha filter is used and an Autofocus run required, it is possible to run
          Autofocus using the Lum filter and then, when complete, adjust the focus position by an Offset value corresponding to the
          predetermined focus difference between the Lum and Ha filters (100 ticks in this example). This is useful when, for example,
          it is difficult to focus some filters directly without excessively long exposure times. Note that this locked filter approach
          may also be used in the <link linkend="ekos-align">Alignment Module</link> whenever it performs a capture for astrometry.</para>

          <para> To use a filter in this way, check <guilabel>Auto Focus</guilabel>, specify the <guilabel>Lock Filter</guilabel> to use
          and make sure that the Offsets for this filter and the <guilabel>Lock Filter</guilabel> are set.</para>
        </listitem>

        <listitem>
          <para> <emphasis role="bold">Use Offsets</emphasis>: It is possible to use filter offsets to adjust focus when swapping
          between filters, without running Autofocus. This requires some setup work ahead of time but has the advantage of
          reducing the number of Autofocus runs and therefore reducing the time spent autofocusing.</para>

          <para> In order to use this feature it is necessary to work out the relative focus position between all filters that you
          wish to use this functionality for. For example, if Lum and Red have the same focus position (they are parfocal) but Green
          focuses 300 ticks further out than Lum (or Red) then setup Offsets for Lum, Red and Green as 0, 0, 300 as shown above. If a
          sequence is created to take 10 subframes of Lum, then 10 Red, then 10 Green, then at the start, since Lum has
          <guilabel>Auto Focus</guilabel> checked, an Autofocus will be run on Lum and the 10 subs taken. Capture will then switch
          filters to Red. Since Red has <guilabel>Auto Focus</guilabel> unchecked no Autofocus will happen and Ekos will look to the
          Offsets between Red and Lum. In this case 0 - 0 = 0. So the focuser will not be moved and Capture will take 10 subs of Red.
          Then Capture will swap from Red to Green. Again, Green has <guilabel>Auto Focus</guilabel> unchecked no Autofocus will happen
          and Ekos will look to the Offsets between Green and Red. In this case 300 - 0 = 300. So Focus will adjust the focus position
          by +300 (move the focuser out by 300 ticks). Capture will then take the 10 Green subs.</para>

          <para> To use a filter in this way, uncheck <guilabel>Auto Focus</guilabel> and make sure that the Offsets for this filter
          and all other filters that can precede this filter in a sequence are set.</para>

          <para> The Offsets can either be worked out by running Autofocus with different filters and manually calculating the relative
          offsets and entering them into the table or by using the <link linkend="build-filter-offsets">Build Offsets</link> tool.</para>
        </listitem>
      </itemizedlist>

      <para>
          Configure settings for each filter in the table:
      </para>
      <orderedlist>
          <listitem>
              <para><guilabel>Filter</guilabel>: Filter Name.</para>
          </listitem>
          <listitem>
              <para><guilabel>Exposure</guilabel>: Set exposure time (in seconds) to be used when performing Autofocus on this filter.
              By default, it is set to 1 second.</para>
          </listitem>
          <listitem>
              <para><guilabel>Offset</guilabel>: Set relative offsets. Ekos will command a focus offset change if there is a
              difference between the current and target filter offsets. For example, given the values in the example image, if the
              current filter is set to <emphasis>Red</emphasis> and next filter is <emphasis>Green</emphasis>, then Ekos shall
              command the focuser to Focus In by +300 ticks. Relative positive focus offsets denote Focus Out while negative
              values denote Focus In.</para>
          </listitem>
          <listitem>
              <para><guilabel>Auto Focus</guilabel>: Check this option to perform AutoFocus whenever the filter is changed
              to this filter.</para>
          </listitem>
          <listitem>
              <para><guilabel>Lock Filter</guilabel>: Set which filter should be set and <emphasis>locked</emphasis> when
              performing autofocus for this filter. "--" indicates no Lock Filter. It is not allowed to next filters more than
              1 deep, i.e. Red cannot be locked to Blue which is itself locked to Green. A filter cannot be locked to itself.</para>
          </listitem>
          <listitem>
              <para><guilabel>Last AF Solution</guilabel>: The last successful Autofocus position. Under normal operation Ekos will
              automatically update this field.</para>
          </listitem>
          <listitem>
              <para><guilabel>Last AF Temp (°C)</guilabel>: The temperature of the <guilabel>Last AF Solution</guilabel>. Under
              normal operation Ekos will automatically update this field.</para>
          </listitem>
          <listitem>
              <para><guilabel>Last AF Alt (°Alt)</guilabel>: The altitude of the <guilabel>Last AF Solution</guilabel>. Under
              normal operation Ekos will automatically update this field.</para>
          </listitem>
          <listitem>
              <para><guilabel>Ticks / °C</guilabel>: The number of ticks to move the focuser when the temperature changes by 1°C.
              For example, if focus moves out by 5 ticks when temperature increases by 1°C, set this field to 5. If focus moves
              in by 5 ticks when temperature increases by 1°C, set this field to -5.</para>
          </listitem>
          <listitem>
              <para><guilabel>Ticks / °Alt</guilabel>: The number of ticks to move the focuser when the altitude changes by 1°Alt.
              For example, if focus moves out by 0.5 tick when altitude increases by 1°Alt, set this field to 0.5. If focus moves in
              by 0.5 tick when altitude increases by 1°Alt, set this field to -0.5.</para>
          </listitem>
          <listitem>
              <para><guilabel>Wavelength</guilabel>: The center of the passband of the filter in nanometers. This is used in
              some Critical Focus Zone (CFZ) calculations in Focus.</para>
          </listitem>
      </orderedlist>

      <para>In addition to the data table, the following controls are available at the bottom of the popup:</para>
      <itemizedlist>
          <listitem>
          <para><guilabel>Build Offsets</guilabel>: Press the <guibutton>Build Offsets</guibutton> button to launch the
          <link linkend="build-filter-offsets">Build Offsets</link> popup.</para>
          </listitem>
          <listitem>
          <para><guilabel>Capture flats at the same focus as lights</guilabel>: When checked, flats will be taken at the
          <guilabel>Last AF Solution</guilabel> focuser position.</para>
          </listitem>
      </itemizedlist>

      <para>Let's take an example. If we have a capture sequence starting with Lum -> Red -> Green -> Blue -> Sii -> Ha -> Oiii
      using the setup in the Filter Settings popup:</para>
      <itemizedlist>
          <listitem>
              <para>Lum: The Lum filter is configured to Autofocus initially so an Autofocus run is performed, then the Lum sequence
              runs.</para>
          </listitem>
          <listitem>
              <para>Red: The Red filter is not configured for Autofocus and has an Offset of 0. So when the Red sequence starts,
              there is no Autofocus run and the relative Offset between Lum and Red is 0, so the focuser is not moved.</para>
          </listitem>
          <listitem>
              <para>Green: The Green filter is not configured for Autofocus and has an Offset of 300. So when the Green sequence
              starts, there is no Autofocus run and the relative Offset between Red and Green is 300 - 0 = +300, so the focuser moves
              out by 300.</para>
          </listitem>
          <listitem>
              <para>Blue: The Blue filter is not configured for Autofocus and has an Offset of 0. So when the Blue sequence starts,
              there is no Autofocus run and the relative Offset between Green and Blue is 0 - 300 = -300, so the focuser moves in
              by 300.</para>
          </listitem>
          <listitem>
              <para>Sii: The Sii filter is configured for Autofocus, is locked to Lum and has an Offset of 0. So when the Sii sequence
              starts, there is an Autofocus run on Lum and the relative Offset between Lum and Sii is 0 - 0 = 0, so the focuser moves
              to the Lum Autofocus run solution.</para>
          </listitem>
          <listitem>
              <para>Ha: The Ha filter is configured for Autofocus, is locked to Lum and has an Offset of 100. So when the Ha sequence
              starts, there is an Autofocus run on Lum and the relative Offset between Lum and Ha is 100 - 0 = +100, so the focuser
              moves to the Lum Autofocus run solution then out by 100.</para>
          </listitem>
          <listitem>
              <para>Oiii: The Oiii filter is configured for Autofocus, is locked to Lum and has an Offset of -100. So when the Oiii
              sequence starts, there is an Autofocus run on Lum and the relative Offset between Lum and Oiii is -100 - 0 = -100, so
              the focuser moves to the Lum Autofocus run solution then in by 100.</para>
          </listitem>
      </itemizedlist>
  </sect3>


  <sect3 id="build-filter-offsets">
      <title>Build Offsets</title>

      <screenshot>
          <screeninfo>
              Build Filter Offsets
          </screeninfo>
          <mediaobject>
              <imageobject>
                  <imagedata fileref="build_filter_offsets.png" format="PNG" width="33%"/>
              </imageobject>
              <textobject>
                  <phrase>Build Filter Offsets</phrase>
              </textobject>
          </mediaobject>
      </screenshot>

      <para>
          Click the <guilabel>Build Offsets</guilabel> button on the <link linkend="focus-filter-settings">Filter Settings</link>
          popup to launch the Build Offsets tool. Filter Offsets can either be entered manually into the table
          in the Filter Settings popup or this tool can be used to assist in creating them.
      </para>
      <para>
          <emphasis>Note: This utility should not be run during an imaging session as it takes exclusive control of the
          Focus process whilst it is running.</emphasis>
      </para>
      <para>
          To start with, configure settings for each filter in the table in the Filter Settings popup and then launch
          Build Filter Offsets. The popup is launched with a table of data with the following columns.
      </para>
      <itemizedlist>
          <listitem>
              <para>
                  <guilabel>Filter</guilabel>: Filter Name. The first filter has an "*" after the filter name, "Lum *" in the above example.
                  This means that Lum is the reference filter against which offsets for other filters will be measured. Double click another
                  Filter Name to make that filter the reference filter.
              </para>
          </listitem>
          <listitem>
              <para>
                  <guilabel>Offset</guilabel>: The current offset.
              </para>
          </listitem>
          <listitem>
              <para>
                  <guilabel>Lock Filter</guilabel>: The current Lock filter.
              </para>
          </listitem>
          <listitem>
              <para>
                  <guilabel># Focus Runs</guilabel>: The number of focus runs for this filter. The default is 5.
                  To exclude a filter from the process set this field to zero. Note, the reference filter must have at least 1 run.
              </para>
          </listitem>
      </itemizedlist>
      <para>
          When the <guilabel># Focus Runs</guilabel> have been configured press the <guilabel>Run</guilabel>
          button to start the automated process.
      </para>
      <para>
          Press the <guilabel>Stop</guilabel> button to stop the process at any time.
      </para>
      <para>
          Toggle the <guilabel>Adapt Focus</guilabel> checkbox at any point in the processing to switch between measured Autofocus results
          and results after Adaptive Focus adjustments have been applied. See the <link linkend="focus-adaptive">Adaptive Focus</link> section
          for more details on what Adaptive Focus is.
      </para>
      <para>
          Let's take an example where we have 7 filters: Lum, Red, Green, Blue, Sii, Ha and Oiii. The 8th slot in the filter wheel is marked
          as Blank. The process has completed 5 runs for all filters, 0 for Blank (effectively excluding Blank from the process). In this
          case 8 extra columns have been created in the table.
      </para>
      <screenshot>
          <screeninfo>
              Build Filter Offsets
          </screeninfo>
          <mediaobject>
              <imageobject>
                  <imagedata fileref="build_filter_offsets2.png" format="PNG" width="50%"/>
              </imageobject>
              <textobject>
                  <phrase>Build Filter Offsets</phrase>
              </textobject>
          </mediaobject>
      </screenshot>
      <itemizedlist>
          <listitem>
              <para>
                  AF Run 1-5: The maximum <guilabel># Focus Runs</guilabel> selected by the user is 5, so 5 columns
                  have been created, 1 for each AF run solution.
              </para>
          </listitem>
          <listitem>
              <para>
                  Average: The average (mean) of the AF solutions.
              </para>
          </listitem>
          <listitem>
              <para>
                   New Offset: The offset calculated from the Lum filter. E.g. for Sii 36731 - 36743 = -12
              </para>
          </listitem>
          <listitem>
              <para>
                  Save: Check to save the offset for this filter when the <guilabel>Save</guilabel> button is pressed.
                  The default is to check these boxes but unchecking allows a value to be ignored whilst saving
                  other filters.
              </para>
          </listitem>
      </itemizedlist>
      <para>
          At this stage, it is recommended to review the AF runs to make sure they are all good. For example, lets
          assume we are unhappy with the 2nd AF run on Oiii. In this case we could either:</para>
          <itemizedlist>
            <listitem>
              <para> Edit AF Run 2 and set the value to whatever value we want.</para>
            </listitem>
            <listitem>
              <para> Edit the New Offset column and set the value directly (bypassing the logic to calculate it).</para>
            </listitem>
            <listitem>
              <para> Discard the AF Run 2 by setting the value to 0 (see below). In this case, the Average and New Offset
              for Oiii is recalculated based on AF Runs 1, 3, 4, 5. In the example below the new Average and New Offsets are
              calculated and displayed.</para>
            </listitem>
          </itemizedlist>
      <screenshot>
          <screeninfo>
              Build Filter Offsets
          </screeninfo>
          <mediaobject>
              <imageobject>
                  <imagedata fileref="build_filter_offsets3.png" format="PNG" width="50%"/>
              </imageobject>
              <textobject>
                  <phrase>Build Filter Offsets</phrase>
              </textobject>
          </mediaobject>
      </screenshot>
      <para>
          After reviewing the results, the user can press:
      </para>
      <itemizedlist>
          <listitem>
              <para>
                  Save: All filters where the <guilabel>Save</guilabel> checkbox is checked will have the New Offset
                  value saved in Filter Offsets for use during the next imaging session.
              </para>
          </listitem>
          <listitem>
              <para>
                  Close: The Build Filter Offsets tool is closed without saving any data.
              </para>
          </listitem>
      </itemizedlist>
      <para>
          If the <guilabel>Adapt Focus</guilabel> box is checked, the AF Runs are updated for Adaptive Focus. See the
          <link linkend="focus-adaptive">Adaptive Focus</link> section for more details on the theory of Adaptive Focus. The first AF run
          (in this example AF Run 1 on Lum) is the basis for the Adaptations. So the temperature and altitude of AF Run 1 on Lum is used as
          the basis for all the other AF Runs and the data is adapted back to what the AF solution would have been, had it been run at the
          temperature and altitude of AF Run 1 on Lum.
      </para>
      <para>
          In this example, Adaptive Focus is setup for Altitude adjustments on the Red filter only in Filter Settings. So the
          Adapted AF Run values are the same as the unadapted values for all the other filters.
      </para>

      <screenshot>
        <screeninfo>
            Build Filter Offsets
        </screeninfo>
        <mediaobject>
            <imageobject>
                <imagedata fileref="build_filter_offsets4.png" format="PNG" width="50%"/>
            </imageobject>
            <textobject>
                <phrase>Build Filter Offsets</phrase>
            </textobject>
        </mediaobject>
      </screenshot>
      <para>
          If you hover the mouse over an AF Run it will show a tooltip Adaptive Focus Explainer. In the example, the mouse is hovering over
          AF Run 1 on Red. The 1st row of the Explainer shows the measured Autofocus result for that run (36683), adaptations for Temperature (0.0C) and Altitude (0.2 degrees Alt).
          The 2nd row of the Explainer shows the Adaptations: 206 total, 0 temperature, 205.9 altitude. The 3rd row shows the Adapted Position
          of 36889.
      </para>
      <para>
          The user can toggle between Adapt Focus or raw values. Whichever values are displayed in the grid will be the values that are saved.
      </para>
      <para>
          Here are some tips for using this utility:
          <itemizedlist>
            <listitem><para> Start by making sure the area of the sky you are running Build Filter Offsets on works well for Autofocus. Aiming
            high in the sky will result in shooting through less atmosphere with smaller, tighter stars. Make sure there are enough stars in the
            frame. Avoid Meridian Flips during the process. Track the same area during the process so each run is using more or less the
            same set of stars. Although the facility to use Adapt Focus is available to adjust for environmental changes such as temperature
            and altitude try to minimise these changes over the course of running the utility by selecting an appropriate area
            of the sky.</para></listitem>

            <listitem><para> Make sure your equipment is in thermal equilibrium before starting. Calculate roughly how long the utility will
            take which is the total number of AF runs * time for a single AF run. Try to make sure that the conditions will remain as
            consistent as possible during this time, e.g. there is enough time before dawn, the moon won't affect focusing of some images
            more than others, the target won't drop below your horizon during the process, etc.</para></listitem>

            <listitem><para> Configure the utility for # Focus Runs (5 is a good start), reference filter (e.g. Lum) and Adapt Focus
            setting. Run the utility to completion.</para></listitem>

            <listitem><para> Review the results. For each filter review each AF run looking for outliers. For each outlier decide what to
            do, e.g. remove from processing by setting to 0. If there are filters for which you are unhappy with the results, uncheck the
            Save checkbox for those filters.</para></listitem>

            <listitem><para> When happy, press Save to save the filter offsets to Filter Settings for future use.</para></listitem>
            </itemizedlist>
      </para>
</sect3>

  <sect3 id="focus-display">
    <title>Focus Display</title>

    <screenshot>
      <screeninfo> Focus Display </screeninfo>

      <mediaobject>
        <imageobject>
          <imagedata fileref="focus_display.png" format="PNG" width="50%"/>
        </imageobject>

        <textobject>
          <phrase>Focus Display</phrase>
        </textobject>
      </mediaobject>
    </screenshot>

    <para> The focus display, displays a FITS viewer window onto the frame
    taken during the focus process. If <guilabel>Ring Mask</guilabel> is selected, then the mask
    is drawn on the image. All the stars detected by Ekos based on the selected parameters, have their
    HFR value displayed next to the associated star (unless Measure is set to FWHM). </para>

    <para> If <guilabel>Mosaic Mask</guilabel> has been selected then the FITS viewer displays the
    mosaic 3x3 grid showing the center, edges and sides as configured in the Mosaic Mask options.
    <screenshot><screeninfo> Focus Display Mosaic</screeninfo><mediaobject>
    <imageobject><imagedata fileref="focus_display_mosaic.png" format="PNG" width="50%"/></imageobject>
    <textobject><phrase>Focus Display Mosaic</phrase></textobject></mediaobject></screenshot></para>

    <para> The window supports the following FITS viewer options (at the top
    of the window):</para>

    <itemizedlist>
      <listitem>
        <para> <guibutton>Zoom In</guibutton> and <guibutton>Zoom
        Out</guibutton>.</para>
      </listitem>

      <listitem>
        <para> <guibutton>Default Zoom</guibutton> and <guibutton>Zoom to
        Fit</guibutton>.</para>
      </listitem>

      <listitem>
        <para> <guibutton>Toggle Stretch</guibutton>: Toggle screen stretch on
        or off.</para>
      </listitem>

      <listitem>
        <para> <guibutton>Toggle Crosshairs</guibutton>: Toggle crosshairs on
        or off.</para>
      </listitem>

      <listitem>
        <para> <guibutton>Toggle Gridlines</guibutton>: Toggle pixel gridlines
        on or off.</para>
      </listitem>

      <listitem>
        <para> <guibutton>Toggle Stars</guibutton>: Toggle star detection on
        or off.</para>
      </listitem>

      <listitem>
        <para> <guibutton>View Star Profile</guibutton>: Launches the View Star Profile dialog.</para>
      </listitem>
    </itemizedlist>
  </sect3>

  <sect3 id="focus-v-curve">
    <title>V-Curve</title>

    <screenshot>
      <screeninfo> Focus V-Curve </screeninfo>

      <mediaobject>
        <imageobject>
          <imagedata fileref="focus_vcurve.png" format="PNG" width="50%"/>
        </imageobject>

        <textobject>
          <phrase>Focus V-Curve</phrase>
        </textobject>
      </mediaobject>
    </screenshot>

    <para> The V-Curve displays focuser position (x-axis) versus focus Measure, e.g. Half-Flux-Radius (HFR) (y-axis).
    Each datapoint is drawn on the graph and represented by a circle with a number representing the datapoint. How many
    datapoints are taken and how the focuser moves is determined by the parameters chosen. </para>

    <para> For certain algorithms, Ekos will also draw a curve of best fit through the datapoints. If <guilabel>Use Weights</guilabel>
    is selected then error bars are indicated on each datapoint that correspond to the standard deviation in measured value.</para>

    <para> The units of the y-axis depend on the selected focus Measure. For example, for HFR, the y-axis will either be in Pixels
    or Arc seconds depending on how <guilabel>Display Units</guilabel> is set.</para>

    <para> If <guilabel>Refine Curve Fit</guilabel> is selected, Focus will check for and potentially exclude outlying datapoints.
    In this case datapoints 1, 5 and 7 were excluded.</para>

    <para> Under the V-Curve a number of parameters are displayed:</para>

    <itemizedlist>
      <listitem>
        <para> <guilabel>HFR</guilabel>: Displays the star HFR for the most recent datapoint if relevant.</para>
      </listitem>

      <listitem>
        <para> <guilabel>FWHM</guilabel>: Displays the star FWHM for the most recent datapoint if relevant.</para>
      </listitem>

      <listitem>
        <para> <guilabel>Stars</guilabel>: The number of stars used for the most recent datapoint.</para>
      </listitem>

      <listitem>
        <para> <guilabel>Iteration</guilabel>: The number of datapoints taken so far.</para>
      </listitem>

      <listitem>
        <para> <guibutton>Relative Profile...</guibutton>: Invokes the <link linkend="focus-relative-profile">Relative Profile</link>
        popup.</para>
      </listitem>

      <listitem>
        <para> <guibutton>Clear Data</guibutton>: Resets the V-Curve graph by clearing the displayed data.</para>
      </listitem>
    </itemizedlist>

    <para> Here is a V-Curve when Measure is set to HFR Adj:
    <screenshot><screeninfo> V-Curve HFR Adj</screeninfo><mediaobject><imageobject>
          <imagedata fileref="focus_vcurve_hfradj.png" format="PNG" width="50%"/></imageobject><textobject>
          <phrase>Focus V-Curve HFR Adj</phrase></textobject></mediaobject></screenshot></para>

    <para> Here is a V-Curve when Measure is set to FWHM:
    <screenshot><screeninfo> V-Curve FWHM</screeninfo><mediaobject><imageobject>
      <imagedata fileref="focus_vcurve_fwhm.png" format="PNG" width="50%"/></imageobject><textobject>
      <phrase>Focus V-Curve FWHM</phrase></textobject></mediaobject></screenshot></para>

    <para> Here is a V-Curve when Measure is set to # Stars. In this case the Critical Focus Zone (CFZ)
    <guilabel>Display</guilabel> checkbox has been checked so the CFZ is displayed as well:
    <screenshot><screeninfo> V-Curve Num Stars</screeninfo><mediaobject><imageobject>
      <imagedata fileref="focus_vcurve_numstars.png" format="PNG" width="50%"/></imageobject><textobject>
      <phrase>Focus V-Curve Num Stars</phrase></textobject></mediaobject></screenshot></para>

    <para> Here is a V-Curve when Measure is set to Fourier:
    <screenshot><screeninfo> V-Curve Fourier</screeninfo><mediaobject><imageobject>
      <imagedata fileref="focus_vcurve_fourier.png" format="PNG" width="50%"/></imageobject><textobject>
      <phrase>Focus V-Curve Fourier</phrase></textobject></mediaobject></screenshot></para>

    <para> When Framing, the graph format changes to that of a "time series" where horizontal axis denotes the frame number.
    This is to aid you in the framing process as you can see how Measure, in this case HFR, changes between frames. </para>

    <para> This is very useful, for example, when trying to get the system into approximate focus before starting an Autofocus run.
    In this case Framing is started and the Step In and Step Out buttons used to adjust focus and the effect on the V-Curve
    observed.</para>

    <screenshot>
      <screeninfo> V-Curve as timeseries</screeninfo>

      <mediaobject>
        <imageobject>
          <imagedata fileref="focus_vcurve_timeseries.png" format="PNG"
                     width="50%"/>
        </imageobject>

        <textobject>
          <phrase>Focus V-Curve Timeseries</phrase>
        </textobject>
      </mediaobject>
    </screenshot>
  </sect3>

  <sect3 id="focus-relative-profile">
    <title>Relative Profile</title>

    <screenshot>
      <screeninfo> Focus Relative Profile </screeninfo>

      <mediaobject>
        <imageobject>
          <imagedata fileref="focus_relative_profile.png" format="PNG"
                     width="50%"/>
        </imageobject>

        <textobject>
          <phrase>Focus Relative Profile</phrase>
        </textobject>
      </mediaobject>
    </screenshot>

    <para> The relative profile is a graph that displays the relative HFR
    values plotted against each other. Lower HFR values correspond to narrower
    shapes and vice-versa. The solid red curve is the profile of the current
    HFR value, while the dotted green curve is for the previous HFR value.
    Finally, the magenta curve denotes the first measured HFR. This enables
    you to judge how well the Autofocus process improved the relative focus
    quality. </para>
  </sect3>

  <sect3 id="How_to_Setup_for_an_Auto_Focus_Run">
    <title>How to Setup for an Autofocus Run</title>

    <para> The exact settings that work best for a given astronomical setup need to be worked out by the user using trial and error.
    A good place to start is the <link linkend="focus-advisor">Focus Advisor</link> section. Run Focus Advisor and accept its
    recommendations. It uses the Linear 1 Pass algorithm:</para>

    <itemizedlist>
      <listitem>
        <para> Setup Backlash. See the <link linkend="focus-backlash">Backlash</link> section for more details.</para>
      </listitem>

      <listitem>
        <para> Initial Step Size. This is a critical parameter. You may have an idea from other people with a similar setup.
        If not you can try setting it from the Critical Focus Zone (CFZ) for your equipment. See the
        <link linkend="focus-cfz">CFZ section</link> for more details.</para>
        </listitem>

      <listitem>
        <para> Start near to focus by manually finding focus. Use the <guibutton>Start Framing</guibutton> option and manually adjust
        the focus to get to approximate focus.</para>
      </listitem>

      <listitem>
        <para> Make sure you are finding enough stars. Increasing the exposure usually finds more stars (but makes the focus process
        longer).</para>
      </listitem>
    </itemizedlist>

    <para> Run Autofocus. This is the sort of V-Curve you are after:</para>
    <screenshot><screeninfo> Good Focus Curve </screeninfo><mediaobject>
    <imageobject><imagedata fileref="focus_good_focus.png" format="PNG" width="50%"/></imageobject>
    <textobject><phrase>Good Focus Curve</phrase></textobject></mediaobject></screenshot>

    <para> In contrast, the next picture shows an Initial Step Size that has been set too low. The HFR varies from about 0.78 to 0.72.
      Which gives a max / min just over 1. The other clue that this is a poor setup is that the Error Bar range is very large compared
      to HFR movement which means that the curve solver is drawing a curve through a lot of noise, which means the results will not be
      very accurate.</para>
    <screenshot><screeninfo> Bad Focus Curve </screeninfo><mediaobject><imageobject>
    <imagedata fileref="focus_bad_focus.png" format="PNG" width="50%"/></imageobject>
    <textobject><phrase>Bad Focus Curve</phrase></textobject></mediaobject></screenshot>
  </sect3>

  <sect3 id="focus-backlash">
    <title>Focuser Backlash</title>

    <para>Backlash in the focuser setup is due to a combination of backlash in the electronic focuser itself (e.g. in the gearing
    mechanism), in the binding of the electronic focuser to the telescope drawtube, and in the telescope drawtube's mechanism. Thus,
    each setup will have its own backlash characteristic even if the same focuser is used.</para>

    <para> It is important to have a clear strategy for dealing with Backlash and to setup Focus appropriately for the chosen
    strategy. It is best to have backlash managed in one place to avoid conflicts. Whilst it is possible to have backlash
    managed in multiple places (this has been done successfully) it is not recommended in general because it can lead to conflicts
    between software components and the focuser.</para>

    <para> There are several ways to measure backlash in ticks. Consult the documentation on your focuser or use the internet
    including the Indi Forum.</para>

    <para> There are several things to consider when working out how to deal with backlash:
    <itemizedlist>
      <listitem>
        <para> <emphasis role="bold">No Backlash</emphasis>: If you are fortunate enough to have a setup with no backlash then it would
        make sense to set <guibutton>Device Backlash</guibutton> and <guibutton>AF Overscan</guibutton> off (set to zero).</para>
      </listitem>

      <listitem>
        <para> <emphasis role="bold">Backlash Managed by Focuser</emphasis>: If your focuser had the ability to manage backlash itself
        then you can use this facility and turn <guibutton>Device Backlash</guibutton> and <guibutton>AF Overscan</guibutton> off
        (set to zero). Alternatively, if it's possible, you could turn off the focuser's backlash facility and use either the
        Device Driver or AF Overscan to manage backlash.</para>
      </listitem>

      <listitem>
        <para> <emphasis role="bold">Backlash Managed by Device Driver</emphasis>: If your device driver has the ability to
        manage backlash then you can use this facility and turn off AF Overscan (set to zero). Alternatively,
        you could turn off the device driver's backlash facility and set AF Overscan.</para>

        <para> To know whether the device driver supports backlash, check the <guibutton>Device Backlash</guibutton> field.
        If it is enabled and you can set values then the driver supports Backlash. If the field is disabled then the driver
        does not support Backlash.</para>
      </listitem>

      <listitem>
        <para> <emphasis role="bold">AF Overscan</emphasis>: The Focus module can manage Backlash itself by over scanning
        outward motions by the value in the <guibutton>AF Overscan</guibutton> field. For example, if <guibutton>AF Overscan</guibutton>
        is set to 40 then whenever Focus moves the focuser outwards, it does this as a 2-step process. Firstly it moves the
        focuser 40 ticks past where it wants to end up; secondly it moves back in by 40 ticks.</para>

        <para> The advantage of <guibutton>AF Overscan</guibutton> is that you do not need to know Backlash exactly, you just need
        to set the <guibutton>AF Overscan</guibutton> &gt;= backlash. So, for example, if you measure backlash as around 60 ticks
        then you could set <guibutton>AF Overscan</guibutton> to 80.</para>

        <para> <guibutton>AF Overscan</guibutton> is also useful where Backlash is not exactly predictable. For example, if Backlash
        measurements yield slightly different values, e.g. 61, 60, 59 ticks then by using <guibutton>AF Overscan</guibutton> this
        inconsistency can be effectively neutralised. Were you to use <guibutton>Focuser Backlash</guibutton> you would probably
        average the readings and set the value to 60. Sometimes this will correctly take up all the backlash; sometimes it will
        be a little short; and sometimes it will over correct.</para>

        <para> All focuser movements managed by Focus will have <guibutton>AF Overscan</guibutton> applied, including Step Out, Goto,
        Autofocus runs, Adaptive Focus movements, Adapt Start Pos movements and Take flats at the same position as lights.</para>
      </listitem>
    </itemizedlist>
    </para>
  </sect3>

  <sect3 id="focus-adaptive">
    <title>Adaptive Focus</title>

    <screenshot>
      <screeninfo> Adaptive Focus  </screeninfo>

      <mediaobject>
        <imageobject>
          <imagedata fileref="focus_adaptive_focus.png" format="PNG" width="75%"/>
        </imageobject>

        <textobject>
          <phrase>Adaptive Focus</phrase>
        </textobject>
      </mediaobject>
    </screenshot>

    <para> Ekos support the concept of Adaptive Focus (AF). Without AF, a typical imaging plan would start
    with an Autofocus run then a sequence of subframes, then an Autofocus run, etc. The Autofocus runs would be triggered by
    a number of factors such as time, filter change, temperature change, etc. So basically as a sequence
    runs subframes are being taken slightly away from optimum focus until a threshold (e.g. temperature
    change) triggers an Autofocus run.</para>

    <para> The idea of AF is to adjust focus as environmental factors change to try to take each subframe
    as close as possible to optimum focus. Ideally, the effect of Adaptive Focus is like performing an Autofocus run before
    each subframe but without the overhead of actually doing the run.</para>

    <para> AF works as a complement to the various triggers for Autofocus that are available in Ekos now. So
    it is not necessary to change the Autofocus triggers when starting to use AF. Indeed, at the start, given
    that AF is an experimental feature, it is not recommended to relax Autofocus conditions when using AF. However,
    over time, as confidence grows in AF it would be possible to do less Autofocusing (and therefore more
    imaging). But either way, each subframe should be more in focus when using AF, providing it is setup correctly. </para>

    <para> So how do you know if AF would be useful for your setup or not? Perhaps the simplest way would be to
    examine subframes just after an Autofocus and compare them with subframes just before the next Autofocus. Can you
    see a difference in focus? If you have a setup where the focus point is tolerant of environmental changes between
    Autofocus runs then AF may not add anything to your images; if however you have a setup that is sensitive to
    environmental changes and the frequency of Autofocus runs is a compromise between quality and imaging time then
    AF ought to improve the quality of your subframes.</para>

    <para>AF currently supports two environmental dimensions: Temperature and Altitude (of the imaged target):</para>
    <itemizedlist>
      <listitem>
        <para> Temperature. All the components of the imaging system will be affected by changes in ambient temperature.
        The most obvious will be the telescope tube. Typically this will expand as temperature increases and contract as
        it decreases. This will affect the focus point. But also the optical path the light from the imaged target takes
        through the atmosphere and through the imaging components of the telescope will be affected by temperature and
        therefore will affect the focus point.</para>

        <para> It is necessary to have a reliable source of temperature information available to the focus module in order
        to use the temperature feature of AF.</para>

        <para> Where the temperature source is located is, of course, up to the user. Given the changes in temperature effect
        many components it is not obvious where the best location would be. Some experimentation may be required to get
        the best results but as a guide, the source should be near the imaging train but not near any heating effect of
        electrical equipment that would say, heat the temperature source but not the optical train. Consistency of location
        is likely to be important.</para>
      </listitem>

      <listitem>
        <para> Altitude. Some users have reported that the focus point changes with the altitude of the target. This effect
        is likely to be smaller than the temperature effect and may be negligible for some setups.</para>
      </listitem>
    </itemizedlist>

    <para> To use AF you need to work out firstly whether you want to adapt for Temperature, Altitude or both. If you are
    new to AF it is recommended to start with Temperature and once you have that working, determine whether your setup would
    benefit from adding Altitude.</para>

    <para> The first step is to workout the <guilabel>Ticks / °C</guilabel> and/or <guilabel>Ticks / °Alt</guilabel> for your
    equipment. To do this there is an existing utility in Ekos whereby when Focus logging is enabled, in addition to adding focus
    messages to the debug log, every time an Autofocus run completes, information is written to a text file in a directory called
    focuslogs located in the same place as the debug logs directory. The files are called “autofocus-(datetime).txt”. The data
    written are: date, time, position, temperature, filter, HFR, altitude. This data will need to be analysed outside of Ekos to
    determine the <guilabel>Ticks / °C</guilabel> and if required the <guilabel>Ticks / °Alt</guilabel>.</para>

    <para> Here is an example of a “autofocus-(datetime).txt” file:
    <screenshot>
      <screeninfo> Focus Autofocus Log </screeninfo>
      <mediaobject> <imageobject> <imagedata fileref="focus_autofocus_log.png" format="PNG" width="50%"/>
        </imageobject><textobject><phrase>Focus Autofocus Log</phrase></textobject></mediaobject>
    </screenshot></para>

    <para> Currently Ekos supports a simple linear relationship between temperature, or altitude, and ticks. In the future,
    if there is demand, more sophisticated relationships could be supported. A linear relationship will deliver the majority
    of the benefit of AF and is fairly straight-forward to administer. More complex relationships could be more accurate but
    come with more complex administration. Note also that more complex focus point vs temperature relationships will likely
    be more or less linear for small changes in temperature.</para>

    <para> A way to get a value for <guilabel>Ticks / °C</guilabel> would be to take the data from the
    autofocus-(datetime).txt files from a few nights of observing into a spreadsheet and graph focus position against temperature
    for each filter. Review the data and remove any outliers and plot a line of best fit. Use the line to get
    <guilabel>Ticks / °C</guilabel>. If you intend to adapt for altitude as well as temperature, then it would be better to use a
    set of data at similar altitude when calibrating temperature. Then its possible to calculate the effect of Temperature and
    remove this from the data when calculating the effect of Altitude.</para>

    <para> You will need to ensure that your focus position is repeatable at the same temperature and altitude and that there
    is no slipping of the focuser or uncompensated backlash. In addition, when calibrating it is better to avoid changing the
    optical train in a way that could change the focus position. If this is unavoidable and if the change affected the focus
    position then you will need to appropriately adjust the historical focus data so they can be compared.</para>

    <para> A simple approach is to start with a small amount of data, say 1 night and use this to calculate, say the Ticks /
    degree C. Run with this and adjust it over time as you collect more data. A way to check how well AF is performing would be
    to use Analyze to review how AF had moved the focus over 1 hour. If things are spot on, then where ever AF had positioned
    the focuser after 1 hour would match the Autofocus result. Where there is a discrepancy, it will be because of randomness
    in the Autofocus result and miscalibration in the AF <guilabel>Ticks / °C</guilabel>. By doing this regularly you will build
    knowledge of your equipment and be able to fine tune AF. Below is a screenshot of Analyze configured for Focus where you can
    see how Focus position changes throughout the imaging session:
    <screenshot>
      <screeninfo> Focus Analyze </screeninfo>
      <mediaobject> <imageobject> <imagedata fileref="focus_analyze.png" format="PNG" width="50%"/>
        </imageobject><textobject><phrase>Focus Analyze</phrase></textobject></mediaobject>
    </screenshot></para>

    <para> Once you have your data you can configure it in the <link linkend="focus-filter-settings">Filter Settings</link>
    popup. Then in Focus, switch on Adaptive Focus on the <link linkend="focus-settings">Focus Settings</link> tab. At this
    point, when you run a sequence, Ekos will check after each subframe whether it needs to adapt the focuser position. If so,
    Focus will do that and then Capture will continue with the next Subframe.</para>

    <para> The screenshot at the top of this section shows an example. <guilabel>Ticks / °C</guilabel> is set to 9.
    Autofocus ran and it solved at 36580 at 10C. Then a simple sequence of 5 subframes was run. The temperature was firstly set to 9C
    then to 8C. After each subframe completed, Ekos performed an adaptive focus run and where there was a temperature change it calculates
    the number of ticks to move the focuser. In this example, the focuser was moved inward by 9 ticks on 2 separate occasions,
    starting at 36580, before moving to 36571 and then to 36562 as shown on the Focus Tab in the Current Position widget and in
    the message box.</para>

    <para> The Adaptive Focus concept has been built into the <link linkend="build-filter-offsets">Build Offsets</link> tool.</para>
  </sect3>


  <sect3 id="Coefficient_of_Determination">
    <title>Coefficient of Determination, R²</title>

    <para> The Coefficient of Determination, or R², is calculated in order to
    give a measure of how well the fitted curve matches the datapoints. More
    information is available <ulink
    url="https://en.wikipedia.org/wiki/Coefficient_of_determination">here</ulink>.
    This feature that is available for the Linear 1 Pass
    focus algorithm. In essence, R² gives a value between 0 and 1, with 1
    meaning a perfect fit where all datapoints sit on the curve, and 0 meaning
    that there is no correlation between the datapoints and the curve. The
    user should experiment with their equipment to see what values they can
    obtain, but as a guide, a value above, say 0.9 would be a good fit.</para>

    <para> There is an option to set an “R² Limit” in the Settings tab of the
    Focus window that is compared to the calculated R² after the auto focus
    run has completed. If the limit value has not been achieved, then the auto
    focus is rerun.</para>

    <para> Setting an R² Limit could be useful for unattended observation if
    the focus run produces a bad result for a 1-off reason. Obviously if the
    reason is not transitory then rerunning will not improve anything.</para>

    <para> If the R² Limit is not achieved and the focus process is rerun, and
    again fails to achieve the R² Limit, then the focus run is marked as
    successful to avoid the process getting stuck rerunning auto focus
    forever.</para>

    <para> This feature is turned off by setting the R² Limit to 0.</para>
  </sect3>

  <sect3 id="Levenberg-Marquardt">
    <title>Levenberg–Marquardt Solver</title>

    <para> The Levenberg-Marquardt (LM) algorithm is used to solve non-linear
    least squares problems. The GNU Science Library provides an implementation
    of the solver. These resources provide more details: </para>

    <itemizedlist>
      <listitem>
        <para>
          <ulink url="https://en.wikipedia.org/wiki/Levenberg–Marquardt_algorithm"/>
        </para>
      </listitem>

      <listitem>
        <para>
          <ulink url="https://www.gnu.org/software/gsl/doc/html/nls.html"/>
        </para>
      </listitem>
    </itemizedlist>

    <para> The Levenberg-Marquardt algorithm is a non-linear least-squares solver and
    thus suitable for many different equations. The basic idea is to adjust
    the equation y = f(x,P) so that the computed y values are as close as
    possible to the y values of the datapoints provided, so that the resultant
    curve fits the data as best as it can. P is a set of parameters that are
    varied by the solver in order to find the best fit. The solver measures
    how far away the curve is at each data point, squares the result and adds
    them all up. This is the number to be minimized, let's call it S. The
    solver is supplied with an initial guess for the parameters, P. It
    calculates S, makes an adjustment to P and calculates a new S1. Provided
    S1 &lt; S then we are moving in the right direction. It iterates through
    the procedure until:</para>

    <itemizedlist>
      <listitem>
        <para> the delta in S is less than a supplied limit (convergence has
        been reached), or</para>
      </listitem>

      <listitem>
        <para> the maximum number of iterations has been reached, or</para>
      </listitem>

      <listitem>
        <para> the solver encountered an error.</para>
      </listitem>
    </itemizedlist>

    <para> The solver is capable of solving either an unweighted or weighted
    set of datapoints. In essence, an unweighted set of data gives equal
    weight to each datapoint when trying to fit a curve. An alternative is to
    weight each datapoint with a measure that corresponds to how accurate the
    measurement of the datapoint actually is. In our case this is the variance
    of star HFRs associated with the datapoint. The variance is the standard
    deviation squared.</para>

    <para> Currently the solver is used to fit either a parabolic or a
    hyperbolic curve.</para>
  </sect3>
</sect2>
