Merge #405: add sparse binary output in DOSXYZnrc

HEN_HOUSE/doc/src/pirs794-dosxyznrc/inputs/dosxyznrc.inp

@@ -842,7 +842,7 @@ Record SC1-20a and SC1-21a (required for sources 20 and 21)
  Record 13 (9 if NMED=0)
  NCASE, IWATCH, TIMMAX, INSEED1, INSEED2,
  BEAM_SIZE, ISMOOTH,IRESTART,IDAT,IREJECT,ESAVE_GLOBAL,NRCYCL,IPARALLEL,
- PARNUM,n_split,ihowfarless,i_phsp_out
+ PARNUM,n_split,ihowfarless,i_phsp_out,i_bindos
 
  NCASE Number of histories
  IWATCH 0=>no tracking output, 1=>list every interaction
@@ -1014,6 +1014,11 @@ Record SC1-20a and SC1-21a (required for sources 20 and 21)
  (synchronized sources) then you also have the option of
  storing frMU_indx in the file (see source inputs).
 
+ i_bindos For outputting sparse binary dose data instead of the
+ dense ASCII .3ddose format. If i_bindos=0, then the
+ dose will be output in .3ddose format. Any other value
+ will output a .bindos file instead.
+
 ----------------------------------------------------------------------------
 ----------------------------------------------------------------------------
  EGSnrc INPUTS

HEN_HOUSE/doc/src/pirs794-dosxyznrc/pirs794-dosxyznrc.tex

@@ -26,6 +26,7 @@
 % Dave Rogers, 2001
 %
 % Contributors: Frederic Tessier
+% Marc-Andre Renaud
 %
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
@@ -3499,6 +3500,12 @@ \subsection{{\tt i\_phsp\_out}}
 
 For more information on the IAEA phase space file format, see the BEAMnrc Users Manual\cite{Ro09}.
 
+\subsection{{\tt i\_bindos}}
+\indexm{i\_bindos}
+If {\tt i\_bindos} is set to 1, DOSXYZnrc outputs a sparse binary dose file instead of a dense ASCII dose file.
+The resulting file typically has a much smaller memory footprint than the default {\tt .3ddose} format.
+See section~\ref{subsec:bindos_format} for a description of the format.
+
 \subsection{ECUTIN}
 \indexm{ECUTIN}
 \label{ECUTIN}
@@ -4316,11 +4323,13 @@ \section{Format of Dose Outputs}
 
 \indexm{.egslst}
 The dose distributions calculated by DOSXYZnrc can be found in the output
-files, ``{\tt .egslst}'', ``{\tt .3ddose}'' and ``{\tt .pardose}''.
+files, ``{\tt .egslst}'', ``{\tt .3ddose}'', ``{\tt .bindos}'' and ``{\tt .pardose}''.
 The file ``{\tt .egslst}''
 \indexm{.pardose}
 \indexm{.3ddose}
+\indexm{.bindos}
 \indexm{files!.3ddose}
+\indexm{files!.bindos}
 \indexm{files!.pardose}
 contains not only the dose (when asked for) and statistical data but also the information
 about simulation geometry, number of histories run, CPU time used, etc.
@@ -4423,6 +4432,35 @@ \subsection{A Sample {\tt .3ddose} File}
 
 \lfoot[]{}
 
+\subsection{{\tt .bindos} Files}
+\label{subsec:bindos_format}
+\indexm{.bindos}
+\indexm{files!.bindos}
+A ``{\tt .bindos}'' file is output instead of a ``{\tt .3ddose}'' file if the
+flag ``{\tt i\_bindos}'' is set to 1. The same dose content is contained in each file,
+but ``{\tt .bindos}'' is a sparse format, hence only information about non-zero dose
+voxels is included. The linearized start and end indices for blocks of contiguous non-zero
+doses are stored. Both integers and floats are stored as 4 bytes each.
+
+\begin{enumerate}
+\item Number of voxels in the x, y, z direction (e.g., $n_x$, $n_y$, $n_z$, 3 ints)
+\item Voxel boundaries (cm) in x direction($ n_x$ +1 floats)
+\item Voxel boundaries (cm) in y direction($ n_y$ +1 floats)
+\item Voxel boundaries (cm) in z direction($ n_z$ +1 floats)
+\item Number of non-zero dose voxels ($n_{nz}$, 1 int)
+\item Number of voxel index pairs ($n_{b}$, 1 int)
+\item Linearized voxel index pairs indicating the [start, end) of contiguous non-zero
+ voxel doses. ($2 \times n_{b}$ ints)
+\item Nonzero voxel doses ($n_{nz}$ floats)
+\item Nonzero voxel uncertainties ($n_{nz}$ floats)
+\end{enumerate}
+
+The linearization formula is as follows:
+\begin{equation}
+v_{lin} = (n_x \times n_y) \cdot v_z + (v_x) \cdot v_y + v_x
+\end{equation}
+where $v_x$, $v_y$, $v_z$ are the voxel indices in the x, y, z axes, respectively.
+
 \subsection{{\tt .pardose} Files}
 \indexm{files!.pardose}
 \indexm{.pardose}

HEN_HOUSE/omega/progs/gui/dosxyznrc/create_file_nrc.tcl

@@ -27,6 +27,7 @@
 # Iwan Kawrakow
 # Ernesto Mainegra-Hing
 # Frederic Tessier
+# Marc-Andre Renaud
 #
 ###############################################################################
 #
@@ -68,7 +69,7 @@ proc create_file { file } {
  global grouping nrow izrow enflag numsrcopts izopts ncpu dflag parnum
  global numthphi angfixed ang1 ang2 nang pang ivary thphidef
  global numsets iso1 iso2 iso3 ang1 ang2 ang3 dsource muI
- global iphant iphspout imuphspout calflag
+ global iphant iphspout imuphspout calflag ibindos
  global level ibcmp_min ibcmp_max iphter_min iphter_max
  global iraylr_min iraylr_max iedgfl_min iedgfl_max
  global i_dbs r_dbs ssd_dbs z_dbs the_beam_code the_input_file the_pegs_file
@@ -446,7 +447,13 @@ set str "$ivary($i), $angfixed($i), $ang1($i), $ang2($i), $nang($i), $pang($i)"
  } else {
  set val 0
  }
- set str "$str$val, $iphspout"
+ set str "$str$val, $iphspout, "
+ if { [string compare $values(ibindos) $options(ibindos,1)]==0 } {
+ set val 1
+ } else {
+ set val 0
+ }
+ set str "$str$val"
 
  puts $file $str
 
@@ -700,5 +707,3 @@ proc error_flag { text } {
  tk_dialog .edit "Bad inputs" "You haven't defined $text. Please\
  fill in all options required before saving." warning 0 OK
 }
-
-

HEN_HOUSE/omega/progs/gui/dosxyznrc/load_input2_nrc.tcl

@@ -27,6 +27,7 @@
 # Iwan Kawrakow
 # Ernesto Mainegra-Hing
 # Frederic Tessier
+# Marc-Andre Renaud
 #
 ###############################################################################
 #
@@ -768,6 +769,14 @@ proc read_input {} {
  set iphspout 0
  if {$arr(0)<=2} { set iphspout $arr(0) }
 
+ # bindos output option
+ set data [get_val $data arr 0]
+ if {$arr(0)==1} {
+ set values(ibindos) $options(ibindos,1)
+ } else {
+ set values(ibindos) $options(ibindos,0)
+ }
+
  # now get the EGSnrc inputs
  foreach i {ecut pcut smaxir estepe ximax bca_algorithm skindepth_for_bca \
  transport_algorithm spin_effects ibrdst ibr_nist ibcmp iprdst\

HEN_HOUSE/omega/progs/gui/dosxyznrc/reset_parameters_nrc.tcl

@@ -26,6 +26,7 @@
 # Contributors: Blake Walters
 # Iwan Kawrakow
 # Frederic Tessier
+# Marc-Andre Renaud
 #
 ###############################################################################
 #
@@ -65,7 +66,7 @@ proc reset_parameters { } {
  global spec_file ecutin pcutin estepm smax imax ivox gvox dsurround
  global inc exc names mvox izvox PhantFileName latbit nbit1 nbit2
  global grouping nrow izrow enflag numsrcopts izopts maxvals
- global dflag dflagopt iphspout imuphspout calflag
+ global dflag dflagopt iphspout imuphspout calflag ibindos
  global numthphi angfixed ang1 ang2 nang pang ivary thphidef
  global numsets iso1 iso2 iso3 ang1 ang2 ang3 dsource muI
  global iphant level the_beam_code the_input_file the_pegs_file
@@ -172,6 +173,7 @@ proc reset_parameters { } {
  set iphspout 0
  set imuphspout 0
  set calflag 0
+ set ibindos 0
 
  set Ein {}
  set spec_file {}

HEN_HOUSE/omega/progs/gui/dosxyznrc/set_main_inputs_egsnrc.tcl

@@ -26,6 +26,7 @@
 # Contributors: Blake Walters
 # Iwan Kawrakow
 # Frederic Tessier
+# Marc-Andre Renaud
 #
 ###############################################################################
 #
@@ -256,7 +257,7 @@ proc edit_parameters {} {
  frame $w
  frame $w1
  frame $w2
- foreach j { 5 6 7 8 9 10 12 ihowfarless } {
+ foreach j { 5 6 7 8 9 10 12 ihowfarless ibindos } {
  frame $w1.inp$j -bd 4
  button $w1.inp$j.help -text "?" -command "help $j"
  label $w1.inp$j.label -text $names($j) -anchor w

HEN_HOUSE/omega/progs/gui/dosxyznrc/xyznrc_parameters.tcl

@@ -27,6 +27,7 @@
 # Iwan Kawrakow
 # Ernesto Mainegra-Hing
 # Frederic Tessier
+# Marc-Andre Renaud
 #
 ###############################################################################
 #
@@ -739,6 +740,18 @@ monoenergetic electron beams.
 Recommended for all homogeneous phantom calculations.
 }
 
+set ibindos {}
+set names(ibindos) "Dose output"
+set numopts(ibindos) 2
+set options(ibindos,0) "3ddose"
+set options(ibindos,1) "bindos (sparse binary format)"
+set values(ibindos) $options(ibindos,0)
+set help_text(ibindos) {
+Set to "3ddose output" to output a voxel doses in a dense ASCII file.
+Set to "sparse binary output" for a sparse binary dose file.
+See the DOSXYZnrc manual section titled "Format of Dose Outputs" for a\
+description of the file formats.
+}
 #################The following are the EGSnrc parameters#############
 
 set ecut {}

HEN_HOUSE/src/egs_utilities.mortran

@@ -28,6 +28,7 @@
 " Blake Walters "
 " Frederic Tessier "
 " Reid Townson "
+" Marc-Andre Renaud "
 " "
 "#############################################################################"
 " "
@@ -1176,7 +1177,8 @@ integer function egs_open_file(iunit,rl,action,extension);
 " If extension is an absolute file name (including path), use extension
 " as a file name, otherwise use output_file.extension in the temporary
 " working directory as name. In both cases use status='unknown' to open the
-" file. If rl = 0, open the file for formatted sequential access, otherwise
+" file. If rl = -1, open the file with stream access to write C-style binary
+" files. If rl = 0, open the file for formatted sequential access, otherwise
 " open for unformatted direct access with record length = rl.
 "******************************************************************************
 implicit none;
@@ -1209,6 +1211,10 @@ IF( egs_is_absolute_path(extension) ) [
  ' Will not try to re-open this file, assuming it has been opened',
  ' by the .io file.');
  ]
+ ELSE IF ( rl = -1 ) [
+ open(the_unit,file=extension,status='unknown',form='unformatted',
+ access='stream');
+ ]
  ELSE IF( rl = 0 ) [
  open(the_unit,file=extension,status='unknown');
  ]
@@ -1237,6 +1243,10 @@ IF(is_open)[
  ' Will not try to re-open this file, assuming it has been opened',
  ' by specifying it in the .io file.');
 ]
+ELSE IF ( rl = -1 ) [
+ open(the_unit,file=tmp_string,status='unknown',form='unformatted',
+ access='stream');
+]
 ELSE IF( rl = 0 ) [
  open(the_unit,file=tmp_string,status='unknown',err=:open_error:);
 ]
@@ -2319,4 +2329,3 @@ $INTEGER function ibsearch(a, nsh, b);
  ]
  ibsearch = min;
  return;end;
-