SetiContainer API Documentation

SetiContainer Class Reference

The SetiContainer class is a C++ class that allows convenient access to all the information in the state files of a SETI@home client. More...

#include <seticontainer.h>

Inheritance diagram for SetiContainer:

Inheritance graph
[legend]
Collaboration diagram for SetiContainer:

Collaboration graph
[legend]
List of all members.

Public Types

enum  SetiStatus { Stopped, Running, Finished, Loading }
enum  sahID {
  SC_StateFile, SC_UserInfoFile, SC_WorkUnitFile, SC_ResultFile,
  SC_ResultHeaderFile, SC_WtempFile
}

Public Slots

int updateSahData (bool sig=true)

Signals

void progressIncreased ()
void progressDecreased ()
void newSpike (SpikeScore sps)
void newGaussian (GaussianScore gas)
void newPulse (PulseScore pus)
void newTriplet (TripletScore trs)
void newWorkUnit (WorkUnitData wud)
void updatedWorkUnitData ()
void updatedUserInfoData ()
void stateChanged (int state, int loadsize=0)

Public Methods

 SetiContainer (const QString &dir, int refresh=30)
 ~SetiContainer ()
void setRefreshInterval (int refresh)
QString directory () const
void setDirectory (const QString &d)
int refreshInterval ()
int fftNumber ()
int fftLength ()
double chirpRate ()
double cpuTime ()
int outfileSize ()
int potFrequency ()
int potActivity ()
double progress ()
double progressRate ()
double remainingTime ()
QString remainingTimeAsString ()
WUScore wuScore ()
SpikeScore spikeScore ()
GaussianScore gaussianScore ()
PulseScore pulseScore ()
TripletScore tripletScore ()
int userID ()
int key ()
QString userEmailAddress ()
QString userName ()
QString userHomepage ()
QString userCountry ()
int userPostalCode ()
bool showName ()
bool showEmail ()
int venue ()
QString registerTime ()
QString registerTimeString ()
QString lastWUTime ()
QString lastResultTime ()
QString lastResultTimeString ()
int numberOfWUs ()
int numberOfResults ()
double totalCPUTime ()
double averageCPUTime ()
double paramsIndex ()
QString task ()
int wuVersion ()
QString wuName ()
QString wuDataType ()
int wuDataClass ()
QString splitterVersion ()
double startRA ()
double startDec ()
double endRA ()
double endDec ()
double angleRange ()
double teraFlops (double ar, int version=0)
double megaFlopsPerSecond ()
QString timeRecorded ()
QString timeRecordedString ()
double centerFrequency ()
double baseFrequency ()
double sampleRate ()
int wuFFTLength ()
int wuIFFTLength ()
int subbandNumber ()
QString receiver ()
int numberOfSamples ()
QString tapeVersion ()
int numberOfCoords ()
QStringList coords ()
int clientVersion ()
bool exists (int sah)
bool isClientRunning (pid_t pid=0, bool checkCmdLine=false)
int clientState () const
void setClientState (int st)
QString readEntry (int sah, const QString &e)

Static Public Methods

void initWUScore (WUScore *score)
QString convertTime (double time, bool hms)
QString convertRAToString (double ra)
QString convertDecToString (double dec)

Protected Methods

int readStateFile (bool sig=true)
int readWorkUnitFile (bool sig=true)
int readUserInfoFile (bool sig=true)
int readSahFile (const QString &file, QStringList &list, const QString &endId=0)
QString readEntry (const QString &fn, const QString &e)
void initStateFileData ()
void initWorkUnitData ()
void initUserInfoData ()
void scanStateFile (bool sig=true)
void scanSpikeData (bool sig=true)
void scanGaussianData (bool sig=true)
void scanPulseData (bool sig=true)
void scanTripletData (bool sig=true)
void scanGaussianGraphData ()
bool scanPulseGraphData ()
bool scanTripletGraphData ()
void scanUserInfoData (bool sig=true)
void scanWorkUnitData (bool sig=true)
int readClientVersion ()
void initAllData (bool sig=false)
virtual void timerEvent (QTimerEvent *e)
int checkClientState ()
int getClientPid ()
int checkClientStatePassive ()
void checkFileExistence ()

Static Protected Methods

QString readEntry (QStringList &list, const QString &e)
int readDataString (unsigned short int data[], QString &str, int cnt)

Protected Attributes

int refreshIval
int sahVersion
bool versionRead
QString setiDirectory
QString stfFileName
QString wufFileName
QString uifFileName
QString rsfFileName
QString rhdFileName
QString wtpFileName
QStringList stateFile
QStringList workunitFile
QStringList userinfoFile
QString stfTimeStamp
QString wufTimeStamp
QString uifTimeStamp
StateFileData stfData
UserInfoData uifData
WorkUnitData wufData
int cltState
int cltPid

Detailed Description

The SetiContainer class is a C++ class that allows convenient access to all the information in the state files of a SETI@home client.

It periodically examines these files and updates its own data members accordingly. Other programs can use this class to extract information about the progress of the client, the found signals, or the work unit being processed. Additional functions offer more advanced info (like the amount of TeraFlops in a work unit, estimated time of completion, etc). The SetiContainer class is based on the Qt toolkit, and extensively uses Qt's Signal/Slot technique.

Using the SetiContainer is very simple. Here is a short code snippet:

 Seticontainer* sec = new SetiContainer("/home/crunchking/setiathome/");

 double  progress = sec->progress();
 QString wuname   = sec->wuName();
 cout << wuname << ": " << progress << " %";
 

This snippet creates a SetiContainer class which monitors the SETI@home client in the given directory. The name of the work unit and the client's progress are read and printed to stdout. By default, the SetiContainer class refreshes its data every 30 seconds. To change the refresh interval to 60 seconds, just do

 sec->setRefreshInterval(60);
 

SetiContainer offers more advanced functions: it calculates the amount of floating point operations (Flops) required to process the WU in dependence on the angle range, calculates the estimated time to complete the work unit, or converts the given time values from seconds into a nicely formatted string.

Another way of using this class is to inherit from it, and to extend it with all the features you would like to have. Have a look at the Ksetiwatch source code (http://ksetiwatch.sourceforge.net) to see how it is done.

All information from the client's output files is organized in a logical manner using dedicated structures. For example, there are the WorkUnitData structure, the UserInfoData structure, or the WUScore structure (which itself consists of four other structures: SpikeScore, GaussianScore, PulseScore, and TripletScore). By proper naming of these structures in your code, the resulting code is very readable. Here is an example; consider we have two WUScore structures, one holds the record signals, the other contains some newly found signals:

 WUScore record;
 WUScore new;
 ...
 ...
 ...
 if(new.pulse.score > record.pulse.score)
   {
   record.pulse = new.pulse;
   }
 ...
 

This piece of code checks if the score value of the new pulse is larger than that of the record pulse, and -if this is true- copies the entire pulse data to the record WUScore.

SetiContainer makes extensive use of Qt's signal/slot mechanism. For example, the progressIncreased() signal is emitted whenever the client has updated its state file with new data, or the newPulse() signal is emitted when a new high pulse signal was found. Connecting to a signal looks like this:

 connect(this,     SIGNAL(progressIncreased()),
         mywidget, SLOT(slotUpdateTimeData()));
 

Using this approach, the GUI elements are only updated when required, resulting in very efficient code.

In addition, the SetiContainer class provides a sophisticated way to check the state of the SETI@home client. It can distinguish between four different states: Running, Stopped, Finished, and Loading. Whenever the state changes, the stateChanged() signal is emitted.

Author:
Gordon Machel <gmachel@users.sourceforge.net>

Definition at line 122 of file seticontainer.h.


Member Enumeration Documentation

enum SetiContainer::SetiStatus
 

Status definition values.

Definition at line 433 of file seticontainer.h.

enum SetiContainer::sahID
 

The identifiers for the different output files of the SETI@home client.

Definition at line 437 of file seticontainer.h.


Constructor & Destructor Documentation

SetiContainer::SetiContainer const QString   dir,
int    refresh = 30
 

Constructs a Seti container class.

Parameters:
dir  The working folder of the SETI@home client.
refresh  The refresh interval. This class looks every refresh seconds if the data needs to be updated. Default is 30 seconds.

Definition at line 33 of file seticontainer.cpp.

References setDirectory, and QObject::startTimer.

SetiContainer::~SetiContainer  
 

The destructor.

Definition at line 50 of file seticontainer.cpp.


Member Function Documentation

void SetiContainer::setRefreshInterval int    refresh
 

Sets the refresh interval to refresh seconds.

Parameters:
refresh  The refresh interval in seconds.

Definition at line 107 of file seticontainer.cpp.

References QObject::killTimer, and QObject::startTimer.

QString SetiContainer::directory   const [inline]
 

Returns the SETI@home directory.

Definition at line 143 of file seticontainer.h.

Referenced by getClientPid, and updateSahData.

void SetiContainer::setDirectory const QString   d
 

Sets the location's directory.

Definition at line 55 of file seticontainer.cpp.

References checkFileExistence, initAllData, StateFileData::prog, and readClientVersion.

Referenced by SetiContainer.

int SetiContainer::refreshInterval   [inline]
 

Returns the current refresh interval time in seconds.

Definition at line 147 of file seticontainer.h.

int SetiContainer::fftNumber   [inline]
 

Returns the number of the currently processed Fast Fourier Transformation.

Definition at line 151 of file seticontainer.h.

References StateFileData::ncfft.

int SetiContainer::fftLength   [inline]
 

Returns the length (in data points) of the currently processed Fast Fourier Transformation.

Definition at line 155 of file seticontainer.h.

References StateFileData::fl.

double SetiContainer::chirpRate   [inline]
 

Returns the current chirp rate (or drift rate) in Hz/s.

Definition at line 157 of file seticontainer.h.

References StateFileData::cr.

double SetiContainer::cpuTime   [inline]
 

Returns the cpu time (in seconds) spent on the current work unit.

Definition at line 159 of file seticontainer.h.

References StateFileData::cpu.

Referenced by progressRate.

int SetiContainer::outfileSize   [inline]
 

Returns the size of the file outfile.sah which collects data about interesting signals to be returned to the SETI@home server.

If this value has increased the client has found a new interesting signal.

Definition at line 164 of file seticontainer.h.

References StateFileData::outfilepos.

int SetiContainer::potFrequency   [inline]
 

This is a parameter used internally by the SETI@home client.

Definition at line 166 of file seticontainer.h.

References StateFileData::potfreq.

int SetiContainer::potActivity   [inline]
 

This is a parameter used internally by the SETI@home client.

Definition at line 168 of file seticontainer.h.

References StateFileData::potactivity.

double SetiContainer::progress   [inline]
 

Returns the progress of the client in per cent.

Definition at line 170 of file seticontainer.h.

References StateFileData::prog.

Referenced by progressRate, and remainingTime.

double SetiContainer::progressRate  
 

Returns the client's progress rate (in % per hour) based on the actual percentage done and the corresponding cpu time.

Definition at line 1064 of file seticontainer.cpp.

References cpuTime, and progress.

Referenced by megaFlopsPerSecond, and remainingTime.

double SetiContainer::remainingTime  
 

Returns the estimated time (in seconds) needed to finish the work unit.

Definition at line 1071 of file seticontainer.cpp.

References progress, and progressRate.

Referenced by remainingTimeAsString.

QString SetiContainer::remainingTimeAsString  
 

Returns the estimated time needed to finish the work unit in form of a formatted string.

Definition at line 1079 of file seticontainer.cpp.

References convertTime, and remainingTime.

WUScore SetiContainer::wuScore   [inline]
 

Returns a WUScore structure containing the highest signals found in the current work unit so far.

See WUScore for details about the members of the WUScore structure.

Definition at line 187 of file seticontainer.h.

References StateFileData::max.

SpikeScore SetiContainer::spikeScore   [inline]
 

Returns a SpikeScore structure containing the highest spike found in the current work unit so far.

See SpikeScore for details about the members of the SpikeScore structure.

Definition at line 192 of file seticontainer.h.

References StateFileData::max, and WUScore::spike.

GaussianScore SetiContainer::gaussianScore   [inline]
 

Returns a GaussianScore structure containing the highest gaussian found in the current work unit so far.

See GaussianScore for details about the members of the GaussianScore structure.

Definition at line 197 of file seticontainer.h.

References WUScore::gaussian, and StateFileData::max.

PulseScore SetiContainer::pulseScore   [inline]
 

Returns a PulseScore structure containing the highest pulse found in the current work unit so far.

See PulseScore for details about the members of the PulseScore structure.

Definition at line 202 of file seticontainer.h.

References StateFileData::max, and WUScore::pulse.

TripletScore SetiContainer::tripletScore   [inline]
 

Returns a TripletScore structure containing the highest triplet found in the current work unit so far.

See TripletScore for details about the members of the TripletScore structure.

Definition at line 207 of file seticontainer.h.

References StateFileData::max, and WUScore::triplet.

int SetiContainer::userID   [inline]
 

Returns the user's id number.

Definition at line 209 of file seticontainer.h.

References UserInfoData::id.

int SetiContainer::key   [inline]
 

Returns the user's id key.

Definition at line 211 of file seticontainer.h.

References UserInfoData::key.

QString SetiContainer::userEmailAddress   [inline]
 

Returns the user's email address.

Definition at line 213 of file seticontainer.h.

References UserInfoData::email_addr.

QString SetiContainer::userName   [inline]
 

Returns the user's name.

Definition at line 215 of file seticontainer.h.

References UserInfoData::name.

QString SetiContainer::userHomepage   [inline]
 

Returns the user's homepage address.

Definition at line 217 of file seticontainer.h.

References UserInfoData::url.

QString SetiContainer::userCountry   [inline]
 

Returns the user's country.

Definition at line 219 of file seticontainer.h.

References UserInfoData::country.

int SetiContainer::userPostalCode   [inline]
 

Returns the user's postal code.

Definition at line 221 of file seticontainer.h.

References UserInfoData::postal_code.

bool SetiContainer::showName   [inline]
 

If true the user's name is allowed to be shown on the SETI@home web pages.

Definition at line 225 of file seticontainer.h.

References UserInfoData::show_name.

bool SetiContainer::showEmail   [inline]
 

If true the user's email address is allowed to be shown on the SETI@home web pages.

Definition at line 229 of file seticontainer.h.

References UserInfoData::show_email.

int SetiContainer::venue   [inline]
 

Returns the venue parameter (whatever it is good for).

Definition at line 231 of file seticontainer.h.

References UserInfoData::venue.

QString SetiContainer::registerTime   [inline]
 

Returns the time the user registered with SETI@home in form of a plain string (as stored in user_info.sah).

Definition at line 235 of file seticontainer.h.

References UserInfoData::register_time.

Referenced by registerTimeString.

QString SetiContainer::registerTimeString  
 

Returns the date and time the user registered with SETI@home in a nicely formatted string.

An empty string is returned when the information could not be found.

Definition at line 1174 of file seticontainer.cpp.

References QString::find, QString::mid, and registerTime.

QString SetiContainer::lastWUTime   [inline]
 

Returns the time the last work unit was sent to the user in form of a plain string (as stored in user_info.sah).

Note: this information is not updated any more.

Definition at line 245 of file seticontainer.h.

References UserInfoData::last_wu_time.

QString SetiContainer::lastResultTime   [inline]
 

Returns the time the user has sent his/her last work unit result to the SETI@home server in form of a plain string (as stored in user_info.sah).

Definition at line 250 of file seticontainer.h.

References UserInfoData::last_result_time.

Referenced by lastResultTimeString.

QString SetiContainer::lastResultTimeString  
 

Returns the date and time the last result was sent in a nicely formatted string.

An empty string is returned when the information could not be found.

Definition at line 1159 of file seticontainer.cpp.

References QString::find, lastResultTime, and QString::mid.

int SetiContainer::numberOfWUs   [inline]
 

Returns the number of work units sent to the user.

Note: this information is not updated any more.

Definition at line 259 of file seticontainer.h.

References UserInfoData::nwus.

int SetiContainer::numberOfResults   [inline]
 

Returns the number of results the user has sent back to the SETI@home server.

Definition at line 263 of file seticontainer.h.

References UserInfoData::nresults.

Referenced by averageCPUTime.

double SetiContainer::totalCPUTime   [inline]
 

Returns the total cpu time (in seconds) the user has processed so far.

Definition at line 266 of file seticontainer.h.

References UserInfoData::total_cpu.

Referenced by averageCPUTime.

double SetiContainer::averageCPUTime  
 

Returns the average CPU time (in seconds) required to process one work unit.

Definition at line 1152 of file seticontainer.cpp.

References numberOfResults, and totalCPUTime.

double SetiContainer::paramsIndex   [inline]
 

Returns a parameter index value.

No idea what this is good for.

Definition at line 272 of file seticontainer.h.

References UserInfoData::params_index.

QString SetiContainer::task   [inline]
 

Returns the task identifier string.

We are all in the "seti" business, aren't we?

Definition at line 276 of file seticontainer.h.

References WorkUnitData::task.

int SetiContainer::wuVersion   [inline]
 

Returns an internal version number.

This is not the version number of the SETI@home client.

Definition at line 280 of file seticontainer.h.

References WorkUnitData::version.

QString SetiContainer::wuName   [inline]
 

Returns the name of the work unit.

Definition at line 282 of file seticontainer.h.

References WorkUnitData::name.

Referenced by scanGaussianData, scanPulseData, scanSpikeData, and scanTripletData.

QString SetiContainer::wuDataType   [inline]
 

Returns the data type of the attached work unit data.

Definition at line 284 of file seticontainer.h.

References WorkUnitData::data_type.

int SetiContainer::wuDataClass   [inline]
 

Returns the data class of the attached work unit data.

Definition at line 286 of file seticontainer.h.

References WorkUnitData::data_class.

QString SetiContainer::splitterVersion   [inline]
 

Returns the version number of the splitter (software?).

Definition at line 288 of file seticontainer.h.

References WorkUnitData::splitter_version.

double SetiContainer::startRA   [inline]
 

Returns the right ascension (RA) value where the telescope has started to scan the sky for this work unit.

Definition at line 292 of file seticontainer.h.

References WorkUnitData::start_ra.

double SetiContainer::startDec   [inline]
 

Returns the declination value where the telescope has started to scan the sky for the current work unit.

Definition at line 296 of file seticontainer.h.

References WorkUnitData::start_dec.

double SetiContainer::endRA   [inline]
 

Returns the right ascension (RA) value where the telescope has stopped to scan the sky for the current work unit.

Definition at line 300 of file seticontainer.h.

References WorkUnitData::end_ra.

double SetiContainer::endDec   [inline]
 

Returns the declination value where the telescope has stopped to scan the sky for the current work unit.

Definition at line 304 of file seticontainer.h.

References WorkUnitData::end_dec.

double SetiContainer::angleRange   [inline]
 

Returns the angle range which the telescope has scanned for the current work unit.

Definition at line 308 of file seticontainer.h.

References WorkUnitData::angle_range.

Referenced by megaFlopsPerSecond.

double SetiContainer::teraFlops double    ar,
int    version = 0
 

Calculates the amount of floating point operations that need to be processed to finish a work unit depending on the angle range.

This function is based on the work of Lawrence Kirby and Roelof Engelbrecht.

Parameters:
ar  The angle range of the work unit.
version  The version of the SETI@home client as an integer value (300 is "3.00", 303 is "3.03"). If omitted, this method uses the version number found in `version.sah'.
Returns:
The number of floating point operations in TeraFlops.

Definition at line 1233 of file seticontainer.cpp.

References clientVersion.

Referenced by megaFlopsPerSecond.

double SetiContainer::megaFlopsPerSecond  
 

Returns the progress rate in MegaFlops/s.

Definition at line 1275 of file seticontainer.cpp.

References angleRange, progressRate, and teraFlops.

QString SetiContainer::timeRecorded   [inline]
 

Returns the time the work unit was recorded (as stored in in the work_unit.sah file).

Definition at line 326 of file seticontainer.h.

References WorkUnitData::time_recorded.

Referenced by timeRecordedString.

QString SetiContainer::timeRecordedString  
 

Returns the date and the time the work unit was recorded in a nicely formatted string.

An empty string is returned when the information could not be found.

Definition at line 1137 of file seticontainer.cpp.

References QString::find, QString::mid, timeRecorded, and QObject::tr.

double SetiContainer::centerFrequency   [inline]
 

Returns the subband center frequency in GHz.

Definition at line 333 of file seticontainer.h.

References WorkUnitData::subband_center.

double SetiContainer::baseFrequency   [inline]
 

Returns the subband base frequency in GHz.

Definition at line 335 of file seticontainer.h.

References WorkUnitData::subband_base.

double SetiContainer::sampleRate   [inline]
 

Returns the sample rate in Hz.

Definition at line 337 of file seticontainer.h.

References WorkUnitData::subband_sample_rate.

int SetiContainer::wuFFTLength   [inline]
 

This parameter is used internally by the SETI@home client.

Definition at line 339 of file seticontainer.h.

References WorkUnitData::fft_len.

int SetiContainer::wuIFFTLength   [inline]
 

This parameter is used internally by the SETI@home client.

Definition at line 341 of file seticontainer.h.

References WorkUnitData::ifft_len.

int SetiContainer::subbandNumber   [inline]
 

Returns the subband number.

Definition at line 343 of file seticontainer.h.

References WorkUnitData::subband_number.

QString SetiContainer::receiver   [inline]
 

Returns the identifier string of the facility that recorded the work unit.

"ao1420" defines the Arecibo Radio Telescope.

Definition at line 347 of file seticontainer.h.

References WorkUnitData::receiver.

int SetiContainer::numberOfSamples   [inline]
 

Returns the number of samples in the work unit.

Definition at line 349 of file seticontainer.h.

References WorkUnitData::nsamples.

QString SetiContainer::tapeVersion   [inline]
 

Returns the version number of the tape storing the work unit.

Definition at line 351 of file seticontainer.h.

References WorkUnitData::tape_version.

int SetiContainer::numberOfCoords   [inline]
 

Returns the number of sky coordinates that define the path of the telescope over the sky during acquisition of the work unit data.

Definition at line 355 of file seticontainer.h.

References WorkUnitData::num_positions.

QStringList SetiContainer::coords   [inline]
 

Returns a string list with all the sky coordinates that define the path of the telescope over the sky during acquisition of the work unit data.

Definition at line 360 of file seticontainer.h.

References WorkUnitData::coordinates.

int SetiContainer::clientVersion   [inline]
 

Returns the version number of the SETI@home client.

It is returned as an integer formed of both the major and the minor version number. Example: for client version 3.03, a 303 is returned.

Definition at line 366 of file seticontainer.h.

Referenced by teraFlops.

bool SetiContainer::exists int    sah
 

Checks if the file represented by sah exists.

Parameters:
sah  Can be one of the following: SC_StateFile, SC_UserInfoFile, SC_WorkUnitFile, SC_ResultFile, SC_ResultHeaderFile, or SC_WtempFile.

Definition at line 1200 of file seticontainer.cpp.

Referenced by checkClientState, readStateFile, readUserInfoFile, and readWorkUnitFile.

bool SetiContainer::isClientRunning pid_t    pid = 0,
bool    checkCmdLine = false
 

Checks if the SETI@home client is running by trying to signal the process pid.

Parameters:
pid  The process id of the client. If omitted the pid will be read from pid.sah.
checkCmdLine  If true, this method checks whether the process defined by pid is really that of a SETI@home client.
Returns:
TRUE if client is running, FALSE if it is stopped or on error.

Definition at line 1415 of file seticontainer.cpp.

References QFile::close, QString::find, getClientPid, and QFile::open.

Referenced by checkClientState.

int SetiContainer::clientState   const [inline]
 

Returns the state of the location.

Definition at line 387 of file seticontainer.h.

void SetiContainer::setClientState int    st [inline]
 

Sets the state of the location.

Setting it to -1, triggers a refresh during the next update cycle.

Definition at line 390 of file seticontainer.h.

QString SetiContainer::readEntry int    sah,
const QString   e
 

This function allows low-level access to the entries in the S@h output files.

It reads the entry e from the file sah. Use this function only if you know what you are doing!

Parameters:
sah  The file from which the entry shall be read. You can choose from four values: SC_StateFile, SC_UserInfoFile, SC_WorkUnitFile, and SC_ResultFile.
e  The entry which shall be retrieved.

Definition at line 298 of file seticontainer.cpp.

Referenced by readClientVersion, scanGaussianData, scanGaussianGraphData, scanPulseData, scanPulseGraphData, scanSpikeData,