Notes/cautions on VIKAR 4.4 (2021-03-06)


********************************************
*****************WARNING********************

If you intend to use VIKAR simulations for
anything that actually matters (a proposal,
publication, etc), or if you are making any
substantial alterations to the code, it is
advised to contact the author (Evil Dr Pain)
to ensure that the code is doing something
vaguely sensible.
Suggestions/requests/comments for changes/
improvements are welcomed.

No liability is taken by the management.
You have been warned. 



For proposals/publications, please cite:

 - S.D. Pain, VIKAR code, https://sites.google.com/a/nuclearemail.org/vikar/
and state the version number used
 - S.D. Pain, AIP Advances 4 (2014) 041015



********************************************
********************************************

As always, it is recommended that you upgrade to the latest version. For details,
see below.



Changes incorporated in VIKAR 4.42
----------------------------------
  - Upgrade fekin.f from v1.0 to v1.1 to aviod compilation errors in picky compilers when passing
   zeros to linear.f
  - Removal of print statement in vikar.f to avoid complaint from picky compilers

Changes incorporated in VIKAR 4.41
----------------------------------
  - Upgrade linear.f from v1.0 to v1.1 to protect against NaN if (xmax-xmin) is exactly 0.0
   (which can cause a crash in kindeux.f if the random number generator generates exactly 0.0)


Changes incorporated in VIKAR 4.40
----------------------------------


The single substantial change over VIKAR 4.3 is the capacity to include simulations of light 
ions evaporated from fusion-evaporation reactions.  In addition, there are a number of minor 
bug fixes. The changes are:

- VIKAR 4.4 incorporates the possibility of including fusion-evaporation reactions in your 
  simulation. As for the main direct reactions, the cross sections are not internally generated, 
  so must be sourced externally. VIKAR 4.4 utilizes fusion-evaporation reaction cross sections 
  calculated externally using the PACE 4 code, propagating the evaporated particles through the 
  experiment (targets and backings, and detector acceptances etc) exactly as it does for particles 
  emitted from direct reactions. PACE 4 can be accessed and run via LISE++. After running PACE 4, 
  copy and paste the entire PACE output into a file; this file can be read in to VIKAR at runtime 
  without further user modification. The fusion-evaporation simulations are performed sequentially 
  following the direct reaction simulations. The FE simulation option is only available using 
  physics-driven statistics option (introduced in VIKAR 4.3), where yields  are determined by 
  cross sections, target thickness, beam intensity and duration. FE reactions can be simulated as 
  originating from the main target material and backings, as desired, with yields based on the 
  respective material thicknesses and FE cross sections read in. This ensures that the FE and 
  direct reaction yields are correctly normalized to each other. Currently, evaporated protons 
  and evaporated alphas can be simulated. Neutrons are to come. Because of the very substantial 
  cross sections for FE reactions, the FE simulations may take substantially longer to complete 
  than the direct reaction simulation. With regard to the fusion-evaporation reactions, the output 
  of VIKAR 4.4 is structured as follows:
    - out_eject_XXX.dat - data from the direct reaction channels only
    - out_fe_p_XXX.dat - data from evaporated protons only
    - out_fe_a_XXX.dat - data from evaporated alphas only
    - out_fe_XXX.dat - data from all evaporated particles
    - out_eject_fe_XXX.dat - data from direct reaction and all evaporated particles

 - AngDist_read2 updated to version 2.1 to fix a possible seg fault issue
 - Modified the function shell (in dedx.f) to v1.1, changing the switch between models to
   occur at ~4 MeV rather than nominal 8 MeV (and previously suppressed) to obtain better 
   agreement with other dedx codes (esp with lighter targets)
 - Modified function de.f to v1.1 to stop a calculation at 1 keV. Previously this continued 
   to 0, but very small residual energies caused SPGES (ie return of de function) to explode, 
   sometimes causing code instabilities (as observed in the VESTRY)


Changes incorporated in VIKAR 4.30
----------------------------------

Substantial changes are incorporated over VIKAR 4.21. The most substantial of these is 
a new feature in which reaction yields are determined from the supplied cross sections
beam intensity, target thickness and experiment duration (physics-driven statistics),
rather than defining an arbitrary number of events to be simulated. This allows you to 
simulate exactly what you'd observe in an experiment of a given duration. The old method
is maintained as an option.  Additionally, a new detector class (RADIAL) detectors is
included, which allows simulation of detectors with circular faces (such as coaxial Ge
detectors, PIPS detectors etc) that are oriented such that they are directly facing the
center of the target. Improved  debugging information is included (separating detection
efficiency from simulation efficiency, and color-coded terminal feedback is included as
an aid to the user, along with a number of minor bug fixes.

 - added RADIAL detector class, allowing circular-faced detectors to be described
   with normals directed toward the origin (target). Currently, no segmentation
   of these detectors is supported
 - fixed xPlane and yPlane dimensions from (200) to (1024) (mistake from v4.21)
 - updated transform from v 2.0 to v 2.1, correcting behaviour for translations 
   through large angles (previously underestimated)
 - updated excitation energy spectrum filenames to _Ex_ rather than _Q_
 - updated debugging information. Periodic status updates now separate detection
   efficiency (eg particles missing detectors, or getting stuck in target layers)
   from efficiency issues from simulation problems (eg beam particles missing a
   jet target, or errors such as particles stopping in the target before reacting).
   As such:
      - the simulation efficiency should be close to 100% (you have problems if it is not)
      - the detection efficiency is a matter for your experiment design 
	(eg solid anglecoverage etc)
 - Some color is used for high-importance feedback in terminal feed from the
   simulations (optimized for light-on-dark terminals)
 - for isotropic angular distributions, the user must now enter a cross section
   for each state independently, allowing cross section estimates to be used 
   when angular distributions are not available. If equal weighting is required,
   the user may enter the same number for all states.
 - a new feature has been added to determine the simulation statistics from the 
   physics that has been input, rather than an arbitrarily-selected number of
   detected events. In this mode, the target thickness used for energy-loss calculations
   is used for luminosity calculations, appropriately scaled by target composition.
   The user-supplied cross sections are employed, coupled to user-supplied
   beam intensity and experiment duration. The simulation will now target the
   appropriate number of events PRIOR TO DETECTION, and the detectors will measure
   the stats you'd expect for that scenario. Note that you if you are using this
   feature to plan an experiment, you will need to manually scale your differential
   cross section by the expected spectroscopic factors in order to get realistic
   yield estimates. The old method of forced statistics is maintained as an option
   at run time.
   Note that the program will exit if the reaction nuclide is not found in the
   target desciption input for energy loss calculations.
 - modded shell in dedx.f to switch models at a different energy to improve
   agreement with other energy loss codes


Changes incorporated in VIKAR 4.21
----------------------------------

The main change incorporated in VIKAR 4.21 is to allow the for individually-weighted
cross sections for final states when isotropic angular distributions are employed.

The functional improvements are:

 - Increased number of states in residual from 20 to 100
 - Added capacity for state-by-state cross sections for isotropic angular distributions
 - Calculation of energy loss tables now account for reaction Q value
   when determining upper energy to tabulate


Changes incorporated in VIKAR 4.2
----------------------------------

The changes incorporated in VIKAR 4.2 reflect debugging efforts resulting from
reported segmentation faults, and the addition of code to deal with stopping targets
which were not previously considered. Improved control of bad simulations, and
debugging capacity is included.

The functional improvements are:

 - Capacity to model stopping targets
 - Output plot of ejectile angle vs recoil angle
 - More sophisticated debugging variables
 - Exit clause to stop never-ending simulations (exits if detection efficiency
   is below 0.1% after 10000 events simulated)
 - Updated product_proc to version 1.4 to reflect correct energy variable being
   passed to E_straggle (to fix seg faults), add debugging variables
 - Updated energy loss calculations for jet targets
 - Fixed energy loss calculations for upstream target backing
 - Applied check if beam stops in upstream target backing
 - Applied check to determine if reactions are energetically possible
 - Updated cart2sphere to version 1.1 to fix minor bug if x = y = 0
 - Updated kindeux to version 3.1 to include debugging output
 - Updated DetHit_ann to version 1.1 to allow for detectors to span phi=0 or phi=360
 - Updated new_resolution_cyl to version 1.1 to correct for energy bug in incomplete_Q 
 - Updated new_resolution_plan to version 1.1 to correct for energy bug in incomplete_Q 


Details of file changes are documented below.

1) Stopping targets are now modelled. Previously, the interaction depth in the target
was selected randomly across the entire target thickness (appropriate for transmission targets).
Now, the code determines whether the beam stops in the target, and if so, the interaction
point is now selected randomly along the range of the beam in the target.

2) VIKAR 4.2 checks if the energy at the reaction point is above threshold for the reaction
entered, avoiding simulating energetically-impossible reactions (important for stopping targets,
and operator error).

3) Improved debugging modes are added, affecting output to terminal. The debugging variable
can be set to:

  0 - Silent, except simulation time and efficiency reporting
  1 - Basic reporting of suspect events, such as stuck particles or double hits
  2 - Event dump mode (forces full level-9 debugging, followed by code halt, for a
      specific event number as appended on extra line at end of input file)
  8 - Full event-by-event reporting to terminal of parameters in vikar only
  9 - Full event-by-event reporting to terminal of parameters in vikar, and
      insubroutines such as product_proc


4) An automatic exit clause is incorporated, to stop run-on simulations. The VIKAR gives
up the ghost when 10000 events have been simulated if the detection efficiency is
below 0.1%. If that's a problem - modify the code, or design a better experiment.

5) Output files are generated of ejectile angle vs recoil angle, useful for modelling coincidence
experiments.

6) Numerous debugging activities in files documented above.



Changes incorporated in VIKAR 4.1
---------------------------------

The changes incorporated in VIKAR 4.1 reflect upgrades in the physics included,
and the usability of the code. The functional improvements are:

 - Realistic simulation of energy straggling in all layers (target and detector) for all particles
 - Support for multi-layer targets
 - Simulated beam tracking to properly reconstruct the event with large-emittance beams
 - Increased the number of detectors from 200 to 1024 for all types - useful for simulating highly
   segmented detectors with irregular strip pitches
 - Changed angular distribution input from CDF to dsigma/dOmega, now using the twfnr 21.X file format
   (CDF is now calculated internally)
 - Added debug variable to turn on/off extra output 
 - Corrected a small error in calculating the thickness of the E layer of an annular detector

Details of file changes are documented below.

1) Fuction E_straggle(v1.0) created, for calculating the energy straggling of
 a particle traversing a medium. The energy of the incident particle, energy loss
in the medium, and medium thickness is passed in, along with details of the
particle and medium. The exiting energy of the particle with straggling included
is returned. The straggling is based on the Bohr expression (energy independent),
subsequently modified by an empirical energy-dependent expression. The energy
straggling impacts particles traversing the target, but also (significantly) detector
punch-through events. See below for comparisons between VIKAR 4.0 and VIKAR 4.1.

2) Support for multi-layer targets added. Targets can now be described in terms of
the active target volume (defined as before) with the option to add backing materials
on the upstream and/or downstream faces. These layers are added in the same 
manner as the target layer, but are inner to reactions (i.e. incorporated for energy-loss
purposes only).

3) Beam tracking is now simulated, where resolutions for tracked beam-target interaction
point and reconstructed angle are entered explicity. An additional set of files corresponding
to reconstructing the reaction vertex based on beam tracking (rather than assumed
(0,0,0) pencil beam interaction), are now created with the suffix  _recon.dat appended
to the filename.

4) Size of detector arrays (ie number of detectors) increased from 200 to 1024

5) The input of user-defined angular distributions has been altered to simplify the life of
the user. Previously, a Cumulative Distribution Function (CFD) was required, which had to
be pre-calculated from a differential cross section. Now, center-of-mass angular distributions
are entered in directly, in the form of a file of

   angle 1   dsigma/dOmega
   angle 2   dsigma/dOmega
   ..
   ..
   angle X   dsigma/dOmega

21.XXXX files from twofnr are perfect, and the VIKAR will bless you for using them.


6) A debug variable has been added. Set this to 1 if you like debugging output (and Nice Mr Tony Blair)
or to 0 for a nice quiet life of ignorance.


Changes incorporated in VIKAR 4.0
---------------------------------

Multiple updates and restructuring isincorporated over VIKAR 3.X. Most significantly, the
reaction geometry has been reworked to be fully rigorous, thereby allowing jet-style targets
to be simulated correctly. This also removes some approximations used in propogating particles
through the two layers of a telescope. Functional improvements include:

 - realistic simulation of jet and foil targets
 - user-defined energy thresholds for detectors
 - slectable position-dependent/independent energy thresholds for resistive/non-resisitve detectors
   in cylindrical coordinates
 - user-defined offset resisitors for resistive-strip detectors
   (which impact position resolution and thresholds)
 - separate energy thresholds for dE and E detectors
 - incomplete charge collection included in detector response (optional)
 - user-defined beam emergence
 - internal Q-value calculations (the code Qvalue is still bundled separately
   for controlled post-processing)
 - basic support for massless and neutral beam particles (for simulation of (n,X) and (g,X) reactions)
 - automatic xmgrace formatting on output files (optional)
 - up-to-date detector files are bundled, including files for ORRUBA, GODDESS, and
   superORRUBA with JENSA

 
Details of file changes are documented in below.

1) Subroutine add_phi (v1.0) created, for rotating the azimuthal angle of a vector
 in polar coordinates by an angle phi, from specific to absolute coordinates

2) Subroutine add_phi (v1.0) created, for rotating the azimuthal angle of a vector
 in polar coordinates by an angle phi from absolute to specific coordinates
 

3) Subroutine DetSet_cyl_read (v1.1) updated to include separate energy detection thresholds
for dE and E detectors, offset resistors (note that strips resistance is nominally 4 kOhm) and
telescope separation.  

4) Subroutine DetSet_plan_read (v1.1) updated to include separate energy detection thresholds
for dE and E detectors, offset resistors (note that strips resistance is nominally 4 kOhm) and
telescope separation.  
 
5) Subroutine DetSet_ann_read (v1.1) updated to allow X,Y translation of detector, separate energy
detection thresholds for dE and E detectors, and telescope separation.  

6) Subroutine jet_out (v1.0) created, to determine the thickness that a particle
 sees when exiting a jet-like target.

7) Subroutine detect_cyl (v1.0) created to determine whether a cylindrical polar detector
is hit. This is a substantial upgrade, allowing event-by-event variations in reaction
coordinate (imperative for JENSA simulations). Resolution-smeared vectors are passed back
to parent program, plus a hit register.

8) Subroutine DetHit_plan updated to v1.1 to include reaction point offset
(due to beam and target size) and to return x,y positions of hit on detector

9) Subroutine DetHit_ann (v1.0) created to determine whether an annular detector is hit.
This is a substantial upgrade, allowing event-by-event variations in reaction coordinate
(imperative for JENSA simulations). Resolution-smeared vectors are passed back to parent
program, plus a hit register.

10) Subroutine det_thick_cyl updated to v2.0 which uses subtract_phi function to more generally
calculate effective detector thickness

11) Subroutine strag_dE_ann updated to v2.0 to properly propagate an ion that has hit the dE
detector through to the E detector, accounting for the non-central interaction point in the
target, and the non-zero distance between dE and E layers in the telescope.

12) Subroutine strag_dE_plan updated to v2.0 to properly propagate an ion that has hit the dE
detector through to the E detector, accounting for the non-central interaction point in the
target, and the non-zero distance between dE and E layers in the telescope.

13) Subroutine strag_dE_cyl updated to v2.0 to properly propagate an ion that has hit the dE
detector through to the E detector, accounting for the non-central interaction point in the
target, and the non-zero distance between dE and E layers in the telescope.

14) new_resolution_cyl (v1.0) created to determine the resolution effects of hitting a
detector in cylindrical coordinates. Detector thresholds, incomplete charge
collection, and detector resolution effects are applied.

15) new_resolution_plan (v1.0) created to determine the resolution effects of hitting a
detector in planar coordinates. Detector thresholds, incomplete charge
collection, and detector resolution effects are applied.

16) new_resolution_ann (v1.0) created to determine the resolution effects of hitting a
detector in annular coordinates. Detector thresholds, incomplete charge
collection, and detector resolution effects are applied.

17) Qcal (v1.0) created, based on Qvalue code, to generate reconstructed excitation energy spectra
from the output files. Running this spectrum creation is optional. Spectrum dispersion is
selectable.

18) product_proc updated to v1.2 for several major alterations. Both jet and foil targets
are now handled. Separate dE and E positions are determined, allowing for offset in separation
between dE and E detector (for non-central reactions and dE straggling). Routine now uses
the detect_cyl routine, and includes incomplete charge collection in detectors (on/off selectable).



Changes since VIKAR 3.1
-----------------------

1) Updates have been made over VIKAR 3.1 to improve the implementation
of beam-spot-size effects for cylindrical and annular detectors. The changes are
manifest in updating the files:

resolution_cyl (v1.0 to v1.1)
product_proc (v1.0 to v1.1)


2) The code qvalue has been updated from v1.0 to v1.1 in order to make it a little
more user friendly. Histogram output is now calibrated in MeV, rather than channel
number. The histogram dispersion is explicitly set within the code.

3) The code qvalue has been corrected (v1.2), so that Ecom is now calculated correctly
for the general case of any number of transferred nucleons.







General notes
-------------


1) Currently, beam spread properties are only implemented for cylindrical and
annular detectors. 

2) If you want to use non-isotropic angular distributions, contact your
minister.

3)  path+file_names up to 40 characters are supported (except 30 for SRIM files)

4) VIKAR 4.0 supports up to 20 excitations in the recoil. do not exceed this
value.

5) VIKAR 4.0 supports up to 200 detectors of each geometry.

6) Up to 50 strips per detector are supported

7) Single-layer targets of up to 10 elements are supported

8) VIKAR 4.0 is a non-relativistic code

9) Q value spectra from VIKAR 3.1 must be externally created. The program
qvlaue 1.0 is provided for this purpose

10) The following examples of detector files are given inthe detectors directory:
     Cylindrical - GODDESS-barrel.dat, orruba-standard.dat
     Annular - annular.dat, GODDESS-QQQ2.dat, GODDESS-QQQ5-back.dat
     Planar - planar.dat

11) Output files all begin with "out_", followed by the particle type (ejectile
or recoil). The energy vs angle plots then list the energy type (E, dE, Etot),
followed by the source of the angular information (dE or E layer of telescope).
Two separate particle ID plots are currently produced, one for angles forward of
90 deg, one backward (as detector setups are often quite different in the
forward and backward hemispheres). Files containing "_unsmeared" include beam
and target effects only (ie no detector resolution effects). The files
"*_angles.dat" contain a hit map of the particles in spherical polar coordinates.




------
Evil Dr Pain (2016-01-30)




