<?xml version="1.0"?>
<!DOCTYPE book PUBLIC '-//OASIS//DTD DocBook XML V4.2//EN' 
              'http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd'
[
<!ENTITY two-theta "
    <inlinemediaobject>
     <imageobject><imagedata fileref='fitykhelp_img/2theta.png'/></imageobject>
     <textobject><phrase>2theta</phrase></textobject>
    </inlinemediaobject> 
  ">
]>
<!-- $Id: fitykhelp.xml,v 1.48 2006/09/15 19:33:27 wojdyr Exp $ -->
<!-- XML header above -->
<!-- SGML header below-->
<!-- <!DOCTYPE article  PUBLIC "-//OASIS//DTD DocBook V4.1//EN"> -->

<book lang="en">
 <title>Fityk 0.7.6 - User's Manual</title> 
 <bookinfo> 
  <date>2006-09-15</date>
  <author> 
   <firstname>Marcin</firstname> <surname>Wojdyr</surname>
  </author> 
 </bookinfo>

 <chapter> 
  <title>Introduction</title> 
  <section>
   <title>What is the program for?</title>
   <para>
    <application>Fityk</application> is a program 
    for nonlinear fitting of analytical functions (especially peak-shaped) 
    to data (usually experimental data). The most concise description:
    peak fitting software. There are also people using it 
    to remove the baseline from data, or to display data only.
   </para>
   <para>
    It is reportedly used in crystallography, 
    chromatography, photoluminescence and photoelectron spectroscopy, infrared and Raman spectroscopy,
    to name but a few. Although the author has a general understanding only of experimental
    methods other than powder diffraction, 
    he would like to make it useful to as many people as possible.
   </para>
   <para>
    <application>Fityk</application> offers various nonlinear fitting methods, 
    simple background subtraction and other manipulations to the dataset, 
    easy placement of peaks and changing of peak parameters, 
    support for analysis of series of datasets,
    automation of common tasks with scripts, and much more. 
    The main advantage of the program is flexibility - parameters
    of peaks can be arbitrarily bound to each other, 
    e.g. the width of a peak can be an independent variable, 
    the same as the width of another peak, 
    or can be given by complex (and general for all peaks) formula.
   </para> 
   <para>
    <application>Fityk</application> is free software; you can redistribute 
    and modify it under the terms of the <acronym>GPL</acronym>, version 2. 
    See <xref linkend="license"/> for details. 
    You can download the latest version of <application>fityk</application> from
    <ulink url="http://www.unipress.waw.pl/fityk">
     http://www.unipress.waw.pl/fityk 
    </ulink>.
    or
    <ulink url="http://fityk.sf.net/">
     http://fityk.sf.net 
    </ulink>.
    To contact the author, visit the same page. 
   </para> 
  </section>

  <section>
   <title>How to read this manual</title>
   <para>
    After this introduction, read the <xref linkend="getstarted"/>.
    If you are using the <acronym>GUI</acronym> versionyou can look at the
    <ulink url="http://www.unipress.waw.pl/fityk/screenshots.html">
     screenshots-based tutorial at this webpage 
    </ulink> 
    and postpone reading
    <xref linkend="CommandReference"/> until you need to write a script
    or understand in more detail how the program works.
   </para>
  </section> 

  <section>
   <title><acronym>GUI</acronym> vs <acronym>CLI</acronym></title>
   <para>
    The program comes in two versions: the <acronym>GUI</acronym> (Graphical User
    Interface) version - more comfortable for most users,
    and the <acronym>CLI</acronym> (Command Line Interface) version 
    (named <command>cfityk</command> to differentiate, Unix only).
   </para>
   <para>
    If the <acronym>CLI</acronym> version was compiled with 
    the <systemitem class="library">GNU Readline Library</systemitem>, 
    command line editing and command history 
    as per <application>bash</application> will be available.
    Especially useful is <keycap>TAB</keycap>-expanding.
    Data and curves fitted to data are visualized with 
    <application>gnuplot</application> (if it is installed).
   </para>
   <para>
    The <acronym>GUI</acronym> version is written using the
    <ulink url="http://www.wxwidgets.org">
     <systemitem class="library">wxWidgets</systemitem> 
    </ulink>
    library. 
    and can be run on Unix species 
    with <systemitem class="library">GTK+</systemitem>
    and on MS Windows. There are also people
    using it on MacOS X (have a look at the fityk-users mailing list archives
    for details).
   </para>
  </section> 
 </chapter>


 <chapter id="getstarted">
  <title>Getting started</title>

  <section>
   <title>The minimal example</title>
   <para>
    Let us analyze a diffraction pattern of NaCl. Our goal is to determine the
    position of the center of the highest peak. It is needed for calculating the
    pressure under which the sample was measured, but this later detail in the processing
    is irrelevent for the time being.
   </para>
   <para>
    The data file used in this example is distributed with the program and 
    can be found in the <filename class="directory">samples</filename> directory. 
   </para>
   <para>
    First load data from file <filename>nacl01.dat</filename>. 
    You can do this by typing <userinput>@0 &lt; nacl01.dat</userinput> 
    in the <acronym>CLI</acronym> version (or in the <acronym>GUI</acronym> version 
    in the input box - at the bottom, just above the status bar). 
    In the <acronym>GUI</acronym>, you can also select
    <menuchoice>
     <guimenu>Data</guimenu><guimenuitem>Load File</guimenuitem>
    </menuchoice> 
    from the menu and choose the appropriate file. 
   </para> 
   <para>
    If you use the GUI, you can zoom-in to the biggest peak 
    using <mousebutton>left</mousebutton> mouse button on the auxiliary plot
    (the plot below the main plot). 
    To zoom out, press the <guiicon>View whole</guiicon> toolbar button.
    Other ways of zooming are described in <xref linkend="mouse"/>. 
    If you want the data to be drawn with 
    larger points or a line, or if you want to change the color of the line or background,
    press <mousebutton>right</mousebutton> mouse button on the main plot
    and use <guimenu>Data point size</guimenu> or <guimenu>Color</guimenu>
    menu from the pop-up menu. To change the color of data points, use the right-hand
    panel.
   </para> 
   <para>
    Now all data points are active.
    Because only the biggest peak is of interest for the sake of this example, 
    the remaining points can be deactivated. 
    Type: <userinput> a = (23.0 &lt; x &lt; 26.0) </userinput>
    or change to <firstterm>range</firstterm> mode (press 
    <guiicon> Data-Range Mode </guiicon>
    button on toolbar) and select range 
    to be deactivated with <mousebutton>right</mousebutton> mouse button.
   </para>
   <para>
    As our example data has no background
    to worry about, our next step is to define a peak with 
    reasonable initial values and fit it to the data. We will
    use Gaussian. 
    To see its formula, type: <userinput>info Gaussian</userinput>
    or look for it in the documentation (in <xref linkend="flist"/>). 
    Incidentally, most of the commands can be abbreviated, 
    e.g. you can type: <userinput>i Gaussian</userinput>. 
   </para>
   <para>
    To define peak, type: 
    <userinput>%p = Gaussian(~60000, ~24.6, ~0.2) -> F</userinput>
    or
    <userinput>%p = guess Gaussian</userinput>
    or select 
    <menuchoice><guilabel>Gaussian</guilabel></menuchoice> 
    from the list of functions on the toolbar and press the
    <guiicon>
     auto-add 
     <!-- <inlinegraphic fileref="../src/img/clickadd.xpm"> -->
    </guiicon> 
    toolbar button.
    There are also other ways to add peak in <acronym>GUI</acronym>
    such as <firstterm>add-peak</firstterm> mode. 
    These mouse-driven ways give function a name like %_1, %_2, etc.
   </para>
   <para>
    Now let us fit the function. Type: <userinput>fit</userinput> 
    or select 
    <menuchoice>
     <guimenu>Fit</guimenu><guimenuitem>Run</guimenuitem>
    </menuchoice> 
    from the menu (or press the toolbar button). 
   </para>
   <para>
    When fitting, 
    the weighted sum of squared residuals (see <xref linkend="nonlinear"/>)
    is being minimized. 
    Note that the default <link linkend="weights">weights of points</link> 
    are not equal. 
   </para>
   <para>
    To see the peak parameters, type: <userinput> info+ %p</userinput>
    or (in the GUI) move the cursor to the top of the peak 
    and try out the context menu (right button), or use the right-hand panel.
   </para>
   <para>
    That's it! To do the same a second time (for example to a similar data set) you can write all the commands 
    to file (you can do it now using command 
    <command>commands &gt; <replaceable>filename</replaceable></command>),
    and use it as script: 
    <userinput>commands &lt; nacl01.fit</userinput>
    or select 
    <menuchoice>
     <guimenu>Session</guimenu><guimenuitem>Execute script</guimenuitem>
    </menuchoice> 
    from menu, or run program with the name of the script: 
    <prompt>bash$ </prompt><userinput>fityk nacl01.fit</userinput>
   </para>
  </section> 

  <section id="invoking">
   <title>Invoking fityk </title>
   <para>
    On startup, the program executes a script from the
    <filename>$HOME/.fityk/init</filename> file.
    Following this, the program reads files given as arguments on the command line.
    If the filename has extension ".fit" or the file begins with a "# Fityk"
    string, it is assumed to be a script and is executed.
    Otherwise,  it is assumed to be a data file and is loaded normally.
    There are also other parameters to the CLI and GUI versions of the program.
    Option "-h" gives the full listing.
    <screen>     
     wojdyr@ubu:~/fityk/src$ ./fityk --help
     Usage: fityk [-h] [-V] [-c &lt;str&gt;] [-I] [-r] [script or data file...]
      -h, --help            show this help message
      -V, --version         output version information and exit
      -c, --cmd=&lt;str&gt;       script passed in as string
      -I, --no-init         don't process $HOME/.fityk/init file
      -r, --reorder         reorder data (50.xy before 100.xy)
    </screen>     
   </para>
  </section> 

  <section id="gui">
   <title>Graphical interface </title>
   <section>
    <title>Plots and other windows</title>
    <para>
     The GUI window of <application>fityk</application> consists 
     of (from the top): menu bar, 
     toolbar, main plot, auxiliary plot, output window, input field,
     status bar and of sidebar at right-hand side. 
     The input field allows you to type and execute commands in a
     similar way as is done in the <acronym>CLI</acronym> version. 
     The output window (which is configurable through a pop-up menu)
     shows the results. Incidentally, all GUI commands are converted into text
     and are visible in the output window, providing a simple way to learn the syntax.
    </para>
    <para>
     The main plot can display
     data points, functions and/or the sum of all functions. Use the pop-up
     menu (click <mousebutton>right</mousebutton> button on the plot) 
     to configure it. 
     Some properties of the plot (e.g. colors of data points) can be changed
     using the sidebar. 
    </para>
    <para>
     One of the most useful things which can be displayed by the auxiliary plot 
     is the difference between the data and the sum of functions. 
     (also controlled by a pop-up menu). Hopefully, a 
     quick look at this menu and a minute or two's worth of experiments will show
     the potential of this auxiliary plot.
    </para>
    <para>
     Configuration of the GUI (visible windows, colors, etc.) can be saved using 
     <menuchoice>
      <guimenu>GUI</guimenu><guimenuitem>Save current config</guimenuitem>
     </menuchoice>. 
     Two different configurations can be saved, 
     which allows easy changing of colors
     for printing. On Unix platforms, these configurations are stored 
     in a file in the user's home directory. 
     On Windows - they are stored in the registry (perhaps in the future they will 
     also be stored in a file).
    </para>
   </section>

   <section id="mouse">
    <title>Mouse usage</title>
    <para>
     The usage of the mouse on menu, dialog windows, 
     input field and output window is (hopefully)
     intuitive, so the only remaining topic to be discussed here is how to effectively
     use the mouse on plots.
    </para>
    <para>
     Let us start with the auxiliary plot. 
     The <mousebutton>right</mousebutton> button displays a pop-up menu with 
     a range of options, 
     while the <mousebutton>left</mousebutton> allows you to 
     select the range to be displayed on the x-axis. 
     Clicking with the <mousebutton>middle</mousebutton> button (or with 
     <mousebutton>left</mousebutton> button and <keycap>Shift</keycap> pressed simultaneously)
     will zoom out to display all data. 
    </para>
    <para>
     On the main plot, the meaning of the <mousebutton>left</mousebutton> and
     <mousebutton>right</mousebutton> mouse button depends on current 
     <firstterm>mode</firstterm> (selected using either the toolbar or menu).  
     There are hints on the status bar.
     In normal mode, the <mousebutton>left</mousebutton> button is used for
     zooming and the <mousebutton>right</mousebutton> invokes the pop-up menu.
     The same behaviour can be obtained in any mode by pressing
     <keycap>Ctrl</keycap> (or <keycap>Alt</keycap>.).

     The <mousebutton>middle</mousebutton> 
     button can be used to select a rectangle that you want to zoom in to. 
     If an operation has two steps, such as rectangle zooming (i.e. first you 
     press a button to select the first corner, then move the mouse and release 
     the button to select the second corner of the rectangle),
     this can be cancelled by pressing another button when the first one is pressed.
    </para>
   </section> 
  </section> 
 </chapter>


 <chapter id="CommandReference">
  <title>Reference </title>
  <section id="GeneralSyntax">
   <title>General syntax </title>
   <para>
    Basically, there is one command per line. 
    If for some reason it is more comfortable to place more than one
    command on one line, they can be separated with a semicolon (;). 
   </para>
   <para>
    Most of the commands can have arguments separated by a comma (,), 
    e.g. <command>delete %a, %b, %c</command>. 
   </para>
   <para>
    Most of the commands can be shortened: e.g. you can type 
    <command>inf</command> or <command>in</command> or <command>i</command>
    instead of <command>info</command>. See <xref linkend="shortenings"/>
    for details.
   </para>
   <para>
    The symbol '#' starts a comment - everything from the
    hash (#) to the end of the line is ignored.
   </para>
  </section>

  <section>
   <title>Data from experiment </title>
   <section id="DataLoad">
    <title>Loading data </title>
    <para>
     Data are stored in files.  Unfortunately, there are various formats of
     files with data. The basic one is a text file with every line 
     corresponding to one data point. The line should contain at least two
     numbers: x and y of the point. It can also contain the standard deviation of the y
     coordinate.  Numbers can be separated by whitespace, commas, colons or
     semicolons. Some lines can contain comments or extra informations. If
     these lines have a hash (#) in the first column, they are ignored. In other
     case, they are also ignored (unless they can be read as a data point). 
     Specific file types that can also be read currently include: .rit, .cpi,
     Siemens-Bruker .raw and .mca. In future, the way the special file formats
     are handled will be changed (external library will be used for it,
     unfortunatelly this library does not yet exist).
    </para>
    <para>
     Points are loaded from files using the command
    </para>
    <cmdsynopsis>
     <arg choice="plain"><replaceable>dataslot</replaceable></arg>
     <command>&lt;</command> 
     <arg choice="plain"><replaceable>filename</replaceable></arg> 
     <arg><replaceable>filetype</replaceable></arg>  
     <arg><replaceable>xcol</replaceable>,<replaceable>ycol</replaceable>
      <arg>,<replaceable>scol</replaceable></arg>
     </arg> 
    </cmdsynopsis>
    <para>
     where 
     <replaceable>dataslot</replaceable> 
     should be replaced with <userinput>@0</userinput>, 
     unless many datasets are to be used simultaneously 
     (for details see: <xref linkend="multidata"/>),
     <replaceable>filetype</replaceable> usually can be omitted 
     (in most of the cases the filetype can be detected automatically,
     all supported filetypes are listed at the end of this section),
     <replaceable>xcol</replaceable>, <replaceable>ycol</replaceable>, 
     <replaceable>scol</replaceable>, 
     are unsigned integers. If the filename contains blank characters,
     a semicolon or comma, it should be put inside single
     quotation marks. If the file is in a text format (columns with numbers)
     it can be specified which column contains x, y, and (optionally) std. dev.
     of y. 
     The list of <replaceable>filetype</replaceable> can be one of the following:
    </para>

    <para>
     Information about the current data can be obtained by using the command:
    </para>
    <cmdsynopsis>
     <command>info</command>
     <arg choice="plain"><replaceable>dataslot</replaceable></arg>
    </cmdsynopsis>

    <variablelist><title>Supported filetypes</title>
     <varlistentry><term>text</term>
      <listitem><para>ASCII format, at least two numbers in each line
      </para></listitem> 
     </varlistentry>

     <varlistentry><term>htext</term>
      <listitem><para>Similar to text, but the first line contains title
      </para></listitem> 
     </varlistentry>

     <varlistentry><term>MCA</term>
      <listitem><para>Spectral data stored by Canberra MCA systems
      </para></listitem> 
     </varlistentry>

     <varlistentry><term>RIT</term>
      <listitem><para>RIT format used by DBWS 
        (the program for Rietveld analysis)
      </para></listitem> 
     </varlistentry>

     <varlistentry><term>CPI</term>
      <listitem><para>Sietronics Sieray CPI format
      </para></listitem> 
     </varlistentry>

     <varlistentry><term>BrukerRAW</term>
      <listitem><para>Simens-Bruker RAW format (version 2)
      </para></listitem> 
     </varlistentry>
    </variablelist>

   </section> 

   <section>
    <title>Active and inactive points</title>
    <para>
     We often have the situation that only a part of the data from a file is of interest.
     We should be able to exclude selected points from fitting and all
     computations. Every point can be either active or inactive.  
     This can be done with the command <command>A=...</command> 
     (see <xref linkend="transform"/> for details)
     or with a <link linkend="mouse">mouse-click in the <acronym>GUI</acronym></link>.
     The idea of active and inactive points is simple: 
     only the active ones are subject to fitting and peak-finding, 
     inactive ones are neglected in these cases. 
    </para>
   </section> 

   <section id="weights">
    <title>Standard deviation (or weight) </title>
    <para>
     When fitting data, we assume that only the y coordinate is subject to
     statistical errors in measurement. This is a common assumption. 
     To see how the y standard deviation
     <inlinemediaobject>
      <imageobject><imagedata fileref="fitykhelp_img/sigma.png"/></imageobject>
      <textobject><phrase>sigma</phrase></textobject>
     </inlinemediaobject>  
     influences fitting (optimization), look at the
     weighted sum of squared residuals formula in <xref linkend="nonlinear"/>. 
     We can also think about weights of points -
     every point has a weight assigned, that is equal 
     <inlineequation>
      <inlinemediaobject>
       <imageobject>
        <imagedata fileref="fitykhelp_img/w_1_sigma.png"/>
       </imageobject>
       <textobject>
        <phrase>w<subscript>i</subscript>=1/sigma^2</phrase>
       </textobject>
      </inlinemediaobject>  
     </inlineequation>
    </para>
    <para>
     Standard deviation of points can be 
     <link linkend="DataLoad">read from file</link> together with the x and y
     coordinates. Otherwise, it is set to max(sqrt(y), 1.0), 
     Setting std. dev. as a square root of the value is common 
     and has theoretical ground when y is the number of independent events.
     You can always change standard deviation, e.g. make it equal for every
     point with command: <userinput>S=1</userinput>.
     See <xref linkend="transform"/> for details.
    </para>
   </section> 

   <section id="transform">  
    <title>Data transformations</title>
    <para>
     Every data point has four properties: x coordinate, y coordinate,
     standard deviation of y and active/inactive flag. Lower case 
     letters x, y, s, a stand for these properties before transformation,
     and upper case X, Y, S, A for the same properties after transformation.
     M stands for the number of points. 
     Data can be transformed using assignments.
     Command <userinput>Y=-y</userinput> will change the sign of the y coordinate
     of every point. You can also apply transformation to selected points:
     <userinput>Y[3]=1.2</userinput> will change point with index 3 
     (which is 4th point, because first has index 0),
     and <userinput>Y[3...6]=1.2</userinput> will do the same for points with 
     indices 3, 4, 5, but not 6. <userinput>Y[2...]=1.2</userinput>
     will apply the transformation to points with index 2 and above.
     You can guess what <userinput>Y[...6]=1.2</userinput> does.
     Most of operations are executed sequentially for points from the first 
     to the last one. n stands for the index of currently transformed point.
     The sequance of commands:
     <userinput>M=500; x=n/100; y=sin(x)</userinput>
     will generate the sinusoid dataset with 500 points. 
    </para>
    <para>
     If you have more than one dataset, you have to specify explicitly
     which dataset transformation applies to. See
     <xref linkend="multidata"/> for details.
    </para>
    <para>
     Note that points are kept sorted according to their x coordinate, so changing x coordinate
     of points will also change the order and indices of points.
    </para>
    <para>
     Expressions can contain 
     real numbers in normal or scientific format (e.g. 1.23e5),
     constant <constant>pi</constant>,
     binary operators: +, -, *, /, ^,
     one argument functions:
     <function>sqrt</function>, 
     <function>exp</function>, 
     <function>log10</function>, 
     <function>ln</function>, 
     <function>sin</function>, 
     <function>cos</function>, 
     <function>tan</function>, 
     <function>atan</function>, 
     <function>asin</function>, 
     <function>acos</function>, 
     <function>erf</function>,
     <function>erfc</function>,
     <function>gamma</function>, 
     <function>lgamma</function> (=ln(|gamma|)), 
     <function>abs</function>,
     <function>round</function> (rounds to the nearest integer),
     two argument functions: 
     <function>min2</function>, 
     <function>max2</function>  
     (e.g. <userinput>max2(3,5)</userinput> will give 5), 
     <function>randuniform(a, b)</function> 
     (random number from interval (a, b)),
     <function>randnormal(mu, sigma)</function> 
     (random number from normal distribution)

     and ternary ?: operator: 
      <replaceable>condition</replaceable> ? 
      <replaceable>expression1</replaceable> : 
      <replaceable>expression2</replaceable>, which performs 
     <replaceable>expression1</replaceable> if condition is true 
     and <replaceable>expression2</replaceable> otherwise.
     Conditions can be built using boolean operators and comparisions: 
     AND, OR, NOT, &gt;, &gt;=, &lt;, &lt;=, ==, 
     != (or &lt;&gt;), TRUE, FALSE.
    </para>
    <para>
     The value of a data expression can be shown using the command 
     <command>info</command>, see examples at the end of this section.
    </para>
    <para>
     <function><replaceable>t</replaceable>[x=expression]</function>, where
     <replaceable>t</replaceable>=x,y,s,a,X,Y,S,A
     gives a linear interpolation of <replaceable>t</replaceable> 
     between two points (or the value of first/last point if the given x is outside 
      the current data range).
    </para>
    <para>
     Important note: all operations are performed on real numbers.
     Two numbers that differ less than epsilon=1e-9 
     i.e. abs(a-b)&lt;epsilon, are considered equal. 
     Indices are also computed in real number domain, 
     and then rounded to the nearest integer.
    </para>
    <para>
     Transformations can be joined with comma (,), e.g.
     <userinput>X=y, Y=x</userinput> swaps axes.
    </para>
    <para>
     Before and after executing transformations, points are always 
     sorted according to their x coordinate. You can change the order of points
     using <command>order=<replaceable>t</replaceable></command>,
     where <replaceable>t</replaceable> is one of x, y, s, a, -x, -y, -s, -a.
     Clearly, this only makes sense for a sequence of transformations (joined with comma)
     as after finishing each transformation, points will be reordered again.
    </para>
    <para>
     Points can be deleted using the following syntax:
     <command>delete[<replaceable>index-or-range</replaceable>]</command>
     or 
     <command>delete(<replaceable>condition</replaceable>)</command>
     and created simply by increasing value of M.
    </para>
    <para>
     There are two parametrized functions: <function>spline</function>
     and <function>interpolate</function>.
     The general syntax is: 
     <replaceable>parametrizedfunc</replaceable> 
     [<replaceable>param1</replaceable>, 
     <replaceable>param2</replaceable>](<replaceable>expression</replaceable>)
     e.g. <userinput>spline[22.1, 37.9, 48.1, 17.2, 93.0, 20.7](x)</userinput> 
     will give the value of a cubic spline interpolation through points 
     (22.1, 37.9), (48.1, 17.2), ... in x.
     Function interpolation is similar, but gives a polyline interpolation.
     Spline function is used for manual background substraction via the GUI.
    </para>
    <para>
     There are also aggragate functions: 
     <function>min</function>, <function>max</function>, 
     <function>sum</function>, <function>avg</function>, 
     <function>stddev</function>, <function>darea</function>. 
     They have two forms. In the simpler one:
     <replaceable>aggragatefunc</replaceable> 
     (<replaceable>expression</replaceable>), the value of expression
     in brackets is calculated for all points. <function>min</function>
     gives the smallest value, <function>max</function> the largest,
     <function>sum</function>, <function>avg</function> and
     <function>stddev</function> give the sum of all values, arithmetic mean
     and standard deviation, respectively. True value in data expression
     is represented numerically by 1., and false by 0, 
     so <function>sum</function> can be also used to count points
     that fulfil given criteria.
    </para>
    <para>
     <function>darea</function> gives the sum of expressions calculated
     using formulae: t*(x[n+1]-x[n-1])/2, where t is the value of the expression
     in brackets. <userinput>darea(y)</userinput> gives 
     the area under interpolated data points, 
     and can be used to normalize the area.
    </para>
    <para>
     The second form: 
     <replaceable>aggragatefunc</replaceable> 
     (<replaceable>expression</replaceable> 
     if <replaceable>condition</replaceable>) takes into account only points
     for which the condition is true.
    </para>
    <para>
     A few examples:
     <screen>     
     Y[1...] = Y[n-1] + y[n] # integrate

     x[...-1] = (x[n]+x[n+1])/2;  # reduces
     y[...-1] = y[n]+y[n+1];      # two times
     delete(n%2==1)               # number of points

     delete(not a) # delete inactive points

     X = 4*pi * sin(x/2*pi/180) / 1.54051 # changes x scale (2theta -> Q)

     # make equal step, keep the number of points the same
     X = x[0] + n * (x[M-1]-x[0]) / (M-1),  Y = y[x=X], S = s[x=X], A = a[x=X]

     # take the first 2000 points, average them and substract as background
     Y = y - avg(y if n&lt;2000)

     # fityk can also be used as a simple calculator
     i 2+2 #4
     i sin(pi/4)+cos(pi/4) #1.41421
     i gamma(10) #362880

     # examples of aggregate functions
     i max(y) # the largest y value
     i sum(y>avg(y)) # the number of points which have y value greater than arithmetic mean
     Y = y / darea(y) # normalize data area
     i darea(y-F(x) if 20&lt;x&lt;25)
     </screen>     
    </para>
   </section> 

   <section id="funcindt">
    <title>Functions and variables in data transformation</title>
    <para>
     Informations in this section are not often used in practice.
     Read it after reading <xref linkend="sum"/>.
    </para>
    <para>
     Variables ($foo) and functions (%bar) can be used in data transformations, 
     and a current value of data expression can be assigned to the variable.
     Values of the function parameters (e.g. %fun[a0]) and pseudo-parameters
     Center, Height, FWHM and Area (e.g. %fun[Area]) can also be used.
     Pseudo-parameters are supported only by functions, which know
     how to calculate these properties. 
    </para>
    <para>
     Some properties of functions can be calculated using functions
     <function>numarea</function>, <function>findx</function> 
     and <function>extremum</function>. 
    </para>
    <para>
     <function>numarea(%f, x1, x2, n)</function> 
     gives area integrated numerically 
     from x1 to x2 using trapezoidal rule with n equal steps.
    </para>
    <para>
     <function>findx(%f, x1, x2, y)</function> 
     finds x in interval (x1, x2) such that 
     %f(x)=y
     using bisection method combined with Newton-Raphson method.
     It is a requirement that %f(x1) &lt; y &lt; %f(x2).
    </para>
    <para>
     <function>extremum(%f, x1, x2)</function> finds x in interval (x1, x2) 
     such that 
     %f'(x)=0 
     using bisection method.  
     It is a requirement that %f'(x1) and %f'(x2) have different signs. 
    </para>
    <para>
     A few examples:
     <screen>     
      $foo = {y[0]} # data expression can be used in variable assignment
      Y = y / $foo  # and variables can be used in data transformation

      Y = y - %f(x) # substracts function %f from data

      Y = y - @0.F(x) # substracts all functions in F

      %c = Constant(~0) -> Z  # fit constant zero-shift (this can be caused...
      fit                # ...by a shift in scale of the instrument collecting data),
      X = x + @0.Z(x)  # ...remove it from dataset,
      del %c           # ...and delete it from sum

      info numarea(%fun, 0, 100, 10000) # shows area of function %fun 
      info %fun[Area] # it is not always supported

      info %_1(extremum(%_1, 40, 50)) # shows extremum value

      # calculate FWHM numerically, value 50 can be tuned
      $c = {%f[Center]}
      i findx(%f, $c, $c+50, %f[Height]/2) - findx(%f, $c, $c-50, %f[Height]/2)
      i %f[FWHM] # should give almost the same.
     </screen>     
    </para>
   </section> 

   <section id="multidata">
    <title>Working with multiple datasets</title>
    <para>
     Let us call a set of data that usually comes from one file - a 
     <firstterm>dataset</firstterm>. 
     All operations described above assume only one dataset.
     If there are more datasets created, it must be explicitly
     stated which dataset the command is being applied to, e.g.
     <userinput>M=500 in @0</userinput>. Datasets have numbers
     and are referenced by '@' with the number, e.g. <userinput>@3</userinput>.
     <userinput>@*</userinput> means all datasets, 
     (e.g. <userinput>Y=y/10 in @*</userinput>).
    </para>
    <para>
     Command
     <cmdsynopsis>
      <arg choice="plain">@+</arg>
      <command>&lt;</command> 
      <arg choice="plain"><replaceable>filename</replaceable></arg> 
      <arg><replaceable>filetype</replaceable></arg>  
      <arg><replaceable>xcol</replaceable>,<replaceable>ycol</replaceable>
       <arg>,<replaceable>scol</replaceable></arg>
      </arg> 
     </cmdsynopsis>
     will load dataset to new slot. Using @+ increases the number of datasets,
     and command <command>delete @<replaceable>n</replaceable></command>
     decreases it. It is also possible to duplicate a dataset (using the command
     <command>@+ &lt; @<replaceable>n</replaceable></command>)
     or to create new dataset as a sum of two or more existing sets 
     (command <command>@+ &lt; @<replaceable>n</replaceable> +
      @<replaceable>m</replaceable> + ...</command>).
    </para>
    <para>
     Each dataset has a separate <link linkend="sum">sum</link>, i.e. a model
     that can be fitted to the data. This is explained in the next chapter.
    </para>
    <para>
     Each dataset also has a title (it does not have to be unique, however).
     When loading file, a title is automatically created, either 
     using the filename or by reading it from the file (depending on the format
     of the file).
     Titles can be changed using the command 
     <command>
      @<replaceable>n</replaceable>.title=<replaceable>new-title</replaceable>
     </command>. 
     To see the current title of the dataset, 
     use <command>info @<replaceable>n</replaceable></command>.
    </para>
   </section> 
   <section id="dexport">
    <title>Exporting data</title>
    <para>
     Command
     <cmdsynopsis>
      <arg choice="plain"><replaceable>dataslot</replaceable></arg>
      <command>(<replaceable>expression</replaceable>, ...)
      &gt;</command> 
      <arg choice="plain"><replaceable>filename</replaceable></arg> 
     </cmdsynopsis>
     can export data to an ASCII TSV (tab separated values) file. 
     To export data in a 3-column (x, y and standard deviation) format, use
     <userinput>@<replaceable>n</replaceable> (x, y, s) > <replaceable>file</replaceable></userinput>.
     If <userinput>a</userinput> is not listed in the list of columns,
     such as in this example, only the active points are exported.
    </para>
    <para>
     All expressions that can be used on the right-hand side of data transformations
     can also be used in the column list, e.g.
     <userinput>@0 (n+1, x, y, @0.F(x), y-@0.F(x), @0.Z(x), %foo(x), a, sin(pi*x)+y^2) > bar.tsv</userinput>. 
     [To make it easier to export all functions
     in F separately, there is an exception in the syntax: "*F(x)" is replaced 
     with all functions in sum of the exported dataset, 
     e.g. with "%_1(x) %_2(x) %_3(x)". This is most likely not a good idea and
     will probably be removed in a future version. If you find it useful, let the author know.]
    </para>
   </section> 
  </section> 


  <section id="sum">
   <title>Sum of fitted functions </title>
   <section id="sumintro">
    <title>Sum - Introduction</title>
    <para>
     The sum of functions S (the curve that is fitted to the data) is itself a
     function. The value of the whole sum is computed as a sum of the functions,
     like Gaussians or polynomials, and can be given by the formula:
     <inlineequation>
      <inlinemediaobject>
       <imageobject>
        <imagedata fileref="fitykhelp_img/sum_f.png"/>
       </imageobject>
       <textobject>
        <phrase>
         S = \sum<subscript>i</subscript> f<subscript>i</subscript>
        </phrase>
       </textobject>
      </inlinemediaobject>  
     </inlineequation>, 
     where f<subscript>i</subscript> is a function of x, and
     depends on a vector of parameters a. This vector contains all
     fitted parameters. 
     Because we often have the situation, that the error 
     in the x coordinate of data points can be modeled with function z(x; a),
     we introduce this term to sum:
     <informalequation>
      <mediaobject>
       <imageobject>
        <imagedata fileref="fitykhelp_img/sum_f_x_z.png"/>
       </imageobject>
       <textobject>
        <phrase>
         S(x;a) = \sum<subscript>i</subscript> f<subscript>i</subscript>
                                                                (x+z(x;a);a)
        </phrase>
       </textobject>
      </mediaobject>  
     </informalequation>
     where
     <inlineequation>
      <inlinemediaobject>
       <imageobject>
        <imagedata fileref="fitykhelp_img/z_x_a.png"/>
       </imageobject>
       <textobject>
        <phrase>
         z(x;a) = \sum<subscript>j</subscript> z<subscript>j</subscript>(x;a)
        </phrase>
       </textobject>
      </inlinemediaobject>  
     </inlineequation>
     . Note that the same z(x) is used in all functions.
    </para>
    <para>
     Now we will have a closer look at f<subscript>i</subscript> functions. 
     Every function f<subscript>i</subscript> has a type chosen from the
     function types available in the program. The same is true about
     functions z<subscript>i</subscript>.
     One of these types is the
     <emphasis>Gaussian</emphasis>. It has the following formula:
     <informalequation>
      <mediaobject>
       <imageobject>
        <imagedata fileref="fitykhelp_img/gauss_example.png"/>
       </imageobject>
       <textobject>
        <phrase>
         height exp[-ln(2) ((x-center)/hwhm)^2]
        </phrase>
       </textobject>
      </mediaobject>  
     </informalequation>
     There are three parameters of Gaussian. These parameters do not
     depend on x. There must be one <firstterm>variable</firstterm> 
     bound to each parameter.
    </para>
   </section>
   <section id="variables">
    <title>Variables</title>
    <para>
     Variables in Fityk have names prefixed with the dollar symbol ($).
     A variable is created by assigning a value to it, e.g.
     <userinput>$foo=~5.3</userinput> 
     or <userinput>$c=3.1</userinput>
     or <userinput>$bar=5*sin($foo)</userinput>.
     <varname>$foo</varname> is here a so-called 
     <firstterm>simple variable</firstterm>. 
     It is created by assigning
     to it real number prefixed with ~. The `~' means that the value
     assigned to the variable can be changed when fitting the sum of the functions to the data.
     For people familiar with optimization techniques: 
     the number of defined simple variables is the number of dimensions
     of space we are looking for the optimum in.
     In the above example, the variable <varname>$c</varname> 
     is actually a constant. <varname>$bar</varname> 
     depends on the value of <varname>$foo</varname>.
     When <varname>$foo</varname> changes, the value 
     of <varname>$bar</varname> also changes.
     Compound variables can be build using operators +, -, *, /, ^
     and the functions 
     <function>sqrt</function>, 
     <function>exp</function>, 
     <function>log10</function>, 
     <function>ln</function>, 
     <function>sin</function>, 
     <function>cos</function>, 
     <function>tan</function>, 
     <function>atan</function>, 
     <function>asin</function>, 
     <function>acos</function>, 
     <function>erf</function>,
     <function>erfc</function>,
     <function>lgamma</function>. Note that this is a subset of the functions
     used in <link linkend="transform">data transformations</link>.
    </para>
    <para>
     Every simple parameter has a value and, optionally, domain.  
     The domain is used only by the fitting algorithms 
     which need to randomly initialize or change variables. 
     Genetic Algorithms are a good example.
    </para>
    <para>
     Variables can be used in data tranformations, 
     e.g. <userinput>Y=y/$a</userinput>.
    </para>
    <para>
     The value of the data expression
     can be used in the variable definition, but it must be inside braces,
     e.g. <userinput>$bleh={M}</userinput> 
     or, to create a simple variable: <userinput>$bleh=~{M}</userinput>.
    </para>
    <para>
     Sometimes it is useful to freeze a variable, i.e. to prevent it from
     changing while fitting. There is no special syntax for it, 
     but it can be done using data expressions in this way:
     <screen>
      $a = ~12.3 # $a is fittable
      $a = {$a}  # $a is not fittable
      $a = ~{$a}  # $a is fittable again
     </screen>
    </para>
    <para>
     It is also possible to define a variable as e.g. 
     <userinput>$bleh=~9.1*exp(~2)</userinput>. In this case two simple
     variables (with values 9.1 and 2) will be created automatically. 
     Automatically created
     variables are named <varname>$_1</varname>, <varname>$_2</varname>, 
     <varname>$_3</varname>, and so on.
    </para>
    <para>
     Variables can be deleted using the command 
     <command>delete <replaceable>$variable</replaceable></command>.
    </para>
    <para>
     Some fitting algorithms need to randomize the parameters of the fitted function
     (i.e. simple variables). For this purpose, 
     the simple variable can have a specified <firstterm>domain</firstterm>.
     Note that the domain does not imply any constraints on the value
     the variable can have -- it is only a hint for fitting methods such as the
     Nelder-Mead simplex or Genetic Algorithms. Further information on how the domain is used in
     these methods is contained in the appropriate fitting description. The syntax is as follows:
     <screen>
      $a = ~12.3 [11 +- 5] # center and width of the domain is given

      $b = ~12.3 [ +- 5] # if the center of the domain is not specified, 
                         # current value of the variable is used
     </screen>
     If the domain is not specified, the value of
     <parameter class="option">variable-domain-percent</parameter>
     option is used
     (domain is +/- value-of-variable * value-of-the-option / 100)
    </para>
   </section>
   <section>
    <title>Function types and functions</title>
    <para>
     Let us go back to functions. Function types have names that start
     with upper case letter, e.g. Linear or Voigt. Functions 
     (i.e. function instances) have names prefixed with a percent symbol,
     e.g. %func. Every function has a type and variables bound to its
     parameters. 
    </para>
    <para>
     To see a list of available function types, use the command 
     <command>info types</command>. 
     You can also use the command
     <command>info <replaceable>typename</replaceable></command>, 
     e.g. <userinput>info Pearson7</userinput> to see the names of the parameters,
     default values and formulae.
    </para>
    <para>
     Functions can be created by giving the type and the correct
     number of comma-separated variables in brackets, e.g.
     <userinput>%f = Gaussian(~66254., ~24.7, ~0.264)</userinput>
     or
     <userinput>%f = Gaussian(~6e4, $ctr, $b+$c)</userinput>.
     Every expression which is valid on the right-hand side of a variable
     assignment, can also be used as a variable.
     If it is not simply a name of a variable, an automatic variable is created.
     In the last example two variables are created (value 60000 and the sum).
    </para>
    <para>
     The second way is to give named parameters of a function, in any order, e.g.
     <userinput>%f = Gaussian(height=~66254., hwhm=~0.264, center=~24.7)
     </userinput>
     Function types can can have specified default values for
     some parameters, so this assignment is also valid:
     <userinput>
     %f = Pearson7(height=~66254., center=~24.7, fwhm=~0.264)
     </userinput>,
     although the shape parameter of Pearson7 is not given.
    </para>
    <para>
     A deep copy of function (i.e. all variables that it depends on
     are also copied) can be made using the command 
     <command>
      <replaceable>%function</replaceable>
      =copy(<replaceable>%anotherfunction</replaceable>)
     </command>
    </para>
    <para>
     Functions can be also created with the command <command>guess</command>,
     as described in <xref linkend="guess"/>.
    </para>
    <para>
     You can change a variable bound to any of the function parameters
     in this manner:
     <screen>
      =-> %f = Pearson7(height=~66254., center=~24.7, fwhm=~0.264)
      New function %f was created.
      =-> %f[center]=~24.8
      =-> $h = ~66254
      =-> %f[height]=$h
      =-> info %f
      %f = Pearson7($h, $_5, $_3, $_4)
      =-> $h = ~60000 # variables are kept by name, so this also changes %f
      =-> %p1[center] = %p2[center] + 3 # keep fixed distance between %p1 and %p2
     </screen>
    </para>
    <para>
     Functions can be deleted using the command 
     <command>delete <replaceable>%function</replaceable></command>.
    </para>
   </section> 

   <section id="udf">
    <title>Used-defined functions (UDF)</title>
    <para>
     User-defined function types can be created using command 
     <command>define</command>, and then used in the same way as built-in
     functions. The name of new type must start with an upper-case
     letter, contain only letters and digits, have at least two characters
     and must not be the same as the name of built-in function.
     Defined functions can be undefined using command 
     <command>undefine</command>.
    </para>
    <para>
     The name of a UDF should be followed by parameters in brackets 
     (see examples). Names of parameters should contain only 
     lower-case alphanumeric characters and the underscore (_), and start
     with lowercase letter. The name "x" is reserved, do not put it
     into parameter list, 
     just use it on the right-hand side of the definition.
    </para>
    <para>
     Each parameter can have a specified default value.
     To allow adding a peak with the command <command>guess</command>,
     the default value is given as an expression which can then be calculated
     for a known "height", "center", "fwhm" and "area".
     If the name itself is one of the following: "height", "center", "fwhm, 
     "area" or "hwhm", default value is deduced (in case of "hwhm" it is
     "fwhm/2").
    </para>
    <para>
     UDFs can be defined either by giving a full formula, 
     or as a sum or modification of already defined functions.
     Hopefully the examples below will make the syntax clear. 
    </para>
    <para>
     How it works (you can skip this paragraph): the formula is parsed, 
     derivatives of the formula are calculated symbolically,
     all expressions are simplified (but there is a lot of space for 
     optimization here), bytecode is created for a kind of virtual machine,
     and when fitting, the VM calculates the value of the function
     and derivatives for every point. Common Subexpression Elimination
     is not implemented yet, I suppose it will noticeably speed up UDFs.
    </para>
    <para>
     Hint: use the <filename>init</filename> file for often-used definitions.
     See <xref linkend="invoking"/> for details.
    </para>
    <para>
     Examples:
     <screen>     
     # first how some built-in functions could be defined
     define MyGaussian(height, center, hwhm) = height*exp(-ln(2)*((x-center)/hwhm)^2)
     define MyLorentzian(height, center, hwhm) = height/(1+((x-center)/hwhm)^2)
     define MyCubic(a0=height,a1=0, a2=0, a3=0) = a0 + a1*x + a2*x^2 + a3*x^3

     # supersonic beam arrival time distribution
     define SuBeArTiDi(c, s, v0, dv) = c*(s/x)^3*exp(-(((s/x)-v0)/dv)^2)/x
     

     # area-based Gaussian can be defined as modification of built-in Gaussian
     # (it is the same as built-in GaussianA function)
     define GaussianArea(area, center, hwhm) = Gaussian(area/fwhm/sqrt(pi*ln(2)), center, hwhm) 

     # sum of Gaussian and Lorentzian (also known as PseudoVoigt)
     define GLSum(height, center, hwhm, shape) = Gaussian(height*(1-shape), center, hwhm) + Lorentzian(height*shape, center, hwhm)

     # to change definition of UDF, first undefine previous definition
     undefine GaussianArea
     </screen>     
    </para>
   </section> 


   <section>
    <title>Speed of computations</title>
    <para>
     With default settings, the value of every function is calculated
     at every point. Functions such as Gaussian often have non-neglectible
     values only in a small fraction of all points. To speed up the calculation,
     set the option
     <parameter class="option">cut-function-level</parameter> 
     to a non-zero value. For each function the range with values
     greater than
     <parameter class="option">cut-function-level</parameter> 
     will be estimated, and all values outside of this range are
     considered to be equal zero.
     Note that not all functions support this optimization.
    </para>
   </section> 
   <section>
    <title>Sum, F and Z</title>
    <para>
     As already discussed, each dataset has a separate sum. i.e. a model
     that can be fitted to the data. 
     As can be seen from the <link linkend="sumintro">formula above</link>,
     the sum consists of functions f<subscript>i</subscript> 
     and z<subscript>i</subscript>. Each dataset has two sets named F and Z,
     containing the names of the functions.
     The sum is constructed by specifying which functions are in F and which in Z.
    </para>
    <para>
     In many cases Z can safely be ignored. The fitted curve is thus the sum of all
     functions in F. These functions can be listed with  
     <command>info F</command>.
    </para>
    <para>
     Command 
     <command><replaceable>%function</replaceable> -&gt; F</command>
     puts <replaceable>%function</replaceable> into F,
     command 
     <command><replaceable>%function</replaceable> -&gt; Z</command>
     puts <replaceable>%function</replaceable> into Z,
     and command 
     <command><replaceable>%function</replaceable> -&gt; N</command>
     removes <replaceable>%function</replaceable> from F or Z.
     If there is more than one dataset, F, Z and N must be prefixed
     with the dataset number, e.g.
     <command>
      <replaceable>%function</replaceable> -&gt; <replaceable>@1</replaceable>.F
     </command>
     or
     <command>
      <replaceable>%function</replaceable> -&gt; <replaceable>@0</replaceable>.N
     </command>.
     The following syntax is also valid:
     <screen>
  # create and add funtion to F
  %g = Gaussian(height=~66254., hwhm=~0.264, center=~24.7) -> @0.F
  # create automatically named funtion and add it to F
  Gaussian(height=~66254., hwhm=~0.264, center=~24.7) -> @0.F
  # clear F
  @0.F = 0
  # clear F and put three functions in it
  @0.F = %a, %b, %c
  # make @1.F the exact (shallow) copy of @0.F
  @1.F = @0.F
  # make @1.F a deep copy of @0.F (all functions and variables
  # are duplicated).
  @1.F = copy(@0.F) </screen>
    </para>
    <para>
     The sum can be exported as data points, using the syntax described in
     <xref linkend="dexport"/>,  or as mathematical formulae,
     using the command <command>info formula in @<replaceable>n</replaceable> &gt; <replaceable>filename</replaceable></command>. Some primitive simplifications
     are applied to the formula. To prevent it, put plus sign (+)
     after "info".
     Peak parameters can be exported using the command
     <command>info peaks in @<replaceable>n</replaceable> &gt; <replaceable>filename</replaceable></command>. Put the plus sign (+) after "info" to also export 
     symmetric errors of the parameters. "@*" will export formulae or parameters
     used in all datasets to the same file. 
    </para>
    <para>
    </para>
    <para>
     It is often required to keep the width or shape of peaks constant
     for all peaks in the dataset. To change the variables bound to parameters
     with a given name for all functions in F, use the command:
     <command>
      F[<replaceable>param</replaceable>]=<replaceable>variable</replaceable>
     </command>. Examples:
     <screen>
  F[hwhm]=$foo # hwhm's of all functions in F that have parameter hwhm will be 
               # equal to $foo. (hwhm here means half-width-at-half-maximum)
  F[shape]=%_1[shape]  # variable bound to shape of peak %_1 is bound
                       # also to shapes of all functions in F
  F[hwhm]=~0.2  # For every function in F a new variable is created and bound 
                # to parameter hwhm. All parameters are independent. </screen>
    </para>
   </section> 
   <section id="guess">
    <title>Guessing peak location </title>
    <para>
     It is possible to guess peak location and add it to F with the command:
     <command>
      <replaceable>%name</replaceable> =
      guess <replaceable>PeakType</replaceable>
      [<replaceable>x1</replaceable>:<replaceable>x2</replaceable>]
      in @<replaceable>n</replaceable>
     </command>, 
     e.g. <userinput>guess Gaussian [22.1:30.5] in @0</userinput>.
     If the range is omitted, the whole dataset will be searched.
     Name of the function is optional. Some of parameters can be specified
     with syntax 
     <replaceable>parameter</replaceable>=<replaceable>variable</replaceable>,
     e.g. <userinput>guess PseudoVoigt [22.1:30.5] center=$ctr, shape=~0.3 in @0</userinput>.
    </para>
    <para>
     Fityk offers only a primitive algorithm for peak-detection. 
     It looks for the highest point in a given range, and than tries to find the 
     width of the peak. 
    </para>
    <para>
     If the highest point is found near the boundary
     of the given range, it is very probable that it is not the peak top,
     and, if <link linkend="settings">the option</link> 
     <parameter class="option">can-cancel-guess</parameter> 
     is set to true, the guess is cancelled.
    </para>
    <para>
     There are two real-number options related to <command>guess</command>: 
     <parameter class="option">height-correction</parameter> and 
     <parameter class="option">width-correction</parameter>. 
     The default value of them is 1.
     The guessed height and width are multiplied by the values of these
     options respectively.
    </para>
   </section> 
   <section>
    <title>Displaying information </title>
    <para>
     If you are using the GUI, most of the available information can be displayed 
     with mouse clicks. Alternatively, you can use the <command>info</command>
     command. Using <command>info+</command> instead of <command>info</command>
     sometimes displays more verbose information.
     Command 
     <command>info guess <replaceable>range</replaceable></command>
     will show where the <command>guess</command> command would find a peak, if it were run.
     <command>info functions</command> lists all defined functions,
     and <command>info variables</command>, all variables.
     <command>info @<replaceable>n</replaceable>.F</command> 
     and <command>info @<replaceable>n</replaceable>.Z</command> show 
     information about F and Z, 
     <command>info formula in @<replaceable>n</replaceable></command>
     shows the mathematical formulae of the fitted functions,
     and 
     <command>
      info @<replaceable>n</replaceable>.dF(<replaceable>x</replaceable>)
     </command>
     compares the symbolic and numerical derivatives in <replaceable>x</replaceable>
     (useful for debugging).
    </para>
   </section> 
  </section>

  <section>
   <title>Fitting </title>
   <section id="nonlinear">
    <title>Nonlinear optimization </title>
    <para>
     This is the core. We have a set of observations (data points), 
     to which we want to fit a <firstterm>model</firstterm> (or sum of functions) 
     that depends on adjustable parameters. 
     Let me quote <citetitle pubwork="book">Numerical Recipes</citetitle>, 
     chapter 15.0, page 656 (if you do not know the book, visit 
     <ulink url="http://www.nr.com">http://www.nr.com </ulink>):
    </para>
    <blockquote>
     <para>
      The basic approach in all cases is usually the same: You choose or design
      a figure-of-merit function (merit function, for short) that measures the
      agreement between the data and the model with a particular choice of
      parameters. The merit function is conventionally arranged so that small
      values represent close agreement. The parameters of the model are then
      adjusted to achieve a minimum in the merit function, yielding best-fit
      parameters.  The adjustment process is thus a problem in minimization in
      many dimensions.  [...] however, there exist special, more
      efficient, methods that are specific to modeling, and we will discuss
      these in this chapter. There are important issues that go beyond the mere
      finding of best-fit parameters. Data are generally not exact. They are
      subject to measurement errors (called noise in the context of
      signal-processing). Thus, typical data never exactly fit the model that
      is being used, even when that model is correct. We need the means to
      assess whether or not the model is appropriate, that is, we need to test
      the goodness-of-fit against some useful statistical standard. We usually
      also need to know the accuracy with which parameters are determined by
      the data set.  In other words, we need to know the likely errors of the
      best-fit parameters. Finally, it is not uncommon in fitting data to
      discover that the merit function is not unimodal, with a single minimum.
      In some cases, we may be interested in global rather than local
      questions. Not, "how good is this fit?" but rather, "how
      sure am I that there is not a very much better fit in some corner of
      parameter space?"
     </para>
    </blockquote>
    <para>
     Our function of merit is <acronym>WSSR</acronym> - the weighted sum of
     squared residuals, also called chi-square:
     <informalequation>
      <mediaobject>
       <imageobject>
        <imagedata fileref="fitykhelp_img/chi2.png"/>
       </imageobject>
       <textobject>
        <phrase>
         chi<superscript>2</superscript> 
         = sum<subscript>i=1</subscript><superscript>N</superscript>
         [(y<subscript>i</subscript> - y(x<subscript>i</subscript>;a))
         /sigma<subscript>i</subscript>]<superscript>2</superscript>
         = sum<subscript>i=1</subscript><superscript>N</superscript>
         w<superscript>i</superscript>
         [y<subscript>i</subscript> - y(x<subscript>i</subscript>;a)]
         <superscript>2</superscript>
        </phrase>
       </textobject>
      </mediaobject>  
     </informalequation>
     Weights are based on standard deviations, 
     <inlineequation>
      <inlinemediaobject>
       <imageobject>
        <imagedata fileref="fitykhelp_img/w_1_sigma.png"/>
       </imageobject>
       <textobject>
        <phrase>w<subscript>i</subscript>=1/sigma^2</phrase>
       </textobject>
      </inlinemediaobject>  
     </inlineequation>.
     You can learn why squares of residuals are
     minimized e.g. from chapter 15.1 of 
     <citetitle pubwork="book">Numerical Recipes</citetitle>. So we
     are looking for a global minimum of chi<superscript>2</superscript>. 
     This field of numerical research (looking for a minimum or maximum)
     is usually called optimization; it is non-linear and global optimization. 
     <application>Fityk</application> implements
     three very different optimization methods. All are well-known and
     described in many standard textbooks. 
    </para>
   </section>

   <section>
    <title>Fitting related commands </title>
    <para>
     To fit sum to data, use command
     <cmdsynopsis>
      <command>fit</command> 
      <arg>+</arg> 
      <arg><replaceable>number-of-iterations</replaceable></arg> 
      <arg>in <replaceable>@n, ...</replaceable></arg> 
     </cmdsynopsis>
     The plus sign (+) prevents initialization of the fitting method.
     It is used to continue the previous fitting where it left off. 

     All non-linear fitting methods are iterative. 
     <replaceable>number-of-iterations</replaceable> 
     is the maximum number of iterations. There are also other 
     stopping criteria, so that the number of executed iterations can be smaller.
    </para>
    <para>
     Fitting methods can be set using the set command:
     <command>set fitting-method = <replaceable>method</replaceable></command>,
     where method is one of: Levenberg-Marquardt, Nelder-Mead-simplex,
     Genetic-Algorithms.
    </para>
    <para>
     All non-linear fitting methods are iterative, and there are two common
     stopping criteria. The first is the number of iterations and can be 
     specified after the <userinput>fit</userinput> command. 
     The second is the number of evaluations of the objective function 
     (<acronym>WSSR</acronym>), specified by the value of option 
     <parameter class="option">max-wssr-evaluations</parameter> (0=unlimited). 
     It is approximately proportional to time of computations, because most of
     time in fitting process is taken by evaluating <acronym>WSSR</acronym>. 
     There are also other criteria, different for each method. 
    </para>
    <para>
     If you give too small <replaceable>n</replaceable> 
     to <command>fit</command> command, and fit is stopped because of
     it, not because of convergence, it makes sense to use 
     <command>fit+</command> command to process further iterations. 
     [TODO: how to stop fit interactively] 
    </para>
    <para>
     Setting <userinput>set autoplot = on-fit-iteration</userinput>
     will draw a plot after every iteration, to visualize progress. 
     (see <link linkend="autoplot">
      <parameter class="option">autoplot</parameter></link>)
    </para>
    <para>
     Information about goodness-of-fit can be displayed using
     <userinput>info fit</userinput>. To see symmetric errors
     use <userinput>info errors</userinput>, 
     and <userinput>info+ errors</userinput> additionally shows the  
     variance-covariance matrix.
    </para>
    <para>
     Available methods can be mixed together, e.g. it is
     sensible to obtain initial parameter estimates using the Simplex method,
     and then fit it using Levenberg-Marquardt. 
     Command <command>s.history</command> can
     be useful for trying various methods with different options and/or
     initial parameters and choosing the best solution.
    </para>
   </section>

   <section>
    <title>Levenberg-Marquardt </title>
    <para>
     This is a standard nonlinear least-squares routine, and involves
     computing the first derivatives of functions. 
     For a description of the L-M method
     see <citetitle pubwork="book">Numerical Recipes</citetitle>, chapter 15.5 
     or Siegmund Brandt <citetitle pubwork="book">Data Analysis</citetitle>,
     chapter 10.15. 
     Essentially, it combines an
     inverse-Hessian method with a steepest descent
     method by introducing a lambda factor. When lambda is equal to 0, the method is
     equivalent to the inverse-Hessian method. When lambda increases, the shift
     vector is rotated toward the direction of steepest descent and the length
     of the shift vector decreases. (The shift vector is a vector that is added
     to the parameter vector.) If a better fit is found on iteration, lambda
     is decreased - it is divided by the value of 
     <parameter class="option">lm-lambda-down-factor</parameter> option 
     (default: 10). Otherwise, lambda is multiplied by the value of 
     <parameter class="option">lm-lambda-up-factor</parameter> (default: 10). 
     The initial lambda value is equal to
     <parameter class="option">lm-lambda-start</parameter> (default: 0.0001). 
    </para>
    <para>
     The Marquardt method has two stopping criteria other than the common 
     criteria. If it happens twice in sequence, that the relative 
     change of the value of the objective function (<acronym>WSSR</acronym>) 
     is smaller then the value of the 
     <parameter class="option">lm-stop-rel-change</parameter> option, the
     fit is considered to have converged and is stopped. 
     Additionally, if lambda is greater than the value of the 
     <parameter class="option">lm-max-lambda</parameter> option 
     (default: 10^15),
     - usually when due to limited numerical precision 
     WSSR is no longer changing, the fitting is also stopped.
    </para>
    <!--
    <para>
     L-M method finds a minimum quickly. The question is, if it is the
     global minimum.  It can be a good idea to add a small random vector to
     the vector of parameters and try again. This small shift vector is added, 
     when value of <parameter class="option">shake-before</parameter> option 
     is positive (by default it is 0). Value of every parameter's shift 
     is independent and randomly drawn from distribution of type specified by
     value of <parameter class="option">shake-type</parameter> option 
     (see <link linkend="distribtype">option 
      <parameter class="option">distrib-type</parameter></link>)
     in simplex method). The expected value of parameter shift is
     directly proportional to both value of 
     <parameter class="option">shake-before</parameter> option and width of
     parameter's domain.
    </para>
    -->
   </section>

   <section>
    <title>Nelder-Mead downhill simplex method </title>
    <para>
     To quote chapter 4.8.3, p. 86 of Peter Gans
     <citetitle>
      Data Fitting in the Chemical Sciences by the Method of Least Squares 
     </citetitle> 
    </para>
    <blockquote>
     <para>
      A simplex is a geometrical entity that has n+1 vertices corresponding to
      variations in n parameters.  For two parameters the simplex is a
      triangle, for three parameters the simplex is a tetrahedron and so forth.
      The value of the objective function is calculated at each of the
      vertices. An iteration consists of the following process. Locate the
      vertex with the highest value of the objective function and replace this
      vertex by one lying on the line between it and the centroid of the other
      vertices. Four possible replacements can be considered, which I call
      contraction, short reflection, reflection and expansion.[...]
     </para>
     <para>
      It starts with an arbitrary simplex. Neither the shape nor position of
      this are critically important, except insofar as it may determine which
      one of a set of multiple minima will be reached. The simplex than expands
      and contracts as required in order to locate a valley if one exists. Then
      the size and shape of the simplex is adjusted so that progress may be
      made towards the minimum. Note particularly that if a pair of
      parameters are highly correlated, <emphasis>both</emphasis> will be
      simultaneously adjusted in about the correct proportion, as the shape of
      the simplex is adapted to the local contours.[...]
     </para>
     <para>
      Unfortunately it does not provide estimates of the parameter errors, etc.
      It is therefore to be recommended as a method for obtaining initial
      parameter estimates that can be used in the standard least squares
      method.
     </para>
    </blockquote>
    <para>
     This method is also described in previously mentioned 
     <citetitle>Numerical Recipes</citetitle> (chapter 10.4) 
     and <citetitle>Data Analysis</citetitle> (chapter 10.8).
    </para>
    <para>
     <note>
      <para>
       The rest of this chapter is outdated,
       At this moment default settings of the fitting methods can't be changed.
       This will be fixed as soon as possible.
      </para>
     </note>
    </para>
    <para>
     There are a few options for tuning this method.
     One of these is a stopping criterium 
     <parameter class="option">min-fract-range</parameter>. If the value of the
     expression 2(M-m)/(M+m), where M and m are the values of the worst and best
     vertices respectively (values of objective functions of vertices, to be
     precise!), is smaller then the value of 
     <parameter class="option">min-fract-range</parameter> option, fitting is
     stopped. In other words, fitting is stopped if all vertices are almost at the
     same level.
    </para>
    <para id="distribtype">
     The remaining options are related to initialization of the simplex. Before
     starting iterations, we have to choose a set of points in space of the 
     parameters, called vertices.  Unless the option 
     <parameter class="option">move-all</parameter> is set, one of these
     points will be the current point - values that parameters have at this
     moment. All but this one are drawn as follows: each parameter of each
     vertex is drawn separately. It is drawn from a distribution that has its center
     in the center of the domain of the parameter, and a width proportional to both width of
     the domain and value of the <parameter class="option">move-multiplier</parameter> 
     parameter.  Distribution type can be set using the option 
     <parameter class="option">distrib-type</parameter> as one
     of: uniform, Gaussian, Lorentzian and bound. The last one causes the value of the
     parameter to be either the greatest or smallest value in the domain of the parameter 
     - one of two bounds of the domain 
     (assuming that <parameter class="option">move-multiplier</parameter>
     is equal 1).
    </para>
   </section>

   <section>
    <title>Genetic Algorithms</title>
    <para>
     [TODO]
    </para>
   </section>
  </section> 

  <section id="settings">
   <title>Settings </title>
   <para>
    This chapter is not about GUI settings (things like colors,
    fonts, etc.), but about settings that are common for both CLI and GUI
    version.
   </para>
   <para>
    Command <command>info set</command> shows the syntax of the set command
    and lists all possible options. 
    <command>set <replaceable>option</replaceable></command> 
    shows the current value of the <replaceable>option</replaceable>, 
    and set 
    <command>
     <replaceable>option</replaceable> = <replaceable>value</replaceable>
    </command>
    changes it. It is also possible to change the value of the option for 
    one command only by prepending the command with 
    <command>with
     <replaceable>option</replaceable> = <replaceable>value</replaceable>
    </command>. The examples at the end of this chapter should clarify this.
   </para>
   <para>
    Some fitting methods and functions, such as <function>randnormal</function>
    in data expressions use a pseudo-random number generator. 
    In some situations
    one may want to have repeatable and predictable results of the fitting, e.g.
    to make a presentation. Seed for a new sequence of pseudo-random
    numbers can be set using the option
    <parameter class="option">pseudo-random-seed</parameter>.
    If it is set to 0, the seed is based on the current time and a sequence of
    pseudo-random numbers is different each time. 
   </para>
   <para>
    [TODO: the rest of options...] 
   </para>
   <para>
    Examples:
    <screen>
     set fitting-method  # show info
     set fitting-method = Nelder-Mead-simplex # change default method
     set verbosity = verbose
     with fitting-method = Levenberg-Marquardt fit 10 
     with fitting-method=Levenberg-Marquardt, verbosity=only-warnings fit 10
    </screen>
   </para>
  </section> 

  <section>
   <title>Other commands </title>
   <section>
    <title>plot: viewing data</title>
    <para>
     In the GUI version there is hardly ever a need to use this command directly.
    </para>
    <para>
     The command <command>plot</command> controls visualization of data 
     and the sum.
     It is used to plot a given area - in <acronym>GUI</acronym> it is plotted
     in the program's main window, in <acronym>CLI</acronym> the popular program 
     <application>gnuplot</application> is used, if available. 
     <cmdsynopsis>
      <command>plot</command> 
      <arg><replaceable>xrange</replaceable>
       <arg><replaceable>yrange</replaceable></arg>
      </arg> 
     </cmdsynopsis>
     <replaceable>xrange</replaceable> and <replaceable>yrange</replaceable>
     have one of two following syntaxes:
     <cmdsynopsis>
      <arg choice="req">[</arg> <arg><replaceable>min</replaceable></arg>
      <arg choice="plain">:</arg>
      <arg><replaceable>max</replaceable></arg> <arg choice="req">]</arg>
     </cmdsynopsis>
     <cmdsynopsis>
      <arg choice="plain">.</arg>
     </cmdsynopsis>
     The second is just a dot (.), and it implies that the appropriate range is not to be changed.
    </para>
    <para>
     Examples:
     <screen>
   plot [20.4:50] [10:20] # show x from 20.4 to 50 and y from 10 to 20

   plot [20.4:] # x from 20.4 to the end, 
                # y range will be adjusted to encompass all data

   plot . [:10] # x range will not be changed, y from the lowest point to 10 
   plot [:] [:] # all data will be shown   
   plot         # all data will be shown   
   plot . .     # nothing changes
     </screen>
    </para>

    <para id="autoplot">
     The value of the option <parameter class="option">autoplot</parameter> changes the
     automatic plotting behaviour. By default, the plot is refreshed automatically 
     after changing the data or the sum of functions.  
     It is also possible to visualize each iteration of the fitting method by
     replotting the peaks after every iteration.
    </para>
   </section>
   <section>
    <title>info: show informations</title>
    <para>
     First, there is an option 
     <parameter class="option">verbosity</parameter>
     (not related to command <command>info</command>)
     which sets the amount of messages displayed when executing commands.
    </para>
    <para>
     If you are using the GUI, most information can be displayed 
     with mouse clicks. Alternatively, you can use the <command>info</command>
     command. Using the <command>info+</command> instead of <command>info</command>
     sometimes displays more detailed information.
    </para>
    <para>
     The output of <command>info</command> can be redirected to file
     using 
     <command>
      info <replaceable>args</replaceable> &gt; 
      <replaceable>filename</replaceable>
     </command>
     syntax to truncate the file or
     <command>
      info <replaceable>args</replaceable> &gt;&gt;
      <replaceable>filename</replaceable>
     </command>
     to append to the file.
    </para>
    <para>
     The following arguments are recognized:
     <simplelist>
      <member>variables</member>
      <member><replaceable>$variable_name</replaceable></member>
      <member>types</member>
      <member><replaceable>TypeName</replaceable></member>
      <member>functions</member>
      <member><replaceable>%function_name</replaceable></member>
      <member>datasets</member>
      <member><replaceable>@dataset_number</replaceable></member>
      <member>commands</member>
      <member>commands [n:m]</member>
      <member>view</member>
      <member>set</member>
      <member>fit [in @<replaceable>n</replaceable>]</member>
      <member>errors [in @<replaceable>n</replaceable>]</member>
      <member>formula [in @<replaceable>n</replaceable>]</member>
      <member>peaks [in @<replaceable>n</replaceable>]</member>
      <member>guess [x-range] [in @<replaceable>n</replaceable>]</member>
      <member><replaceable>data-expression</replaceable> [in @<replaceable>n</replaceable>]</member>
      <member>[@<replaceable>n</replaceable>.]F</member>
      <member>[@<replaceable>n</replaceable>.]Z</member>
      <member>[@<replaceable>n</replaceable>.]dF(<replaceable>data-expression</replaceable>)</member>
      <member>der <replaceable>mathematic-function</replaceable></member>
     </simplelist>
    </para>
    <para>
     <command>info der</command> shows derivatives of given function.
     <screen>
      =-> info der sin(a) + 3*exp(b/a)
      f(a, b) = sin(a)+3*exp(b/a)
      df / d a = cos(a)-3*exp(b/a)*b/a^2
      df / d b = 3*exp(b/a)/a
     </screen>
    </para>
   </section>
   <section>
    <title>commands, dump, sleep, reset, quit</title>
    <para>
     All commands given during program execution are stored in memory.
     They can be listed using the command:
     <command>
      info commands [<replaceable>n</replaceable>:<replaceable>m</replaceable>]
     </command> 
     or written to file: 
     <command>
      commands [<replaceable>n</replaceable>:<replaceable>m</replaceable>]
      &gt; <replaceable>filename</replaceable>
     </command>. 
     To put all commands executed so far during the session into the 
     file <filename>foo.fit</filename>, type 
     <userinput>commands[:] > foo.fit</userinput>.
     With the plus sign (+) (i.e.
     <command>
      info commands+ [<replaceable>n</replaceable>:<replaceable>m</replaceable>]
     </command> 
     and
     <command>
      commands+ [<replaceable>n</replaceable>:<replaceable>m</replaceable>]
      &gt; <replaceable>filename</replaceable>)
     </command> information about the exit status of each command will be added. 
    </para>
    <para>
     To log commands to a file when they are executed, use:
     <command>
      commands &gt; <replaceable>filename</replaceable>
     </command> or, to log also the output:
     <command>
      commands+ &gt; <replaceable>filename</replaceable>
     </command>.
     To stop logging, use: <command> commands &gt; /dev/null </command>.
    </para>
    <para>
     Scripts can be executed using the command:
     <command>
      commands &lt; <replaceable>filename</replaceable>
     </command>.
    </para>
    <para>
     There is also a command
     <command>dump &gt; <replaceable>filename</replaceable></command>,
     [TODO] which is not working at this moment.
    </para>
    <para>
     Command <command>sleep <replaceable>sec</replaceable></command> 
     makes the program wait <replaceable>sec</replaceable> seconds,
     before continuing. 
    </para>
    <para>
     The command <command>quit</command> works as expected. 
     If this command is found in a script it will close the program as well.
    </para>
    <para>
     If the option <parameter class="option">exit-on-warning</parameter> 
     is set, any warning will also close the program. 
     This ensures that no warnings can be overlooked.
    </para>
   </section> 
  </section> 
 </chapter>


 <chapter id="useandextend">
  <title>Using and extending </title>
  <section id="usecases">
   <title>Use cases</title>
   <para>
    [TODO]
   </para>
  </section> 
  <section id="extensions">
   <title>Extensions</title>
   <section>
    <title>How to add your own built-in function</title>
    <para>
     To add a built-in function, you have to change the source of the program
     and then recompile it. Users who want to do this should be able to compile
     the program from source and know the basics of C, C++ or another programming
     language.
    </para>
    <para>
     The description that follows is not complete. If something is not clear,
     you can always send me e-mail, etc.
    </para>
    <para>
     "fp" you can see in fityk source means a real (floating point) number 
     (typedef double fp).
    </para>
    <para>
     The name of your function should start with uppercase letter and contain
     only letters and digits.  Let us add function Foo with the formula: 
     Foo(height, center, hwhm) = height/(1+((x-center)/hwhm)^2).
     C++ class representing Foo will be named FuncFoo.
    </para>
    <para>
     In src/func.cpp you will find a list of functions: 
     <screen>     
       ...
       FACTORY_FUNC(Polynomial6)
       FACTORY_FUNC(Gaussian)
       ...
      </screen>     
     Now, add:
     <screen>     
       FACTORY_FUNC(Foo)
      </screen>     

     Then find another list:
     <screen>     
       ...
       FuncPolynomial6::formula,
       FuncGaussian::formula,
       ...
      </screen>     
     and add the line
     <screen>     
      FuncFoo::formula,
     </screen>     
     Note that in the second list
     all items but the last are followed by comma.
    </para>
    <para>
     Write the function formula in the same file in this way:
     <screen>     
      const char *FuncFoo::formula
      = "Foo(height, center, hwhm) = height/(1+((x-center)/hwhm)^2)";
     </screen>     
     The syntax of the formula is the same as that of 
     the <link linkend="udf">UDF</link>, but 
     for built-in functions only the left hand side of the formula is parsed.
    </para>
    <para>
     In the file <filename>src/bfunc.h</filename> you can now begin writing the definition 
     of your class:
     <screen>
      class FuncFoo : public Function
      {
          DECLARE_FUNC_OBLIGATORY_METHODS(Foo)
     </screen>
     If you want to make some calculations every time parameters of the function
     are changed, you can do it in method do_precomputations.
     This possibility is provided for calculating expressions,
     which do not depend on x. Write the declaration here:
     <screen>
     void do_precomputations(std::vector&lt;Variable*&gt; const &amp;variables);
     </screen>
     and provide a proper definition of this method 
     in <filename>src/bfunc.cpp</filename>.
    </para>
    <para>
     If you want to optimize the calculation of your function by neglecting
     its value outside of a given range 
     (see option <parameter class="option">cut-function-level</parameter> 
     in the program),
     you will need to use the method:
     <screen>
      bool get_nonzero_range (fp level, fp &amp;left, fp &amp;right) const;
     </screen>
     This method takes the level below which the value of the function
     can be approximated by zero, and should set the left and right variables
     to proper values of x, 
     such that if x&lt;left or x&gt;right than |f(x)|&lt;level. 
     If the function sets left and right, it should return true.
    </para>
    <para>
     If your function does not have a "center" parameter, and there is a 
     center-like point where you want the peak top to be drawn, write:
     <screen>
      bool has_center() const { return true; }
      fp center() const { return vv[1]; }
     </screen>
     In the second line, between return and the semicolon, there is an expression
     for the x coordinate of peak top; vv[0] is the first parameter of function,
     vv[1] is the second, etc.
    </para>
    <para>
     Finally, close the definition of the class with:
     <screen>
      };
     </screen>
    </para>
    <para>
     Write in <filename>src/bfunc.cpp</filename>
     how to calculate the value of the function:
     <screen>
      FUNC_CALCULATE_VALUE_BEGIN(Foo)
          fp xa1a2 = (x - vv[1]) / vv[2];
          fp inv_denomin = 1. / (1 + xa1a2 * xa1a2);
      FUNC_CALCULATE_VALUE_END(vv[0] * inv_denomin)
     </screen>
     The expression at the end (i.e. vv[0]*inv_denomin) is the calculated value.
     xa1xa2 and inv_denomin are variables introduced to simplify the
     expression. Note the "fp" (you can also use "double") at the beginning
     and semicolon at the end of both lines. The meaning of vv has  
     already been explained.

     Usually it is more difficult to calculate derivatives:

     <screen>
      FUNC_CALCULATE_VALUE_DERIV_BEGIN(Foo)
          fp xa1a2 = (x - vv[1]) / vv[2];
          fp inv_denomin = 1. / (1 + xa1a2 * xa1a2);
          dy_dv[0] = inv_denomin;
          fp dcenter = 2 * vv[0] * xa1a2 / vv[2] * inv_denomin * inv_denomin;
          dy_dv[1] = dcenter;
          dy_dv[2] = dcenter * xa1a2;
          dy_dx = -dcenter;
      FUNC_CALCULATE_VALUE_DERIV_END(vv[0] * inv_denomin)
     </screen>

     You must set derivatives 
     dy_dv[n] for n=0,1,...,(number of parameters of your function - 1)
     and dy_dx. In the last brackets there is a value of the function again.
    </para>
    <para>
     After compilation of the program check if the derivatives are calculated 
     correctly using command "info dF(x)", e.g. i dF(30.1).
     You can also use <function>numarea</function>, 
     <function>findx</function> and <function>extremum</function> 
     (see <xref linkend="funcindt"/> for details) 
     to verify center, area, height and FWHM properties.
    </para>
    <para>
     Hope this helps.
     Do not hesistate to change this description or ask questions 
     if you have any.
    </para>
   </section>
  </section> 
 </chapter>

 <appendix id="flist">
  <title>List of functions</title>
  <para>

   The list of all functions can be obtained using 
   <userinput>i+ types</userinput>. Some formulae here have long parameter
   names (like "height", "center" and "hwhm") replaced with 
   a<subscript><replaceable>i</replaceable></subscript>.

   <equation id="gaussian">
    <title>Gaussian</title>
    <mediaobject>
     <imageobject>
      <imagedata fileref="fitykhelp_img/gaussian.png"/>
     </imageobject>
     <textobject>
      <phrase> 
       Type in program "info Gaussian" to see the formula.
      </phrase>
     </textobject>
    </mediaobject>  
   </equation>

   <equation id="splitgaussian">
    <title>SplitGaussian</title>
    <mediaobject>
     <imageobject>
      <imagedata fileref="fitykhelp_img/splitgaussian.png"/>
     </imageobject>
     <textobject>
      <phrase> 
       Type in program "info SplitGaussian" to see the formula.
      </phrase>
     </textobject>
    </mediaobject>  
   </equation>

   <equation id="gaussiana">
    <title>GaussianA</title>
    <mediaobject>
     <imageobject>
      <imagedata fileref="fitykhelp_img/gaussiana.png"/>
     </imageobject>
     <textobject>
      <phrase> 
       Type in program "info GaussianA" to see the formula.
      </phrase>
     </textobject>
    </mediaobject>  
   </equation>

   <equation id="lorentzian">
    <title>Lorentzian</title>
    <mediaobject>
     <imageobject>
      <imagedata fileref="fitykhelp_img/lorentzian.png"/>
     </imageobject>
     <textobject>
      <phrase> 
       Type in program "info Lorentzian" to see the formula.
      </phrase>
     </textobject>
    </mediaobject>  
   </equation>

   <equation id="lorentziana">
    <title>LorentzianA</title>
    <mediaobject>
     <imageobject>
      <imagedata fileref="fitykhelp_img/lorentziana.png"/>
     </imageobject>
     <textobject>
      <phrase> 
       Type in program "info LorentzianA" to see the formula.
      </phrase>
     </textobject>
    </mediaobject>  
   </equation>

   <equation id="pearson7">
    <title>Pearson VII (Pearson7)</title>
    <mediaobject>
     <imageobject>
      <imagedata fileref="fitykhelp_img/pearson7.png"/>
     </imageobject>
     <textobject>
      <phrase> 
       Type in program "info Pearson7" to see the formula.
      </phrase>
     </textobject>
    </mediaobject>  
   </equation>

   <equation id="splitpearson7">
    <title>Split-Pearson-VII (SplitPearson7)</title>
    <mediaobject>
     <imageobject>
      <imagedata fileref="fitykhelp_img/splitpearson7.png"/>
     </imageobject>
     <textobject>
      <phrase> 
       Type in program "info SplitPearson7" to see the formula.
      </phrase>
     </textobject>
    </mediaobject>  
   </equation>

   <equation id="pearson7a">
    <title>Pearson-VII-Area (Pearson7A)</title>
    <mediaobject>
     <imageobject>
      <imagedata fileref="fitykhelp_img/pearson7a.png"/>
     </imageobject>
     <textobject>
      <phrase> 
       Type in program "info Pearson7A" to see the formula.
      </phrase>
     </textobject>
    </mediaobject>  
   </equation>

   <equation id="psvoigt">
    <title>Pseudo-Voigt (PseudoVoigt)</title>
    <mediaobject>
     <imageobject>
      <imagedata fileref="fitykhelp_img/pseudo_voigt.png"/>
     </imageobject>
     <textobject>
      <phrase> 
       Type in program "info PseudoVoigt" to see the formula.
      </phrase>
     </textobject>
    </mediaobject>  
   </equation>
   Pseudo-Voigt is a name given to the sum of Gaussian and Lorentzian.
   a<subscript>3</subscript> parameters in Pearson VII and Pseudo-Voigt 
   are not related.

   <equation id="psvoigta">
    <title>Pseudo-Voigt-Area (PseudoVoigtA)</title>
    <mediaobject>
     <imageobject>
      <imagedata fileref="fitykhelp_img/pseudo_voigta.png"/>
     </imageobject>
     <textobject>
      <phrase> 
       Type in program "info PseudoVoigtA" to see the formula.
      </phrase>
     </textobject>
    </mediaobject>  
   </equation>

   <equation id="voigt">
    <title>Voigt</title>
    <mediaobject>
     <imageobject>
      <imagedata fileref="fitykhelp_img/voigt.png"/>
     </imageobject>
     <textobject>
      <phrase> 
       Type in program "info Voigt" to see the formula.
      </phrase>
     </textobject>
    </mediaobject>  
   </equation>
   The Voigt function is a convolution of Gaussian and Lorentzian functions.
   a<subscript>0</subscript> = heigth,
   a<subscript>1</subscript> = center,
   a<subscript>2</subscript> is proportional to the Gaussian width, and
   a<subscript>3</subscript> is proportional to the ratio of Lorentzian 
   and Gaussian widths. 
   Voigt is computed according to R.J.Wells, 
   <citetitle pubwork="article">
    Rapid approximation to the Voigt/Faddeeva function and its derivatives
   </citetitle>, 
   Journal of Quantitative Spectroscopy &amp; Radiative Transfer 
   62 (1999) 29-48.
   (See also: http://www.atm.ox.ac.uk/user/wells/voigt.html).
   Is the approximation exact enough for all possible uses of 
   <application>fityk</application> program? 

   <equation id="voigta">
    <title>VoigtA</title>
    <mediaobject>
     <imageobject>
      <imagedata fileref="fitykhelp_img/voigta.png"/>
     </imageobject>
     <textobject>
      <phrase> 
       Type in program "info VoigtA" to see the formula.
      </phrase>
     </textobject>
    </mediaobject>  
   </equation>

   <equation id="emg">
    <title>Exponentially Modified Gaussian (EMG)</title>
    <mediaobject>
     <imageobject>
      <imagedata fileref="fitykhelp_img/emg.png"/>
     </imageobject>
     <textobject>
      <phrase> 
       Type in program "info EMG" to see the formula.
      </phrase>
     </textobject>
    </mediaobject>  
   </equation>

   <equation id="doniachs">
    <title>Doniach-Sunjic (DoniachSunjic)</title>
    <mediaobject>
     <imageobject>
      <imagedata fileref="fitykhelp_img/doniachs.png"/>
     </imageobject>
     <textobject>
      <phrase> 
       Type in program "info DoniachSunjic" to see the formula.
      </phrase>
     </textobject>
    </mediaobject>  
   </equation>

   <equation>
    <title>Polynomial5</title>
    <mediaobject>
     <imageobject>
      <imagedata fileref="fitykhelp_img/polynom5.png"/>
     </imageobject>
     <textobject>
      <phrase> 
       Type in program "info Polynomial5" to see the formula.
      </phrase>
     </textobject>
    </mediaobject>  
   </equation>

  </para>
 </appendix>

 <appendix id="shortenings">
  <title>Command shortenings</title>
  <para>
   The pipe symbol (|) shows the minimum length of the command. "def|ine" means
   that the shortest version is "def", but "defi", "defin" and "define" 
   are also valid and mean exactly the same. 
   Arguments of "info" command can not be shortened,
   i.e. you must write "i fit", not "i f". Commands which cannot be shortened
   are not listed here.
   <simplelist>
    <member><command>c|ommands</command></member> 
    <member><command>def|ine  </command></member> 
    <member><command>f|it     </command></member> 
    <member><command>g|uess   </command></member> 
    <member><command>i|nfo    </command></member> 
    <member><command>p|lot    </command></member> 
    <member><command>s|et     </command></member> 
    <member><command>undef|ine</command></member> 
    <member><command>w|ith    </command></member> 
   </simplelist>
  </para>
 </appendix>

 <appendix id="license">
  <title>License</title>
  <para>
   <application>Fityk</application> is free software; you can redistribute
   and modify it under terms of GNU General Public License,
   version 2. There is no warranty. 
   <acronym>GPL</acronym> is one of the most popular
   licenses, and it is worth reading if you have not done so
   before. The program is copyrighted by the author, and the license
   itself by the <acronym>FSF</acronym>. 
   Text of the license is distributed with the program 
   in the file <filename>COPYING</filename>.
  </para>
 </appendix> 

 <appendix>
  <title>About this manual </title>
  <para>
   This manual is written in DocBook (XML)
   and converted to other formats. All changes, improvements,
   fixes of mistakes, etc. are welcome. 
   The <filename>fitykhelp.xml</filename> file is
   distributed with the program sources, and can be modified with any
   text editor. 
  </para>
  <para>
   The author would like to thank people who have helped to improve this
   manual (in chronological order): Stan Gierlotka, Jaap Folmer, 
   Michael Richardson.
  </para>
 </appendix> 

 <bibliography> 
  <biblioentry> 
   <abbrev>1</abbrev>
   <authorgroup>
    <author>
     <surname>Press</surname>  <firstname>William</firstname>
    </author>
    <author>
     <surname>Teukolsky</surname> <firstname>Saul</firstname>
    </author>
    <author>
     <surname>Vetterling</surname> <firstname>William</firstname>
    </author>
    <author>
     <surname>Flannery</surname> <firstname>Brian</firstname>
    </author>
   </authorgroup>
   <title>Numerical Recipes in C</title>
   <address><otheraddr>http://www.nr.com</otheraddr></address>
  </biblioentry>
  <biblioentry> 
   <abbrev>2</abbrev>
   <author>
    <surname>Gans</surname> <firstname>Peter</firstname>
   </author>
   <title>
    Data Fitting in the Chemical Sciences by the Method of Least Squares
   </title>
   <publishername>John Wiley &amp; Sons</publishername>
   <pubdate>1992</pubdate>
  </biblioentry> 
  <biblioentry>
   <abbrev>3</abbrev>
   <author><firstname>Siegmund</firstname><surname>Brandt</surname></author>
   <title>Data Analysis</title>
   <publishername>Springer Verlag</publishername>
   <pubdate>1999</pubdate>
  </biblioentry>
  <biblioentry>
   <abbrev>4</abbrev>
   <title>PeakFit 4.0 for Windows User's Manual</title>
   <publishername>AISN Software</publishername>
   <pubdate>1997</pubdate>
  </biblioentry>
  <biblioentry>
   <abbrev>5</abbrev>
   <author>
    <firstname>Zbigniew</firstname><surname>Michalewicz</surname>
   </author>
   <title>Algorytmy genetyczne + struktury danych = programy ewolucyjne</title>
   <publishername>WNT</publishername>
   <pubdate>1996</pubdate>
  </biblioentry>
<!--
  <biblioentry>
   <abbrev>6</abbrev>
   <editor><firstname>R. A.</firstname><surname>Young</surname></editor>
   <title>The Rietveld Method</title>
   <publishername>Oxford University Press</publishername>
   <pubdate>1993</pubdate>
  </biblioentry>
  <biblioentry>
   <abbrev>7</abbrev>
   <author><firstname>R. A.</firstname><surname>Young</surname></author>
   <title>User's Guide to Program DBWS-9807a</title>
   <pubdate>2000</pubdate>
  </biblioentry>
-->
 </bibliography>

</book>
<!-- vim: set ai sw=1 expandtab:  -->