Developers' Guide

This page contains details on LibGeoDecomp's internals. We don't have a terrible lot of documentation online as most of the team work at FAU. However, here are some starting points.

  • The trunk is hosted on GitHub. You can also report bugs there.
    Status: Travis CI: ,
  • Mainline development goes through GentryX' repository. Changes get merged to trunk automatically once they clear CI tests.
    Status: Travis CI: ,
  • The API documentation is available here.
LibGeoDecomp is written in 1TBS (one true brace style) and mostly follows the coding style of Qt and KDE. Compliance is important to keep the codebase consistent and readable.
  • Pass primitive types (int, double, char, size_t) by value, all others as const references. Exception: if a function is meant to modify its parameters, then pass those as pointers.
  • Use const TYPE& var instead of TYPE const & var.
  • Don't repeat yourself! When writing comments, please focus on the WHY and not the WHAT. What the code does, should be obvious from the method name and/or code itself. Don't repeat yourself. But if your code is doing something complex or counterintuitive, a short explanation would be helpful.
  • Sometimes you'll need to bind template arguments of a frequently used type in a typedef, e.g. typedef typename CELL_TYPE::Topology Topology. (see example on the right).
  • Header guards are also all caps with underscores. The are simply the path of the given file within the source repositiory, e.g. #ifndef LIBGEODECOMP_MISC_GRID_H for misc/grid.h.
  • Layout:
    • Indentation: 4 spaces, no tabs
    • No indentation for namespaces
    • No trailing whitespace
  • Naming conventions
    • Use CamelCase for classes, typenames, functions, variables. All types are capitalized, all functions and variables start with lower case characters.
    • ALL_CONSTANTS are all caps, delimited by underscores.
    • Please don't shorten variable names to crptcAbvtns or single letters. No one can remember what k2, alpha, xx and such mean, not even you. Bytes are cheap these days. Why not use descriptiveNames?
namespace LibGeoDecomp {

template<typename CARGO>
class Container
{
public:
    friend class ThatOtherClass;
    typedef typename CARGO::Topology Topology;
    static const int DIM = Topology::DIM;

    inline Container(size_t size, const CARGO& default)
    {
        myData = new CARGO[size];
        for (size_t i = 0; i < size; ++i) {
          myData[i] = default;
        }
    }

    ~Container()
    {
        delete myData;
    }

    inline void setFront(const CARGO& newFront)
    {
        myData[0] = newFront;
    }

    /**
     * Will exchange 
     */
    inline void swapFront(CARGO *newFront)
    {
        std::swap(myData[0], *newFront);
    }

    inline CARGO *data()
    {
      return myData;
    }
};

}

Lines of Code

The C++ stats include libgeodecomp/src only; the build system includes all CMake files and the TypemapGenerator. All stats exclude generated files.

lines of code vs. revisions

Revisions vs. Time

revisions vs. date

Fixmes

How often does the term fixme occur in the code? (Fewer would be better.)

occurrences of term FIXME vs. revisions arrow down, label: better

Undocumented Classes

How many classes lack (basic) documentation?

number of undocumented classes vs. revisions arrow down, label: better

Unmatched Header Guards

number of unmatched header guards vs. revisions arrow down, label: better

Bad Includes

number of bad includes vs. revisions arrow down, label: better

size_t Misuse

How often is size_t used instead of std::size_t?

number of size_t misuse vs. revisions arrow down, label: better

Performance plots typically use seconds (s, the fewer the better) or Giga Lattice Updates Per Second (GLUPS, the more the better) as their unit of measure. They contain multiple curves which compare implementations based on LibGeoDecomp with manual implementations. The names of the curves indicate which kind of implementation was used:

  • Metal names (bronze, silver, gold, platinum) are assigned to implementations which use LibGeoDecomp, with bronze being the least optimized implementation and platinum representing the highest degree of ptimization.
  • Spices (vanilla, pepper) are used for manual, mostly C-style implementations. They mimic the codes developers would need to write if the had no access to LibGeoDecomp. Vanilla is typically a very basic code, while pepper may contain optimizations.

Please mind the different scales in the plots. Some benchmarks were introduced at different times to the various architectures, which is why the horizontal scales differ. And of course the vertical scales differ, too, as the different hardware architectures yield different levels of performance.

1. Mini Apps

This category contains multiple mini apps which are identical, or at least good representatives of those kernels found in actual simulation codes. They were chosen so that they allow comparison with competing implementations. We are testing a Lattice Boltzmann Method (LBM, D3Q19), a Reverse Time Migration (RTM, 3D), and a Jacobi smoother (7-point stencil), as well as some tests for unstructured grids (SPMVM, with SELL-C-Sigma storage).

LBM (Tesla K20c, Kepler)

arrow up, label: better

Show: last Month, last week, all

LBM (Tesla K40m, Kepler40)

arrow up, label: better

Show: last Month, last week, all

LBM (Tesla K80, Kepler80)

arrow up, label: better

Show: last Month, last week, all

LBM (E5-2660 v3, HaswellEP)

arrow up, label: better

Show: last Month, last week, all

LBM (E5-2670 v2, IvyBridgeEP)

arrow up, label: better

Show: last Month, last week, all

LBM (X5650, Nehalem)

arrow up, label: better

Show: last Month, last week, all

LBM (E5-2690, SandyBridgeEP)

arrow up, label: better

Show: last Month, last week, all

RTM (Tesla K20c, Kepler)

arrow up, label: better

Show: last Month, last week, all

RTM (Tesla K40m, Kepler40)

arrow up, label: better

Show: last Month, last week, all

RTM (Tesla K80, Kepler80)

arrow up, label: better

Show: last Month, last week, all

Jacobi3D (E5-2660 v3, HaswellEP)

arrow up, label: better

Show: last Month, last week, all

Jacobi3D (E5-2670 v2, IvyBridgeEP)

arrow up, label: better

Show: last Month, last week, all

Jacobi3D (X5650, Nehalem)

arrow up, label: better

Show: last Month, last week, all

Jacobi3D (E5-2690, SandyBridgeEP)

arrow up, label: better

Show: last Month, last week, all

SPMVM (E5-2660 v3, HaswellEP)

arrow up, label: better

Show: last Month, last week, all

SPMVM (E5-2670 v2, IvyBridgeEP)

arrow up, label: better

Show: last Month, last week, all

SPMVM (X5650, Nehalem)

arrow up, label: better

Show: last Month, last week, all

SPMVM (E5-2690, SandyBridgeEP)

arrow up, label: better

Show: last Month, last week, all

SELLInit (E5-2660 v3, HaswellEP)

arrow down, label: better

Show: last Month, last week, all

SELLInit (E5-2670 v2, IvyBridgeEP)

arrow down, label: better

Show: last Month, last week, all

SELLInit (X5650, Nehalem)

arrow down, label: better

Show: last Month, last week, all

SELLInit (E5-2690, SandyBridgeEP)

arrow down, label: better

Show: last Month, last week, all

2. Geometry Subsystem

The geometry subsystem is responsible for the domain decomposition. (I.e. which parts of the grid are assigned to which node and how can we determine halos and traverse the coordinates?) Their primary purpose is to discover involuntary performance degradations.

CoordEnumeration (E5-2660 v3, HaswellEP)

arrow down, label: better

Show: last Month, last week, all

CoordEnumeration (E5-2670 v2, IvyBridgeEP)

arrow down, label: better

Show: last Month, last week, all

CoordEnumeration (X5650, Nehalem)

arrow down, label: better

Show: last Month, last week, all

CoordEnumeration (E5-2690, SandyBridgeEP)

arrow down, label: better

Show: last Month, last week, all

FloatCoordAccumulation (E5-2660 v3, HaswellEP)

arrow down, label: better

Show: last Month, last week, all

FloatCoordAccumulation (E5-2670 v2, IvyBridgeEP)

arrow down, label: better

Show: last Month, last week, all

FloatCoordAccumulation (X5650, Nehalem)

arrow down, label: better

Show: last Month, last week, all

FloatCoordAccumulation (E5-2690, SandyBridgeEP)

arrow down, label: better

Show: last Month, last week, all

RegionCount (E5-2660 v3, HaswellEP)

arrow down, label: better

Show: last Month, last week, all

RegionCount (E5-2670 v2, IvyBridgeEP)

arrow down, label: better

Show: last Month, last week, all

RegionCount (X5650, Nehalem)

arrow down, label: better

Show: last Month, last week, all

RegionCount (E5-2690, SandyBridgeEP)

arrow down, label: better

Show: last Month, last week, all

RegionInsert (E5-2660 v3, HaswellEP)

arrow down, label: better

Show: last Month, last week, all

RegionInsert (E5-2670 v2, IvyBridgeEP)

arrow down, label: better

Show: last Month, last week, all

RegionInsert (X5650, Nehalem)

arrow down, label: better

Show: last Month, last week, all

RegionInsert (E5-2690, SandyBridgeEP)

arrow down, label: better

Show: last Month, last week, all

RegionIntersect (E5-2660 v3, HaswellEP)

arrow down, label: better

Show: last Month, last week, all

RegionIntersect (E5-2670 v2, IvyBridgeEP)

arrow down, label: better

Show: last Month, last week, all

RegionIntersect (X5650, Nehalem)

arrow down, label: better

Show: last Month, last week, all

RegionIntersect (E5-2690, SandyBridgeEP)

arrow down, label: better

Show: last Month, last week, all

RegionSubtract (E5-2660 v3, HaswellEP)

arrow down, label: better

Show: last Month, last week, all

RegionSubtract (E5-2670 v2, IvyBridgeEP)

arrow down, label: better

Show: last Month, last week, all

RegionSubtract (X5650, Nehalem)

arrow down, label: better

Show: last Month, last week, all

RegionSubtract (E5-2690, SandyBridgeEP)

arrow down, label: better

Show: last Month, last week, all

RegionUnion (E5-2660 v3, HaswellEP)

arrow down, label: better

Show: last Month, last week, all

RegionUnion (E5-2670 v2, IvyBridgeEP)

arrow down, label: better

Show: last Month, last week, all

RegionUnion (X5650, Nehalem)

arrow down, label: better

Show: last Month, last week, all

RegionUnion (E5-2690, SandyBridgeEP)

arrow down, label: better

Show: last Month, last week, all

RegionExpand1 (E5-2660 v3, HaswellEP)

arrow down, label: better

Show: last Month, last week, all

RegionExpand1 (E5-2670 v2, IvyBridgeEP)

arrow down, label: better

Show: last Month, last week, all

RegionExpand1 (X5650, Nehalem)

arrow down, label: better

Show: last Month, last week, all

RegionExpand1 (E5-2690, SandyBridgeEP)

arrow down, label: better

Show: last Month, last week, all

RegionExpand5 (E5-2660 v3, HaswellEP)

arrow down, label: better

Show: last Month, last week, all

RegionExpand5 (E5-2670 v2, IvyBridgeEP)

arrow down, label: better

Show: last Month, last week, all

RegionExpand5 (X5650, Nehalem)

arrow down, label: better

Show: last Month, last week, all

RegionExpand5 (E5-2690, SandyBridgeEP)

arrow down, label: better

Show: last Month, last week, all

PartitionHIndexing (E5-2660 v3, HaswellEP)

arrow down, label: better

Show: last Month, last week, all

PartitionHIndexing (E5-2670 v2, IvyBridgeEP)

arrow down, label: better

Show: last Month, last week, all

PartitionHIndexing (X5650, Nehalem)

arrow down, label: better

Show: last Month, last week, all

PartitionHIndexing (E5-2690, SandyBridgeEP)

arrow down, label: better

Show: last Month, last week, all

PartitionStriping (E5-2660 v3, HaswellEP)

arrow down, label: better

Show: last Month, last week, all

PartitionStriping (E5-2670 v2, IvyBridgeEP)

arrow down, label: better

Show: last Month, last week, all

PartitionStriping (X5650, Nehalem)

arrow down, label: better

Show: last Month, last week, all

PartitionStriping (E5-2690, SandyBridgeEP)

arrow down, label: better

Show: last Month, last week, all

PartitionHilbert (E5-2660 v3, HaswellEP)

arrow down, label: better

Show: last Month, last week, all

PartitionHilbert (E5-2670 v2, IvyBridgeEP)

arrow down, label: better

Show: last Month, last week, all

PartitionHilbert (X5650, Nehalem)

arrow down, label: better

Show: last Month, last week, all

PartitionHilbert (E5-2690, SandyBridgeEP)

arrow down, label: better

Show: last Month, last week, all

PartitionZCurve (E5-2660 v3, HaswellEP)

arrow down, label: better

Show: last Month, last week, all

PartitionZCurve (E5-2670 v2, IvyBridgeEP)

arrow down, label: better

Show: last Month, last week, all

PartitionZCurve (X5650, Nehalem)

arrow down, label: better

Show: last Month, last week, all

PartitionZCurve (E5-2690, SandyBridgeEP)

arrow down, label: better

Show: last Month, last week, all

PartMngr3D(RecursiveBisection) (E5-2660 v3, HaswellEP)

arrow down, label: better

Show: last Month, last week, all

PartMngr3D(RecursiveBisection) (E5-2670 v2, IvyBridgeEP)

arrow down, label: better

Show: last Month, last week, all

PartMngr3D(RecursiveBisection) (X5650, Nehalem)

arrow down, label: better

Show: last Month, last week, all

PartMngr3D(RecursiveBisection) (E5-2690, SandyBridgeEP)

arrow down, label: better

Show: last Month, last week, all

PartMngr3D(ZCurve) (E5-2660 v3, HaswellEP)

arrow down, label: better

Show: last Month, last week, all

PartMngr3D(ZCurve) (E5-2670 v2, IvyBridgeEP)

arrow down, label: better

Show: last Month, last week, all

PartMngr3D(ZCurve) (X5650, Nehalem)

arrow down, label: better

Show: last Month, last week, all

PartMngr3D(ZCurve) (E5-2690, SandyBridgeEP)

arrow down, label: better

Show: last Month, last week, all

3. MPI

Some of our components naturally rely on MPI. This set of benchmarks evaluates how well they perform.

PatchLink(TestCell(3) ) (E5-2660 v3, HaswellEP)

arrow up, label: better

Show: last Month, last week, all

PatchLink(TestCell(3) ) (E5-2670 v2, IvyBridgeEP)

arrow up, label: better

Show: last Month, last week, all

PatchLink(TestCell(3) ) (X5650, Nehalem)

arrow up, label: better

Show: last Month, last week, all

PatchLink(TestCell(3) ) (E5-2690, SandyBridgeEP)

arrow up, label: better

Show: last Month, last week, all

PatchLink(MySimpleCell) (E5-2660 v3, HaswellEP)

arrow up, label: better

Show: last Month, last week, all

PatchLink(MySimpleCell) (E5-2670 v2, IvyBridgeEP)

arrow up, label: better

Show: last Month, last week, all

PatchLink(MySimpleCell) (X5650, Nehalem)

arrow up, label: better

Show: last Month, last week, all

PatchLink(MySimpleCell) (E5-2690, SandyBridgeEP)

arrow up, label: better

Show: last Month, last week, all

CollectingWriter(TestCell(3) ) (E5-2660 v3, HaswellEP)

arrow up, label: better

Show: last Month, last week, all

CollectingWriter(TestCell(3) ) (E5-2670 v2, IvyBridgeEP)

arrow up, label: better

Show: last Month, last week, all

CollectingWriter(TestCell(3) ) (X5650, Nehalem)

arrow up, label: better

Show: last Month, last week, all

CollectingWriter(TestCell(3) ) (E5-2690, SandyBridgeEP)

arrow up, label: better

Show: last Month, last week, all

CollectingWriter(MySimpleCell) (E5-2660 v3, HaswellEP)

arrow up, label: better

Show: last Month, last week, all

CollectingWriter(MySimpleCell) (E5-2670 v2, IvyBridgeEP)

arrow up, label: better

Show: last Month, last week, all

CollectingWriter(MySimpleCell) (X5650, Nehalem)

arrow up, label: better

Show: last Month, last week, all

CollectingWriter(MySimpleCell) (E5-2690, SandyBridgeEP)

arrow up, label: better

Show: last Month, last week, all

4. HPX

This section contains performance tests which utilize the HPX backend. HPX is the first implementation of the upcoming C++ standard for concurrency and parallelism.

HPXBusyworkCell (E5-2660 v3, HaswellEP)

arrow up, label: better

Show: last Month, last week, all

HPXBusyworkCell (E5-2670 v2, IvyBridgeEP)

arrow up, label: better

Show: last Month, last week, all

HPXBusyworkCell (E5-2690, SandyBridgeEP)

arrow up, label: better

Show: last Month, last week, all

5. LibFlatArray

LibFlatArray performance, as reported by libflatarray/examples/performance_tests.

JacobiD3Q7 (E5-2660 v3, HaswellEP)

arrow up, label: better

Show: last Month, last week, all

JacobiD3Q7 (E5-2670 v2, IvyBridgeEP)

arrow up, label: better

Show: last Month, last week, all

JacobiD3Q7 (X5650, Nehalem)

arrow up, label: better

Show: last Month, last week, all

JacobiD3Q7 (E5-2690, SandyBridgeEP)

arrow up, label: better

Show: last Month, last week, all

NBody (E5-2660 v3, HaswellEP)

arrow up, label: better

Show: last Month, last week, all

NBody (E5-2670 v2, IvyBridgeEP)

arrow up, label: better

Show: last Month, last week, all

NBody (X5650, Nehalem)

arrow up, label: better

Show: last Month, last week, all

NBody (E5-2690, SandyBridgeEP)

arrow up, label: better

Show: last Month, last week, all

ParticleMover (E5-2660 v3, HaswellEP)

arrow down, label: better

Show: last Month, last week, all

ParticleMover (E5-2670 v2, IvyBridgeEP)

arrow down, label: better

Show: last Month, last week, all

ParticleMover (X5650, Nehalem)

arrow down, label: better

Show: last Month, last week, all

ParticleMover (E5-2690, SandyBridgeEP)

arrow down, label: better

Show: last Month, last week, all

ParticleInteractor (E5-2660 v3, HaswellEP)

arrow down, label: better

Show: last Month, last week, all

ParticleInteractor (E5-2670 v2, IvyBridgeEP)

arrow down, label: better

Show: last Month, last week, all

ParticleInteractor (X5650, Nehalem)

arrow down, label: better

Show: last Month, last week, all

ParticleInteractor (E5-2690, SandyBridgeEP)

arrow down, label: better

Show: last Month, last week, all

ConditionalAny (E5-2660 v3, HaswellEP)

arrow down, label: better

Show: last Month, last week, all

ConditionalAny (E5-2670 v2, IvyBridgeEP)

arrow down, label: better

Show: last Month, last week, all

ConditionalAny (X5650, Nehalem)

arrow down, label: better

Show: last Month, last week, all

ConditionalAny (E5-2690, SandyBridgeEP)

arrow down, label: better

Show: last Month, last week, all

last modified: Wed Nov 30 17:16:41 2016 +0100