[[PageOutline]]

= Dealing with numerical discrepancies =

Most numerical applications produce different outcomes for a given workunit
depending on the machine architecture, operating system, compiler, and compiler flags.
For some applications these discrepancies produce only small differences in the final output,
 and results can be validated using a 'fuzzy comparison' function that allows for deviations of a few percent.

Other applications are 'divergent' in the sense that small numerical differences lead to unpredictably large differences in the final output.
For such applications it may be difficult to distinguish between results that are correct
but differ because of numerical discrepancies, and results that are erroneous.
The 'fuzzy comparison' approach does not work for such applications.

== Eliminating discrepancies ==

One approach is to eliminate numerical discrepancies.
Some notes on how to do this for Fortran programs are given in a paper,
[//MOM1MP01.pdf Massive Tracking on Heterogeneous Platforms] and in an earlier [//fortran_numerics.txt text document],
both courtesy of Eric !McIntosh from CERN.

== Homogeneous redundancy ==

BOINC provides a feature called '''homogeneous redundancy''' (HR) to handle divergent applications.
HR divides hosts into 'numerical equivalence classes':
two hosts are in the same class if they return identical results for your applications.
The BOINC scheduler will send results for a given workunit only to hosts in the same class;
this lets you use strict equality to compare redundant results.

You can enable HR for a project by including the line
{{{
<homogeneous_redundancy>N</homogeneous_redundancy>
}}}
in the [ProjectConfigFile config.xml] file, where N is the "HR type" to use (see below).

Alternatively, you can enable HR for a single application by setting the `homogeneous_redundancy` field
in its database record to the HR type for use with that application.

An "HR type" is a host classification.
Currently the following HR types are defined:

 0:: No homogeneous redundancy (all hosts are numerically equivalent)
 1:: A fine-grained classification with 80 classes (4 OS and 20 CPU types).
 2:: A coarse-grained classification in which there are 4 classes: Windows, Linux, Mac-PPC and Mac-Intel.

The proper classification depends on your application,
and how it's compiled (compiler, compiler options, math libraries) on the various platforms.
For example, WCG reports that the following gcc options (on Linux) cause their apps to produce identical results on all processor types:
{{{
-mieee-fp -O3 -fno-rtti -ffor-scope -DNDEBUG
}}}
This allows them to use HR type 2.

There are two ways to find what HR type is needed for a given application.
The bottom-up approach is to use a fine classification,
and (by manually examining result files)
identify classes that can be merged.
The top-down approach is to use a coarse classification (e.g., 0)
and (by analyzing the hosts involved in validation failures)
identify host types that must go in separate classes.

You can modify the pre-defined HR types, or add your own, by editing the file
'''sched/hr.cpp'''.

== Scheduling considerations ==

When HR is used, once an instance of a job has been sent to a host,
the job is "committed" to the HR class of that host.
This can potentially lead to a situation where the scheduler's
[ProjectOptions#Job-cachescheduling job cache]
contains only jobs committed to a particular HR class,
and hosts of other HR classes won't get jobs.
You can use the '''show_shmem''' command to check whether this is happening.

For most projects this doesn't occur.
If it does, BOINC provides a mechanism that allocates slots in the job cache
to different HR classes, in proportion to the aggregate processing rate
of hosts in each class.
To enable this, put
{{{
<hr_allocate_slots/>
}}}
in your '''config.xml''' file.

If you use this mechanism, you must periodically run a program called '''census'''
that computes the shares for each HR class.
To do so, add the following config.xml entry:
{{{
<task>
   <cmd>census</cmd>
   <period>1 day</period>
</task>
}}}

The BOINC distribution includes a file '''sched/sample_hr_info.txt'''
containing host-distribution data from a large project.
You can use this e.g., during the period when your project is starting up
and doesn't have a lot of hosts yet.
Copy it to your project's root directory as '''hr_info.txt'''.

If you send the feeder a SIGUSR1 signal,
it will write a summary of shared-memory contents,
and allocations among HR classes, to its log file.
This may be useful in debugging problems related to HR.

== Specifying the HR class of jobs ==

Normally a job's HR class is determined on the fly;
it's determined by the host that is issued the first instance of the job.

You can also specify the HR class of jobs [JobSubmission when they're created].
If you do this, put
{{{
<hr_class_static/>
}}}
in your config.xml file.
This suppresses a mechanism that clears the HR class of a job
if an instance fails and there are no other instances in progress or finished.

== Changing an app's HR type ==

Don't change an application's HR type while there are jobs in progress;
the meaning of HR classes will change,
and jobs will be "stranded" in non-existent HR classes.

Instead, you can either:

 * Wait until there are no jobs in progress,
  either by waiting for them to finish or by canceling workunits using the [HtmlOps administrative web page]
 * Create a new application.