%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
This is the README file for PRIMAT (version 0.3.0), a code to perform BBN computations, maintained by Cyril Pitrou.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
30 september 2024
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

If you use PRIMAT for publications, please cite along the website and the companion paper (Pitrou et al. 2018, arXiv:1801.08023, Physics. Rept. 04 005 (2018)).


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-The main code of PRIMAT is the file PRIMAT-Main.nb
First open the notebook in Mathematica. Then in the Evaluation menu, select ‘Evaluate notebook’. If asked the question ‘evaluate initialization cells first ?’, answer no. Then Mathematica proceeds in evaluating all cells, in order, and it should reach the end of the notebook (with the plots and results) in less than one minute.


-Furthermore, when PRIMAT-Main.nb is opened and saved in Mathematica, the cells which are 'initialization cells' are saved into PRIMAT-Main.m. 
This file contains then all the principal definitions and functions and variables
which can be loaded from another notebook to perform BBN computations and analysis of results. The ‘Examples’ Folder contains several typical applications which work exactly like that (first it loads all necessary definitions stored in PRIMAT-Main.m and then it performs a few useful computations for each selected example).


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
*’Examples’ Folder

Several examples are located in the Examples folder. see READme file in that folder.



%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
*’CSV’ Folder
Interpolations of weak rates (but also for QED plasma corrections and neutrino incomplete decoupling) are computed and stored in this folder. They can be overwritten if appropriate booleans in PRIMAT-Main.nb are set to True ($RecomputeWeakRates,$RecomputePlasmaCorrections). On some machines and for some versions of Mathematica, there is an incompatibility with the files which are packaged in the PRIMAT zip file. In that case, the code outputs non-sense as it cannot read them. Just erase all files in the ‘CSV’ folder to force Mathematica recomputing them. The first time, it might take a few minutes or about an hour and then the second time it should run rapidly as it would use the newly created files.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
*'PythonInterface' folder
An example (as a python notebook PRIMAT_python_demo.ipynb) of how PRIMAT can be called within python and its results retrieved (via storing in the disk in csv files). This can be used to template a python code which must call PRIMAT. See Readme file in that folder.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
*'Plot' folder
When running PRIMAT with some options asking for plots, this is the default folder in which the plots are stored. It must exist (even if empty) in order to avoid errors of output.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
*'Results' folder
When running some examples in the Example folder, this folder is used to store the results which are quite often results of Monte-Carlo estimation of uncertainty.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
*'lib' folder
The code is now fast to load because it compiles the main functions which are used in the differential equation solver. The compile libraries (.dylib on Mac), are usually destroyed in Mathematica. Hence to avoid loss of time and recompilation for each new Kernel, they are stored in that folder. If they already exist, then PRIMAT reads them instead of redefining these compiled functions, which saves about 2 seconds. This can be overridden by erasing the content of the folder, or by setting the option $Recompile=True. This storing of compiled function can also be bypassed by setting $StoreCompilation=False which is advised if it happens to crash on different OS for which this was not tested.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
*'Rates' folder
Most of the rates, and the most relevant for BBN, are stored in an external file (created by Alain Coc).
The full file is BBNRatesAC2022.dat and contains several hundreds of reactions, whereas BBNRatesAC2022_small_network contains only the 12 important ones (hence it makes 13 reactions when adding the weak rates which convert neutrons and protons).


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
Should you find difficulties in using PRIMAT, please email to
pitrou@iap.fr
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

The file PRIMAT-Main.pdf is a pdf dump of the Mathematica notebook that can be used to visualize the code without a Mathematica front-end.

Note also that you can collapse the sections of the Mathematica notebook for better readability. 

The file PhysReptArxivVersion.pdf is the arXiv version (1801.08023) of the published Physics Reports, 04, (2018) 005. 
All equations in the code refer to the arXiv version numbering.