# The KSetiSpy Handbook

## Introduction

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.

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.

One of the most complete SETI@home monitoring tools available today is a Windows program named SETI Spy. &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;.

&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 rvirga@users.sourceforge.net.

Thanks for using my little program! I hope you'll find it useful.

## Getting Started with &kapp;

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 download page of SETI@home site.

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.

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 `/home/rvirga/SETI@home/`, and that the email address associated with the account is `rvirga@users.sourceforge.net`. Replace these values with the ones you used in your setup.

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 the installation chapter.

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 `ksetispy &` (followed by a carriage return) in a command shell.

The first time you run &kapp;, you'll be presented with a window like this:

You'll need to create a new profile that contains enough information to allow &kapp; to run the SETI@home client.

Click on Add.... The following dialog will appear:

Choose a name for this profile; for example, "My Profile".

Next, you need to tell &kapp; which directory contains all the SETI@home files (these are a bunch of files, all ending in `.sah` that the SETI@home client creates when it runs. You can type the path of this directory in the Files location field; Alternatively, you can click the browse button next to it, browse with the mouse to that directory (this second method is probably easier).

You'll also need to tell &kapp; where to find the client application, by filling the Client location field. Do this in a similar way to what you did for the File location, but this time selecting a file (the SETI@home client file) instead of a directory.

Finally, you'll need to type the e-mail address you used to register to SETI@home in the User e-mail field.

All done. You can click OK now to create the profile. There are a lot of other parameters you can modify, 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.

## Command Reference

### The main &kapp; window

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.

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 Copy to clipboard.

#### The Progress panel

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 unknown.

Here is a brief explanation of the fields it contains:

CPU time

- 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.

Estimated total time

- An estimate of the total computing time required to complete the current work unit.

Speed

- The average speed, measured in MegaFLOPS.

Estimated time left

- An estimate of the computing time required to complete the work unit. This is can be obtained as the difference between Estimated total time and CPU time.

Rate

- The (average) speed of the client, measured as the percentage of work unit it processes every hour.

Estimated time done

- 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.

Efficiency

- Average efficiency of the CPU, measured in CpF.

Drift rate

- The drift rate currently being analyzed. For SETI@home version 3.08, this is a value ranging between -50 and +50.

Completed

- Percentage of the work unit that has already been processed.

FFT number

- Number of FFTs computed so far. In SETI@home version 3.08, processing a work unit involves performing about 31,560 FFTs.

#### The Performance panel

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 unknown value.

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.

A brief description of the fields follows:

Processing rate

- 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.

Processing speed

- The processing speed in MegaFLOPS.

Processing efficiency

- The average number of CPU cycles necessary to complete an elementary floating point operation (CpF).

Floating point operations to process

- The total number of FLOPs 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.

Pressing the Compare button opens the Peak Processing Efficiency window.

#### The Results panel

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.

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.

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.

The View Log and Details buttons open the the Log and Results Details windows, respectively.

#### The Work Unit panel

The fields in this panel report information about the origin of the data stored in the current work unit. They are:

Work unit name

- The unique ID that SETI@home uses to identify the work unit.

Recorded

- Day and time the data contained in this work unit was recorded.

Position

- Position in the sky, given as Right Ascension (RA), Declination (Dec), and Angle Range (AR).

Nearest constellation

- Name and 3-letter symbol of the closest constellation. Clicking on the link, you can get more information on the specific constellation.

Source

- Radio telescope that collected the data. Currently, this is always Arecibo. By clicking on the link, you can visit the Arecibo web site.

Base frequency

- Base of the frequency slice examined in this work unit.

Pressing the Sky Map button opens the Sky Map window.

#### The User Statistics panel

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 Update button.

The fields contained in this panel are:

User

- 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.

Registered

- 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).

Results returned

- 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.

Total CPU time

- Total time dedicated by this user to processing work units.

Result interval

- Average time elapsed between two consecutive work units are completed and their results returned to the servers.

Avg. CPU time

- CPU time to process a work unit, averaged over all the work units completed so far.

CPU dedication

- Average of the number of CPUs (computers) the user is using to process work units.

Environment

- 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.

  Information about your environment was entered by you when you registered with SETI@home.

Country

- 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.

Rank

- Rank of the user, measured in terms of number of completed work units returned.

Clicking the Calendar button will open the Calendar window.

In most situations, &kapp; should be able to download the extra user information quickly and without problems each time you click on the Update button. In case something goes wrong, however, this can be usually tracked down to one or more of the following things:

- Internet connection

  Check that you're connected to the internet. If you are behind a firewall that uses a HTTP proxy server, check Konqueror'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.

- The SETI@home stats web server

  The web server &kapp; uses for the connection is the one specified in the User Data panel of the Statistics Servers Setup dialog. Try to browse that web site with Konqueror (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.

- E-mail address

  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 User field to be static text instead of an link, and the Update grayed out. If you're using the cache, you need to fill that address in the Cache Setup dialog; if you're not using the cache, edit the current profile instead.

#### The Group Statistics panel

Much like as for User Statistics, 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.

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 unknown.

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 Update button. They are:

Group

- Name of the team you belong to, and link to a web page containing your team's statistics.

Results returned

- Number of completed work units that have been returned to SETI@home by members of this team.

Total CPU time

- Total time spent by members of this team crunching work units.

Avg. CPU time

- Average time needed to process a work unit by members of this team.

Founder

- The founder of this group.

Members

- The number of SETI@home who are currently members of this group.

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:

Results per day

- An estimate of the number of completed work units that are returned each day by members of this team.

CPUs

- The number of CPUs from members of this group 100% dedicated on processing work units, and their average frequency.

Speed

- The speed at which the group is processing data, measured in FLOPS.

#### The Client panel

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:

SETI@home client

- The version of the SETI@home client.

URL

- Location of the SETI@home files.

Operating system

- The operating system of the machine. For Linux, this will typically list the kernel version, and possibly the maker of the distribution.

Physical memory size

- The amount of physical memory (in KB, MB or GB) installed in the machine.

Swap space size

- The amount of virtual memory (in KB, MB or GB).

You can start the client by pressing Start (if it's not running), and stop it pressing Stop (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 Profile configuration dialog.

#### The Processor panel

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 can be changed if you use &kapp; to monitor clients running remotely.

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.

The panel also contains the following fields:

CPU type

- 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 Peak Processing Efficiency window or choosing the right calibration.

CPU speed

- The speed in MHz of the processor.

Cache

- The size (in KB or MB) of the CPU's (or sometimes motherboard's) cache.

BogoMIPS

- 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 MegaFLOPS.

  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.

#### The Work Unit Cache panel

Here you will find information about the work unit cache management system. The following fields are displayed:

Location

- The complete path of the directory containing the cache.

Capacity

- The maximum number of work units the cache will download from the server.

Available

- The number of work units that have been downloaded and await to be processed.

Done

- The number of work units that have been completed and whose results still need to be uploaded into the servers.

Last download

- The date and time of the last successful work unit download (if any).

Last upload

- The date and time of the last successful result upload (if any).

Next download

- The date and time of the next scheduled work unit download (if any).

Next upload

- The date and time of the next scheduled result upload (if any).

The Setup... button will bring up the Cache Setup dialog, allowing you to set up the cache or modify some of its parameters. The Show Log button will open the Connection Log window, where you will be able to see the input/output of the most recent connection.

For the impatient, there is a Connect button that will start both download and upload connections to the servers (provided there is anything to transmit or receive).

#### The Setup panel

This panel controls most of &kapp;'s settings. They are grouped in three tabs.

##### The Profiles tab

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.

The list on the left enumerates all the profiles defined so far. The current profile has a "(current)" suffix.

The Add... button allows you to create a new profile, that, upon completion, will be added to the list. Pressing Edit... you will be able to modify the profile that is currently highlighted on the list. Delete 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, Set Current will change the current profile to the one that's currently highlighted.

##### The Display tab

Three of the four checkboxes in this tab deal with the tray icon. Checking Minimize to tray causes &kapp; to minimize to an icon in the system tray rather than to a taskbar button. If Run in tray is checked, the tray icon will be visible at all times. Finally, with Close to tray 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 Quit from the menu.

The Remember windows positions 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.

##### The User Statistics tab

This tabs groups together all the settings relative to the User Statistics and Group Statistics panels.

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).

If you use the cache, you may want to update automatically your user statistics after you upload your cached results.

The Servers... button opens the Statistics Servers Setup dialog, 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.

#### The About panel

This panel gives you the program version, a brief description, and credits.

Pressing the Help will launch the KDE help application, and open it to a copy of this very manual you're reading.

### The Peak Processing Efficiency window

This window allows you to compare your CPU's efficiency (measured in CpFs) to others. The comparison table used here has been obtained from data collected by the Team Lamb Chop Benchmarking page and is provided courtesy of Roelof Engelbrecht. Please consult the SETI Spy web page for a more in-depth discussion about processor efficiency in the context of SETI@home data processing.

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 Performance panel. 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 Copy to clipboard you will get a copy in tab-separated values format, ready for use in any spreadsheet or word processing application.

### The Work Unit Log window

This windows presents a table whose rows correspond to the work units that have been completed and recorded in the log file.

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 SETILog 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 KSetiWatch, another SETI@home add-on for KDE whose functionality nicely complements &kapp;'s own.

The log table can be sorted and copied to the clipboard, in the same way described for the Peak Processing Efficiency window.

### The Results Details window

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.

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 SETI@home one, or a Default format suitable for submission to the CITY@home web site. A menu option also allows you to open a browser window pointing to that site.

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.

### The Sky Map window

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.

If you select Show history 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.

#### The Sky Map legend

The legend gives the abbreviation and name of each of the 88 constellations in the sky. The constellation names are links to the Basic Celestial Phenomena web pages, which are provided courtesy of Kerry Magruder KVMagruder@mac.com.

#### The Telescope Path window

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.

### The Work Unit Calendar window

This windows gives you an overview of your standings with respect to the number of work units returned.

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 Work units per day 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).

The cells corresponding to past days in which you returned work units will have a dark red background, and the number of units returned.

### The Cache Setup dialog

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.

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.

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).

In order to set up the cache, you need to provide the following data:

Location

- 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.

Client

- The full path of the SETI@home client executable you will be using.

User e-mail

- The e-mail address you used to register to SETI@home.

Capacity

- The maximum number of work units the cache will store.

Proxy server

- If you don't use a proxy server, select No proxy. If instead you use a regular proxy server, select Proxy and fill the Host and Port fields. Finally, if you have a SOCKS proxy server, you will need to provide a login name and password too.

Schedule

- 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.

Download threshold

- 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.

#### Interval selection

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.

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.

Intervals are colored according to their type:

- Download only: &kapp; will download new work units at a random time within the interval.
- Upload only: &kapp; results for work units that have been completed will be uploaded to the servers.
- Both: a combination of both upload and download.

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

To resize an interval, drag one of the two gray resize handles located at its extremities:

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.

You delete an interval in pretty much the same way you created it: simply double-click on it.

#### Carbon copy buttons

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.

### The Connection Log window

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 (Downloads or Uploads).

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.

You can abort an ongoing connection by clicking the Kill Connection button. Pressing this button while there's no active connection has no effect.

Finally, by right clicking anywhere in the window, a menu will pop up allowing you to copy the current text to the clipboard.

### The Profile dialog

#### The Setup tab

Two important bits of information in a profile are the Profile name and the Files location. 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.

Also important is the location of the SETI@home client, whose complete path must be filled in the Client location 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.

The Poll interval 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 Client idle timeout, &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.

Using the check boxes in the Process Control 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.

By checking Use work unit cache, 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 Cache Setup dialog.

In the User e-mail field you can provide an e-mail address that the User Statistics panel will use to retrieve information about your SETI@home account. If you leave this field blank, most probably this functionality will be disabled.

#### The Logging tab

&kapp; has the ability to read and write both SETI Spy and SETILog log files. The SETI Spy log is a single file called `setispy.log` that contains information both about the work units and the returned signals. The SETILog format is more detailed and comprises two files: `SETILog.csv`, which contains work unit data, and `SETIResult.log`, which instead stores info about the returned signals.

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.

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 SETI@home format, short and wide, or the Default format, which is the right size for submissions to Alfred Das' CITY@home gallery. 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.

#### The Calibration tab

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.

Since the length of this pre-analysis depends on the Angle Range (AR)], there are three calibration sets:

- Low AR
- (AR < 0.2255)
- Medium AR
- (0.2255 <= AR <= 1.1274)
- High AR
- (AR > 1.1274)

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 SETI Spy web page, 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.

### The Statistics Servers Setup Dialog

On June 2002, some of the scripts that are used by &kapp; in the User Statistics and Group Statistics 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.

There are five locations that can be set, namely:

User Data

- The location where most of the data displayed in the User Statistics panel is extracted from.

User Link

- This is the link displayed in the User field.

Group Data

- The location used to extract Group Statistics information.

Group Link

- The link displayed in the Group field (if you belong to a group).

Certificate Link

- The link displayed in the Results returned field (if any).

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.

Unless you know exactly what you are doing, it is strongly recommended you do not set the User Data or Group Data 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.

### The Tray Icon

Depending on some settings in the Setup panel, &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:

- The client is idle.
- The client is running; there are no returned signals.
- The client is running; there are returned signals.
- The client is running; there are interesting gaussians.

Right-clicking on the tray icon, it will bring up a menu with the following items:

Client

- 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 Profile configuration dialog.

Tooltip text

- Here you can choose what information the &kapp;'s tray icon tooltip should display.

Profiles

- Using this submenu you can see which profile is current, as well as change the current profile.

About &kapp;

- Brings up the panel containing version number and credits.

Minimize/Restore

- Minimizes/restores the &kapp; main window.

Quit

- Exits the application.

### Sounds and system notifications

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 Control Center.

## Advanced Settings

### Introduction

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.

### Customizing System Information

By default, the information presented in the Client and Processor panels about the system's processor, memory and operating system is obtained by looking at three files:

- `/proc/cpuinfo` (processor info)
- `/proc/meminfo` (memory and swap file info)
- `/proc/version` (operating system info)

These can be found on most Linux distributions, so these defaults are reasonable.

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.

To accommodate for these special situations, &kapp; allows you to specify a directory, different from `/proc/`, 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:

1. You have a profile named "My Profile" pointing to a SETI@home client directory located in `/home/rvirga/SETI@home/`.

2. The directory containing the modified system information will be a subdirectory of the SETI@home directory named `proc`.

Obviously, in applying these instructions, you will change these parameters with those appropriate to your situation.

First, let's create `/home/rvirga/SETI@home/proc/` 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 to download a tarball containing these files from the &kapp; site. 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).

In this example, we choose this second option. Download and extract the files to the destination directory:

    % pwd
    /home/rvirga/SETI@home
    % tar zxvf setiproc.tar.gz
    proc/
    proc/cpuinfo
    proc/meminfo
    proc/version
    % ls -l proc
    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

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.

The configuration file is stored in a subdirectory of the KDE local prefix. The local prefix is usually `~/.kde`, but to make sure, type:

    % kde-config --localprefix
    /home/rvirga/.kde/

The full path of the configuration file is obtained by appending `share/config/ksetispyrc` to the local prefix; hence in this case is `/home/rvirga/.kde/share/config/ksetispyrc`.

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":

    ...
    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/
    ...

Change "System info URL=/proc/" to "System info URL=/home/rvirga/SETI@home/proc/" and save.

Finally, launch &kapp;, and verify that everything works with the new settings:

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 `/proc/` as default for all your profiles. Edit again the configuration file, this time looking for the string "Default system info URL":

    ...
    [KSetiSpy]
    Current profile=My Profile
    Default system info URL=/proc/
    First time=false
    Profiles=1
    Remember window positions=true
    Tray flags=3
    ...

Changing this field will cause all the future profiles you create to have automatically the right settings.

### DCOP Scripting

#### Introduction

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.

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.

&kapp; defines three interfaces:

- `Views-Interface`

  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:

  - `int current()`
  - Currently visible panel.
  - `void setCurrent()`
  - Changes the currently visible panel.
  - `QString name(int index)`
  - Name of the panel. This is the text string shown in the panel header.
  - `QStringList content(int index)`
  - List of the fields (and their values) of the panel.

- `Profiles-Interface`

  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.

  - `QString current()`
  - Current profile.
  - `void setCurrent()`
  - Sets the current profile.
  - `void start()`
  - Starts the client, if it wasn't running.
  - `void stop()`
  - Stops the client, if it was running.

- `Cache-Interface`

  This interface collects all cache-handling functions. They are:

  - `int available()`
  - Number of work units sitting in the cache awaiting to be processed.
  - `int done()`
  - Number of work units already completed, whose results are ready to be sent.
  - `QDateTime lastDownload()`
  - Date and time of the most recent work unit download.
  - `QDateTime lastUpload()`
  - Date and time of the most recent result upload.
  - `QDateTime nextDownload()`
  - Date and time of the next scheduled work unit download.
  - `QDateTime nextUpload()`
  - Date and time of the next scheduled result upload.
  - `ASYNC connect()`
  - 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).

To experiment with these new concepts, launch kdcop by typing `kdcop &` 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. kdcop lets you execute interactively those functions, so you can familiarize yourself with the way DCOP works.

Another way to test DCOP scripting is from the command line. Type, for example:

    % dcop ksetispy Views-Interface setCurrent 0

This will bring up the Progress panel, just as if you pressed the corresponding button in the toolbar.

#### Example: Starting and Stopping the Client Using the CLI

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:

    #!/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

You can save the code above as a file named, say, `ksetispy-cli`, and turn its execute bit on, so that it can be run:

    % chmod a+x ksetispy-cli

After that, you'll be able to start the SETI@home client by typing:

    % ksetispy-cli start

and stop it with:

    % ksetispy-cli stop

The applications of this simple script are numerous. For example, if you usually run KSensors to monitor the temperature of your computer, you can set it up to execute `ksetispy-cli stop` if the CPU gets too hot.

### Network Transparence

In KDE, a path like `/home/rvirga/SETI@home/` is seen as a contracted form of the URL `file:/home/rvirga/SETI@home/`. 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 `sftp://rvirga@localhost/home/rvirga/SETI@home/` would refer to the same directory, this time accessed through the Secure FTP protocol.

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".

Starting from version 0.6.0, &kapp; is, for the most part, network transparent. More precisely:

- Monitoring of remote clients is 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.

- Reading and writing of log files is 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.

- The location of the cache is not 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.

The following screenshot demonstrates a possible use of network transparence. Here, &kapp; is used to monitor a remote client through Secure FTP:

### Using the Windows Client

In addition to the native SETI@home client, Linux users have the option of running the Windows command-line client under Wine. Here is a simple wrapper for the Windows client:

    #!/bin/sh
    exec wine -- setiathome-winnt.exe $*

You can save it under the name, say, of `setiathome-winnt`. Don't forget to set the execute bit for this file, so that it can be executed from the command line:

    % chmod a+x setiathome-winnt

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.

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).

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.

The instructions to locate and edit the configuration file are the same we gave earlier, but we repeat them here. First, check what is the local prefix in your KDE installation, by typing:

    % kde-config --localprefix
    /home/rvirga/.kde/

This is usually `.kde` in your home directory, but it never hurts to check. &kapp;'s configuration file location will be obtained by appending `share/config/ksetispyrc` to this local prefix.

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)":

    ...
    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
    ...

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;.

### Icon Themes

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.

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.

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).

Regardless of your choice, it is useful to check what are the local and global prefixes in your KDE installation. Use the `kde-config` to find out what they are:

    % kde-config --prefix
    /usr/
    % kde-config --localprefix
    /home/rvirga/.kde/

The location where you'll have to install the new icon theme will be obtained by appending `share/apps/ksetispy/icons/crystalsvg/` to one of the prefixes above.

In what follows, I'll assume:

1. We want to install the Redmond-XP theme, that we have already downloaded and saved in `~/redmond-xp.theme.tar.bz2`.

2. We want to install the icon theme locally, rather than for all users.

The instructions for your install should be easily obtainable by making small and obvious changes to the ones presented here.

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 `mkdir`. Therefore the installation steps will be the following:

    % mkdir -p /home/rvirga/.kde/share/apps/ksetispy/icons/crystalsvg
    % cd /home/rvirga/.kde/share/apps/ksetispy/icons/crystalsvg
    % tar jxvf ~/redmond-xp.theme.tar.bz2

After you restart &kapp;, it now should look like this:

## Credits and License

&kapp;

Program copyright 2001-2003 Roberto Virga rvirga@users.sourceforge.net

Documentation copyright 2001-2003 Roberto Virga rvirga@users.sourceforge.net

&underFDL; &underGPL;

### Acknowledgments

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 SETI Spy, 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.

My thanks also go to Gordon Machel, author of KSetiWatch, and Everaldo Coelho. 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.

I'm very grateful to Team Ars Technica Lamb Chop 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.

My gratitude also goes to Diego Iastrubni and Pascal Hartig, for translating &kapp; in Hebrew and German, respectively.

Finally, I'd like to dedicate &kapp; to M.M.M.

## Installation

### How to obtain &kapp;

The main site for &kapp; is hosted by SourceForge. You can download the latest version from:

- ftp://ftp.sourceforge.net/pub/sourceforge/ksetispy/

### Requirements

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.

In order to use &kapp;, you will also need a version of the SETI@home client, which can be obtained from the SETI@home download page.

You can find a list of changes at the &kapp; web site.

### Compilation and Installation

#### Installing an RPM File

The &kapp; site has binary RPMs for the most popular distributions. These end with a suffix `.rpm`. Their name will also indicate the CPU architecture they're for (usually `i386` or `i586`), 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.

If you're so lucky to find an RPM exactly for the linux you're running, download it, and then install it using `rpm -Uvh`. For example:

    # rpm -Uvh ksetispy-0.6.0-rh9.i386.rpm

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.

#### Compiling and Installing From Source

If there are no RPMs for your distribution, you can always compile &kapp; from source.

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.

Download the source code distribution of &kapp;. This will be a file ending in `.tar.bz2`. 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.

The first step is to unpack the archive:

    # tar jxvf ksetispy-0.6.0.tar.bz2

This will create a directory named `ksetispy` and populate it with files (and a few subdirectories). Enter inside this directory:

    # cd ksetispy

From there, type the following three commands (wait before each terminates successfully before typing the next one):

    # ./configure --prefix=`kde-config --prefix`
    # make
    # make install

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).

## Glossary

CpF

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 MegaFLOPS. 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).

FFT

A Fast Fourier Transform (abbreviated as FFT) is an algorithm frequently used in signal analysis.

FLOP

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 FLOPS) are used as measure of the amount of computation to perform.

A MegaFLOP corresponds to 106 FLOPs, a GigaFLOP is 109 FLOPs, and a TeraFLOP is 1012 FLOPs.

FLOPS

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 FLOPs that are processed in one second. Hence, for example, a CPU that processes 1.2 GigaFLOPs per minute, has a speed of

              1.2 * 109 FLOPs / 60 seconds = 20 MegaFLOPS

MegaFLOPS, GigaFLOPS, and TeraFLOPS stand for 106, 109, and 1012 FLOPSs, respectively.

&documentation.index;