================ BetaShape v2.3.1 ================ ----------------------------------------------------------------------------------- 1. How to use the BetaShape code Running the benchmark calculations is recommended at first use of BetaShape (see Section 2). Make sure that the local directory is defined in the PATH: - MacOS and Ubuntu to check: echo $PATH to set: export PATH="$PATH:./" - CentOS8 and Scientific Linux to check: echo $PATH to set: setenv 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 (through your .bash_profile, or .ucshrc, or .zshrc, etc.). 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 Bühring 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=0 -> No calculation of correlated neutrino spectra. Other: nu=1 for 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. * -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. 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 ----------------------------------------------------------------------------------- 2. 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. ----------------------------------------------------------------------------------- 3. 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. 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. ----------------------------------------------------------------------------------- 4. History 4.1 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. 4.2 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. 4.3 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.