Commit 64d53818 authored by Jan Burle's avatar Jan Burle
Browse files

This is release 2.0.4

parent 9f4e01f4
This is: STeCa2 - StressTextureCalculator ver. 2.
Copyright (C) 2016 Forschungszentrum Jülich GmbH.
Released under GNU General Public License v3 or higher (see COPYING).
Authors:
Scientific Computing Group at MLZ Garching
Rebecca Brydon, Jan Burle, Antti Soininen
Based on the original STeCa by Christian Randau
Homepage: http://apps.jcns.fz-juelich.de/steca2
ver. 2.0.4, released 2016.12.01
-------------------------------
New features:
* image overlay: visualise gamma slices and 2theta bins;
show where gamma=0 is
* the "about" dialog indicates if the build is 64-bit;
startup options reset after a new version is installed
(to alert the user to that fact)
Improvements:
* raw diffractogram (before background adjustment) is plotted as dots
(to show the nature of the histogram binning)
* detector geometry defaults to 1035 / 1 mm
* image color scale adjusted to show lower counts more clearly
* add/remove file buttons moved above the file list
Bug fixes:
* more conservative memory allocation that, we hope, fixes the strange
"bad allocation" errors on some machines
* utf8 (Greek) characters replaced by ASCII strings (e.g. "gamma")
in output text files
ver. 2.0.3a (hotfix), released 2016.11.14
-----------------------------------------
......
# STeCa2: Coding Guidelines
(This file is GitHub-flavoured Markdown; a nice editor is here: https://stackedit.io/editor)
In principle we tried to follow BornAgain (BA) where appropriate.
## Qt:: & std::
The project is based in Qt. Therefore staying within Qt and using (current, not deprecated) Qt classes
and other resources is preferable. In particular, use Qt collections (`QVector`,
`QHash`, `QMap`), smart pointers (`QScopedPointer`,`QSharedPointer`) templated
functions (`qMin`,`qBound`), types (`qreal`, `quint16`), etc.,
rather than the corresponding `std::` counterparts.
A notable exception is `std::sort` (and perhaps other std algorithms).
## QtCreator
Qt Creator - a modern IDE that supports Qt development - provides syntax-aware coloring, block highlight, fast switching between header and source files, fast navigation through code, type hierarchy and usage of symbols, integration with the debugger, etc. All that improves productivity and allows code formatting with less whitespace and ornamentation.
## code formatting
### indentation and alignment
Indent by 2 spaces, no tabs!
Align code in vertical columns. It looks good, and one can quickly spot inconsistencies. Human brain is good in pattern-recognition, so why not use it? (Indentation by 2 spaces helps that we do not quickly run off the right edge.)
Compare:
```
class Exception: public QException {
public:
Exception(rcstr msg_) throw(): msg(msg_) {}
Exception(Exception const& that) throw(): msg(that.msg) {}
~Exception() throw() {}
Exception *clone() const;
void raise() const;
str msg;
};
```
with
```
class Exception: public QException {
public:
Exception(rcstr msg_) throw(): msg(msg_) {}
Exception(Exception const& that) throw(): msg(that.msg) {}
~Exception() throw() {}
Exception *clone() const;
void raise() const;
str msg;
};
```
### braces
Egyptian.
### spaces
_Yes_ between a control statement and `(` and before `{`. _No_ between a function name and `(`.
Otherwise use spaces parsimoniously. Syntax-colouring and font-variation (bold, italics) in IDEs visually separates elements that in the past had to be separated by spaces. That way spaces and blank lines can be saved for where it matters. The best (arguably) is: colour and font-coding provides the grain, while more of text fits on one screen concisely.
```
int foo(int n) {
for_i (n) {
int square = i*i;
}
switch (i) {
case 0:
break;
default:
break;
}
}
```
## Comments & doxygen
BA uses Qt-style doxygen tags `/*!`. So do we in the _boilerplate headers_, otherwise we use `///`.
Doxygen comments should be only in header files.
Make the code read like a story - then it does not need much commenting.
Use comments to express intentions, and to explain what is not included in or
understandable from code. Be brief and concise. Do not repeat what the code says.
## class - struct
Classes have hidden data members and are mainly about the interface; structs have public data members and almost no member functions - perhaps only a constructor, assignment, equality operator.
### class accessor method names
- use `foo()` and `setFoo(...)` to access `foo_`.
- use `get...` if it really goes and fetches something.
- use `calc...` if it does a costly calculation.
### struct members
Directly accessible, such as `dataPoint.x`. No accessor methods.
## names of things
- Classes: camel case, begin with uppercase.
- Variables: camel case, begin with lowercase. Use descriptive names, the longer the
scope and life span, the longer the name.
- Permissible one-letter names: `i`, `n`, `x`, `y`, etc.
- Permissible two-letter names: `ij`, `xy` (coordinates)
- Permissible three-letter names (or parts of names):
`min`, `max`, `res` (result), `val` (value), `msg` (message), `add`,
`rem` (remove), `del` (delete), `fun` (that's what we have, kids),
`rge` (range), `avg`, etc.
- Plurals: whatever name ends in -s is a collection of some sort.
Cf. `inten`(sity) and `intens`(ities).
- data members of *classes*: postfixed with `_`
- data members of *structs*: do not decorate
- lists: `..._lst`, e.g. `typedef QStringList str_lst;`
- vectors: `..._vec`, e.g. `typedef QVector<qreal> qreal_vec;`, `typedef QVector<uint> uint_vec;`
- typedefs of primitive types and structs: `..._t`, e.g. `typedef float inten_t;`
- reference const typedefs prefix with `rc...`, e.g. `rcJson`.
## `typedef` & `using`
Use `typedef` to type-define types (globally). Use `using` for local-scope aliases.
## auto
Be careful with `auto` (copy) v. `auto &` (reference).
Also use `auto const&` to make the point.
## polymorphism
There is no real need to mark overriden virtual methods as `virtual` and/or
`override`; the syntax colouring in Qt Creator does it nicely.
## prefix ++
If there can be both, `++i` is better than `i++`, although people usually do the
opposite.
## postpositive `const`
C++ syntax allows `const` that modifies a type to either precede or follow the
type name. One can be English or French.
- English (pre-positive): red mill; constant integer, `const int`
- French (post-positive): moulin rouge; integer constant, `int const`
Would you rather eat English or French cuisine? Also, tt is productive to
organize code in simple visual patterns, such as aligned columns.
Compare:
```
int a = 1;
const int b = 2;
```
with
```
int a = 1;
int const b = 2;
```
Also, the `const`s that modify `this` and `*` are post-positive.
Why then not all `const`s? Compare:
```
class C {
const int * const foo() const;
};
```
with
```
class C {
int const * const foo() const;
// each const modifies the preceding thing
};
```
Q.E.D.
## useful macros
### SUPER
The macro SUPER is super handy. It defines aliases:
- `thisClass` for the current class,
- `super` for the superclass.
### for_i, for_int, for_ij
Use `for_i (n)` instead of the full idiomatic
```
for (int i=0, iEnd=(n); i<iEnd; ++i)
```
`for_int (v,n)` instead
```
for (int v=0, vEnd=(n); v<vEnd; ++v)
```
and `for_ij(m,n)` instead of
```
for_int (i,m)
for_int (j,n)
```
## the choice of float and double
If saving space is required, use `float`. If specifically 64b floating point is required, use `double`. (In both cases consider an appropriate `typedef`.)
Otherwise, which is in most cases, use `qreal`.
## the choice of int and uint
If negative values cannot be, use `uint` to express it. There is a rub: in many places in libraries (Qt etc.), `int` is used instead. The probable reason is that with `uint`s one can be careful when it comes to underflows. Therefore we must occasionally cast our `uint`s to `int`s or the other way.
Remember, when casting `int` to `uint`, it must be guaranteed that its value is non-negative. When casting `uint` to `int`, one loses half the range (is 2 billion enough?).
## Exceptions
Exceptions happen; therefore write exception-safe code (did we mention `QScopedPointer`?) Throw an `Exception` if something goes wrong, namely if data are incorrect during import of data files. To do that, use `THROW` and `RUNTIME_CHECK` macros; mark yer functions that do throw exceptions with `THROWS`.
### Debug time
Use:
- `ASSERT`
- `TR`
- `WT`
- `NEVER_HERE`
## Refactoring
Consider:
- abstraction is good, unless it has an undue impact on performance
- eliminate clutter of all sorts
- descriptive names
- enforce consistency
- Simplify, simplify, simplify!
- Discard, discard, discard!
## Templates
### header file
```
// ************************************************************************** //
//
// STeCa2: StressTexCalculator ver. 2
//
//! @file <file_name.h>
//! @brief <brief_description>
//!
//! @homepage http://apps.jcns.fz-juelich.de/steca2
//! @license GNU General Public License v3 or higher (see COPYING)
//! @copyright Forschungszentrum Jülich GmbH 2016
//! @authors Scientific Computing Group at MLZ Garching
//! @authors Original version: Christian Randau
//! @authors Version 2: Antti Soininen, Jan Burle, Rebecca Brydon
//
// ************************************************************************** //
#ifndef <GUARD>
#define <GUARD>
#include "other Steca headers"
#include <Qt includes>
namespace <name> {
//------------------------------------------------------------------------------
//------------------------------------------------------------------------------
}
#endif //<GUARD>
```
### source file
```
// ************************************************************************** //
//
// STeCa2: StressTexCalculator ver. 2
//
//! @file <file_name.cpp>
//!
//! @homepage http://apps.jcns.fz-juelich.de/steca2
//! @license GNU General Public License v3 or higher (see COPYING)
//! @copyright Forschungszentrum Jülich GmbH 2016
//! @authors Scientific Computing Group at MLZ Garching
//! @authors Original version: Christian Randau
//! @authors Version 2: Antti Soininen, Jan Burle, Rebecca Brydon
//
// ************************************************************************** //
#include "file_name.h"
#include "other Steca headers"
#include <Qt includes>
namespace core {
//------------------------------------------------------------------------------
//------------------------------------------------------------------------------
}
// eof
```
Notes:
- @brief is not needed in .cpp
- do prefer includes in .cpp file, forward declarations in .h
### class definition
```cpp
//! @class <name>
class SimpleFunction: public Function {
SUPER(SimpleFunction,Function)
public:
};
```
(eof)
/*******************************************************************************
* STeCa2 - StressTextureCalculator ver. 2
*
* Copyright (C) 2016 Forschungszentrum Jülich GmbH 2016
*
* This program is free software: you can redistribute it and/or modify it
* under the terms of the GNU General Public License as published by the Free
* Software Foundation, either version 3 of the License, or (at your option)
* any later version.
*
* This program is distributed in the hope that it will be useful, but
* WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
* or FITNESS FOR A PARTICULAR PURPOSE.
*
* See the COPYING and AUTHORS files for more details.
******************************************************************************/
#ifndef TYP_ARRAY2D_H
#define TYP_ARRAY2D_H
#include "def/defs.h"
#include "def/def_compare.h"
#include "typ/typ_vec.h"
namespace typ {
//------------------------------------------------------------------------------
struct size2d {
CLS(size2d)
uint w, h;
size2d() : size2d(0, 0) {}
size2d(uint w_, uint h_) : w(w_), h(h_) {}
bool isEmpty() const {
return 0 == w && 0 == h;
}
uint count() const {
return w * h;
}
int compare(rc that) const {
COMPARE_VALUE(w)
COMPARE_VALUE(h)
return 0;
}
friend bool operator==(rc s1, rc s2) {
return s1.w == s2.w && s1.h == s2.h;
}
friend bool operator!=(rc s1, rc s2) {
return !(s1 == s2);
}
friend size2d operator-(rc s1, rc s2) {
int w = to_i(s1.w) - to_i(s2.w);
int h = to_i(s1.h) - to_i(s2.h);
return size2d(to_u(qMax(w, 0)), to_u(qMax(h, 0)));
}
size2d transposed() const {
return size2d(h, w);
}
size2d scaled(qreal f) const {
f = qMax(f, .0);
return size2d(to_u(qRound(w*f)), to_u(qRound(h*f)));
}
};
// 2D (indexed by uint i/j) array
template<typename T> class Array2D {
public:
// empty array
Array2D(): size_(0,0) {
}
// is empty?
bool isEmpty() const {
return 0 == count();
}
// 2D image size
size2d::rc size() const {
return size_;
}
// number of elements
uint count() const {
return size_.count();
}
// make empty
void clear() {
fill(T(), size2d(0,0));
}
// allocate and fill with a value
void fill(T const& val, size2d const& size) {
size_ = size; // set size first
ts_.fill(val, count());
}
// allocate and fill with a default value
void fill(size2d::rc size) {
fill(T(), size);
}
// Calculate the 1D index of an element. Row by row.
uint index(uint i, uint j) const {
return i + j * size_.w;
}
// access using 1D index
T const& at(uint i) const {
return ts_.at(i);
}
// access using 2D index
T const& at(uint i, uint j) const {
return ts_.at(index(i,j));
}
// set using 1D index
void setAt(uint i, T const& val) {
ts_[i] = val;
}
// set using 2D index
void setAt(uint i, uint j, T const& val) {
ts_[index(i,j)] = val;
}
// raw access
T* data() {
return ts_.data();
}
// raw access
T const* data() const {
return const_cast<Array2D*>(this)->data();
}
// subscript operator
T& operator[](uint i) {
return ts_[i];
}
// subscript operator
T const& operator[](uint i) const {
return const_cast<Array2D*>(this)[i];
}
protected:
size2d size_;
vec<T> ts_;
};
//------------------------------------------------------------------------------
}
#endif // TYP_ARRAY2D_H
// ************************************************************************** //
//
// STeCa2: StressTextureCalculator ver. 2
//
//! @file calc_lens.cpp
//!
//! @homepage http://apps.jcns.fz-juelich.de/steca2
//! @license GNU General Public License v3 or higher (see COPYING)
//! @copyright Forschungszentrum Jülich GmbH 2016
//! @authors Scientific Computing Group at MLZ Garching
//! @authors Rebecca Brydon, Jan Burle, Antti Soininen
//! @authors Based on the original STeCa by Christian Randau
//
// ************************************************************************** //
/*******************************************************************************
* STeCa2 - StressTextureCalculator ver. 2
*
* Copyright (C) 2016 Forschungszentrum Jülich GmbH 2016
*
* This program is free software: you can redistribute it and/or modify it
* under the terms of the GNU General Public License as published by the Free
* Software Foundation, either version 3 of the License, or (at your option)
* any later version.
*
* This program is distributed in the hope that it will be useful, but
* WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
* or FITNESS FOR A PARTICULAR PURPOSE.
*
* See the COPYING and AUTHORS files for more details.
******************************************************************************/
#include "calc/calc_lens.h"
#include "session.h"
......@@ -107,7 +109,7 @@ inten_t ImageLens::imageInten(uint i, uint j) const {
inten_t inten = image_.inten(i, j);
if (intensCorr_)
inten *= intensCorr_->at(i, j);
inten *= intensCorr_->inten(i, j);
return inten;
}
......
// ************************************************************************** //
//
// STeCa2: StressTextureCalculator ver. 2
//
//! @file calc_lens.h
//! @brief The lens system
//!
//! @homepage http://apps.jcns.fz-juelich.de/steca2
//! @license GNU General Public License v3 or higher (see COPYING)
//! @copyright Forschungszentrum Jülich GmbH 2016
//! @authors Scientific Computing Group at MLZ Garching
//! @authors Rebecca Brydon, Jan Burle, Antti Soininen
//! @authors Based on the original STeCa by Christian Randau
//
// ************************************************************************** //
/*******************************************************************************
* STeCa2 - StressTextureCalculator ver. 2
*
* Copyright (C) 2016 Forschungszentrum Jülich GmbH 2016
*
* This program is free software: you can redistribute it and/or modify it
* under the terms of the GNU General Public License as published by the Free
* Software Foundation, either version 3 of the License, or (at your option)
* any later version.
*
* This program is distributed in the hope that it will be useful, but
* WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
* or FITNESS FOR A PARTICULAR PURPOSE.
*
* See the COPYING and AUTHORS files for more details.
******************************************************************************/
#ifndef CALC_LENS_H
#define CALC_LENS_H
......
// ************************************************************************** //
//
// STeCa2: StressTextureCalculator ver. 2
//
//! @file calc_polefigure.cpp
//!
//! @homepage http://apps.jcns.fz-juelich.de/steca2
//! @license GNU General Public License v3 or higher (see COPYING)
//! @copyright Forschungszentrum Jülich GmbH 2016
//! @authors Scientific Computing Group at MLZ Garching
//! @authors Rebecca Brydon, Jan Burle, Antti Soininen
//! @authors Based on the original STeCa by Christian Randau
//
// ************************************************************************** //
/*******************************************************************************