Rachel GUI

From GOSIA

Jump to: navigation, search
(→Beta version capabilities: Added BR, matrix element, lifetime and mixing ratio data capability)
(Changed installation to include forking the git repo.)
 
Line 1: Line 1:
-
==Rachel, a GUI for Gosia==
+
==General description==
[[File:Guisnapshot.png|thumb|right|A snapshot of the alpha version GUI.]]
[[File:Guisnapshot.png|thumb|right|A snapshot of the alpha version GUI.]]
-
===General description===
+
For a demo of Rachel's capabilities, watch [http://youtu.be/moVVC-GODzQ The Rachel Video on Youtube], or [http://www.pas.rochester.edu/~hayes/beta_rachel/main_ad.html Download the mp4 (9MB)].
-
A GUI (Graphical User Interface) has been developed for Gosia version 20081208.10 and is currently undergoing beta-testing.  The latest beta-test version can be [downloaded here].  Rachel is written in Python 2.6 and is expected to be Python 2.7 compliant.  It runs under Linux and Unix (OS X) machines, but is ''not'' Windows compatible.
+
The Rachel interface facilitates [http://www.pas.rochester.edu/~hayes/beta_rachel/calculation_in_2_minutes.html fast setup of Gosia calculations] and data analysis using push-button controls with guided input and 'plain language' warnings during setup.  Rachel is written in Python 2.6 and is expected to be Python 2.7 compliant.  It runs under Linux and Unix (OS X) machines.  A Windows version is not planned.
-
A 64-bit processor is desirable, because Gosia runs fastest and most accurately on 64-bit machines.  The release-candidate version, expected in early 2011, will have many structural changes in the code, allowing more automation, more general particle detector options and fewer user prompts for standard operations.
+
A 64-bit processor is essential, because Gosia runs fastest and most accurately on 64-bit machines.  Versions 1.* have many structural changes in the code, allowing more automation, more general particle detector options and fewer user prompts for standard operations.
-
[[File:Typicalgosiainput.png|thumb|right|Excerpt of a typical Gosia input for a collective system.]]While gosia.20081208 incorporates the [[OP,BRIC]] command to read internal conversion data from BrIcc data files, removing the burden of entering ICC interpolation data by the user, the GUI allows the greatest possible automation by prompts for pre-defined or user-defined germanium detector crystals or arrays, calculation of Zeigler stopping power data, optimum meshpoint selection for yield calculations, transformation of rectilinear detector definition to laboratory-frame spherical-polar interpolation coordinates, etc.  For standard problems, the burden on the user is reduced to entering nuclear level and matrix data for simulations (including optional data-set simulation) and real experimental data for fitting.  For collective systems, where the matrix definition often includes several hundred lines of matrix elements, rotor parameters can be given to reduce the input definition considerably.  This also eliminates the need for the user to re-index the reduced matrix elements by hand as changes are made to the matrix.
+
[[File:Typicalgosiainput.png|thumb|right|Excerpt of a typical Gosia input for a collective system.]]While gosia.20081208 incorporates the [[OP,BRIC]] command to read internal conversion data from BrIcc data files, removing the burden of entering ICC interpolation data by the user, the GUI allows the greatest possible automation by prompts for pre-defined or user-defined germanium detector crystals or arrays, calculation of Zeigler stopping power data, optimum meshpoint selection for yield calculations, transformation of rectilinear detector definition to laboratory-frame spherical-polar interpolation coordinates, etc.  For standard problems, the burden on the user is reduced to entering nuclear level and matrix data for simulations (including optional data-set simulation) and real experimental data for fitting of matrix elements.  For collective systems, where the matrix definition often includes several hundred lines of matrix elements, rotor parameters can be given to reduce the setup time for the initial guesses of matrix element values.  This also eliminates the need for the user to re-index the reduced matrix elements by hand as changes are made to the matrix or level scheme.
-
===Upgrade strategy===
+
==How to get the Rachel package==
-
Upgrades are being made to incorporate all of the capabilities of Gosia, with a focus on the most commonly used features.  Prioritization of the upgrades will be directed primarily by Gosia user input on the [[Gosia forum]]. Users are encouraged to submit requested upgrades to handle present features of Gosia that are not already included, ''as well as new functions that Gosia does not handle, but which could be incorporated via the GUI.'' 
+
Get the latest release version from the [[Gosia#Downloads | Downloads section on the Main Page]].
-
===GUI version backward compatibility===
+
==Version notes==
-
The GUI preserves backward-compatibility of the saved session files, so that users can upgrade the GUI without having to rebuild the session.
+
The [[Gui_release_notes | version notes page]] gives a history of Rachel updates.  Known issues are given for each version, as well as the current version.
-
===Beta version capabilities===
+
==Installation notes==
 +
===General===
 +
 +
A script was added by Mitch Allmond that compiles and sets up Rachel, Gosia and Elast in one step.  First, un-tar the distribution, or pull the git repo from the [[Gosia#Downloads | Downloads section on the Main Page]].  Please fork it and make pull requests if you have anything to contribute.
 +
 +
<pre>
 +
% tar -xvf rachel_distribution_1.3.0.tar
 +
</pre>
 +
 +
or similar for the correct version number.  Move into the new Rachel directory and run compile-all.sh:
 +
 +
<pre>
 +
% cd rachel_distribution_1.3.0
 +
% ./compile-all.sh
 +
</pre>
 +
 +
You will be prompted if any previous setup information needs to be overwritten.
 +
 +
Rachel has been installed successfully on a number of Linux and OS X systems.  Most problems are related to the level scheme graphics.  Refer to [http://matplotlib.sourceforge.net/faq/installing_faq.html#backends matplotlib backends] for remedies.  You can view or submit detailed installation notes for any particular operating system.  (Please link them to a separate Wiki page.)
 +
 +
If the default python environment set in the rachel.py executable is not appropriate, the following error will appear:
 +
 +
<pre>
 +
% [path].rachel.py
 +
/usr/bin/env: python2.6: No such file or directory
 +
%
 +
</pre>
 +
 +
The correct Python environment can be invoked by typing instead:
 +
 +
<pre>
 +
% [python] [path].rachel.py
 +
</pre>
 +
 +
where [python] is the Python executable with the correct path and [path] is the path to the rachel.py executable where the user installed it.
 +
 +
===Installation notes for other Linux/Unix systems===
 +
 +
* [[rachel_installation_ubuntu | Ubuntu]]
 +
* [[rachel_installation_open_suse | OpenSuse]]
 +
* [[rachel_installation_fedora | Fedora]]
 +
* [[rachel_installation_mac_os_x | Mac OS X]]
 +
 +
The final tests that all necessary libraries and codes are installed are usually the following:
 +
 +
* Load a level scheme and see that the level scheme window is drawn properly.  Rarely, after loading a level scheme with no errors (e.g. using one of the example files included in the Rachel distribution), the user must click "Examine fig. window" once to create the level scheme window.  On most systems, with the correct libraries installed, the level scheme display pops up when a valid level scheme is loaded with no errors.  If the GUI starts and can load and draw the level diagram without errors, then it is unlikely that there are any missing libraries.  Also note that on some systems the matplotlib back-end must be changed.  This is done by editing the <tt>~/.matplotlib/matplotlibrc</tt> file so that the back-end line reads
 +
 +
<pre>
 +
backend : [backend]
 +
</pre>
 +
 +
where <tt>[backend]</tt> may be one of several back-ends described here: [http://matplotlib.sourceforge.net/faq/installing_faq.html#backends matplotlib backends].  Usually <tt>TkAgg</tt> works except on Mac OS X.  Refer to [[rachel_installation_mac_os_x | Mac OS X]].
 +
 +
* After running a calculation ("integration"), test the yield-plotting feature using the "Plot yields" button.  If there is an error finding gnuplot, install gnuplot on the system so that it is in the user's path, i.e., that it can be invoked by typing "gnuplot" at the terminal prompt.
 +
 +
 +
==GUI version backward compatibility==
 +
 +
In the beta versions, the GUI preserves backward-compatibility of the saved session files, so that users can upgrade the GUI without having to rebuild the session.
 +
 +
When changing to version 1.0 or later, users will have to rebuild their sessions, because of major changes in the internal structure that cannot be automatically upgraded.  This can be aided by the export/import tools for the level and matrix data.  Subsequent versions will have the automatic upgrading reinstated.
 +
 +
==Graphics Issues==
 +
 +
If you do not see a level scheme diagram after loading a level scheme or a saved session, click "Examine fig. window" once.  The level scheme should then appear.
 +
 +
If it does not, or if the level scheme window buttons (zoom, pan, etc.) do not work, you may need to change the graphics back-end.  The matplotlib graphics library used for the level scheme and particle detector layout comes with several choices of back-ends. 
 +
 +
*On OS X machines, "macosx" may work best.
 +
*On Ubuntu, GTKAgg works best, but the user must click "Examine fig. window" 'once' after loading a level scheme or saved session.
 +
 +
The back-end is in the matplotlibrc file in the .matplotlib directory, or will be, after you start Rachel for the first time.
 +
 +
<pre>
 +
hayes@Sobchak:~$ cd .matplotlib/
 +
hayes@Sobchak:~/.matplotlib$ ll
 +
total 116K
 +
drwxr-xr-x  3 hayes hayes 4.0K Nov  5 12:30 ./
 +
drwxr-xr-x 125 hayes hayes  12K Nov  5 12:53 ../
 +
-rw-r--r--  1 hayes hayes  92K Oct 27 13:13 fontList.cache
 +
-rw-r--r--  1 hayes hayes  17 Aug 19 02:09 matplotlibrc
 +
drwxrwxr-x  2 hayes hayes 4.0K Oct 27 13:13 tex.cache/
 +
hayes@Sobchak:~/.matplotlib$ cat matplotlibrc
 +
backend : GTKAgg
 +
hayes@Sobchak:~/.matplotlib$
 +
</pre>
 +
 +
Change the backend line as desired.  The choices are found
 +
 +
 +
==Capabilities of version 1==
 +
 +
Note that there are major simplifications in the Ge detector array setup and data loading.
 +
 +
* Human-readable data files that are robust for changes in the experimental setup and level scheme
* Azimuthally symmetric particle detection
* Azimuthally symmetric particle detection
* Partitioning particle-detector data by azimuthal angle
* Partitioning particle-detector data by azimuthal angle
Line 27: Line 121:
* Normal or inverse kinematics experiments
* Normal or inverse kinematics experiments
* A user-expandable library of standard Ge crystals e.g. Gammasphere
* A user-expandable library of standard Ge crystals e.g. Gammasphere
 +
* A user-expandable library of detector arrays (Tigress, Miniball, Gammasphere...)
* Data from summed 4pi arrays
* Data from summed 4pi arrays
* Efficiency-corrected gamma-ray data only
* Efficiency-corrected gamma-ray data only
Line 35: Line 130:
* Accuracy testing to determine if Gosia will be appropriate for a planned experiment
* Accuracy testing to determine if Gosia will be appropriate for a planned experiment
* Fitting and correlated error estimations
* Fitting and correlated error estimations
-
* Reading level schemes and gamma-ray data from Radware AGS files and [[Rachel format nuclear data files]] including
+
* Reading level schemes and gamma-ray data from Radware AGS files and [[Rachel_yield_data_files | Rachel text format]] including
** Branching ratio data
** Branching ratio data
** Previously measured EM matrix elements, including the measured phases
** Previously measured EM matrix elements, including the measured phases
** Lifetime data for ''excited states'' (not the ground state lifetime)
** Lifetime data for ''excited states'' (not the ground state lifetime)
** Mixing ratios
** Mixing ratios
-
* Instantly generating plots of experimental vs. predicted yields via gnuplot  [[File:plottingexample.png|thumb|right|A plot of yield vs. spin in a rotational band generated instantly from the Gosia output and experimental data.  The plot has been expanded around several points using the zoom feature.]]
+
* Several supported data file formats
 +
** [Radware] AGS format
 +
** [[Rachel format nuclear data files]]
 +
** Gosia format (experimental yield and fitted matrix element data)
 +
* Instantly generating plots of experimental vs. predicted yields via gnuplot  [[File:plottingexample.png|thumb|right|A zoomed view of a plot of yield vs. spin in a rotational band generated from the Gosia output and experimental data.]]
* Automated generation of stopping power and internal conversion input for Gosia
* Automated generation of stopping power and internal conversion input for Gosia
-
* Push-button controls
+
* Push-button controls, optional pop-up guidance and guided prompts
* A searchable help function
* A searchable help function
-
* Saving the entire session to a file
+
* Undo/Redo of most functions and crash recovery
-
* Undo/Redo of most functions
+
 
-
* As of version 2 beta, automatic conversion of users' session files to upgraded formats
+
Using Rachel, the user will be able to build a level scheme from either a hand-written text file and/or a Radware AGS file, define the experimental setup and import relative-efficiency-corrected gamma-ray data from Rachel-format text and/or AGS files.  The matrix and fit parameters can be defined by push-buttons and prompts or imported from a Rachel-format matrix file.  Gosia will then be run by push-button GUI controls.  Most prompts will be preceded by help information, suggestions, or warnings.   
Using Rachel, the user will be able to build a level scheme from either a hand-written text file and/or a Radware AGS file, define the experimental setup and import relative-efficiency-corrected gamma-ray data from Rachel-format text and/or AGS files.  The matrix and fit parameters can be defined by push-buttons and prompts or imported from a Rachel-format matrix file.  Gosia will then be run by push-button GUI controls.  Most prompts will be preceded by help information, suggestions, or warnings.   
Line 52: Line 150:
For experiments that fit the capabilities above, the user can view the Gosia inputs to learn the format, but will not be required to type any input code.  Experienced Gosia users can export a GUI-generated input skeleton file and abandon the GUI to use the more advanced capabilities of Gosia.
For experiments that fit the capabilities above, the user can view the Gosia inputs to learn the format, but will not be required to type any input code.  Experienced Gosia users can export a GUI-generated input skeleton file and abandon the GUI to use the more advanced capabilities of Gosia.
-
===Tutorial videos and run-time help===  
+
==Upgrade strategy==
-
The Rachel manual has been incorporated into the [[Gosia manual]]. Tutorial videos generated with a pre-beta version are now available.  While the GUI control panel and some user input and output formats
+
Upgrades are being made to incorporate all of the capabilities of Gosia, with a focus on the most commonly used features.  Prioritization of the upgrades eventually will be directed primarily by [[software upgrade voting|votes]] cast by the user community.  Users are encouraged to submit requested upgrades to handle present features of Gosia that are not already included, ''as well as new functions that Gosia does not handle, but which could be incorporated via the GUI.''
-
have changed slightly, most of these changes should be obvious during operation.   
+
 
 +
This voting plan has not been implemented yet.  Users are encouraged to suggest desired upgrades through the Forum or the [[rachel_desired_upgrades | desired upgrades]] page to steer the software development.
 +
 
 +
===Planned upgrades===
 +
 
 +
There are a number of planned upgrades, many of which have already been added to versions 1.0 and later.  The upgrade plan and priorities will be changed based on user feedback and bug reports. 
 +
 
 +
# More accurate stopping power calculations for low-Z beams.
 +
# Improved graphics including
 +
## a transition from matplotlib graphics to pyGtk in the level scheme window
 +
## clickable objects in the level scheme diagram
 +
# Addition of Ge clusters with libraries of array geometries (Gammasphere, Agata, Miniball etc.)
 +
# Plot functions to visualize fit conflicts in the data
 +
# Improved object structure for Ge detectors.  This will reduce the burden on the user by automatically updating the data set passed to Gosia as the level scheme and matrix change.
 +
# Optional setting of symbolic matrix definitions, whereas now the matrix is stored numerically.  This will allow greater user control by allowing tuning of model parameters, e.g. <gam|E2|gsb> = M1 + a*M2, where 'a' can be adjusted by the user.
 +
# Optional simple distributed processing of some functions.  This will allow the user to set a maximum number of independent processes to speed up separable calculations (integrated yields, corrected yields and experiment simulations) by issuing a separate call to Gosia for each process<ref>True distributed computing is not handled by the current version of Gosia</ref>.
 +
 
 +
==Videos, manual and run-time help==
 +
 
 +
===Quick advertising and demos===
 +
 
 +
[http://www.pas.rochester.edu/~hayes/beta_rachel/main_ad.html The Rachel advertising video]
 +
 
 +
[http://www.pas.rochester.edu/~hayes/beta_rachel/calculation_in_2_minutes.html Fast setup of Gosia calculations]
 +
 
 +
===Help with Rachel on this Wiki===
 +
 
 +
Use the search function to the left, or start here.
 +
 
 +
[[rachel_selected_topics | Selected help topics for Rachel]]
 +
 
 +
===Tutorial videos===
 +
 
 +
[[rachel_1.0_tutorial_videos | New Tutorial videos]] are being produced for version 1.0.  These will be much shorter and more focused than the old videos.
 +
 
 +
You can still watch [[rachel_beta_tutorial_videos | beta-version tutorial videos]], but there have been many changes.  General procedures are similar.  These old videos contain more topics per video, so some are quite long.
 +
 
 +
===The manual===
 +
 
 +
The Rachel manual has been incorporated into the [[Gosia_Manual | Gosia manual]]. 
 +
 
 +
===Other help resources===
Run-time help is available using the Help button.  Users are encouraged to submit suggestions for additional help data.
Run-time help is available using the Help button.  Users are encouraged to submit suggestions for additional help data.
-
====The basics====
+
===Experiment planning and accuracy testing tools===
 +
 
 +
The simulation tools have been improved since the recording of these video tutorials.  The user will find extra prompts for the details of the planned beam run, and estimated absolute measured counts will be calculated and displayed.  The display format looks like the following:
 +
 
 +
<pre>
 +
Experiment 1
 +
Target excitation by Z,A = 54,136 at 517 MeV. Mean scattering angle = 45.0 deg.
 +
Detector 1
 +
Single crystal at theta, phi = 45.0, 45.0 deg. Solid angle = 0.06 sr.
 +
This simulation does not include random gaussian scatter.  Counts represent the cross sections calculated by Gosia.     
 +
      Transition            |  Gammas incident      |                    Fraction of |        Observed Counts       
 +
                              |  on Ge detectors      | Gamma              Incident    |                               
 +
Initial        Final        |                      | Energy **Detector  Gammas      |                               
 +
    Band Spin    Band Spin  | Counts    *Error      | (keV)  Efficiency  Detected    | Rate(Hz)  Counts  ***Error   
 +
-------------------------------------------------------------------------------------------------------------------------
 +
    gsb  1.5      gsb  0.5    4.662e+06  2.332e+05    100.0  0.00049    0.09962      1.075e+00  4.644e+05  6.815e+02
 +
    gsb  2.5      gsb  0.5    1.570e+07  7.848e+05    200.0  0.00179    0.36853      1.339e+01  5.784e+06  2.405e+03
 +
      a  2.5      gsb  0.5    1.079e+04  5.647e+02    250.0  0.00189    0.38907      9.719e-03  4.199e+03  6.480e+01
 +
      a  2.5      gsb  1.5    9.816e+02  7.705e+01    150.0  0.00135    0.27823      6.322e-04  2.731e+02  1.653e+01
 +
      a  2.5        b  3.5    4.689e+05  2.376e+04      75.0  0.00015    0.0312        3.387e-02  1.463e+04  1.210e+02
 +
</pre>
 +
 
 +
The "Observed Counts" are calculated using the efficiency curve from the detector library or a detector created by the user.  The "Detector Efficiency" <math>\epsilon</math> is the usual definition.  Possion counting errors are based on the observed counts, while additional error on the ''total'' efficiency-corrected counts may be added by the user.
 +
 
 +
Refer to the page [[Rachel_simulated_yield_output | Rachel simulated yield output]] for more information about simulations with the GUI.
 +
 
 +
===Troubleshooting===
 +
 
 +
For troubleshooting help, refer to the [[rachel_troubleshooting | troubleshooting]] page, or use the search box at the left.
 +
 
 +
==Bug reports==
 +
 
 +
Check the [[gui_release_notes | release notes]] page for a history of bugs and bug-fix versions.
-
# To install Rachel and get it running for the first time, watch [http://www.pas.rochester.edu/~hayes/beta_rachel/rachel_installation.html Rachel Installation].
+
Users are encouraged to submit bug reports via the [http://www-user.pas.rochester.edu/~gosia/phpBB3/ Gosia forum].  The operation that revealed the bug should be reported, and the session file saved before this operation should be included if possible.
-
# A short video on [http://www.pas.rochester.edu/~hayes/beta_rachel/undo_redo.html the undo/redo buttons].
+
-
# How to [http://www.pas.rochester.edu/~hayes/beta_rachel/crash_recovery.html recover data from a crashed session].
+
-
# First steps: [http://www.pas.rochester.edu/~hayes/beta_rachel/reading_level_schemes.html Reading level schemes.]
+
-
# How to [http://www.pas.rochester.edu/~hayes/beta_rachel/add_matrix_non_collective.html add individual matrix elements].  This is most applicable to small, non-collective systems, such as the one in the sample file example2levels.txt file distributed with Rachel.
+
-
# How to [http://www.pas.rochester.edu/~hayes/beta_rachel/add_matrix_collective.html add matrix elements systematically], i.e., for collective nuclei with rotational bands.
+
-
# How to [http://www.pas.rochester.edu/~hayes/beta_rachel/setting_up_calculations.html define experiments, Ge detectors and calculate predicted yields]. This video will show how to define experimental detector setup, data partitions and make instant plots as well.
+
-
# A [http://www.pas.rochester.edu/~hayes/beta_rachel/basic_fit_example.html very basic example of fitting] including a correlated error calculation. The entire video is about 30 minutes long. You can follow along using the GUI on your system and the example files shown in the video, which are included with your Rachel distribution in the .../example_files/ subdirectory.
+
-
# More advanced selection of fit parameters are shown in this video on [http://www.pas.rochester.edu/~hayes/beta_rachel/experiment_planning_2.html experiment planning].
+
-
====Experiment planning and accuracy testing tools====
+
==Links==
-
# [http://www.pas.rochester.edu/~hayes/beta_rachel/accuracy_testing.html Testing the accuracy] of your Gosia calculations and the applicability of Gosia to a planned experiment.
+
[http://www.pas.rochester.edu/~hayes/beta_rachel/main_ad.html The Rachel advertising video]
-
# Semiclassical Coulomb excitation codes have inherent adiabaticity and eccentricity limits. [http://www.pas.rochester.edu/~hayes/beta_rachel/adiabaticity_limit.html This video] shows how to test for these limits with an experiment that would ''not'' be appropriate for Gosia.
+
-
# [http://www.pas.rochester.edu/~hayes/beta_rachel/experiment_planning.html Generating simulated data]. The errors in the simulated data are based on Poisson statistics and the expected number of days, beam current, etc. to estimate your ability to observe desired gamma-ray yields and to fit matrix elements to the observed yields. The present beta version applies ''optionally'' a quasi-gaussian random scatter of the predicted yield data [http://www.pas.rochester.edu/~hayes/beta_rachel/experiment_planning_2.html as demonstrated in this video] to better aid in predicting expected precision of fitted matrix elements. Watch this supplemental video to see how this works. You should also watch the [http://www.pas.rochester.edu/~hayes/beta_rachel/accuracy_testing.html accuracy testing video] to see if Gosia would be an appropriate analysis tool for your planned experiment.
+
-
===Bug reports===
+
==Notes==
-
Users are encouraged to submit bug reports via the [[Gosia forum]].  The operation that revealed the bug should be reported, and the session file saved before this operation should be included if possible.
+
<references/>

Latest revision as of 13:07, 17 May 2013

Retrieved from "https://www-user.pas.rochester.edu/~gosia/mediawiki/index.php/Rachel_GUI"
Personal tools