-
Notifications
You must be signed in to change notification settings - Fork 146
Citing EGSnrc
Please cite the EGSnrc software using its Digital Object Identifier (doi):
Kawrakow I, Rogers DWO, Mainegra-Hing E, Tessier F, Townson RW, Walters BRB.
EGSnrc toolkit for Monte Carlo simulation of ionizing radiation transport,
doi:10.4224/40001303 (2000).
The first authors are I. Kawrakow and D.W.O. Rogers, and the remaining authors are listed alphabetically. The reference year 2000 corresponds to the initial release of EGSnrc. The identifier doi:10.4224/40001303 currently resolves to the EGSnrc page in the NRC Publications Archive, and it is strongly recommended to cite the doi in case the software repository is moved to another location in the future. Please also cite the EGSnrc scientific papers that are relevant to your work.
See Versioning to understand how the EGSnrc software is versioned. If the citation pertains to work carried out with the EGSnrc software, indicate the specific version used, specified with the yearly release tag (note that the citation date remains the original release year 2000):
Kawrakow I, Rogers DWO, Mainegra-Hing E, Tessier F, Townson RW, Walters BRB.
EGSnrc toolkit for Monte Carlo simulation of ionizing radiation transport,
doi:10.4224/40001303 [release v2023] (2000).
The tag of an official EGSnrc release is given by the terminal command git describe --tags.
Published work should be based on an official release of EGSnrc, without modifications.
However, in some cases you might need to cite a specific version
between official releases, or even your own
code modifications. For instance,
perhaps your work relates to a feature that is still in development
(on the develop branch). In this case, cite the explicit commit hash (at
least 7 characters), for example:
Kawrakow I, Rogers DWO, Mainegra-Hing E, Tessier F, Townson RW, Walters BRB.
EGSnrc toolkit for Monte Carlo simulation of ionizing radiation transport,
doi:10.4224/40001303 [commit 7b99451] (2000).
Again, the citation date remains the initial release year 2000. If using a commit hash, ensure that it exists on the master branch or the develop branch of the repository. All other commits are considered temporary and will eventually be pruned from the project. At any rate, do not cite branch names, since those point to new commits as the software evolves.
Here is a BibTeX entry for citing EGSnrc:
@software{egsnrc,
title = {EGSnrc toolkit for Monte Carlo simulation of ionizing radiation transport},
author = {Kawrakow, I and Rogers, DWO and Mainegra-Hing, E and Tessier, F and Townson, RW and Walters, BRB},
year = {2000},
howpublished = {\href{https://doi.org/10.4224/40001303}{doi:10.4224/40001303} [release v2023]}
}If \usepackage{hyperref} if not available to provide the \href command, then
simply use howpublished = {doi:10.4224/40001303 [release v2023]}.
EGSnrc is a free software toolkit, the whole point of which is that it can be modified for specific purposes. 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 yearly release tag or the commit hash), along with a list of revisions. Reporting local revisions ensures that anyone is able to reproduce the exact state of the software that is cited, even if has been modified.
If you have followed the installation steps for easy EGSnrc upgrade, then you can follow those instructions to cite all code modifications. Otherwise, you can follow the instructions below to do it by hand, so to speak.
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 you are using EGSnrc v2020 (which corresponds to commit
7b994519), but that you changed some files. Upon going inside the top EGSnrc
directory (where the HEN_HOUSE is located), you 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 changes are spelled out for each
file. This output is already in the expected format for patching, so you can
simply copy-paste the output in a file or redirect the output to create a patch
file:
git diff > mypatchThis patch file should then be supplied as electronic Supplementary Material in
a publication, or else provided upon request to other researchers seeking to
use this exact EGSnrc version, including your modifications. At the other end,
one can apply mypatch by checking out the v2020 version of EGSnrc and
issuing the following command inside the repository (typically the top-level
EGSnrc directory):
git apply-patch /path/to/mypatch` # where /path/to/mypatch is the location of the patch fileWhen EGSnrc is installed, the ready-made applications are extracted from
HEN_HOUSE/user_codes/ to a newly created egs_home/ directory (or any other
name picked during the configuration). This egs_home/ directory is entirely
ignored by git, because in time it typically contains simulation results and
other user files.
This poses a riddle in terms of tracking code modification in those
applications (DOSXYZnrc, egs_chamber, etc.), because git only keeps track of
the pristine copy of the application source code in HEN_HOUSE/user_codes/;
however, users would normally modify the source code located in the egs_home/
after installation. Hence, in reporting code modifications, one should also
compare the source code within egs_home/ against the pristine versions
preserved in HEN_HOUSE/user_codes/. The following command performs this
comparison:
diff -u -r $HEN_HOUSE/user_codes $EGS_HOME | grep -v "Only in $EGS_HOME"For example, say you modified your $EGS_HOME copies of files dosxyznrc/dosxyznrc.mortran and egs_chamber/egs_chamber.cpp; the above command reports your modifications:
diff -u -r HEN_HOUSE/user_codes/dosxyznrc/dosxyznrc_user_macros.mortran egs_home/dosxyznrc/dosxyznrc_user_macros.mortran
--- HEN_HOUSE/user_codes/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"
diff -u -r HEN_HOUSE/user_codes/egs_chamber/egs_chamber.cpp egs_home/egs_chamber/egs_chamber.cpp
--- HEN_HOUSE/user_codes/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) {Hence, one ought to report such differences in a publication (or at least the ones pertaining to the application(s) used for that publication). Ideally this would be submitted as electronic Supplementary Material alongside the publication, or as an appendix if it is only a few lines long.
Below is a list of key peer-reviewed scientific articles that provide more specific references for the various software components and features of EGSnrc:
Karwakow I. Accurate condensed history Monte Carlo simulation of electron transport. I. EGSnrc, the new EGS4 version. Medical Physics 27, 485–498 (2000).
Karwakow I. Accurate condensed history Monte Carlo simulation of electron transport. II. Application to ion chamber response simulations. Medical Physics 27, 499–513 (2000).
Buckley LA, Kawrakow I, Rogers DWO. CSnrc: Correlated sampling Monte Carlo calculations using EGSnrc: Implementation of correlated sampling in EGSnrc. Medical Physics 31, 3425–3435 (2004).
Malkov VN, Rogers DWO. Charged particle transport in magnetic fields in EGSnrc. Medical Physics 43, 4447–4458 (2016).
Wulff J, Zink K, Kawrakow I. Efficiency improvements for ion chamber calculations in high energy photon beams. Medical Physics 35, 1328–1336 (2008).
Mainegra-Hing E, Reynaert N, Kawrakow I. Novel approach for the Monte Carlo calculation of free-air chamber correction factors. Medical Physics 35, 3650–3660 (2008).
Mainegra-Hing E, Kawrakow I. Variance reduction techniques for fast Monte Carlo CBCT scatter correction calculations. Physics in Medicine & Biology 55, 4495–4507 (2010).
Thing RS, Mainegra-Hing E. Optimizing cone beam CT scatter estimation in egs_cbct for a clinical and virtual chest phantom. Medical Physics 41, 071902 (2014).
Rogers DWO, Faddegon BA, Ding GX, MA CM, We J, TR Mackie. BEAM: a Monte Carlo code to simulate radiotherapy treatment units. Medical Physics 22, 503–524 (1995).
Walters BRB, Kawrakow I, Rogers DWO. History by history statistical estimators in the BEAM code system. Medical Physics 29, 2745–2752 (2002).
Heath E, Seuntjens J. Development and validation of a BEAMnrc component module for accurate Monte Carlo modelling of the Varian dynamic Millennium multileaf collimator. Physics in Medicine & Biology 48, 4045–4064 (2004).
Kawrakow I, Rogers DWO, Walters BRB. Large efficiency improvements in BEAMnrc using directional bremsstrahlung splitting: directional bremsstrahlung splitting. Medical Physics 31, 2883–2898 (2004).
Mainegra-Hing E, Kawrakow I. Efficient x-ray tube simulations. Medical Physics 33, 2683–2690 (2006).
Ali ESM, Rogers DWO. Efficiency improvements of x-ray simulations in EGSnrc user-codes using bremsstrahlung cross-section enhancement (BCSE). Medical Physics 34, 2143–2154 (2007).
Walters BRB. Increasing efficiency of BEAMnrc-simulated Co-60 beams using directional source biasing. Medical Physics 42, 5817–5827 (2015).
Bielajew AF, Rogers DWO. A standard timing benchmark for EGS4 Monte Carlo calculations. Medical Physics 19, 303–304 (1992).
Walters BRB, Kawrakow I, Rogers DWO. History by history statistical estimators in the BEAM code system. Medical Physics 29, 2745–2752 (2002).
Kawrakow I, Walters BRB. Efficient photon beam dose calculations using DOSXYZnrc with BEAMnrc. Medical Physics 33, 3046–3056 (2006).
Walters BRB, Kawrakow I. A "HOWFARLESS" option to increase efficiency of homogeneous phantom calculations with DOSXYZnrc. Medical Physics 34, 3794–3807 (2007).
Lobo J, Popescu IA. Two new DOSXYZnrc sources for 4D Monte Carlo simulations of continuously variable beam configurations, with applications to RapidArc, VMAT, TomoTherapy and CyberKnife. Physics in Medicine & Biology 55, 4431–4444 (2010).
Mainegra-Hing E, Rogers DWO, Kawrakow I. Calculation of photon energy deposition kernels and electron dose point kernels in water. Medical Physics 32, 685–699 (2005).
- Overview
- Install on VirtualBox
- Install on Linux
- Install on macOS
- Install on Windows
- Quick installation
- Upgrading