==================
| BetaShape v3.0 |
==================

-----------------------------------------------------------------------------------
1. Installing the BetaShape code

1.1 Local running

The code can be run locally as it is. Make sure that the local directory is defined in the PATH:

* MacOS and Ubuntu
  to check: echo $PATH 
  to set: export PATH="$PATH:./"

* Windows: should not be necessary; otherwise: 
  to check: echo %path%
  to set: setx path "%path%;.\"
  
In order to avoid doing this every time a terminal is opened, the PATH can be defined permanently (see Section 1.2).


1.2 Environment variable

If you want to run it from any directory, you need to define the environment variable BSINSTALL and add it to your PATH permanently.

Let's assume that the directory of BetaShape will be: /home/xavier/BetaShape

* Ubuntu 26.04.1
In your home directory (here /home/xavier ), add these two lines in your .bashrc file:
export BSINSTALL=/home/xavier/BetaShape
export PATH=$BSINSTALL:$PATH

Then, source the .bashrc file, or quit the terminal and restart it.

* macOS 27 Golden Gate
In your home directory (here /home/xavier ), add these two lines in your .zprofile file:
export BSINSTALL="/home/xavier/BetaShape"
export PATH="$BSINSTALL:$PATH"

Then, source the .zprofile file, or quit the terminal and restart it.

* Windows 11
Let's assume that the directory of BetaShape will be: C:\Codes\BetaShape
On your keyboard, "Windows button + x" will open a menu. Select System. 
Type in the search bar (top left corner) "envir" and select Edit environment variables for your account.
Create a new variable called BSINSTALL with the value equal to the path where BetaShape is located (here C:\Codes\BetaShape )
Modify the Path variable adding a new line with the path where BetaShape is located (here C:\Codes\BetaShape )

If the shell is opened, quit and restart it.


1.3 Changing the installation directory

When BetaShape is installed in a new directory (e.g. new version), the old path has to be replaced by the new one in BSINSTALL and in the PATH. The following scripts do it, in the current shell and in the file given in Section 1.2 (a backup copy of this file is kept). Run them from the new BetaShape directory, or give the new directory as argument:

* Ubuntu:      source update_bsinstall_ubuntu.sh
* macOS:       source update_bsinstall_macos.zsh
* Windows:     update_bsinstall_windows.cmd (or double-click on it); the user variables BSINSTALL and Path are modified.

Terminals already opened keep the old PATH: open a new one. Then check with: betashape -version


-----------------------------------------------------------------------------------
2. How to use the BetaShape code

Running the benchmark calculations is recommended at first use of BetaShape (see Section 3).

All input and output files are text files, whatever the file extension.

To use the code, provide a formatted ENSDF file as an input to the betashape program. Such files can be downloaded on NNDC website (https://www.nndc.bnl.gov/) or on the IAEA Live Chart of Nuclides (https://www-nds.iaea.org/relnsd/vcharthtml/VChartHTML.html) or on DDEP website (http://www.lnhb.fr/nuclear-data/nuclear-data-table/). 

Default options are the recommended ones. Example:
C:\...> betashape Ni63.txt

List of options and default values (parameters not required for default values):
* sc=1           -> Numerical (tabulated) atomic screening. Others: sc=2 for Rose screening; sc=3 for Buhring screening; sc=0 turns off screening correction.
* ex=1           -> Numerical (tabulated) atomic exchange (only for beta minus transitions). Other: ex=0 turns off exchange corrections.
* ov=1           -> Atomic overlap correction (for beta transitions). Other: ov=0 turns off overlap correction.
* rd=1           -> Radiative corrections. Other: rd=0 turns off these corrections.
* ff=1           -> Search for an experimental shape factor within the database. Other: ff=0 turns off this possibility.
* nu=1           -> Calculation of neutrino spectra. Other: nu=0 for not calculating neutrino spectra.
* l1=0           -> Full calculation of theoretical shape factors. Other: l1=1 for additional calculation with lamda_k = 1 within theoretical shape factors.
* outprec=5      -> Precision digits. Others: any positive integer.
* Nstep=300      -> Number of energies to be calculated (constant step determined from maximum energy). Others: any positive integer.
* fixint=0       -> Splitting of the branch between electron capture and beta plus decays is calculated and used. Other: fixint=1 for keeping the intensities from the input file.
* myEstep=0.     -> BetaShape automatically manages the energy steps of the calculated spectra. Others: any positive double number (e.g. 'myEstep=1.') for fixing a constant energy step (in keV) for all calculated spectra.
* unc_digit=50   -> Rounding limit for uncertainties, from 1 to 99. 
* brnb=0         -> In the updated ENSDF file, B and E intensities, treated either as absolute or relative, are not updated. Other: brnb=1; intensities are updated as absolute and NB is updated consistently.
* brnb_lim=1.e-5 -> In ENSDF file, if |BR*NB - 1| <= u(BR*NB) or brnb_lim, B and E intensities are assumed as absolute and maintained. Otherwise, they are assumed as relative and recalculated, propagating the BR*NB uncertainty.
* mnu=0          -> Define neutrino mass, in keV. Others: any positive real number.
* mst=0          -> Define sterile neutrino mass, in keV. Relative probability also needs to be non-zero. Others: any positive real number.
* Pst=0          -> Define relative probability of sterile neutrino, in [0.,1.]. Sterile neutrino mass also needs to be non-zero. Others: any real number in [0.,1.].
* recoil=1       -> Nuclear recoil: beta, neutrino and recoil spectra consistently calculated from three-body kinematics. Other: recoil=0 turns off recoil.
* ibmodel=1      -> Internal bremsstrahlung spectrum in beta decay, including Coulomb effect and nucleus recoil (Ivanov). Other: ibmodel=0 for the faster Knipp-Uhlenbeck-Bloch model (no Coulomb effect nor nucleus recoil).
* rmsmodel=3     -> Root-mean-square charge radius model. 0: uniformly charged sphere. 1: liquid drop model. 2: along the stability line. 3: offline the stability line (default).
* -saisinuc      -> Creates a specific formatted output file for the Saisinuc Microsoft Access database. Default: turned off.
* -qval          -> Without this option, Q-values of the input file are kept. With this option, automatic update of the Q-values with AME2020 evaluation is considered. Default: turned off.
* -csv           -> Creates CSV files (separator is ',') for beta minus and electron capture / beta plus transitions.
* -csv_fr        -> Same as '-csv' option but separator is ';'.
* -asym          -> Treatment of asymmetric uncertainties in half-lives and log-ft values. Default: not activated, asymmetric uncertainties are symmetrized.
* -version       -> Print the code version in the command shell.
* -help          -> Print section 2 of the README file in the command shell.
* -silent        -> Prevent ordinary messages in the shell.


Example of a calculation with Q-value update and a constant energy step of 0.5 keV:
C:\...> betashape Ni63.txt -qval myEstep=0.5


-----------------------------------------------------------------------------------
3. Benchmark calculations

The script mybench can be used to automatically run benchmark calculations. The script mydiff is then called to show the differences between the calculated files and the reference files stored in the bench directory.

Beta and electron capture transitions are calculated for the following decays: 40K, 133I, 130Cs and 205Pb. Electron capture transitions take time to be calculated, especially for high Z. Differences can appear on the last digits depending on the operating system. 


-----------------------------------------------------------------------------------
4. CSV files

CSV files can be opened by any text editor and are automatically parsed by any spreadsheet software. A format description is given in Microsoft Excel file apart.

A line that starts with a hash symbol '#' contains comments or the header. Data can be separated by a comma ',' as in English format (option -csv) or by a semicolon ';' as in French format (option -csv_fr). 

Three types of CSV files can be generated by BetaShape:
- [Filename]_bm.csv for beta minus transitions.
- [Filename]_bp.csv for beta plus transitions if no electron capture transition is calculated.
- [Filename]_ecbp.csv for electron capture and beta plus transitions.

Each data line corresponds to a single transition. Quantities are defined in the header. Each quantity is followed by its uncertainty, if relevant. All energies are in keV, except the mean recoil energy of the energy balance block, which is given in eV. For each transition, information given is:
- Parent symbol, Z, A, Jpi, level energy.
- Daughter symbol, Z, A, Jpi, level energy.
- Q-value, half-life, transition nature, transition nature used, branching ratio, log ft, f-value.

The transition nature is given via a symbol: 'A' for allowed, 'iU' for i-th forbidden unique, 'jN' for j-th forbidden non-unique.

Jpi corresponds to the 'J' field within the input ENSDF file that defines the spin and parity of the nuclear level. Attention must be paid to possible multiple spins and parities in this field, separated by commas ','. For example, one can find: (7/2,9/2,11/2)-. Such commas disturb the automatic parsing of the CSV file. The use of the French version, with a semicolon ';' as separator, avoids this issue.

For beta minus transitions, and beta plus transitions if no electron capture transition is calculated, additional information is:
- Transition energy, calculated mean energy, experimental mean energy (if an experimental shape factor is present in the database), calculated mean neutrino energy, experimental mean neutrino energy.

For electron capture and beta plus transitions, additional information is:
- Electron capture: branching, log ft and f-value of this component, transition energy, mean neutrino energy.
- Beta plus: branching, log ft and f-value of this component, transition energy, calculated mean energy, experimental mean energy (if an experimental shape factor is present in the database), calculated mean neutrino energy, experimental mean neutrino energy.
Next, probabilities are given:
- Total EC/b+: name, value.
- Number of shells (K,L,M,etc.).
- For each shell: shell name, relative capture probability, capture probability, (capture probability)/b+
- Number of subshells (K,L1,L2,etc.).
- For each subshell: subshell name, relative capture probability, capture probability, (capture probability)/b+

Relative capture probabilities are defined such that their sum equals unity. Capture probabilities are defined as in ENSDF format, being the calculated fraction of the decay by electron capture from each (sub)-shell. The relationship between the former (e.g. PK) and the latter (e.g. CK) is: 
CK = PK * I(ec) / [ I(ec) + I(b+) ] 
where I(ec) is the electron capture branching of the transition, and I(b+) the corresponding counter-part.

For electron capture, the mean neutrino energy corresponds to the mean kinetic energy of the neutrino spectrum (lines + continuum).

Two comment lines of the header give the format version and announce the energy balance block:
# CSV format: 3.0
# Energy balance: yes (per transition for beta decays, per capture for EC; recoil energy in eV, other energies in keV)

Energy balance: each data line ends with the energy balance of the transition, as given in the 'Energy balance' section of the .bs files, per transition for beta decays and per capture for electron capture. The block always has 17 columns: a label, then available energy, mean beta energy, mean neutrino energy, mean recoil energy (eV), mean internal bremsstrahlung energy, mean atomic energy (shaking included), shaking energy and sum, each followed by its uncertainty. A cell is empty when the quantity is not calculated (calculation options) or does not apply (decay mode).
- [Filename]_bm.csv and [Filename]_bp.csv: one block labelled 'balance'.
- [Filename]_ecbp.csv: two blocks, 'balance ec' (electron capture) then 'balance b+' (beta plus branch; empty cells if there is no beta plus branch).


-----------------------------------------------------------------------------------
5. History

5.1 Main changes since v2.4

* All physical constants are now from CODATA 2022.

* Implementation of the '-version', '-help' and '-silent' options.

* All the programs are called in the bin/ directory of the installation directory (BSINSTALL), so that BetaShape can be run from any directory.

* CSV files: energy balance of each transition added at the end of each data line; format version given in the header ('# CSV format: 3.0'); for electron capture, the mean neutrino energy is now the mean kinetic energy of the neutrino spectrum (lines + continuum).

* Intensities with non numerical uncertainties are now limited to three significant digits.

* Information about experimental shape factors provided in updated ENDF file modified to agree with ENSDF rules.

* If |BR*NB - 1| <= u(BR*NB) or 1.e-5 (namely, 0.001%) in the ENSDF file, beta and capture intensities are assumed as absolute, i.e. they are not recalculated employing the BR*NB normalization factor. Otherwise, the intensities are assumed as relative and recalculated, propagating the BR*NB normalization factor and its uncertainty. The limit of 1.e-5 can be changed with the 'brnb_lim=' option. 

* By default (brnb=0), beta and capture intensities are not updated in the new ENSDF file. With the brnb=1 option, they are updated as absolute and NB is updated consistently.

* With nu=1 option, atomic orbital energies and neutrino energies are now given in the output file specific to each electron capture transition.

* A neutrino mass can be defined with the option 'mnu=' followed by an energy in keV. Example: 'mnu=0.5' defines a neutrino mass of 0.5keV. Default: mnu=0.

* A sterile neutrino can be defined with the option 'mst=' to define its mass (same as 'mnu=') and its contribution with the option 'Pst=' followed by a number between 0 and 1. Default: mst=0 and Pst=0. Both mst and Pst must be non zero for accounting of a sterile neutrino contribution.

* Different models from Angeli [IAEA report INDC(HUN)-033, 1999] are available for the root-mean-square charge radius, consistently propagated throughout the modelling.

* Change in atomic overlap correction: B'' now derived from B employed in AME2020; relativistic correction beyond sudden approximation added for b+ decays (no such correction for b-).

* Internal bremsstrahlung (IB) photon spectra are calculated for beta and electron capture transitions when radiative corrections are switched on (rd=1).
  - Beta transitions: model of Ivanov et al. (option 'ibmodel=1', default; [PRC 90, 064608, 2014]) or model of Knipp, Uhlenbeck and Bloch (option 'ibmodel=0', [Physica 3, 425, 1936; Phys. Rev. 50, 272, 1936]). The photon intensity is the total radiative correction times the transition intensity. The mean photon energy is given per emitted photon, as for electron capture transitions: the product of the photon intensity and the mean photon energy is the IB energy per decay. The IB energy per beta decay, given in the energy balance, is determined from the calculated spectrum before its normalization. Because of the infrared divergence of the IB spectrum at low energy, the number of photons, and thus the mean photon energy, depend on the normalization to the total radiative correction, whereas the IB energy per decay does not. The mean photon energy recalculated from the printed spectrum can differ from the given value for large energy steps. It is recommended to take the printed mean photon energy and photon intensity.
  - Electron capture transitions: Coulomb-free model of Morrison and Schiff [Phys. Rev. 58, 24, 1940] for the s subshells, weighted by the capture probabilities. Capture from other subshells does not contribute. The mean photon energy is given per emitted photon; the IB energy per capture is given in the energy balance.

* Nuclear recoil is now described for beta and electron capture transitions. 
  - For beta transitions, beta, neutrino and recoil spectra are consistently calculated from three-body kinematics (option 'recoil=1', default; 'recoil=0' turns off recoil). Recoil spectra are given in eV. 
  - For electron capture transitions, the two-body recoil energy is given for each subshell and each neutrino channel (regular and sterile, if defined). Continuous recoil associated with IB emission is neglected, keeping the two-body value.

* Detailed energy balance for each transition: the mean energies of the emitted particles are compared with the available energy. For beta transitions, a small residual exists because four-body treatment would be necessary with IB emission. It is absorbed in the neutrino spectrum by an exponential tilt of its shape; the beta spectrum is not modified. For electron capture transitions, the balance is given per capture (neutrino, IB photons, recoil, atomic energy available for relaxation) and per subshell. Shaking is not included in the spectra; it is accounted for in the energy balance as a global estimate within the atomic energy.

* Total spectra of each radionuclide: recoil and IB spectra are added for beta transitions. For electron capture transitions, a new output file (capt_[Element][A]_tot.bs) gives the total neutrino spectrum (lines from non-radiative capture, continuum from radiative capture), the total IB spectrum and the mean energy balance per capture. Totals of electron capture and beta plus transitions are given separately.

* Uncertainties of the total spectra and mean energies have been revised. The uncertainty on the intensity of each transition is propagated, including when there is a single transition. The uncertainty of a weighted mean energy accounts for the uncertainties of both values and weights. The total mean IB photon energy is weighted by the photon intensities, for beta and electron capture transitions.

* A missing or incomplete transition file is not accounted for in the total spectra; a warning is given in the total file and in the mult.log file.

* [Beta version] Input files in the NNDC ENSDF-JSON format are accepted (extension .json): the input file is converted to the ENSDF format before the calculation, and the updated file is also given in JSON format ([Filename]_updated.json). A scheme is proposed to include correctly the information on experimental shape factors.


5.2 Main changes since v2.3

* Better management of end-of-line characters (CRLF for Windows, LF for Linux based OS) in input files. Basically, input file is re-written and the original one is saved as your_input_file.extension

* Better management of calculation over a full mass chain. Tested and validated on the entire ENSDF database, archive version of January 2024.

* Extensive tabulation of wave function overlaps required for EC transitions. This drastically speeds up EC calculations.

* Possibility to define an environment variable (BSINSTALL). The code can then be run from anywhere.


5.3 Main changes since v2.2

* Update of some experimental shape factors in the database.

* Numerical atomic screening and exchange correction through tabulated values. Formalism implemented for specific treatment of allowed and forbidden unique transitions.

* Atomic overlap correction as in L. Hayen et al., Rev. Mod. Phys.90, 015008 (2018). Automatically switched off for ultra low-energy transitions for which there is no sufficient energy.

* Propagation of non-numeric uncertainties.

* Propagation of asymmetric uncertainties in half-lives and log-ft values with the Min-Max method.

* Rounding limit can be changed with a simple option. For example, changing the rounding limit of 50 (default) to 35 requires to add the option 'unc_digit=35'.

* Mean neutrino energies (beta minus, beta plus and electron capture transitions) added in CSV files, only if neutrino option is switched on ('nu=1').

* f-values added in CSV files.

* Modification of forbidenness assignement: in case of several spins or parities for the same level, previous treatment was "first read, first used". Now, the transition is treated as allowed.

* Transition intensities: N and PN records are now (re-)used to determine a global normalization factor. Uncertainties are propagated.


5.4 Main changes since v2.0

* A new option has been implemented that allows the creation of CSV output files. These files provide a lot of information (mean energies, log ft, capture probabilities, etc.) except continuous spectra. Usual (English) CSV files can be generated with the '-csv' option. French CSV files (separator is ';' instead of ',') can be generated with the '-csv_fr' option.

* Some bugs have been fixed regarding the printout of EC and B+ intensities in ENSDF files in specific cases. Additional records on the last line of ENSDF files was not manage correctly, now fixed.

* Value of tropical year is now from Particle Data Group review 2020.

* Q-values can be updated on-the-fly with AME2020 evaluation (option is now '-qval'). The new Q-value is then used in all calculations and set in the updated ENSDF file. In the report file, old and new parent cards are given.

* A progress bar in the terminal has been implemented.

* Name of the main executable 'readENSDF' has been changed to 'betashape'.

* Transition intensities are now assumed to be absolute, i.e. per 100 decays of the parent nucleus, in the ENSDF file. It means that N and PN records are disregarded, only B and EC records are considered for transition intensities. It is user responsibility to make sure about the EC/B feedings. Such treatment is consistent with ENSDF policy (from the last 15 years). 

* Treatment of EC/B+ intensities has been revised to ensure the consistency of the recalculated intensities and their uncertainties. A bug has been fixed: the code was previously crashing when transition energy and its uncertainty were around the B+ threshold (e.g. 1025 (10) keV).

* A new option has been implemented for ensuring an automatic coupling with the Saisinuc Microsoft Access database (used by the DDEP international collaboration on atomic and nuclear decay data evaluations).

* Experimental shape factors given in the updated ENSDF files are described in a comment line following printing ENSDF policy.


5.5 Main changes since v1.0

* Some bugs have been fixed regarding the printout of numbers in some specific cases. 

* In v1, it was not possible to switch off the radiative correction because the option was not activated in the code. It is now possible in v2.

* In v1, the input ENSDF file was given to the readENSDF program through the option 'inpf='. In v2, this option has been removed and the input file is the default input parameter. This allows to drag-and-drop the input file on the executable of the readENSDF program.

* Uncertainty treatment has been changed when no uncertainty is existing in the input file for a given quantity. In v1, an uncertainty of about 60% of the value (estimated from a flat distribution) was considered, leading to unrealistic uncertainties especially for energy levels. In v2, a null uncertainty is considered (as in the LogFT code) and it is the responsibility of the user to manage such a case.

* All physical constants are now from CODATA 2018.

* Names of elements are now included up to Z=118 according to IUPAC recommendations.

* Q-values can be updated on-the-fly with AME2016 evaluation (option is 'qval=1'). The new Q-value is then used in all calculations and set in the updated ENSDF file.

* The radiative corrections for beta decays have been revised. The formalism from J.C. Hardy and I.S. Towner (Phys. Rev. C 91, 025501 (2015) and references therein) used for high-precision calculation of super-allowed Fermi transitions, has been considered. The charge density distribution of the nucleus is modelled by a two-parameter Fermi distribution for which the parameters are adjusted to reproduce the rms nuclear charge radii of I. Angeli determined along the stability line (see IAEA Nuclear Data Section, INDC(HUN)-033 (1999)). An excellent agreement was found with the total radiative corrections given by J.C. Hardy and I.S. Towner.

* Some experimental shape factors have been updated or added: 14O, 36Cl and 138La. Parameters in database have changed for 66Ga and 137Cs compared with database in BetaShape v1, however the shape factors are still identical (only their treatment in the C++ class has changed).

* Experimental shape factors are included in the updated ENSDF file as a continuation record.

* Electron capture are now treated. The computational time is significantly higher than for beta decays.

* Relative capture probabilities are given in the updated ENSDF file. It is not clear what exactly is given in the ENSDF format. Something to discuss with Balraj, Filip, etc.

* Splitting of the branch between electron capture and beta plus decays is calculated when relevant. The intensities are updated and used consistently in all calculations. It is possible to force the code not to update the intensities and to use consistently the input intensities in all calculations (option is 'fixint=1'). This option is useful when, for example, a capture-to-positron ratio is determined from measurements and adopted in the evaluation. 

* It is now possible to fix a constant energy step for the calculated spectra (single, total, beta and neutrino). For example, to fix an energy step of 1 keV, the option is 'myEstep=1.' (energies are assumed to be in keV). Additional output files are then created with this energy step.

* Log ft values calculated from experimental shape factors are given only for information. Their correctness depends on the method used to extracted the experimental shape factors and cannot be guaranteed. 
