'lvl_builder' Program Introduction

lvl_builder is a python script to build an energy level scheme that is normally used in the nuclear physics. There are several good plotting tools already for energy level scheme, such as a Mathematica plug-in LevelScheme, and well-known Radware program. So...what's new for this lvl_builder program? OK, there are several useful features.

My goal of writing lvl_builder is to let users don't worry about the calculations or arrangement. (I wish to make the plotting a fun and easy task). The spirit of lvl-builder is similar to using Latex, one just inputs very minimal information for level and gamma, and the program does all the hard work for you. Meanwhile, the lvl_builder uses the xmgrace, one of very popular and powerful scientific tool, as the rendering tool, and so user can get the full control of "ALL" the details.

Still thinking about the input job is too tedious? I have another small program, parseNNDC2, which can turn the data at the NNDC website into the input file format for 'lvl_builder' so that you can have a plot in just a second. Of course, the presentation will be raw, but the adjustment is very quick.

Demos

demo1:

Figure: a fake level scheme to demonstrate the basic proprieties of lvl_builder. (input file)
Here we can see:



demo2:

Figure: a demo for the evolution of the states among several nuclei. The length of the bar indicates the strength of spectroscopic factors. (input file)

demo3:

Figure: a demo for beta-decay level scheme. It contains some "invisible" auxiliary lines. (input file)

demo4:

Figure: Raw results from the parseNNDC2 program. There are 35 states and 63 gamma rays.


Figure: Raw results from the parseNNDC2 program for A=even Si isotopes under 4000 keV.


How to run

The files can be downloaded from my Github.

Since lvl_builder uses xmgrace to plot, xmgrace has to be installed. This script works for both Python2.7 or Python3.X. Run linux command chmod 755 ./lvl_builder.py to make the file executable.

./lvl_builder.py inputfile [fine_control_paramter_file] [ouput]
The "fine_control_paramter_file" and "output" are optional arguments.
By default, it reads in "fineParameter.txt" file, and the default output is output.ps.

for example:
./lvl_builder   demo_general_properties.txt   fineParameter.txt

In the package, there is a "preview_tool.py" python script. It may help you quickly make a draft. There is a text box at the bottom. You can type in the syntax for a level and a gamma. Use the "plot" button at the menu bar or to plot. See the following demo.



Quick Start

Let's talk about the basic of the input file.
There are only two categories -- level and gamma.
a line starts with "#" will be treated as a comment. and an empty line will be ignore.
The format is @key1 value1 @key2 value2 ....

For a level, there are two required key-value pairs -- lvlE and bandN. For example:
@lvlE 0 @bandN 1 , you create a level at energy 0, and it locates at bandN ( region ) = 1.
@lvlE 100 @bandN 1 , now you know this is to create a level at energy =100, and at bandN 1.

By default, lvlE = 100 or 100.0 or 100.1 will all display as a level at 100, since the levelDigit is set to 0 in the fine_control_paramter_file file. But they are treated as different levels. You can use this as a trick to set the second "ground state".

bandN can either positive, negative value or 0,
and you can create a level across multiple band by use "_", ex. 2_3,
or -1_3, which will cross from bandN = -1 to bandN = 3.


For a gamma, and we have two required key-value pairs; they are Ei adn Ef -- the energies for the initial state and final state. For example:
@Ei 100 @Ef 0 , we will connect the states with an arrowed line.

You can notice the gamma automatically changes its placement when we adjust its levels. Furthermore, when an initial state and a final state are too far away, we will add an auxiliary dashed line. (You can also define how far to let the auxiliary line appears, which can be set in the fine_control_paramter_file. )

Now, you have learn the most essential part of lvl_builder program, and you are good to explore more options.
Just remember: for a level, we require "lvlE" and "bandN", for a gamma "Ei" and "Ef" are required.



Optional keys

For a level, your optional keys:


for example:
by
@lvlE 100 @bandN 1 @spin 2+ @color red @linewidth 20 @linestyle 2



by
@lvlE 200 @bandN 1 @label SF=0.8 @boxW 0.8 @boxColor red @linewidth 20



For a gam, your optional keys:


for example:
, the gamma is set by
@Ei 100 @Ef 0 @I 15.2 @label 100? @color blue @arrow 0



fine tune parameters

You can fine tune the output details in case you want to improve the default output.



Adding text

It is possible to add some texts below each band, such as the following figure.

The command will be a little bit longer:
./lvl_builder.py inputfile fineParameter output bandTextfile.
Currently, you cannot skip fineParameter and output.

The format for a bandTextFile is as following: 

    # this is comment.
    # bandN "TEXT"
    0    "31Si"
    1    "33Si"
The lvl_builder program will calculate the position of the text, and the text will be placed the bottom.



A brief note for the gamma grouping algorithm

If you are interested in how gammas are grouped and arranged, here are some short notes for you.

The first concept is the overlapped range. For simplicity, I call it xi-xf range. ( the wedge shape level makes the xi-xf range a little bit complicated)


Then let's talk about the concept of X subgroup first. When the gammas have the same xi-xf range, they will be grouped, and I call the they are in the same X subgroup.


It is also worthy of having a y subgroup within a x subgroup. In this way, we can do some manipulation on each y subgroup, so that we can save more space.


Finally, in a y subgroup under a particular x subgroup, we re-arrange the gammas in such way that the divisions are minimal ( to save space).