========================================================================================
                              Software for FRIB-TA summer school
                           August 2025 - Tim Gray - tgray30@utk.edu
========================================================================================

General requirements:
---------------------
You will need access to a computer with 
- a FORTRAN compiler
- a python3 installation
- a C++ compiler

For example, on an Ubuntu machine
sudo apt install gfortran
sudo apt install g++
sudo apt install python3 

On macOS, homebrew or macports are your easiest solutions.

On Windows, I would recommend getting Windows Subsystem for Linux (WSL) set up

========================================================================================
kshell
------

Shell-model code: download here (https://sites.google.com/alumni.tsukuba.ac.jp/kshell-nuclear/). Put into an "install" directory called "kshell". Open up the file

kshell/src/Makefile

in a text editor. You will see some options at the top: by default the compiler is the Intel Fortran compiler. Comment this out, and uncomment the section relevant to whichever compiler you have -- probably the GNU Fortran compiler gfortran. Save the Makefile, and while in that directory run 

make

Next, add the "bin" directory to your $PATH environment variable. Open up the text file ~/.bashrc in a text editor (or ~/.zshrc if you use the ZSH shell). Add a line

export PATH="<path-to-your-kshell-folder/bin/":$PATH

If you restart your terminal, and enter some "working directory" (where you want to run a calculation), you should be able to run

kshell_ui.py

and be greeted by a message like this:


-----------------------------
  KSHELL user interface
     to generate job script.
-----------------------------

with a question/answer interface to run your calculation. You may encounter this error:

/usr/bin/env: ‘python’: No such file or directory

to fix this, edit the bin/kshell_ui.py script. At the top, change 

/usr/bin/env python

to 

/usr/bin/env python3

You may have to do this with some of the other python scripts in the same "bin" directory: "collect_logs.py" collates the output and is another one that will be called directly.

==============================================================
Particle-Rotor programs
-----------------------

There are two particle-rotor packages that are included here. The first is a set of FORTRAN programs which are in the "ParticleRotor" directory. You can compile these with 

make

If you wish, you can add this folder to your $PATH variable, so that they can be called from any directory. The is a manual (PRmanual.pdf) included, along with some examples in the "IR-Example" directory

The second package is essentially a partial re-write of the FORTRAN particle-rotor programs in modern C++. This is in the "PRM" directory. To install, you will need a few dependencies: namely the GNU Scientific Library (GSL), see here https://www.gnu.org/software/gsl/ and Armadillo packages (https://arma.sourceforge.net/). On an Ubuntu system, these can be installed from the repositories with

sudo apt install libgsl-dev
sudo apt install libarmadillo-dev

Once these are installed, you can compile the main program with 

cd src/
make
cd ../

The executable "PRM" can be run with

./PRM

which will bring up an interactive plot. Otherwise, an input file can be specified

./PRM prmtest.inp

Outputs will be written to the output file (specified in the input file, in this case prm.out). Useful features include viewing a Nilsson plot: if you run

./PRM

to bring up the interactive interface, and then

load prmtest.inp

to load the parameters in the input file, and run the calculation, you can then run

epsplot -0.4 0.4 0.02

To bring up a visual representation of the Nilsson orbits as a function of epsilon (deformation). Type 

help

to view other commands.

=======================================================================================
Generalized Triaxial Rotor Model

This is a pure python3 script. You will need numpy, matplotlib, and sympy installed. Run with

./gtrm.py

With no arguments, it will start an interactive prompt. Example input files for 186Os and 110Ru are included (os186.inp and ru110.inp). If you run 

./gtrm.py os186.inp

It will read in the input parameters from the input file and run the calculation. A plot showing the calculated level scheme should appear.

There are options to fit either energy levels or E2 strengths. These are commented out at the bottom of the two input files. They fetch experimental data from os186_me.txt or ru110.lvl, and adjust model parameters to find the best fit.

There is an additional script "gtrm_batch.py" that gives and indication of how you may use the GTRM code as a library. This script loads the GTRM classes, reads an input file, and then adjusts some parameters through a loop, re-calculating the GTRM results each time. You may experiment with taking different outputs from the GTRM calculation class, plotting them and/or writing them out to different files.

