==================================================================================================== Quick Installation Guide of Utsusemi4 for Ubuntu 20.04LTS ==================================================================================================== :Author: Yasuhiro Inamura :Last update: Jul. 13th, 2021 :Utsusemi version: 4.0 or later .. contents:: Contents :depth: 2 Supported Ubuntu ============================ The following Ubuntu linux versions are supported - 20.04 LTS on amd64 (x86_64) Supported Beam Lines at MLF ============================ Beam lines supported by Utsusemi4 debian pakages are below. +---------+---------------------+-------------------+ |BL(code) |Notes |status | +=========+=====================+===================+ |BL01(SIK)|None |Ready | +---------+---------------------+-------------------+ |BL02(DNA)|not including QENSfit|Ready | +---------+---------------------+-------------------+ |BL14(AMR)|None |Ready | +---------+---------------------+-------------------+ |BL11(HPN)|not including Teuse |Ready | +---------+---------------------+-------------------+ |BL15(SAS)|not including Dview |Ready | +---------+---------------------+-------------------+ Installation ================== Utsusemi4 Installer for Ubuntu is distributed as a debian pakage (.deb) file. Users have only to download the packages and to execute installation command as below. .. note:: Before installation, you must confirm the target PC is connected with the internet. --------------------- 1. Download pakages --------------------- Installation packages can be downloaded from Utsusemi Portal site ( https://mlfinfo.jp/groups/comp/en/utsusemi.html ). .. table:: Packages :widths: 5 25 35 25 10 +-+----------------------+-----------------------------------+----------------------+----------------+ | |Package Name |Installed software |required package |BL | +=+======================+===================================+======================+================+ |1|mlf-manyo1 |Manyo Library | |All BLs | +-+----------------------+-----------------------------------+----------------------+----------------+ |2|mlf-utsusemi-with-ugao|Whole software of Utsusemi4, |mlf-manyo1 |All BLs | | | |including uGao (Visualizations) | | | +-+----------------------+-----------------------------------+----------------------+----------------+ |3|mlf-utsusemi-sas |BL15 environment on Utsusemi4. |mlf-utsusemi-with-ugao|BL15 | +-+----------------------+-----------------------------------+----------------------+----------------+ |4|mlf-utsusemi-dna |BL02 environment on Utsusemi4. |mlf-utsusemi-with-ugao|BL02 | +-+----------------------+-----------------------------------+----------------------+----------------+ Actual package file names to be downloaded are shown below (just example). +-+-------------------------------------------------+ | |Package File Name (for Ubuntu 20.04) | +=+=================================================+ |1|mlf-manyo1_0.3.4.210713-ubu20_amd64.deb | +-+-------------------------------------------------+ |2|mlf-utsusemi-with-ugao_4.0.210713-ubu20_amd64.deb| +-+-------------------------------------------------+ |3|mlf-utsusemi-sas_4.0.210713-ubu20_amd64.deb | +-+-------------------------------------------------+ |4|mlf-utsusemi-dna_4.0.210713-ubu20_amd64.deb | +-+-------------------------------------------------+ where *0.3.4* and *4.0* means the release-version, which is given by a large update, and *210713* is the latest update day. *ubu20* means this pakcages can be installed in Ubuntu20.04. ---------------------------- 2. Delete previous Utsusemi ---------------------------- If Utsusemi has been already installed in your target PC by installation script (not debian package), you have to delete installed files as below. :: $ sudo rm -rf /opt/mlfsoft When you are not sure how to install Utsusemi, attempt to execute command, :: $ sudo dpkg -l mlf-manyo1 If Utsusemi was installed by Debian packages, this command returns message like below. :: $ sudo dpkg -l mlf-manyo1 [sudo] password for hoge: Desired=Unknown/Install/Remove/Purge/Hold | Status=Not/Inst/Conf-files/Unpacked/halF-conf/Half-inst/trig-aWait/Trig-pend |/ Err?=(none)/Reinst-required (Status,Err: uppercase=bad) ||/ Name Version Architecture Description +++-================-==================-============-==========================> ii mlf-manyo1:amd64 0.3.4.210713-ubu20 amd64 Manyo Library When not installed by Debian packages, shows below. :: $ sudo dpkg -l mlf-manyo1 [sudo] password for hoge: dpkg-query: no packages found matching mlf-manyo1 If Utsusemi had been installed by Debian packages, you have not to delete it, just have only to install (overwrite) by new version packages. ----------------------------- 3. Installation of packages ----------------------------- To install Manyo Library, execute command using the downloaded mlf-manyo1 package ( example : *mlf-manyo1_0.3.4.210713-ubu20_amd64.deb* ) . :: $ sudo apt install ./mlf-manyo1_0.3.4.210713-ubu20_amd64.deb You must give the file path to deb package file to be installed. In above, **./** is used as a path to this package file because this command is executed in same folder as where package file is placed. Therefore, you will meet the *Unable to locate package* if you execute a command as below. :: $ sudo apt install mlf-manyo1_0.3.4.210713-ubu20_amd64.deb This command shows logs and the confirmation to install pacakges required by Manyo library. :: $ sudo apt install ./mlf-manyo1_0.3.4.210713-ubu20_amd64.deb [sudo] password for hoge: Reading package lists... Done Building dependency tree Reading state information... Done Note, selecting 'mlf-manyo1' instead of '/media/psf/Home/Ubuntu20.04/mlf-manyo1_0.3.4.210713-ubu20_amd64.deb' The following additional packages will be installed: libaec0 libboost-program-options1.71.0 libboost-serialization1.71.0 libgfortran5 libgsl23 libgslcblas0 libhdf4-0 libhdf5-103 libnexus1 libsz2 Suggested packages: gsl-ref-psdoc | gsl-doc-pdf | gsl-doc-info | gsl-ref-html libhdf4-doc libhdf4-dev hdf4-tools The following NEW packages will be installed: libaec0 libboost-program-options1.71.0 libboost-serialization1.71.0 libgfortran5 libgsl23 libgslcblas0 libhdf4-0 libhdf5-103 libnexus1 libsz2 mlf-manyo1 0 upgraded, 11 newly installed, 0 to remove and 0 not upgraded. Need to get 4,050 kB/5,722 kB of archives. After this operation, 27.1 MB of additional disk space will be used. Do you want to continue? [Y/n] Answer "Y" to continue. Next is the Utsusemi4 installation by using downloaded mlf-utsusemi-with-ugao pacakge ( *mlf-utsusemi-with-ugao_4.0.210713-ubu20_amd64.deb* ). :: $ sudo apt install ./mlf-utsusemi-with-ugao_4.0.210713-ubu20_amd64.deb As same as Manyo library installation, many logs and the confirmation to install pacakges required by Utsusemi4 are shown like below. :: $ sudo apt install ./mlf-utsusemi-with-ugao_4.0.210713-ubu20_amd64.deb Reading package lists... Done Building dependency tree Reading state information... Done Note, selecting 'mlf-utsusemi-with-ugao' instead of '/media/psf/Home/Ubuntu20.04/mlf-utsusemi-with-ugao_4.0.210713-ubu20_amd64.deb' The following additional packages will be installed: blt fonts-lyx javascript-common libblas3 libdouble-conversion3 libjs-jquery libjs-jquery-ui liblapack3 ... python3-pyside2.qtgui python3-pyside2.qtwidgets python3-scipy python3-tk qt5-gtk-platformtheme qttranslations5-l10n tk8.6-blt2.5 ttf-bitstream-vera 0 upgraded, 40 newly installed, 0 to remove and 0 not upgraded. Need to get 43.2 MB/63.7 MB of archives. After this operation, 243 MB of additional disk space will be used. Do you want to continue? [Y/n] Answer "Y" to continue. Manyo Library and Utsusemi software are installed in the folder of */opt/mlfsoft/* . 3-1. BL15(SAS) Installation ---------------------------------------------- BL15 environment requires the other package (mlf-utsusemi-sas). :: $ sudo apt install -y ./mlf-utsusemi-sas_4.0.210713-ubu20_amd64.deb 3-2. BL02(DNA) Installation ---------------------------------------------- BL02 environment requires the other package (mlf-utsusemi-dna). :: $ sudo apt install -y ./mlf-utsusemi-dna_4.0.210713-ubu20_amd64.deb In addition, you need to copy some files used for data reduction on BL02 environment into a folder under home folder (~/ana/DNA) as below. :: $ mkdir -p ~/ana/DNA $ cp -r /opt/mlfsoft/python-utsusemi/utsusemi/DNA/environ-home/ana/* ~/ana/DNA Set up ========= -------------------------------- Creation of necessary folders -------------------------------- The following folder must be prepared before use of Utsusemi, which folder stores raw data files. +-------------------------------+----------------------------------------------------------------------------------------------------------------+ |Folder (Environment valuable) |Description | +===============================+================================================================================================================+ |Data folder (UTSUSEMI_DATA_DIR)|Folder to store raw data which includs folder for each BL like SIK/, AMR/, HPN/ and so on ) | +-------------------------------+----------------------------------------------------------------------------------------------------------------+ The default path of this data folder is */data* . Of course you can choose other directory as you like, for example in HOME folder. You have to create folder and sub-folder in it. sub-folder is named by instrument-codes and is used to store each BL's raw data folders. :: $ sudo mkdir -p /data/SIK $ sudo mkdir -p /data/AMR $ sudo mkdir -p /data/HPN $ sudo mkdir -p /data/SAS $ sudo mkdir -p /data/DNA If you do not use default */data* folders, you have to set the environment variable **UTSUSEMI_DATA_DIR** . **Rule for raw data location** Raw data should be stored in the folder specified by *UTSUSEMI_DATA_DIR* according to the following rule. 1. Create a folder who has the same name as the instrument code. For example, "SIK" for 4SEASONS (BL01) and "AMR" for AMATERAS (BL14). 2. Place the data folder of corresponding instrument in this folder. The name of the data folder must include each Run No. For example, "SIK012345_20150301" for 4SEASONS. +---------------+----------+----------------------------+ |BL |Code |Example of data folder | +===============+==========+============================+ |BL01 4SEASONS |SIK |/data/SIK/SIK012345_20160401| +---------------+----------+----------------------------+ |BL02 DNA. |DNA |/data/DNA/DNA012345_20160401| +---------------+----------+----------------------------+ |BL11 PLANET |HPN |/data/HPN/HPN012345_20160401| +---------------+----------+----------------------------+ |BL14 AMATERAS |AMR |/data/AMR/AMR012345_20160401| +---------------+----------+----------------------------+ |BL15 TAIKAN |SAS |/data/SAS/SAS012345_20160401| +---------------+----------+----------------------------+ |BL19 TAKUMI |ENG |/data/ENG/ENG012345_20160401| +---------------+----------+----------------------------+ ------------------------------------------------ Environment variables setting and requirements ------------------------------------------------ Defalt settings of the environment variables for each BL are included in template files below. +-------------------+--------------------------------------------------------+ |Target BL |Setting template file for each BL | +===================+========================================================+ |BL01 (4SEASONS,SIK)|/opt/mlfsoft/python-utsusemi/utsusemi/SIK/bashrc.py3.SIK| +-------------------+--------------------------------------------------------+ |BL10（PLANET,HPN） |/opt/mlfsoft/python-utsusemi/utsusemi/HPN/bashrc.py3.HPN| +-------------------+--------------------------------------------------------+ |BL14 (AMATERAS,AMR)|/opt/mlfsoft/python-utsusemi/utsusemi/AMR/bashrc.py3.AMR| +-------------------+--------------------------------------------------------+ |BL15 (SAS) |/opt/mlfsoft/python-utsusemi/utsusemi/SAS/bashrc.py3.SAS| +-------------------+--------------------------------------------------------+ |BL02 (DNA) |/opt/mlfsoft/python-utsusemi/utsusemi/DNA/bashrc.py3.DNA| +-------------------+--------------------------------------------------------+ These files are a template file including default settings. Main environment variables described in these template files for Utsusemi4 are listed below. .. table:: Environment Variables of Utsusemi :widths: 25 30 45 +---------------------+---------------------------+---------------------------------------------------------------------------------+ |Environment variables|Default value | | +=====================+===========================+=================================================================================+ |UTSUSEMI_INST_CODE | |Instrument code [SIK,AMR,HPN and so on] | +---------------------+---------------------------+---------------------------------------------------------------------------------+ |UTSUSEMI_DATA_DIR |"/data" |Data folder | +---------------------+---------------------------+---------------------------------------------------------------------------------+ |UTSUSEMI_USR_DIR |${UTSUSEMI_USR_DIR-${HOME}}|Users folder ( HOME folder is default ) | +---------------------+---------------------------+---------------------------------------------------------------------------------+ |UTSUSEMI_LOG_QUIET |n |Control of log showing on data reduction.If "Y" , logs are decreased. | +---------------------+---------------------------+---------------------------------------------------------------------------------+ |UTSUSEMI_MULTH |8 |The number of multi processing for high performance on analysis on data reduction| +---------------------+---------------------------+---------------------------------------------------------------------------------+ |UTSUSEMI_DEBUGMODE |n |Flag for debugging ( n is default ) | +---------------------+---------------------------+---------------------------------------------------------------------------------+ To set thease Utsusemi environment variables, simply execute command like this. :: $ source /opt/mlfsoft/python-utsusemi/utsusemi/SIK/bashrc.py3.SIK =========================================== Welcome to Utsusemi Environment for SIK ver 4.0 =========================================== Ana : Sequencer M2Plot: M2PlotPlus D4mat : D4MatSlicer D4mat2: D4Mat2Slicer =========================================== This setting way, however, is complicated because of long file path. Recommended is to add shell descriptions into ~/.bashrc like below. :: # Utsusemi4 environments # For BL01 (SIK) if [ -f /opt/mlfsoft/python-utsusemi/utsusemi/SIK/bashrc.py3.SIK ]; then alias SIK="source /opt/mlfsoft/python-utsusemi/utsusemi/SIK/bashrc.py3.SIK" fi # For BL02 (DNA) if [ -f /opt/mlfsoft/python-utsusemi/utsusemi/DNA/bashrc.py3.DNA ]; then alias DNA="source /opt/mlfsoft/python-utsusemi/utsusemi/DNA/bashrc.py3.DNA" fi # For BL11 (HPN) if [ -f /opt/mlfsoft/python-utsusemi/utsusemi/HPN/bashrc.py3.HPN ]; then alias HPN="source /opt/mlfsoft/python-utsusemi/utsusemi/HPN/bashrc.py3.HPN" fi # For BL14 (AMR) if [ -f /opt/mlfsoft/python-utsusemi/utsusemi/AMR/bashrc.py3.AMR ]; then alias AMR="source /opt/mlfsoft/python-utsusemi/utsusemi/AMR/bashrc.py3.AMR" fi # For BL15 (SAS) if [ -f /opt/mlfsoft/python-utsusemi/utsusemi/SAS/bashrc.py3.SAS ]; then alias SAS="source /opt/mlfsoft/python-utsusemi/utsusemi/SAS/bashrc.py3.SAS" fi After adding, execute below command or restart the terminal app to activate settings. :: $ source ~/.bashrc To confirm settings, type a instrument code on the terminal to choose environment for each instrument. +----------------+----------+ |instrument |code | +================+==========+ |BL01 (4SEASONS) |SIK | +----------------+----------+ |BL02 (DNA) |DNA | +----------------+----------+ |BL11 (PLANET) |HPN | +----------------+----------+ |BL14 (AMATERAS) |AMR | +----------------+----------+ |BL15 (SAS) |SAS | +----------------+----------+ For example, when you choose 4SEASONS environment, type "SIK". :: $ SIK =========================================== Welcome to Utsusemi Environment for SIK ver 4.0 =========================================== Ana : Sequencer M2Plot: M2PlotPlus D4mat : D4MatSlicer D4mat2: D4Mat2Slicer =========================================== $ When you want to set other values to environment variable, you should copy a template file ( bashrc.py3.XXX ) to rewrite the variables as your situations. Especially, if you want to change the data folder path, you must change **UTSUSEMI_DATA_DIR** setting in copied setting file and rewrite ~/.bashrc to use new setting file ( but not touch it in detail in this document ). Uninstall ============ To uninstall Utsusemi4, execute below commands. First is mlf-utsusemi-with-ugao, next mlf-manyo1 which order is obeyed the dependencies between packages. :: $ sudo apt remove mlf-utsusemi-dna # if you installed. $ sudo apt remove mlf-utsusemi-sas # if you installed. $ sudo apt remove mlf-utsusemi-with-ugao $ sudo apt remove mlf-manyo1 Version number confirmation ============================= Utusemi version can be seen in the following ways. It is useful when you report bugs or update Utsusemi. 1. Installer file name Installer file name consists of two sets of numbers. +-------+----------------------+ |Example|MLFSOFT.X.Y.Z.nnnnnn | +=======+======================+ |X.Y.Z |Release number | +-------+----------------------+ |nnnnnn |Latest date for update| +-------+----------------------+ 2. Command of **Utsusemi Shell** Launch **Utsusemi Shell**, and run the following command. .. code-block:: python >>> import utsusemi >>> utsusemi.__version__ '4.0.0' Or, .. code-block:: python import UtsusemiInfo Then, the following information is displayed. .. code-block:: shell --------------------------------------------- Utsusemi Info --------------------------------------------- version : X.Y.Z (rev nnnnnn) Contact person : Yasuhiro Inamura e-mail : xxxxx.yyyyy@j-parc.jp --------------------------------------------- X.Y.Z, and nnnn are release number and the latest date for update, respectively. Troubles =========== If you feel something wrong on Utsusemi works, for example no progress of commands steps, please send a report about your situations and a log file "/tmp/mlfsoft.log" . ------------------------------------- What must be reported ------------------------------------- To report your trouble, you tell us the information as below : - Which software or command you are using - What you are going to - What you did - What happened ---------------- Logs for errors ---------------- Full logs from the beginning of command execution to error messages with *UTSUSEMI_LOG_QUIET=n* are helpfull to fix it. In addition, to get more helpful informations, please set *UTSUSEMI_DEBUGMODE=y* and 1. Create folders ~/ana/xml and ~/ana/tmp 2. Set environment variables *UTSUSEMI_DEBUGMODE* to "y" 3. Execute commands to occur the error 4. Send full logs on the terminal and ~/ana folder including some temporal files. :: $ mkdir -p ${UTSUSEMI_USR_DIR}/ana/xml $ mkdir -p ${UTSUSEMI_USR_DIR}/ana/tmp $ export UTSUSEMI_DEBUGMODE=y $ Ana ... execute script occuring errors.