Versioning

How EGSnrc is versioned

Every change in a git repository is uniquely identified with a 40 hexadecimal digits hash value (a 160-bit SHA1 hash). This is useful to refer to a specific point in the EGSnrc code history, for example, commit 98c008213fef79506e6d9e87a444a139b0f79cc5 (in practice it proves sufficient to quote the first 7 characters 98c0082 to identify any particular commit, or more characters if there is a collision). The git log -1 command shows the current commit hash if you have installed EGSnrc by cloning its repository.

The commit hash is the most unambiguous way to refer to the EGSnrc version in question: it is a permanent reference to a unique and atomic point in the evolution of the software. See Citing EGSnrc for the recommended citation format.

Versioning by year

Commit hashes are unsorted and rather cryptic, so for convenience we also tag the repository every year with "v" and the 4-digit year number, for example v2021. This tag point is called a release and is accessible via the Releases page. Significant changes or new features will only be added on release points, so in general parlance or in publications you may use this version number to identify the version of EGSnrc you are using. If you are using a commit that is between yearly release points, then we recommend using the commit hash to refer to your version.

If we need to release more than once every calendar year—for example if a critical bug is uncovered and fixed—we add a letter to the release number, as in 2019a, 2019b, etc. See Citing EGSnrc for the recommended citation format.

Reporting code modifications

EGSnrc is a free software toolkit and therefore it can be modified to suit specific needs. If the source code is modified at all, then the proper way to cite the software version is to provide the closest commit from the official repository (as the commit hash or the yearly release tag), along with a list of revisions.

Ideally, changes are provided as a patch file, which makes it easy to re-build the exact version of EGSnrc which is referred to. If EGSnrc is installed via git clone, then it is easy to generate a list of differences and a patch file with git commands.

By way of example, say I am using EGSnrc v2020 (which corresponds to commit 7b994519), but that I made some change in some files. Upon going inside the top EGSnrc directory (where the HEN_HOUSE is located), I can generate a list of changes with the git diff command, which yields:

diff --git a/HEN_HOUSE/src/egsnrc.mortran b/HEN_HOUSE/src/egsnrc.mortran
index fd81573..36f9411 100644
--- a/HEN_HOUSE/src/egsnrc.mortran
+++ b/HEN_HOUSE/src/egsnrc.mortran
@@ -407,6 +407,8 @@ IF( ibr_nist >= 1 ) [
     IF( jj >  $MXBRES ) [ jj = $MXBRES; ajj = -1; ]
 ]

+"Add a comment in the code"
+
 DO ibr = 1,nbr_split [

     IF( ibr_nist >= 1 ) [ "use the NIST or NRC bremsstrahlung cross section"
diff --git a/HEN_HOUSE/src/emf_macros.mortran b/HEN_HOUSE/src/emf_macros.mortran
index 4aff08c..d2944bf 100644
--- a/HEN_HOUSE/src/emf_macros.mortran
+++ b/HEN_HOUSE/src/emf_macros.mortran
@@ -123,7 +123,7 @@ REPLACE {$EMFLMT} WITH {EMLMTIN}
 "THIS MACRO IS THE UPPER LIMIT ON THE AVERAGE AMOUNT OF CHANGE OF THE         "
 "DIRECTION VECTOR DUE TO MULTIPLE SCATTERING.                                 "
 "                                                                             "
-REPLACE {$EMMLMT} WITH {0.20}
+REPLACE {$EMMLMT} WITH {0.10}
 ;
 "                                                                             "
 "*****************************************************************************"

This indicates that there are 2 files that have been modified compared to the pristine reference version v2020: HEN_HOUSE/src/egsnrc.mortran and HEN_HOUSE/src/emf_macros.mortran, and the details of the change is shown for each file. This output is already in the expected format for patching, so one can simply copy-paste the output in a file or redirect the output to create a patch file:

git diff > mypatch

This file should then be supplied as electronic Supplementary Material in a publication, or else provided upon request to other researchers seeking to use my exact EGSnrc version, including my modifications. At the other end, one can apply mypatch by checking out the v2020 version of EGSnrc and issuing the following command

git apply-patch /path/to/mypatch`    # where /path/to/mypatch is the location of the patch file

Reporting application code modifications

When EGSnrc is installed, the ready-made applications are extracted from HEN_HOUSE/user_codes/ to a newly created egs_home/ directory (or another directory name picked during the configuration). This egs_home/ is ignored by git, because it will typically contain simulation results and other user files.

This poses a problem in terms of tracking code modification in those applications, because git only keep tracks of the pristine copy of the application source code in HEN_HOUSE/user_codes/, but users normally modify the source code located in egs_home/ after installation. Hence, in reporting code modifications, one ought to also compare source code within egs_home/ against the pristine versions preserved in HEN_HOUSE/user_codes/. The following commands will provide this comparison:

diff -u -r $HEN_HOUSE/user_codes $EGS_HOME | grep -v "Only in $EGS_HOME"

For example, say I modified my $EGS_HOME copies of both the egs_chamber.cpp and dosxyznrc.mortran files; the above command will report the discrepancies:

--- dosxyznrc/dosxyznrc_user_macros.mortran	2021-02-24 09:33:23.242197258 -0500
+++ ../../egs_home/dosxyznrc/dosxyznrc_user_macros.mortran	2021-04-13 17:55:02.537531262 -0400
@@ -87,11 +87,11 @@
 "
 REPLACE {$STAT}    WITH {10}  "Number of batches to use in calcn of statistics"
                               "It works with $STAT = 1 but gives no stats"
-REPLACE {$MXMED}   WITH {20}   "Maximum number of media
+REPLACE {$MXMED}   WITH {30}   "Maximum number of media
 REPLACE {$MXSTACK} WITH {10000}  "Maximum particle stack size
-REPLACE {$IMAX}    WITH {128} "Maximum number of x cells
-REPLACE {$JMAX}    WITH {128} "Maximum number of y cells
-REPLACE {$KMAX}    WITH {128} "Maximum number of z cells
+REPLACE {$IMAX}    WITH {256} "Maximum number of x cells
+REPLACE {$JMAX}    WITH {256} "Maximum number of y cells
+REPLACE {$KMAX}    WITH {256} "Maximum number of z cells
 REPLACE {$MAXDOSE} WITH {{COMPUTE $IMAX*$JMAX*$KMAX+1}}
          "Number of dose regions, can be set to < $IMAX*$JMAX*$KMAX if "
          "necessary to reduce memory requirement, +1 for outside region"
--- egs_chamber/egs_chamber.cpp	2021-02-24 09:33:23.309196472 -0500
+++ ../../egs_home/egs_chamber/egs_chamber.cpp	2021-04-13 17:53:46.335426586 -0400
@@ -2592,6 +2592,7 @@

 /*! Output the results of a simulation. */
 void EGS_ChamberApplication::outputResults() {
+    egsInformation("\n\n Added an output message in the log.\n\n");
     egsInformation("\n\n last case = %lld fluence = %g\n\n",
             current_case,source->getFluence());
     //*HB_start************************
@@ -2607,7 +2608,7 @@
     for(int j=0; j<ngeom; j++) {
         double r,dr; dose->currentResult(j,r,dr);
         if( r > 0 ) dr = 100*dr/r; else dr = 100;
-        EGS_Float norm = 1.602e-10*current_case/source->getFluence();
+        EGS_Float norm = 1.60217662e-10*current_case/source->getFluence();
         norm /= mass[j];
 	//*HB_start************************
         if(pu_flag&&j) {

I should then report these changes in my publication (or at least the ones pertaining to the application(s) that I used to generate data for that publication). Ideally this would be submitted as electronic Supplementary Material alongside the publication.