Critical bug: electron energy offset by electron rest mass

[ftessier]

Description

A critical bug has been uncovered in EGSnrc which causes the electron energy to be offset by the value of the electron rest mass in some applications. This bug was introduced in commit 1eaf898 and is caused by the prm variable (precise rest mass) being used before it is initialized via call hatch.

Scope

Affects versions of EGSnrc downloaded between 3 February 2017 and 2 March 2017, inclusively. For those working off the develop branch, the corrupted date range is 24 January to 2 March.

Remediation

The fix involves patching three source files, as detailed in commit 805881c. The EGSnrc repository has been patched accordingly as of 1 March 2017, on both branch master (commit 805881c) and branch develop (commit 1c1cdb2).

Unfortunately, the change originally implemented to fix this bug was incomplete, and in turn caused egs++ applications to crash, as reported in issue #260. This was addressed on 2 March 2017, as documented in pull request #261, on both master (commit a4b710b) and develop (commit 71b63ec).

Recommendation

Please update your local clone accordingly, or download an up-to-date copy of EGSnrc. We recommend re-compiling and re-running simulations that relied on corrupted source code.

Details

The bug was introduced in commit 1eaf898 and is caused by the prm variable (precise rest mass) being used before it is initialized via call hatch. As far as we can tell, egs++ applications are unaffected, but the following Mortran applications (at least) are affected by the bug:

BEAMnrc
CAVRZnrc
CAVSPHnrc
DOSXYZnrc
SPRRZnrc

A typical symptom of this bug in DOSXYZnrc, for example, is that the input kinetic energy of incident electrons for monoenergetic sources became the total energy (because the rest mass prm was 0 when reading the input kinetic energy, before hatch), thus reducing the effective kinetic energy by about 0.511 MeV, hence considerably skewing the results. This is how the bug was initially discovered by Shahid Naqvi on 28 February 2017: a depth-dose curve from 5.511 MeV electrons in water matched a 5 MeV depth-dose curve obtained with an earlier version of EGSnrc.

The initial bug fix involved moving the declaration of the rest mass inside the COMIN/USEFUL/ macro in the egsnrc.macros file. Unfortunately this in turn broke C and C++ EGSnrc applications because the C interface relies on its own declaration of the COMIN/USEFUL/ macro, which also had to be updated with the rest mass data statement, accordingly.

See pull requests #256 for more details. See also related issue #260 and pull request #261.

Acknowledgements

🥇 to Shahid Naqvi for reporting and helping to diagnose this issue.
🥇 to @MartinMartinov for reporting the collateral bug with egs++ applications.