<?xml version="1.0" ?>
<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.1-Based Variant V1.0//EN"
"dtd/kdex.dtd" [
<!ENTITY kapp "<application>KSetiSpy</application>">
<!ENTITY % addindex "IGNORE">
<!ENTITY % English "INCLUDE">
]>
<book lang="&language;">
<bookinfo>
<title>The KSetiSpy Handbook</title>
<authorgroup>
<author>
<firstname>Roberto</firstname>
<othername>A.</othername>
<surname>Virga</surname>
<affiliation>
<address><email>rvirga@users.sourceforge.net</email></address>
</affiliation>
</author>
</authorgroup>
<copyright>
<year>2003</year>
<holder>Roberto A. Virga</holder>
</copyright>
<legalnotice>&FDLNotice;</legalnotice>
<date>20/9/2003</date>
<releaseinfo>0.06.00</releaseinfo>
<abstract>
<para>
&kapp; is a <ulink url="http://setiathome.ssl.berkeley.edu/">SETI@home</ulink>
add-on application. It monitors the progress of the SETI@home client, and
reports various information about the data being computed. It provides roughly
the same interface as
<ulink url="http://cox-internet.com/setispy/">SETI Spy</ulink>, a Windows
program written by Roelof J. Engelbrecht.
</para>
</abstract>
<keywordset>
<keyword>KDE</keyword>
<keyword>monitoring</keyword>
<keyword>astronomy</keyword>
<keyword>seti</keyword>
<keyword>distributed computing</keyword>
</keywordset>
</bookinfo>
<chapter id="introduction">
<title>Introduction</title>
<para>
The SETI@home project started in May 1999; its goal is to harness the power of
distributed computing to analyze radio signals from space, for "the small but
captivating possibility of detecting the faint murmur of a civilization beyond
Earth". To participate in this exciting project, all you have to do is to
run the SETI@home client program. This program downloads a set of data
(usually called "work unit") from the SETI@home servers, processes it on the
local machine (using idle processing time that would otherwise go wasted), and
then transmits the result back to the servers.
</para>
<para>
Over time, SETI@home participants people have become more and more
interested in learning everything about the data contained in these work
units and the computations done on them. To address these needs, several
SETI@home monitoring add-on programs were developed. These extract
interesting information from the SETI@home client and present it in a
user-friendly way.
</para>
<para>
One of the most complete SETI@home monitoring tools available today is a
Windows program named <ulink url="http://cox-internet.com/setispy/">SETI
Spy</ulink>. &kapp; has been created with the intent of providing a version
of SETI Spy for my favorite desktop environment (KDE). &kapp; borrows most
of its user interface conventions from SETI Spy, so SETI Spy users
will feel immediately at home with &kapp;.
</para>
<para>
&kapp; started as a programming experiment in KDE in June 2001, and has
grown a lot since then, mainly to keep up with the ever-increasing feature
set of its Windows counterpart. Like many open source projects, it's
basically the work of a single developer (that would be me), working on it
on his spare time. Therefore advancement is not linear, and debugging is
mostly left to the users (that would be you). If you run into a bug,
please report it to Roberto Virga <email>rvirga@users.sourceforge.net</email>.
</para>
<para>
Thanks for using my little program! I hope you'll find it useful.
</para>
</chapter>
<chapter id="getting-started">
<title>Getting Started with &kapp;</title>
<para>
First of all, in order to participate in SETI@home, you must download
and install the client program, if you haven't done so already. You can get
it from the
<ulink url="http://setiathome.ssl.berkeley.edu/download.html">download
page</ulink> of SETI@home site.
</para>
<para>
The first time you'll run the client, it will ask you for the e-mail address
associated with your account. If you don't have an account, the client will
allow you to register for one by providing a (valid) e-mail address.
</para>
<para>
In what follows, it is assumed that you already have done this. To make
the presentation more understandable, I'll furthermore assume that the
directory containing the SETI@home client is
<userinput>/home/rvirga/SETI@home/</userinput>, and that the email address
associated with the account is
<userinput>rvirga@users.sourceforge.net</userinput>. Replace these values with
the ones you used in your setup.
</para>
<para>
The next step is to actually install &kapp;. Several distributions already
include &kapp;, so it might be on your computer, or easily installable from
your distribution's CD. If your distribution doesn't bundle &kapp;, or if the
version they include is out of date, you will find instructions on how to
install &kapp; in the
<link linkend="installation">the installation chapter</link>.
</para>
<para>
The installation should create an icon in the KDE menu, so that you should
be able to launch &kapp; using your mouse. However, if you can't find an
icon, you can always launch the program by typing
<userinput>ksetispy &</userinput> (followed by a carriage return) in a
command shell.
</para>
<para>
The first time you run &kapp;, you'll be presented with a window like this:
<screenshot>
<mediaobject>
<imageobject>
<imagedata fileref="setup1.png" format="PNG"/>
</imageobject>
</mediaobject>
</screenshot>
</para>
<para>
You'll need to create a new profile that contains enough information to
allow &kapp; to run the SETI@home client.
</para>
<para>
Click on <guibutton>Add...</guibutton>. The following dialog will appear:
<screenshot>
<mediaobject>
<imageobject>
<imagedata fileref="profile1.png" format="PNG"/>
</imageobject>
</mediaobject>
</screenshot>
</para>
<para>
Choose a name for this profile; for example, "My Profile".
</para>
<para>Next, you need to tell &kapp; which directory contains all the SETI@home
files (these are a bunch of files, all ending in <filename>.sah</filename>
that the SETI@home client creates when it runs. You can type the path of
this directory in the <guilabel>Files location</guilabel> field; Alternatively,
you can click the browse button next to it, browse with the mouse to that
directory (this second method is probably easier).
</para>
<para>You'll also need to tell &kapp; where to find the client application,
by filling the <guilabel>Client location</guilabel> field. Do this in a
similar way to what you did for the <guilabel>File location</guilabel>,
but this time selecting a file (the SETI@home client file) instead of
a directory.
</para>
<para>
Finally, you'll need to type the e-mail address you used to register to
SETI@home in the <guilabel>User e-mail</guilabel> field.
</para>
<para>
All done. You can click <guibutton>OK</guibutton> now to create the profile.
There are a lot of other <link linkend="profile-dialog">parameters you can
modify</link>, but setting them is not mandatory, as &kapp; offers reasonable
defaults. Moreover, you can always change them later by editing the profile
you just created.
</para>
</chapter>
<chapter id="commands">
<title>Command Reference</title>
<sect1 id="mainwindow">
<title>The main &kapp; window</title>
<para>
<screenshot>
<mediaobject>
<imageobject>
<imagedata fileref="main.png" format="PNG"/>
</imageobject>
</mediaobject>
</screenshot>
</para>
<para>
The main window of &kapp; contains two elements: a toolbar and a panel. The
toolbar allows you to select which panel you want to see: each button
corresponds to a different panel. By default, it is located on the left,
and it displays both names and icons of the panels. However, you can change
both its position and its look by right-clicking on it and choosing from
the pop-up menu that will appear.
</para>
<para>
Each panel has a header containing its name and icon. Below the header, there
is the content area. Typically, you'll be able to copy the content area to
the clipboard by right-clicking on it and choosing
<guimenuitem>Copy to clipboard</guimenuitem>.
</para>
<sect2 id="mainwindow-progress">
<title>The Progress panel</title>
<para>
<screenshot>
<mediaobject>
<imageobject>
<imagedata fileref="progress.png" format="PNG"/>
</imageobject>
</mediaobject>
</screenshot>
</para>
<para>
This panel reports on the progress of the computation. Therefore, it will be
most useful when the client is running; otherwise, the majority of
its content will be set to <guilabel>unknown</guilabel>.
</para>
<para>
Here is a brief explanation of the fields it contains:
</para>
<variablelist>
<varlistentry>
<term><guilabel>CPU time</guilabel></term>
<listitem>
<para>
The time the client has been processing the current work unit. This counts
the time spent analyzing the work unit, not the time elapsed since the
analysis started. That is, if for example we run the client for 2 hours,
then stop it, wait 8 hours, and resume the computation, the CPU time reported
would be 2 hours, not 10.
</para><para></para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Estimated total time</guilabel></term>
<listitem>
<para>
An estimate of the total computing time required to complete the current work
unit.
</para><para></para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Speed</guilabel></term>
<listitem>
<para>
The average speed, measured in <link linkend="flops">MegaFLOPS</link>.
</para><para></para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Estimated time left</guilabel></term>
<listitem>
<para>
An estimate of the computing time required to complete the work unit. This is
can be obtained as the difference between
<guilabel>Estimated total time</guilabel>
and
<guilabel>CPU time</guilabel>.
</para><para></para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Rate</guilabel></term>
<listitem>
<para>
The (average) speed of the client, measured as the percentage of work unit it
processes every hour.
</para><para></para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Estimated time done</guilabel></term>
<listitem>
<para>
An estimate of the time by which, at the current speed, the analysis will be
done. Typically, this will be a time of the day, in the format specified by
the system locale setting. If it exceeds 24 hours, there will be a "(+n)"
suffix to indicate the number of days.
</para><para></para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Efficiency</guilabel></term>
<listitem>
<para>
Average efficiency of the CPU, measured in <link linkend="cpf">CpF</link>.
</para><para></para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Drift rate</guilabel></term>
<listitem>
<para>
The drift rate currently being analyzed. For SETI@home version 3.08, this is a
value ranging between -50 and +50.
</para><para></para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Completed</guilabel></term>
<listitem>
<para>
Percentage of the work unit that has already been processed.
</para><para></para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>FFT number</guilabel></term>
<listitem>
<para>
Number of <link linkend="fft">FFTs</link> computed so far. In SETI@home
version 3.08, processing a work unit involves performing about 31,560 FFTs.
</para><para></para>
</listitem>
</varlistentry>
</variablelist>
</sect2>
<sect2 id="mainwindow-performance">
<title>The Performance panel</title>
<para>
<screenshot>
<mediaobject>
<imageobject>
<imagedata fileref="performance.png" format="PNG"/>
</imageobject>
</mediaobject>
</screenshot>
</para>
<para>
This panel measures the performance of the SETI@home client.
Therefore, the data presented will be meaningful only when the client is
running. Otherwise, most fields will have a <guilabel>unknown</guilabel> value.
</para>
<para>
Performance can be measured instantaneously (i.e. the current speed will be
reported) or averaged over all the time spent so far analyzing the current
work unit. Instantaneous performance is computed by comparing
the last two consecutive measurements, so it might take a minute or two after
you launch client application before &kapp; has enough data to provide
meaningful values.
</para>
<para>
A brief description of the fields follows:
<variablelist>
<varlistentry>
<term><guilabel>Processing rate</guilabel></term>
<listitem>
<para>
The processing rate, presented both as the number of hours necessary to
complete the work unit and as the percentage of work unit that is processed
each hour.
</para><para></para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Processing speed</guilabel></term>
<listitem>
<para>
The processing speed in <link linkend="flops">MegaFLOPS</link>.
</para><para></para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Processing efficiency</guilabel></term>
<listitem>
<para>
The average number of CPU cycles necessary to complete an elementary floating
point operation (<link linkend="cpf">CpF</link>).
</para><para></para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Floating point operations to process</guilabel></term>
<listitem>
<para>
The total number of <link linkend="flop">FLOPs</link> required to process this
work unit. In version 3.08 of the client, it takes approximately from 3.3 to
4.5 TeraFLOPs to complete a work unit.
</para><para></para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
Pressing the <guibutton>Compare</guibutton> button opens the
<link linkend="cpf-window">Peak Processing Efficiency window</link>.
</para>
</sect2>
<sect2 id="mainwindow-results">
<title>The Results panel</title>
<para>
<screenshot>
<mediaobject>
<imageobject>
<imagedata fileref="results.png" format="PNG"/>
</imageobject>
</mediaobject>
</screenshot>
</para>
<para>
This panel summarizes the signals found so far by plotting them in a
two-dimensional diagram. The x-axis expresses the drift rate. For SETI@home
version 3.08, drift rates have values ranging from -50 to +50. A vertical red
bar indicates the current drift rate. This will move back and forth during the
processing of the work unit.
</para>
<para>
The y-axis measures the strength of the signal. Signals in the black area are
considered completely uninteresting, and will not be reported back to the
SETI@home servers. Signals in the blue zone may be of some significance, and
will be returned to the servers for further consideration.
<note>
<para>
Just because a signal is returned to the servers, don't break out the
champagne and announce to the world you found proof of extra-terrestrial
intelligence! First of all, most work units have returned signals, so this is
not an unusual occurrence. But even if you encounter a signal whose strength
stands out over all the signals you've ever come across, still chances are
that this comes from terrestrial radio interference rather than from an
extra-terrestrial civilization.
</para>
</note>
</para>
<para>
The <guibutton>View Log</guibutton> and <guibutton>Details</guibutton> buttons
open the the <link linkend="wu_log-window">Log</link> and
<link linkend="results_details-window">Results Details</link> windows,
respectively.
</para>
</sect2>
<sect2 id="mainwindow-wu">
<title>The Work Unit panel</title>
<para>
<screenshot>
<mediaobject>
<imageobject>
<imagedata fileref="wu.png" format="PNG"/>
</imageobject>
</mediaobject>
</screenshot>
</para>
<para>
The fields in this panel report information about the origin of the data
stored in the current work unit. They are:
</para>
<para>
<variablelist>
<varlistentry>
<term><guilabel>Work unit name</guilabel></term>
<listitem>
<para>
The unique ID that SETI@home uses to identify the work unit.
</para><para></para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Recorded</guilabel></term>
<listitem>
<para>
Day and time the data contained in this work unit was recorded.
</para><para></para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Position</guilabel></term>
<listitem>
<para>
Position in the sky, given as Right Ascension (RA), Declination (Dec), and
Angle Range (AR).
</para><para></para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Nearest constellation</guilabel></term>
<listitem>
<para>
Name and 3-letter symbol of the closest constellation. Clicking on the link,
you can get more information on the specific constellation.
</para><para></para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Source</guilabel></term>
<listitem>
<para>
Radio telescope that collected the data. Currently, this is always Arecibo. By
clicking on the link, you can visit the Arecibo web site.
</para><para></para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Base frequency</guilabel></term>
<listitem>
<para>
Base of the frequency slice examined in this work unit.
</para><para></para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
Pressing the <guibutton>Sky Map</guibutton> button opens the
<link linkend="skymap-window">Sky Map window</link>.
</para>
</sect2>
<sect2 id="mainwindow-user">
<title>The User Statistics panel</title>
<para>
<screenshot>
<mediaobject>
<imageobject>
<imagedata fileref="user.png" format="PNG"/>
</imageobject>
</mediaobject>
</screenshot>
</para>
<para>
Much of the information presented in this panel cannot be computed by just
looking at the local files. Instead, it must first be retrieved from the
SETI@home web site. This can be done by pressing the
<guibutton>Update</guibutton> button.
</para>
<para>
The fields contained in this panel are:
<variablelist>
<varlistentry>
<term><guilabel>User</guilabel></term>
<listitem>
<para>
The user name handle. If there is an email address known for this user, this
name will be a link, and clicking over it will open the SETI@home account
stats page associated to that address.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Registered</guilabel></term>
<listitem>
<para>
Date in which the current SETI@home account was created. This is a link to the
registration class page (i.e. the page containing a list of all other users
that registered that day).
</para><para></para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Results returned</guilabel></term>
<listitem>
<para>
Number of completed work units that have been returned to SETI@home under
this account. If you have been awarded any certificate, this will be a link
to the latest certificate awarded.
</para><para></para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Total CPU time</guilabel></term>
<listitem>
<para>
Total time dedicated by this user to processing work units.
</para><para></para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Result interval</guilabel></term>
<listitem>
<para>
Average time elapsed between two consecutive work units are completed and
their results returned to the servers.
</para><para></para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Avg. CPU time</guilabel></term>
<listitem>
<para>
CPU time to process a work unit, averaged over all the work units completed so
far.
</para><para></para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>CPU dedication</guilabel></term>
<listitem>
<para>
Average of the number of CPUs (computers) the user is using to process work
units.
</para><para></para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Environment</guilabel></term>
<listitem>
<para>
Environment in which your computer operates. If known, this is one of three
possible values: home, school, or work. In this case, a link to a page
containing the top 1000 users with your environment is also provided.
</para>
<para>
Information about your environment was entered by you when you registered with
SETI@home.
</para>
<para></para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Country</guilabel></term>
<listitem>
<para>
Country in which you're located (this too was entered by you during the
registration process). Clicking on this link brings up a web page listing the
top 1000 users of your country.
</para><para></para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Rank</guilabel></term>
<listitem>
<para>
Rank of the user, measured in terms of number of completed work units returned.
</para><para></para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
Clicking the <guibutton>Calendar</guibutton> button will open the
<link linkend="wu_calendar-window">Calendar window</link>.
</para>
<note>
<para>
In most situations, &kapp; should be able to download the extra user
information quickly and without problems each time you click on the
<guibutton>Update</guibutton> button. In case something goes wrong, however,
this can be usually tracked down to one or more of the following things:
<itemizedlist>
<listitem>
<para>Internet connection</para>
<para>
Check that you're connected to the internet. If you are behind a firewall that
uses a HTTP proxy server, check <application>Konqueror</application>'s
settings and make sure that the proxy name and port are correctly set. As a
rule of thumb, if you can browse the web using Konqueror, &kapp; should also be
able to retrieve the information it needs from the web server.
</para>
<para>
</para>
</listitem>
<listitem>
<para>The SETI@home stats web server</para>
<para>
The web server &kapp; uses for the connection is the one specified in the
<guimenu>User Data</guimenu> panel of the
<link linkend="stats-servers">Statistics Servers Setup dialog</link>.
Try to browse that web site with <application>Konqueror</application>
(or any web browser you normally use). If you cannot browse it, it might be
the case that the SETI@home web server is down, or that you're trying to
connect to the wrong web server.
</para>
<para>
</para>
</listitem>
<listitem>
<para>E-mail address</para>
<para>
In order to locate your account statistics, SETI@home needs the e-mail address
you used when you created that account. If &kapp; doesn't know that address,
it can't download the information. If this is the case, you should see your
name in the <guilabel>User</guilabel> field to be static text instead of an
link, and the <guibutton>Update</guibutton> grayed out.
If you're using the cache, you need to fill that address in the
<link linkend="cache-setup">Cache Setup dialog</link>; if you're not using
the cache, <link linkend="mainwindow-setup-profiles">edit the current
profile</link> instead.
</para>
</listitem>
</itemizedlist>
</para>
</note>
</sect2>
<sect2 id="mainwindow-group">
<title>The Group Statistics panel</title>
<para>
<screenshot>
<mediaobject>
<imageobject>
<imagedata fileref="group.png" format="PNG"/>
</imageobject>
</mediaobject>
</screenshot>
</para>
<para>
Much like as for <link linkend="mainwindow-user">User Statistics</link>, the
information presented in this panel has to be retrieved from the SETI@home
statistics web server. Hence the troubleshooting tips listed before for the
User Stats panel also apply here.
</para>
<para>
SETI@home allows single users to form teams. The information presented in
this panel relate to the user's team. If you do not belong to any team,
most of the fields will have value <guilabel>unknown</guilabel>.
</para>
<para>
Some of the fields of these panel can be computed by a single lookup to
the statistics servers, and hence they will be computed each time you
will press the <guibutton>Update</guibutton> button. They are:
<variablelist>
<varlistentry>
<term><guilabel>Group</guilabel></term>
<listitem>
<para>
Name of the team you belong to, and link to a web page containing your
team's statistics.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Results returned</guilabel></term>
<listitem>
<para>
Number of completed work units that have been returned to SETI@home by members
of this team.
</para><para></para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Total CPU time</guilabel></term>
<listitem>
<para>
Total time spent by members of this team crunching work units.
</para><para></para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Avg. CPU time</guilabel></term>
<listitem>
<para>
Average time needed to process a work unit by members of this team.
</para><para></para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Founder</guilabel></term>
<listitem>
<para>
The founder of this group.
</para><para></para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Members</guilabel></term>
<listitem>
<para>
The number of SETI@home who are currently members of this group.
</para><para></para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
Other fields show information that requires at least two consecutive
measurements. Therefore, these may not appear immediately after you start
using &kapp;, but will eventually appear after a few days of use. They are:
<variablelist>
<varlistentry>
<term><guilabel>Results per day</guilabel></term>
<listitem>
<para>
An estimate of the number of completed work units that are returned each
day by members of this team.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>CPUs</guilabel></term>
<listitem>
<para>
The number of CPUs from members of this group 100% dedicated on processing
work units, and their average frequency.
</para><para></para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Speed</guilabel></term>
<listitem>
<para>
The speed at which the group is processing data, measured in
<link linkend="flops">FLOPS</link>.
</para><para></para>
</listitem>
</varlistentry>
</variablelist>
</para>
</sect2>
<sect2 id="mainwindow-client">
<title>The Client panel</title>
<para>
<screenshot>
<mediaobject>
<imageobject>
<imagedata fileref="client.png" format="PNG"/>
</imageobject>
</mediaobject>
</screenshot>
</para>
<para>
Here we present some data about the SETI@home client, and the system
(i.e. memory, OS) on which it runs. This information is organized in the
following fields:
<variablelist>
<varlistentry>
<term><guilabel>SETI@home client</guilabel></term>
<listitem>
<para>
The version of the SETI@home client.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>URL</guilabel></term>
<listitem>
<para>
Location of the SETI@home files.
</para><para></para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Operating system</guilabel></term>
<listitem>
<para>
The operating system of the machine. For Linux, this will typically list the
kernel version, and possibly the maker of the distribution.
</para><para></para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Physical memory size</guilabel></term>
<listitem>
<para>
The amount of physical memory (in KB, MB or GB) installed in the machine.
</para><para></para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Swap space size</guilabel></term>
<listitem>
<para>
The amount of virtual memory (in KB, MB or GB).
</para><para></para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
You can start the client by pressing <guibutton>Start</guibutton> (if it's not
running), and stop it pressing <guibutton>Stop</guibutton> (if it is). In
order for this button to work, however, you need first to fill out the client
location (and command line arguments, if any) in the
<link linkend="profile-setup">Profile configuration dialog</link>.
</para>
</sect2>
<sect2 id="mainwindow-processor">
<title>The Processor panel</title>
<para>
<screenshot>
<mediaobject>
<imageobject>
<imagedata fileref="processor.png" format="PNG"/>
</imageobject>
</mediaobject>
</screenshot>
</para>
<para>
This panel reports some information about the processor running SETI@home.
This is by default the processor (or processors) of the machine &kapp; is
running, but <link linkend="advanced-custom-sysinfo">can be changed</link> if you use
&kapp; to monitor clients running remotely.
</para>
<para>
It contains a pop-up menu that allows you to select the CPU you're interested
in. Admittedly, this is not very useful on computers with just one processor,
or homogeneous (all the processors have the same characteristics)
multiprocessor machines, but has been included for generality.
</para>
<para>
The panel also contains the following fields:
<variablelist>
<varlistentry>
<term><guilabel>CPU type</guilabel></term>
<listitem>
<para>
The name of the CPU. This typically includes the manufacturer's name (for
example: Intel), the CPU family and model (for example: Pentium III), and
possibly the codename (for example: Katmai). This information might prove
useful when looking at the
<link linkend="cpf-window">Peak Processing Efficiency window</link>
or
<link linkend="profile-calibration">choosing the right calibration</link>.
</para><para></para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>CPU speed</guilabel></term>
<listitem>
<para>
The speed in MHz of the processor.
</para><para></para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Cache</guilabel></term>
<listitem>
<para>
The size (in KB or MB) of the CPU's (or sometimes motherboard's) cache.
</para><para></para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>BogoMIPS</guilabel></term>
<listitem>
<para>
MIPS is an acronym for Millions of Instructions Per Second. It is used to
indicate the speed of a CPU, and can be considered the integer equivalent of
<link linkend="flops">MegaFLOPS</link>.
</para><para></para>
<para>
However, BogoMIPS are not MIPS, although the two are (very loosely) related.
This is a measure Linus Torvalds came up with, and measures the number of
times the CPU executes one particular loop in the Linux kernel in one second.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</sect2>
<sect2 id="mainwindow-cache">
<title>The Work Unit Cache panel</title>
<para>
<screenshot>
<mediaobject>
<imageobject>
<imagedata fileref="cache.png" format="PNG"/>
</imageobject>
</mediaobject>
</screenshot>
</para>
<para>
Here you will find information about the work unit cache management system.
The following fields are displayed:
<variablelist>
<varlistentry>
<term><guilabel>Location</guilabel></term>
<listitem>
<para>
The complete path of the directory containing the cache.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Capacity</guilabel></term>
<listitem>
<para>
The maximum number of work units the cache will download from the server.
</para><para></para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Available</guilabel></term>
<listitem>
<para>
The number of work units that have been downloaded and await to be processed.
</para><para></para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Done</guilabel></term>
<listitem>
<para>
The number of work units that have been completed and whose results still need
to be uploaded into the servers.
</para><para></para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Last download</guilabel></term>
<listitem>
<para>
The date and time of the last successful work unit download (if any).
</para><para></para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Last upload</guilabel></term>
<listitem>
<para>
The date and time of the last successful result upload (if any).
</para><para></para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Next download</guilabel></term>
<listitem>
<para>
The date and time of the next scheduled work unit download (if any).
</para><para></para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Next upload</guilabel></term>
<listitem>
<para>
The date and time of the next scheduled result upload (if any).
</para><para></para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
The <guibutton>Setup...</guibutton> button will bring up the
<link linkend="cache-setup">Cache Setup dialog</link>, allowing you to set up
the cache or modify some of its parameters. The
<guibutton>Show Log</guibutton> button will open the
<link linkend="connection-log">Connection Log window</link>, where you will be
able to see the input/output of the most recent connection.
</para>
<para>
For the impatient, there is a <guibutton>Connect</guibutton> button that will
start both download and upload connections to the servers (provided there is
anything to transmit or receive).
</para>
</sect2>
<sect2 id="mainwindow-setup">
<title>The Setup panel</title>
<para>
This panel controls most of &kapp;'s settings. They are grouped in three tabs.
</para>
<sect3 id="mainwindow-setup-profiles">
<title>The Profiles tab</title>
<para>
<screenshot>
<mediaobject>
<imageobject>
<imagedata fileref="setup2.png" format="PNG"/>
</imageobject>
</mediaobject>
</screenshot>
</para>
<para>
To account for the fact that one may want to monitor more than a single
SETI@home client, &kapp; allows you to define several profiles. Each profile
will point to a different SETI@home directory, and will be identified by a
unique name. However, since &kapp; is geared toward displaying information
regarding a single client at a time, the concept of "current profile" is used.
At any time, &kapp; will report data relative to the current profile only, but
at the same time you'll be able to switch the current profile with ease.
</para>
<para>
The list on the left enumerates all the profiles defined so far. The current
profile has a "(current)" suffix.
</para>
<para>
The <guibutton>Add...</guibutton> button allows you to create a new profile,
that, upon completion, will be added to the list. Pressing
<guibutton>Edit...</guibutton> you will be able to modify the profile that is
currently highlighted on the list. <guibutton>Delete</guibutton> will destroy
the highlighted profile. It will display a confirmation dialog first, so if
you pressed this button accidentally you'll be given the chance to cancel the
operation. Finally, <guibutton>Set Current</guibutton> will change the
current profile to the one that's currently highlighted.
</para>
</sect3>
<sect3 id="mainwindow-setup-display">
<title>The Display tab</title>
<para>
<screenshot>
<mediaobject>
<imageobject>
<imagedata fileref="setup3.png" format="PNG"/>
</imageobject>
</mediaobject>
</screenshot>
</para>
<para>
Three of the four checkboxes in this tab deal with the
<link linkend="tray">tray icon</link>. Checking
<guilabel>Minimize to tray</guilabel> causes &kapp; to minimize to an icon in
the system tray rather than to a taskbar button. If
<guilabel>Run in tray</guilabel> is checked, the tray icon will be visible at
all times. Finally, with <guilabel>Close to tray</guilabel> set, clicking the
close button will leave the application running in the tray; if this option is
checked, the only way to exit &kapp; will be to right-click the tray icon,
and then select <guimenuitem>Quit</guimenuitem> from the menu.
</para>
<para>
The <guilabel>Remember windows positions</guilabel> setting tells &kapp;
whether to remember the location and size of all its windows. If you change
screen resolution often, you may want to leave this unchecked, since otherwise
at lower resolutions some of the windows might end up being located off-screen.
On the other hand, if your screen resolution always stays the same, it's
probably more convenient to check this option and let &kapp; remember the
window layout you used last time.
</para>
</sect3>
<sect3 id="mainwindow-setup-stats">
<title>The User Statistics tab</title>
<para>
<screenshot>
<mediaobject>
<imageobject>
<imagedata fileref="setup4.png" format="PNG"/>
</imageobject>
</mediaobject>
</screenshot>
</para>
<para>
This tabs groups together all the settings relative to the
<link linkend="mainwindow-user">User Statistics</link> and
<link linkend="mainwindow-group">Group Statistics</link> panels.
</para>
<para>
You can have &kapp; to automatically download an up-to-date version of your
stats on startup, and/or at regular intervals (in multiples of 1 hour).
</para>
<para>
If you use the <link linkend="mainwindow-cache">cache</link>, you may want to
update automatically your user statistics after you upload your cached results.
</para>
<para>
The <guibutton>Servers...</guibutton> button opens the
<link linkend="stats-servers">Statistics Servers Setup dialog</link>, that you
can use in the (statistically unlikely, but possible) event that SETI@home
moves its statistics web servers to a different address, or changes the syntax
used to dynamically generate the stats pages.
</para>
</sect3>
</sect2>
<sect2 id="mainwindow-about">
<title>The About panel</title>
<para>
<screenshot>
<mediaobject>
<imageobject>
<imagedata fileref="about.png" format="PNG"/>
</imageobject>
</mediaobject>
</screenshot>
</para>
<para>
This panel gives you the program version, a brief description, and credits.
</para>
<para>
Pressing the <guibutton>Help</guibutton> will launch the KDE help application,
and open it to a copy of this very manual you're reading.
</para>
</sect2>
</sect1>
<sect1 id="cpf-window">
<title>The Peak Processing Efficiency window</title>
<para>
<screenshot>
<mediaobject>
<imageobject>
<imagedata fileref="cpf.png" format="PNG"/>
</imageobject>
</mediaobject>
</screenshot>
</para>
<para>
This window allows you to compare your CPU's efficiency (measured in
<link linkend="cpf">CpFs</link>) to others. The comparison table used here has
been obtained from data collected by the
<ulink url="http://www.teamlambchop.com/bench/index.htm">Team Lamb Chop
Benchmarking page</ulink>
and is provided courtesy of Roelof Engelbrecht. Please consult the
<ulink url="http://cox-internet.com/setispy/">SETI Spy web page</ulink>
for a more in-depth discussion about processor efficiency in the context of
SETI@home data processing.
</para>
<para>
The row corresponding to your CPU will be easily identifiable by the arrow
symbol on the left. The efficiency reported will be the instantaneous or
average one, depending on what you set in the
<link linkend="mainwindow-performance">Performance panel</link>.
You will be able to sort the table by clicking on the appropriate header.
Clicking on the sorting column header will toggle the sort order between
ascending and descending.
Finally, by right-clicking anywhere on the table and choosing
<guimenuitem>Copy to clipboard</guimenuitem> you will get a copy
in tab-separated values format, ready for use in any spreadsheet or word
processing application.
</para>
</sect1>
<sect1 id="wu_log-window">
<title>The Work Unit Log window</title>
<para>
<screenshot>
<mediaobject>
<imageobject>
<imagedata fileref="wu_log.png" format="PNG"/>
</imageobject>
</mediaobject>
</screenshot>
</para>
<para>
This windows presents a table whose rows correspond to the work units that
have been completed and recorded in the log file.
</para>
<para>
If you're using the SETI Spy log format, this table is a faithful reproduction
of the contents of the log file. If instead you're using the
<ulink url="http://members.home.net/mloukko/SETILog.html">SETILog</ulink>
format, this can be considered a summary of the data contained in the log (the
SETILog format is more information-rich). If you'd like to view the content of
the SETILog data in its entirety, you can use
<ulink url="http://ksetiwatch.sourceforge.net/">KSetiWatch</ulink>,
another SETI@home add-on for KDE whose functionality nicely complements
&kapp;'s own.
</para>
<para>
The log table can be sorted and copied to the clipboard, in the same way
described for the
<link linkend="cpf-window">Peak Processing Efficiency window</link>.
</para>
</sect1>
<sect1 id="results_details-window">
<title>The Results Details window</title>
<para>
<screenshot>
<mediaobject>
<imageobject>
<imagedata fileref="results_details.png" format="PNG"/>
</imageobject>
</mediaobject>
</screenshot>
</para>
<para>
There are for types of signals the SETI@home client looks for: spikes,
gaussians, pulses, and triplets. For each class, the client keeps track of the
best signal discovered so far, and also incrementally constructs a list of
signals that will be returned to the servers at the end of the analysis. This
windows tries to display as much information as possible about all these
signals.
</para>
<para>
For gaussians and pulses, a "city skyline"-style graph will be shown.
Right-clicking it, you will be given the possibility to save it to file and/or
copy it to the clipboard. You'll also be able to resize it to two pre-defined
formats: the standard
<guimenuitem>SETI@home</guimenuitem> one, or a
<guimenuitem>Default</guimenuitem> format suitable for submission to the
<ulink url="http://home.hccnet.nl/a.alfred/p-free-p1city.html">CITY@home web
site</ulink>. A menu option also allows you to open a browser window pointing
to that site.
</para>
<para>
For spikes and triplets unfortunately there's not enough information to plot a
graph. All the known data will be presented conveniently organized in a table.
</para>
</sect1>
<sect1 id="skymap-window">
<title>The Sky Map window</title>
<para>
<screenshot>
<mediaobject>
<imageobject>
<imagedata fileref="skymap.png" format="PNG"/>
</imageobject>
</mediaobject>
</screenshot>
</para>
<para>
This windows shows you the point in the sky from where the data contained in
the current work unit comes from. That point is indicated by a red pulsating
signal. You'll notice that there is a band in the picture colored with a
lighter tone of black: that segment is the portion of the sky observable by
Arecibo.
</para>
<para>
If you select <guimenuitem>Show history</guimenuitem> several more dots will
appear, corresponding to all the work units that you have processed so far and
that have been recorded in the log. These are typically drawn in red, but work
units containing interesting gaussians (a gaussian is considered interesting
if Fit < Power*1.5 + 2) are green. Moving the mouse over any of these will
display a tooltip with more information.
</para>
<sect2 id="skymap-legend">
<title>The Sky Map legend</title>
<para>
<screenshot>
<mediaobject>
<imageobject>
<imagedata fileref="skymap_legend.png" format="PNG"/>
</imageobject>
</mediaobject>
</screenshot>
</para>
<para>
The legend gives the abbreviation and name of each of the 88 constellations in
the sky. The constellation names are links to the
<ulink url="http://www.earthvisions.net/bcp/">Basic Celestial Phenomena</ulink>
web pages, which are provided courtesy of Kerry Magruder
<email>KVMagruder@mac.com</email>.
</para>
</sect2>
<sect2 id="telescope-window">
<title>The Telescope Path window</title>
<para>
<screenshot>
<mediaobject>
<imageobject>
<imagedata fileref="telescope.png" format="PNG"/>
</imageobject>
</mediaobject>
</screenshot>
</para>
<para>
This window shows the path along which the telescope moved while recording the
current work unit. As for most of other windows displaying graphics, you can
save this picture and/or copy it to the clipboard by right-clicking it and
choosing the appropriate menu
option.
</para>
</sect2>
</sect1>
<sect1 id="wu_calendar-window">
<title>The Work Unit Calendar window</title>
<para>
<screenshot>
<mediaobject>
<imageobject>
<imagedata fileref="wu_calendar.png" format="PNG"/>
</imageobject>
</mediaobject>
</screenshot>
</para>
<para>
This windows gives you an overview of your standings with respect to the
number of work units returned.
</para>
<para>
The cell corresponding to the current day, as well as those of all future
dates, will contain an estimate of the number of the work unit completed.
Adjusting the <guilabel>Work units per day</guilabel> counter to your
throughput, you can predict in which day, week and month you will reach a goal
(for example: when you'll complete 5,000 work units).
</para>
<para>
The cells corresponding to past days in which you returned work units will
have a dark red background, and the number of units returned.
</para>
</sect1>
<sect1 id="cache-setup">
<title>The Cache Setup dialog</title>
<para>
<screenshot>
<mediaobject>
<imageobject>
<imagedata fileref="cache_setup.png" format="PNG"/>
</imageobject>
</mediaobject>
</screenshot>
</para>
<para>
In January 2002 SETI@home started experiencing bandwidth-related problems. At
the time of this writing, connecting to the servers during peak hours
(8AM - 10PM PST) is often problematic. For these reasons, starting with
version 0.4.0, &kapp; offers a very sophisticated caching system, allowing you
to schedule unattended connections to the servers during off-peak hours.
</para>
<para>
Connections of the client to the servers are of two kinds: uploads and
downloads. Periodically, the client downloads a fresh new work unit to
process. Work units are very large (approx. 360 KB), and therefore they are
the main cause of bandwidth problems. After it finishes processing the current
work unit, the client also connect to upload the result of its computation.
Result files are much smaller (1-2 KB), so incoming traffic is not usually an
issue for the servers.
</para>
<para>
Recognizing the differences between these two types of connections, &kapp;
allows you to schedule them differently. You may want to download new work
units only during off-peak hours. On the other hand, if you're a "stats junkie"
(I know I am) who wants his/her profile information to be up-to-date all the
time, you can schedule result uploads throughout the day (see figure above).
</para>
<para>
In order to set up the cache, you need to provide the following data:
<variablelist>
<varlistentry>
<term><guilabel>Location</guilabel></term>
<listitem>
<para>
The location where &kapp; will store the cache files. You don't need to create
this directory beforehand: if it doesn't exist, &kapp; will create it for you.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Client</guilabel></term>
<listitem>
<para>
The full path of the SETI@home client executable you will be using.
</para><para></para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>User e-mail</guilabel></term>
<listitem>
<para>
The e-mail address you used to register to SETI@home.
</para><para></para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Capacity</guilabel></term>
<listitem>
<para>
The maximum number of work units the cache will store.
</para><para></para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Proxy server</guilabel></term>
<listitem>
<para>
If you don't use a proxy server, select <guilabel>No proxy</guilabel>. If
instead you use a regular proxy server, select <guilabel>Proxy</guilabel> and
fill the <guilabel>Host</guilabel> and <guilabel>Port</guilabel> fields.
Finally, if you have a SOCKS proxy server, you will need to provide a login
name and password too.
</para><para></para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Schedule</guilabel></term>
<listitem>
<para>
In order for &kapp; to connect automatically, you must provide a connection
schedule. You do so by specifying a set of time intervals. To connect, &kapp;
will pick a random time within the next interval. Interval selection is
describe in detail below.
</para><para></para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Download threshold</guilabel></term>
<listitem>
<para>
In order to ease the load on the servers, you may also tell the cache
management system to avoid downloading new work units until the number of
empty slots in your cache goes beyond a certain threshold.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<sect2>
<title>Interval selection</title>
<para>
There are seven controls for interval selection, one for each day of the week.
Each control displays a bar, with tags on the upper half. Major tags are
numbered from 0 to 23 and stand for hours of the day. The smaller ones are for
halves and quarters, respectively.
</para>
<para>
You create a new interval by double-clicking the lower half (below the tagged
line) of the bar. This will create a new 1-hour interval for both download and
upload. You can then proceed modifying its type, length, start and end points.
</para>
<para>
Intervals are colored according to their type:
<simplelist type='horiz' columns='2'>
<member>
<guiicon>
<inlinemediaobject>
<imageobject>
<imagedata fileref="schedule_detail3.png" />
</imageobject>
</inlinemediaobject>
</guiicon>
</member>
<member>
Download only: &kapp; will download new work units at a random time within the
interval.
</member>
<member>
<guiicon>
<inlinemediaobject>
<imageobject>
<imagedata fileref="schedule_detail4.png" format="PNG" />
</imageobject>
</inlinemediaobject>
</guiicon>
</member>
<member>
Upload only: &kapp; results for work units that have been completed will be
uploaded
to the servers.
</member>
<member>
<guiicon>
<inlinemediaobject>
<imageobject>
<imagedata fileref="schedule_detail2.png" />
</imageobject>
</inlinemediaobject>
</guiicon>
</member>
<member>
Both: a combination of both upload and download.
</member>
</simplelist>
</para>
<para>
You change the type of the interval by right-clicking the internal part of it.
This will bring up a pop-up menu that will allow you to check/uncheck download
and upload properties. Unchecking both download and upload will cause the
interval to be removed
</para>
<para>
To resize an interval, drag one of the two gray resize handles located at its
extremities:
<screenshot>
<mediaobject>
<imageobject>
<imagedata fileref="schedule_detail1.png" format="PNG"/>
</imageobject>
</mediaobject>
</screenshot>
</para>
<para>
When you grab the handle, its color will change to red and you will be able to
move it backward or forward along the line. To prevent abuses of the caching
system that would result in an increased load on the SETI@home servers, &kapp;
won't allow you to shrink an interval to less than 1 hour, thus limiting the
maximum number of different intervals in one day to 24.
</para>
<para>
You delete an interval in pretty much the same way you created it: simply
double-click on it.
</para>
</sect2>
<sect2>
<title>Carbon copy buttons</title>
<para>
In case you want to use a same schedule for more than one day of the week (or
possibly for all days in the week), &kapp; gives you "carbon copy" buttons,
which are located to the right of the interval selection control and are
marked by a double arrow pointing down. Pressing the carbon copy button
corresponding to one day causes the schedule of the previous day to be copied
over. For example, pressing the button for Tuesday causes the schedule of
Monday to be used for Tuesday too. Carbon copy buttons are cyclical, in the
sense that pressing the button for Sunday (the first day in the list) causes
the schedule for Saturday to be copied over.
</para>
</sect2>
</sect1>
<sect1 id="connection-log">
<title>The Connection Log window</title>
<para>
<screenshot>
<mediaobject>
<imageobject>
<imagedata fileref="connect.png" format="PNG"/>
</imageobject>
</mediaobject>
</screenshot>
</para>
<para>
This window shows you the input and output of the last download/upload
connection, or the current one if there's one in progress. Two radio boxes let
you switch between the two connection types
(<guilabel>Downloads</guilabel> or <guilabel>Uploads</guilabel>).
</para>
<para>
Messages about the status of the connection are printed in bold. The output
generated by the client will be printed in black, plain text, while the input
will be colored in gray.
</para>
<para>
You can abort an ongoing connection by clicking the
<guibutton>Kill Connection</guibutton>
button. Pressing this button while there's no active connection has no effect.
</para>
<para>
Finally, by right clicking anywhere in the window, a menu will pop up allowing
you to copy the current text to the clipboard.
</para>
</sect1>
<sect1 id="profile-dialog">
<title>The Profile dialog</title>
<sect2 id="profile-setup">
<title>The Setup tab</title>
<para>
<screenshot>
<mediaobject>
<imageobject>
<imagedata fileref="profile1.png" format="PNG"/>
</imageobject>
</mediaobject>
</screenshot>
</para>
<para>
Two important bits of information in a profile are the
<guilabel>Profile name</guilabel> and the <guilabel>Files location</guilabel>.
The first is a unique name, chosen by you, to identify this profile; the
second is the location of the SETI@home files.
When creating a new profile you will be asked to enter both; when editing an
existing profile, you will be able to change the first, but not the second.
</para>
<para>
Also important is the location of the SETI@home client, whose complete path
must be filled in the <guilabel>Client location</guilabel> field. You can
also provide some extra command-line arguments to be passed to the client,
for example to lower the priority at which it will run.
</para>
<para>
The <guilabel>Poll interval</guilabel> will tell &kapp; how often to check the
SETI@home files for changes. If the files haven't been changed for a period
of time exceeding <guilabel>Client idle timeout</guilabel>, &kapp; will assume
that the remote SETI@home client application has stopped running. These
parameters are meaningful for monitoring remote clients only: for local ones,
&kapp; relies on operating system functions to be notified of changes to the
SETI@home files the very same moment they happen.
</para>
<para>
Using the check boxes in the <guilabel>Process Control</guilabel> area, you can
set up &kapp; so that it will launch the client when it starts up. You
can can also tell it to keep the client running at all time, restarting it if
necessary.
</para>
<para>
By checking <guilabel>Use work unit cache</guilabel>, you can tell &kapp; to
use the work unit cache for this profile. If you do, you will notice that the
e-mail and client name fields to become grayed out. This is because when using
the caching system, the e-mail address used to connect to the servers and the
client that will perform the download/upload operations will always be
those specified in the <link linkend="cache-setup">Cache Setup dialog</link>.
</para>
<para>
In the <guilabel>User e-mail</guilabel> field you can provide an e-mail
address that the <link linkend="mainwindow-user">User Statistics</link> panel
will use to retrieve information about your SETI@home account. If you leave
this field blank, most probably this functionality will be disabled.
</para>
</sect2>
<sect2 id="profile-logging">
<title>The Logging tab</title>
<para>
<screenshot>
<mediaobject>
<imageobject>
<imagedata fileref="profile2.png" format="PNG"/>
</imageobject>
</mediaobject>
</screenshot>
</para>
<para>
&kapp; has the ability to read and write both
<ulink url="http://cox-internet.com/setispy/">SETI Spy</ulink> and
<ulink url="http://members.home.net/mloukko/SETILog.html">SETILog</ulink>
log files. The SETI Spy log is a single file called
<filename>setispy.log</filename> that contains information both about the work
units and the returned signals. The SETILog format is more detailed and
comprises two files: <filename>SETILog.csv</filename>, which contains work
unit data, and <filename>SETIResult.log</filename>, which instead stores info
about the returned signals.
</para>
<para>
You can specify which log files &kapp; should read by selecting the
appropriate radio button. Also, you can select in which format (possibly none,
or both) &kapp; should log the work units that get completed while it's
running. Finally, you can specify the directory where the log files are stored;
if you don't specify any, the SETI@home directory will be used.
</para>
<para>
In addition to writing to log files, &kapp; also gives you the option to save
pictures of the gaussians that are discovered during the analysis and/or those
that are returned to the servers. You can choose to save all of them, just the
interesting ones (an interesting gaussian is one such that Fit < Power*1.5
+ 2), or those whose Signal-to-noise Ration (S. R.) is above some fixed
threshold. Moreover, you can specify the graphic format. For the size,
you can choose between two preset values: the
<guimenuitem>SETI@home</guimenuitem> format, short and wide, or the
<guimenuitem>Default</guimenuitem> format, which is the right size for
submissions to
<ulink url="http://home.hccnet.nl/a.alfred/p-free-p1city.html">Alfred Das'
CITY@home gallery</ulink>. Finally, you can specify the directory where you
want these images saved to; if you don't provide one, the log file directory
will be assumed as default.
</para>
</sect2>
<sect2 id="profile-calibration">
<title>The Calibration tab</title>
<para>
<screenshot>
<mediaobject>
<imageobject>
<imagedata fileref="profile3.png" format="PNG"/>
</imageobject>
</mediaobject>
</screenshot>
</para>
<para>
Starting with version 3.x, the SETI@home client performs some pre-analysis in
the initial stage of the processing of a work unit. As a consequence of this,
progress is not linear, and &kapp;'s reported speed at the beginning of a new
work unit might be substantially different from the average one. Calibration
is designed to compensate for these variations
by allowing you to modify the "percentage done" bit of information.
</para>
<para>
Since the length of this pre-analysis depends on the Angle Range (AR)], there are three
calibration sets:
<simplelist type='horiz' columns='2'>
<member>Low AR</member><member>(AR < 0.2255)</member>
<member>Medium AR</member><member>(0.2255 <= AR <= 1.1274)</member>
<member>High AR</member><member>(AR > 1.1274)</member>
</simplelist>
</para>
<para>
If you don't know what calibration values are right for your computer, don't
worry: &kapp; offers you presets for most common CPU types. These presets are
taken from the
<ulink url="http://cox-internet.com/setispy/">SETI Spy web page</ulink>, and
are provided courtesy of Roelof Engelbrecht et al. The SETI Spy web page also
contains a more thorough discussion of calibration than what presented here.
</para>
</sect2>
</sect1>
<sect1 id="stats-servers">
<title>The Statistics Servers Setup Dialog</title>
<para>
<screenshot>
<mediaobject>
<imageobject>
<imagedata fileref="stats_servers.png" format="PNG"/>
</imageobject>
</mediaobject>
</screenshot>
</para>
<para>
On June 2002, some of the scripts that are used by &kapp; in the
<link linkend="mainwindow-user">User Statistics</link> and
<link linkend="mainwindow-group">Group Statistics</link> panels were rewritten
in Fast-CGI and moved to a different path in the web server. This temporarily
broke most of &kapp;'s stats displaying functionality. To minimize the chance
of this happening again, starting from version 0.5.2, &kapp; allows you to
select the URL used to retrieve user and team statistics.
</para>
<para>
There are five locations that can be set, namely:
</para>
<para>
<variablelist>
<varlistentry>
<term><guimenu>User Data</guimenu></term>
<listitem>
<para>
The location where most of the data displayed in the User Statistics panel is
extracted from.
</para><para></para>
</listitem>
</varlistentry>
<varlistentry>
<term><guimenu>User Link</guimenu></term>
<listitem>
<para>
This is the link displayed in the <guilabel>User</guilabel> field.
</para><para></para>
</listitem>
</varlistentry>
<varlistentry>
<term><guimenu>Group Data</guimenu></term>
<listitem>
<para>
The location used to extract Group Statistics information.
</para><para></para>
</listitem>
</varlistentry>
<varlistentry>
<term><guimenu>Group Link</guimenu></term>
<listitem>
<para>
The link displayed in the <guilabel>Group</guilabel> field (if you belong to
a group).
</para><para></para>
</listitem>
</varlistentry>
<varlistentry>
<term><guimenu>Certificate Link</guimenu></term>
<listitem>
<para>
The link displayed in the <guilabel>Results returned</guilabel> field (if any).
</para><para></para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
For each of these locations, you can choose whether to use the SETI@home CGI
server, or a web page of your choice. For the former, you will be able to
specify the server, the path of the CGI script, and the command used.
<note>
<para>
Unless you know exactly what you are doing, it is strongly recommended you do
not set the <guimenu>User Data</guimenu> or <guimenu>Group Data</guimenu>
locations to a custom web page. &kapp; expects these page to have a very
specific format in order to parse the data, and data extraction will likely
fail if the page you specify does not have such format.
</para>
</note>
</para>
</sect1>
<sect1 id="tray">
<title>The Tray Icon</title>
<para>
<screenshot>
<mediaobject>
<imageobject>
<imagedata fileref="tray.png" format="PNG"/>
</imageobject>
</mediaobject>
</screenshot>
</para>
<para>
Depending on <link linkend="mainwindow-setup-display">some settings in the
Setup panel</link>, &kapp; will also have an icon in the tray. The color and
shape of this icon will convey information about the state of the SETI@home
client. More precisely, the icon will be one of the following:
<simplelist type='horiz' columns='2'>
<member>
<guiicon>
<inlinemediaobject>
<imageobject>
<imagedata fileref="idle.png" />
</imageobject>
</inlinemediaobject>
</guiicon>
</member>
<member>
The client is idle.
</member>
<member>
<guiicon>
<inlinemediaobject>
<imageobject>
<imagedata fileref="uninteresting.png" format="PNG" />
</imageobject>
</inlinemediaobject>
</guiicon>
</member>
<member>
The client is running; there are no returned signals.
</member>
<member>
<guiicon>
<inlinemediaobject>
<imageobject>
<imagedata fileref="returned.png" />
</imageobject>
</inlinemediaobject>
</guiicon>
</member>
<member>
The client is running; there are returned signals.
</member>
<member>
<guiicon>
<inlinemediaobject>
<imageobject>
<imagedata fileref="interesting.png" />
</imageobject>
</inlinemediaobject>
</guiicon>
</member>
<member>
The client is running; there are interesting gaussians.
</member>
</simplelist>
</para>
<para>
Right-clicking on the tray icon, it will bring up a menu with the following
items:
<variablelist>
<varlistentry>
<term><guimenu>Client</guimenu></term>
<listitem>
<para>
This submenu allows you to start/stop the client. You can also lower the
priority if the client is running. Note that while you'll alway be able to
stop a running client, you won't be able to start it unless you have
previously provided its location (and command line arguments, if any) in the
<link linkend="profile-setup">Profile configuration dialog</link>.
</para><para></para>
</listitem>
</varlistentry>
<varlistentry>
<term><guimenu>Tooltip text</guimenu></term>
<listitem>
<para>
Here you can choose what information the &kapp;'s tray icon tooltip should
display.
</para><para></para>
</listitem>
</varlistentry>
<varlistentry>
<term><guimenu>Profiles</guimenu></term>
<listitem>
<para>
Using this submenu you can see which profile is current, as well as change the
current profile.
</para><para></para>
</listitem>
</varlistentry>
<varlistentry>
<term><guimenuitem>About &kapp;</guimenuitem></term>
<listitem>
<para>
Brings up the <link linkend="mainwindow-about">panel containing version number
and credits</link>.
</para><para></para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<guimenuitem>Minimize</guimenuitem>/<guimenuitem>Restore</guimenuitem>
</term>
<listitem>
<para>
Minimizes/restores the &kapp; main window.
</para><para></para>
</listitem>
</varlistentry>
<varlistentry>
<term><guimenuitem>Quit</guimenuitem></term>
<listitem>
<para>
Exits the application.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</sect1>
<sect1 id="sounds">
<title>Sounds and system notifications</title>
<para>
<screenshot>
<mediaobject>
<imageobject>
<imagedata fileref="notify.png" format="PNG"/>
</imageobject>
</mediaobject>
</screenshot>
</para>
<para>
Starting with version 0.3.8, &kapp; issues system notifications when some
events occur. You can choose to be notified by a sound, a dialog, or to log
these events in a file by checking the appropriate option in the
<application>Control Center</application>.
</para>
</sect1>
</chapter>
<chapter id="advanced">
<title>Advanced Settings</title>
<sect1 id="advanced-intro">
<title>Introduction</title>
<para>
In this chapter we present some advanced &kapp; features. Some of these
require prior knowledge of shell scripting, or, in general, a good
understanding of Linux.
</para>
</sect1>
<sect1 id="advanced-custom-sysinfo">
<title>Customizing System Information</title>
<para>
By default, the information presented in the
<link linkend="mainwindow-client">Client</link> and
<link linkend="mainwindow-processor">Processor</link> panels about
the system's processor, memory and operating system is obtained by looking
at three files:
<simplelist>
<member>
<filename>/proc/cpuinfo</filename> (processor info)
</member>
<member>
<filename>/proc/meminfo</filename> (memory and swap file info)
</member>
<member>
<filename>/proc/version</filename> (operating system info)
</member>
</simplelist>
</para>
<para>
These can be found on most Linux distributions, so these defaults are
reasonable.
</para>
<para>
However, if you're running your client on, say, a BSD system, these files
won't be available. Also, if you monitor a remote client, running, say,
on a Windows machine, these files will be available but will report incorrect
information, since they will report information of your local Linux machine,
and not of the remote Windows one.
</para>
<para>
To accommodate for these special situations, &kapp; allows you to specify
a directory, different from <filename>/proc/</filename>, where to look for
these three files. Unfortunately, however, there is no graphical user
interface option for doing this, so you'll have to edit the &kapp;
configuration file. In the rest of the section I'll explain how to do this.
To make the explanation more concrete, I'll stipulate the following:
<orderedlist>
<listitem>
<para>
You have a profile named "My Profile" pointing to a SETI@home client directory
located in
<filename>/home/rvirga/SETI@home/</filename>.
</para>
</listitem>
<listitem>
<para>
The directory containing the modified system information will be a subdirectory
of the SETI@home directory named <filename>proc</filename>.
</para>
</listitem>
</orderedlist>
</para>
<para>
Obviously, in applying these instructions, you will change these parameters
with those appropriate to your situation.
</para>
<para>
First, let's create <filename>/home/rvirga/SETI@home/proc/</filename> and
populate it with the three files. There are at least two ways to do it. The
first is to copy the files from a Linux machine you have access to. The
second way, offered for your convenience, is
<ulink url="http://ksetispy.sourceforge.net/files/setiproc.tar.gz">
to download a tarball containing these files from the &kapp; site</ulink>.
These files have already been modified so that they will report a fictitious
dual processor machine, where the first processor is a 1 GHz Itanium, and the
second a 2 GHz Pentium 4 (change this information to something more of your
liking).
</para>
<para>
In this example, we choose this second option. Download and extract the files
to the destination directory:
<screen width="80">
<prompt>%</prompt> <userinput>pwd</userinput>
/home/rvirga/SETI@home
<prompt>%</prompt> <userinput>tar zxvf setiproc.tar.gz</userinput>
proc/
proc/cpuinfo
proc/meminfo
proc/version
<prompt>%</prompt> <userinput>ls -l proc</userinput>
total 12
-rw-r--r-- 1 rvirga rvirga 737 Aug 17 14:06 cpuinfo
-rw-r--r-- 1 rvirga rvirga 549 Aug 17 14:06 meminfo
-rw-r--r-- 1 rvirga rvirga 78 Aug 17 14:06 version
</screen>
</para>
<para>
Before modifying the configuration file, it's important to make sure &kapp; is
not running. &kapp; reads the configuration file on startup and writes it on
exit, so any manual modification done to the configuration while it's running
is going to be ignored, and eventually overwritten.
</para>
<para>
The configuration file is stored in a subdirectory of the KDE local prefix.
The local prefix is usually <filename>~/.kde</filename>, but to make sure,
type:
<screen width="80">
<prompt>%</prompt> <userinput>kde-config --localprefix</userinput>
/home/rvirga/.kde/
</screen>
</para>
<para>
The full path of the configuration file is obtained by appending
<filename>share/config/ksetispyrc</filename> to the local prefix; hence in
this case is
<filename>/home/rvirga/.kde/share/config/ksetispyrc</filename>.
</para>
<para>
Editing this file, look for the section containing the settings relative to
the profile "My Profile". This can be done by searching for the string
"Name=My Profile":
<screen width="80">
...
Log file directory URL=/home/rvirga/SETI@home/
Name=My Profile
Poll interval=15
Record WUs in SETI Spy log=false
Record WUs in SetiWatch log=false
Returned gaussians log URL=/home/rvirga/SETI@home/
Returned gaussians log filter=0
Returned gaussians log image format=1
Returned gaussians log image size=0
Returned gaussians log threshold=3.5
System info URL=/proc/
...
</screen>
</para>
<para>
Change "System info URL=/proc/" to
"System info URL=/home/rvirga/SETI@home/proc/" and save.
</para>
<para>
Finally, launch &kapp;, and verify that everything works with the new settings:
<screenshot>
<mediaobject>
<imageobject>
<imagedata fileref="processor_modified.png" format="PNG"/>
</imageobject>
</mediaobject>
</screenshot>
</para>
<para>
If you are running &kapp; on an operating system other than Linux, you would
have to do the procedure outlined above for every profile you create. This
is, of course, most inconvenient. For this reason, &kapp; allows you to
set a directory different than <filename>/proc/</filename> as default for
all your profiles. Edit again the configuration file, this time looking for
the string "Default system info URL":
<screen width="80">
...
[KSetiSpy]
Current profile=My Profile
Default system info URL=/proc/
First time=false
Profiles=1
Remember window positions=true
Tray flags=3
...
</screen>
</para>
<para>
Changing this field will cause all the future profiles you create to have
automatically the right settings.
</para>
</sect1>
<sect1 id="advanced-dcop-scripting">
<title>DCOP Scripting</title>
<sect2 id="advanced-dcop-scripting-intro">
<title>Introduction</title>
<para>
DCOP, the Desktop COmmunication Protocol, is a mechanism through which KDE
programs expose some of their functionality, so that it can be invoked from
other programs (not necessarily KDE ones), or even from shell scripts.
</para>
<para>
Under DCOP, typically an application publishes a list of functions that it
will provide, specifying for each function the number and types of the
arguments it will require, and its return value. Any time the application will
be running, it will honor execution requests for all the functions it
advertises. To allow a more rational organization of these functions, they are
grouped into interfaces.
</para>
<para>
&kapp; defines three interfaces:
<itemizedlist>
<listitem>
<para><classname>Views-Interface</classname></para>
<para>
This interface groups all functions having to do with panels and their
contents. Panels are referred by a number, that represents the order
in which they appear in the toolbar. The functions offered by this interface
are:
<simplelist type='horiz' columns='2'>
<member>
<methodname>int current() </methodname>
</member>
<member>
Currently visible panel.
</member>
<member>
<methodname>void setCurrent() </methodname>
</member>
<member>
Changes the currently visible panel.
</member>
<member>
<methodname>QString name(int index) </methodname>
</member>
<member>
Name of the panel. This is the text string shown in the panel header.
</member>
<member>
<methodname>QStringList content(int index) </methodname>
</member>
<member>
List of the fields (and their values) of the panel.
</member>
</simplelist>
</para>
</listitem>
<listitem>
<para><classname>Profiles-Interface</classname></para>
<para>
This interface collects the functions that allow to read and set the current
profile, and start/stop the SETI@home client monitored by the current profile.
<simplelist type='horiz' columns='2'>
<member>
<methodname>QString current() </methodname>
</member>
<member>
Current profile.
</member>
<member>
<methodname>void setCurrent() </methodname>
</member>
<member>
Sets the current profile.
</member>
<member>
<methodname>void start() </methodname>
</member>
<member>
Starts the client, if it wasn't running.
</member>
<member>
<methodname>void stop() </methodname>
</member>
<member>
Stops the client, if it was running.
</member>
</simplelist>
</para>
</listitem>
<listitem>
<para><classname>Cache-Interface</classname></para>
<para>
This interface collects all cache-handling functions. They are:
<simplelist type='horiz' columns='2'>
<member>
<methodname>int available() </methodname>
</member>
<member>
Number of work units sitting in the cache awaiting to be processed.
</member>
<member>
<methodname>int done() </methodname>
</member>
<member>
Number of work units already completed, whose results are ready to be sent.
</member>
<member>
<methodname>QDateTime lastDownload() </methodname>
</member>
<member>
Date and time of the most recent work unit download.
</member>
<member>
<methodname>QDateTime lastUpload() </methodname>
</member>
<member>
Date and time of the most recent result upload.
</member>
<member>
<methodname>QDateTime nextDownload() </methodname>
</member>
<member>
Date and time of the next scheduled work unit download.
</member>
<member>
<methodname>QDateTime nextUpload() </methodname>
</member>
<member>
Date and time of the next scheduled result upload.
</member>
<member>
<methodname>ASYNC connect() </methodname>
</member>
<member>
Connects to the server for downloading of fresh work units and uploading of
results. Since this operation might take some time, this function is
asynchronous (non-blocking).
</member>
</simplelist>
</para>
</listitem>
</itemizedlist>
</para>
<para>
To experiment with these new concepts, launch <application>kdcop</application>
by typing <userinput>kdcop &</userinput> followed by a carriage return.
If &kapp; is running, you should see an entry for it. Browsing that entry
will expose all the interfaces and functions &kapp; publishes.
<application>kdcop</application> lets you execute interactively those
functions, so you can familiarize yourself with the way DCOP works.
</para>
<para>
Another way to test DCOP scripting is from the command line. Type, for example:
<screen width="80">
<prompt>%</prompt> <userinput>dcop ksetispy Views-Interface setCurrent 0</userinput>
</screen>
</para>
<para>
This will bring up the Progress panel, just as if you pressed the
corresponding button in the toolbar.
</para>
</sect2>
<sect2 id="advanced-dcop-scripting-ex1">
<title>Example: Starting and Stopping the Client Using the CLI</title>
<para>
This is a simple shell script that allows to start or stop the SETI@home
client of a specific profile (in this example, a profile named "My Profile")
from the command line:
<programlisting width="80">
#!/bin/sh
PROFILE="My Profile"
INTERFACE=Profiles-Interface
case $1 in
start)
OLDPROFILE=`dcop ksetispy $INTERFACE current` ;
dcop ksetispy $INTERFACE setCurrent "$PROFILE" ;
dcop ksetispy $INTERFACE start ;
dcop ksetispy $INTERFACE setCurrent "$OLDPROFILE" ;;
stop)
OLDPROFILE=`dcop ksetispy $INTERFACE current` ;
dcop ksetispy $INTERFACE setCurrent "$PROFILE" ;
dcop ksetispy $INTERFACE stop ;
dcop ksetispy $INTERFACE setCurrent "$OLDPROFILE" ;;
*)
echo "syntax: `basename $0` start|stop" 1>&2 ;;
esac
</programlisting>
</para>
<para>
You can save the code above as a file named, say,
<filename>ksetispy-cli</filename>, and turn its execute bit on, so that it
can be run:
<screen width="80">
<prompt>%</prompt> <userinput>chmod a+x ksetispy-cli</userinput>
</screen>
</para>
<para>
After that, you'll be able to start the SETI@home client by typing:
<screen width="80">
<prompt>%</prompt> <userinput>ksetispy-cli start</userinput>
</screen>
</para>
<para>
and stop it with:
<screen width="80">
<prompt>%</prompt> <userinput>ksetispy-cli stop</userinput>
</screen>
</para>
<para>
The applications of this simple script are numerous. For example, if you
usually run <ulink url="http://ksensors.sourceforge.net">KSensors</ulink> to
monitor the temperature of your computer, you can set it up to execute
<userinput>ksetispy-cli stop</userinput> if the CPU gets too hot.
</para>
</sect2>
</sect1>
<sect1 id="advanced-network-transparence">
<title>Network Transparence</title>
<para>
In KDE, a path like <filename>/home/rvirga/SETI@home/</filename> is seen
as a contracted form of the URL
<filename>file:/home/rvirga/SETI@home/</filename>. The latter is what is
called a URL (Uniform Resource Locator). In addition to the path itself,
the URL also contains the name of the protocol (in this case, a lookup
in the local filesystem) to use. If the the host was a Secure FTP
server, the URL
<filename>sftp://rvirga@localhost/home/rvirga/SETI@home/</filename>
would refer to the same directory, this time accessed through the Secure
FTP protocol.
</para>
<para>
KDE provides a library that allows programs to be easily converted so that
they accept general URLs instead of just pathnames, allowing the user
to access (both read and write) files directly through a myriad of
supported protocols, such as Secure FTP, DAV, HTTP, FTP, Gopher, IMAP, etc.
Programs that have been converted in such way are called "network transparent".
</para>
<para>
Starting from version 0.6.0, &kapp; is, for the most part, network transparent.
More precisely:
<itemizedlist>
<listitem>
<para>
Monitoring of remote clients <emphasis>is</emphasis> network-transparent, and
can be done through any of the protocols supported by KDE. Obviously, the
ability to start/stop the client is not available for remote clients.
</para>
</listitem>
<listitem>
<para>
Reading and writing of log files <emphasis>is</emphasis> network-transparent.
For writing of log and image files, you're required to use a protocol that
supports writing (for example: HTTP is a read-only protocol, while FTP is
read/write), as well as to make sure you have write permissions on the remote
machine.
</para>
</listitem>
<listitem>
<para>
The location of the cache <emphasis>is not</emphasis> network transparent.
Any attempt to enter a non-local (i.e. not starting with "file:") will
trigger an error message. This is because in order to send and receive
work units the cache must call the SETI@home client, which is a local
application.
</para>
</listitem>
</itemizedlist>
</para>
<para>
The following screenshot demonstrates a possible use of network transparence.
Here, &kapp; is used to monitor a remote client through Secure FTP:
<screenshot>
<mediaobject>
<imageobject>
<imagedata fileref="remote.png" format="PNG"/>
</imageobject>
</mediaobject>
</screenshot>
</para>
</sect1>
<sect1 id="advanced-windows-client">
<title>Using the Windows Client</title>
<para>
In addition to the native SETI@home client, Linux users have the option of
running the Windows command-line client under
<ulink url="http://www.winehq.org/">Wine</ulink>. Here is a simple wrapper
for the Windows client:
<programlisting width="80">
#!/bin/sh
exec wine -- setiathome-winnt.exe $*
</programlisting>
</para>
<para>
You can save it under the name, say, of <filename>setiathome-winnt</filename>.
Don't forget to set the execute bit for this file, so that it can be executed
from the command line:
<screen width="80">
<prompt>%</prompt> <userinput>chmod a+x setiathome-winnt</userinput>
</screen>
</para>
<para>
The performance of the Windows client differs from that of the Linux one.
For regular work units, it is faster, but it gets far, far slower on those
work units which have a very low angle range (these work units are often
referred in the SETI@home enthusiasts community as "VLAR"). On average, the
performance of the two clients are therefore the same, since any advantage
cumulated by the Windows client is lost at the first VLAR it gets.
</para>
<para>
To allow Linux SETI@home enthusiasts to get the best performance they can
possibly get from their system, &kapp; 0.6.0 and later offer the possibility
to specify different SETI@home clients for regular work units and for VLARs
(&kapp; considers a VLAR any work unit with AR < 0.1).
</para>
<para>
Since this is a quite advanced feature, and having to choose two clients would
have confused novice users, I decided not to provide a GUI interface to it.
Therefore, the only way to access this feature is by editing &kapp;'s
configuration file.
</para>
<para>
The instructions to locate and edit the configuration file are the same
<link linkend="advanced-custom-sysinfo">we gave earlier</link>, but we repeat
them here. First, check what is the local prefix in your KDE installation,
by typing:
<screen width="80">
<prompt>%</prompt> <userinput>kde-config --localprefix</userinput>
/home/rvirga/.kde/
</screen>
</para>
<para>
This is usually <filename>.kde</filename> in your home directory, but it never
hurts to check. &kapp;'s configuration file location will be obtained by
appending <filename>share/config/ksetispyrc</filename> to this local prefix.
</para>
<para>
Say the profile you want to modify is named "My Profile", look for the string
"Name=My Profile". In the vicinity of this line (usually a few lines above it)
there will be two other entries "Client URL" and "Client URL (VLAR)":
<screen width="80">
...
Client URL=/home/rvirga/SETI@home/setiathome
Client URL (VLAR)=/home/rvirga/SETI@home/setiathome
Client command line arguments=
E-mail=rvirga@users.sourceforge.net
Keep client alive=false
Kill client on exit=false
Launch client on startup=false
Log file directory URL=/home/rvirga/SETI@home/
Name=My Profile
...
</screen>
</para>
<para>
Change these two so that the first points to the wrapper for the Windows
client, and the second to the Linux client. Save the configuration file and
then start &kapp;.
</para>
</sect1>
<sect1 id="advanced-icon-themes">
<title>Icon Themes</title>
<para>
Version 0.6.0 introduced several improvements in the way icons are handled
in &kapp;. First of all, icons are now in a directory of their own, separated
them from other pictures used by the program. Secondly, most icons are
rendered at all the resolutions allowed by KDE, instead of just one.
Finally, we also install vector descriptions (SVG) of all the icons, so
that future versions of KDE will be able to scale the icons to arbitrarily
large sizes.
</para>
<para>
All these changes have improved the visual quality of the icons of &kapp;.
They also made it easier to customize &kapp;'s look by installing different
icon themes. At the time of this writing, there's already another theme
available, Redmond-XP, with more under construction. In this section we
describe the steps required to replace &kapp;'s icon theme.
</para>
<para>
A choice you have to do is whether to install the new icons locally (only for
your user account), or globally (for all users in your system). In the
latter case you'll need to login as superuser (root).
</para>
<para>
Regardless of your choice, it is useful to check what are the local and global
prefixes in your KDE installation. Use the <userinput>kde-config</userinput>
to find out what they are:
<screen width="80">
<prompt>%</prompt> <userinput>kde-config --prefix</userinput>
/usr/
<prompt>%</prompt> <userinput>kde-config --localprefix</userinput>
/home/rvirga/.kde/
</screen>
</para>
<para>
The location where you'll have to install the new icon theme will be
obtained by appending
<filename>share/apps/ksetispy/icons/crystalsvg/</filename>
to one of the prefixes above.
</para>
<para>
In what follows, I'll assume:
<orderedlist>
<listitem>
<para>
We want to install the Redmond-XP theme, that we have already downloaded
and saved in <filename>~/redmond-xp.theme.tar.bz2</filename>.
</para>
</listitem>
<listitem>
<para>
We want to install the icon theme locally, rather than for all users.
</para>
</listitem>
</orderedlist>
</para>
<para>
The instructions for your install should be easily obtainable by making
small and obvious changes to the ones presented here.
</para>
<para>
While the directory for the global installation will always exist (it
is created during the installation of &kapp; to store the default theme), the
directory for a local installation most likely won't exist and will need to
be created using the command <userinput>mkdir</userinput>. Therefore the
installation steps will be the following:
<screen width="80">
<prompt>%</prompt> <userinput>mkdir -p /home/rvirga/.kde/share/apps/ksetispy/icons/crystalsvg</userinput>
<prompt>%</prompt> <userinput>cd /home/rvirga/.kde/share/apps/ksetispy/icons/crystalsvg</userinput>
<prompt>%</prompt> <userinput>tar jxvf ~/redmond-xp.theme.tar.bz2</userinput>
</screen>
</para>
<para>
After you restart &kapp;, it now should look like this:
<screenshot>
<mediaobject>
<imageobject>
<imagedata fileref="theme.png" format="PNG"/>
</imageobject>
</mediaobject>
</screenshot>
</para>
</sect1>
</chapter>
<chapter id="credits">
<title>Credits and License</title>
<para>
&kapp;
</para>
<para>
Program copyright 2001-2003 Roberto Virga
<email>rvirga@users.sourceforge.net</email>
</para>
<para>
Documentation copyright 2001-2003 Roberto Virga
<email>rvirga@users.sourceforge.net</email>
</para>
&underFDL;
&underGPL;
<sect1>
<title>Acknowledgments</title>
<para>
I'd like to thank a few people without whom &kapp; could not have been done.
First and foremost, I'd like to thank Roelof Engelbrecht, author of
<ulink url="http://pages.tca.net/roelof/setispy/">SETI Spy</ulink>,
a wonderful Windows SETI@home monitoring utility. &kapp; borrows from SETI Spy
its clean and well-designed interface. Not only that, but studying SETI Spy's
code has been instrumental to figuring out what formulas to use in computing
much of the information &kapp; displays.
</para>
<para>
My thanks also go to Gordon Machel, author of
<ulink url="http://ksetiwatch.sourceforge.net/">KSetiWatch</ulink>, and
<ulink url="http://www.everaldo.com/">Everaldo Coelho</ulink>. Gordon's
SetiContainer influenced the development of some of &kapp;'s monitoring
classes, and Everaldo's Crystal icons theme influenced the design of
&kapp;'s icons.
</para>
<para>
I'm very grateful to
<ulink url="http://www.teamlambchop.com/">Team Ars Technica Lamb Chop</ulink>
in general, and to zAmboni, Rat Bastard, Hagabard, Roelof (once again), and
Max in particular, for all their work on the statistics and benchmarking pages.
</para>
<para>
My gratitude also goes to Diego Iastrubni and Pascal Hartig, for translating
&kapp; in Hebrew and German, respectively.
</para>
<para>
Finally, I'd like to dedicate &kapp; to M.M.M.
</para>
</sect1>
</chapter>
<appendix id="installation">
<title>Installation</title>
<sect1 id="getting-ksetispy">
<title>How to obtain &kapp;</title>
<para>
The main site for &kapp; is hosted by
<ulink url="http://www.sourceforge.net/">SourceForge</ulink>. You can download
the latest version from:
<simplelist>
<member>
<ulink url="ftp://ftp.sourceforge.net/pub/sourceforge/ksetispy/">
ftp://ftp.sourceforge.net/pub/sourceforge/ksetispy/
</ulink>
</member>
</simplelist>
</para>
</sect1>
<sect1 id="requirements">
<title>Requirements</title>
<para>
In order to successfully use &kapp;, you need Qt 3.1 and KDE 3.1 or later.
&kapp; uses about 8 terabytes of memory to run, but this may vary depending on
your platform and configuration.
</para>
<para>
In order to use &kapp;, you will also need a version of the SETI@home client,
which can be obtained from the
<ulink url="http://setiathome.ssl.berkeley.edu/download.html">SETI@home
download page</ulink>.
</para>
<para>
You can find a list of changes at the
<ulink url="http://ksetispy.sourceforge.net/history.php">&kapp;
web site</ulink>.
</para>
</sect1>
<sect1 id="install">
<title>Compilation and Installation</title>
<sect2 id="install-binary-rpm">
<title>Installing an RPM File</title>
<para>
The &kapp; site has binary RPMs for the most popular distributions. These end
with a suffix <filename>.rpm</filename>. Their name will also indicate
the CPU architecture they're for (usually <filename>i386</filename> or
<filename>i586</filename>), as well as the distribution and the operating
system version they are for. For example, an RPM with "rh9"
in the name will be for RedHat Linux version 9, "mdk91" stands for Mandrake
Linux 9.1, and so on.
</para>
<para>
If you're so lucky to find an RPM exactly for the linux you're running,
download it, and then install it using <userinput>rpm -Uvh</userinput>. For
example:
<screen width="80">
<prompt>#</prompt> <userinput>rpm -Uvh ksetispy-0.6.0-rh9.i386.rpm</userinput>
</screen>
</para>
<para>
It is possible that the execution of this command may fail because some of the
packages &kapp; depends upon have not been yet installed into your system. In
that case, consult your distribution's documentation to find out how to
install the missing packages, and then try again.
</para>
</sect2>
<sect2 id="install-source-tar">
<title>Compiling and Installing From Source</title>
<para>
If there are no RPMs for your distribution, you can always compile &kapp; from
source.
</para>
<para>
Compiling a KDE program requires a lot more software than you would need
installing a pre-compiled RPM file. At a minimum, you will need GCC (the
GNU C/C++ Compiler). You'll also need a bunch of other development tools;
the configuration script will check what is installed in your system and
will inform you of what you will need to install (if any) to get &kapp;
to successfully compile.
</para>
<para>
Download the source code distribution of &kapp;. This will be a file
ending in <filename>.tar.bz2</filename>. In what follows, we will give
instructions to install version 0.6.0, but the procedure for any other
version will be the same except for the name of the file.
</para>
<para>
The first step is to unpack the archive:
<screen width="80">
<prompt>#</prompt> <userinput>tar jxvf ksetispy-0.6.0.tar.bz2</userinput>
</screen>
</para>
<para>
This will create a directory named <filename>ksetispy</filename> and
populate it with files (and a few subdirectories). Enter inside this
directory:
<screen width="80">
<prompt>#</prompt> <userinput>cd ksetispy</userinput>
</screen>
</para>
<para>
From there, type the following three commands (wait before each terminates
successfully before typing the next one):
<screen width="80">
<prompt>#</prompt> <userinput>./configure --prefix=`kde-config --prefix`</userinput>
<prompt>#</prompt> <userinput>make</userinput>
<prompt>#</prompt> <userinput>make install</userinput>
</screen>
</para>
<para>
The last command in this sequence will require super-user (root) privileges,
but the previous two can be executed while logged as a normal user (of course,
you can execute all of them as root, if you like).
</para>
</sect2>
</sect1>
</appendix>
<glossary>
<title>Glossary</title>
<glossentry id="cpf">
<glossterm>CpF</glossterm>
<glossdef>
<para>
CpF stands for "Cycles per FLOP", and measures the efficiency of a processor.
A 500MHz CPU performs 500,000,000 cycles each second, but typically its
computing speed will be lower than 500 <link linkend="flops">MegaFLOPS</link>.
This is because, in real-life conditions, several factors make it so that
usually it takes several cycles to perform a single elementary floating point
operation. CpF expresses the average number of cycles needed to compute 1 FLOP.
It is obtained by dividing the CPU clock frequency (expressed in Hz) by
the CPU speed (expressed in FLOPS).
</para><para></para>
</glossdef>
</glossentry>
<glossentry id="fft">
<glossterm>FFT</glossterm>
<glossdef>
<para>
A Fast Fourier Transform (abbreviated as FFT) is an algorithm frequently used
in signal analysis.
</para><para></para>
</glossdef>
</glossentry>
<glossentry id="flop">
<glossterm>FLOP</glossterm>
<glossdef>
<para>
FLOP is an acronym for FLoating point OPeration. A floating point operation is
meant to be an elementary operation (such as sum, subtraction, multiplication,
division). FLOPs (the lowercase s suffix stands for the plural, and should not
be confused with <link linkend="flops">FLOPS</link>) are used as measure of the
amount of computation to perform.
</para>
<para>
A MegaFLOP corresponds to 10<superscript>6</superscript> FLOPs, a GigaFLOP is
10<superscript>9</superscript> FLOPs, and a TeraFLOP is
10<superscript>12</superscript> FLOPs.
</para><para></para>
</glossdef>
</glossentry>
<glossentry id="flops">
<glossterm>FLOPS</glossterm>
<glossdef>
<para>
FLOPS is an acronym for FLoating point Operations Per Second. This is used to
express the speed of a processor, and it measures the number of
<link linkend="flop">FLOPs</link> that are processed in one second. Hence, for
example, a CPU that processes 1.2 GigaFLOPs per minute, has a speed of
<literallayout>
1.2 * 10<superscript>9</superscript> FLOPs / 60 seconds = 20 MegaFLOPS
</literallayout>
</para>
<para>
MegaFLOPS, GigaFLOPS, and TeraFLOPS stand for 10<superscript>6</superscript>,
10<superscript>9</superscript>, and 10<superscript>12</superscript> FLOPSs,
respectively.
</para><para></para>
</glossdef>
</glossentry>
</glossary>
&documentation.index;
</book>
<!--
Local Variables:
mode: sgml
sgml-minimize-attributes:nil
sgml-general-insert-case:lower
sgml-indent-step:0
sgml-indent-data:nil
End:
-->
distrib
>
Mandriva
>
9.2
>
i586
>
media
>
contrib
>
by-pkgid
>
1cd08b83dbeee96d33440cc87e49c159
>
files
>
131
