==================================================================================================== Quick Installation Guide of Utsusemi for MacOS ==================================================================================================== :Author: Yasuhiro Inamura, Ryoichi Kajimoto :Last update: Feb. 9th, 2018 :Utsusemi version: 0.3.5.1 or later .. contents:: Contents :depth: 3 Supported MacOS ============================ The following MacOS X's are supported - 10.10 (Yosemite) - 10.11 (El Capitan) - 10.12 (macOS Sierra), 10.13 (macOS High Sierra) Notice : A part of installation steps is different before. Installation ================== 1. Preparation ( Setting for MacOS Security ) ------------------------------------------------ Utsusemi software is not reliable from a point of view of MacOS security policy because Apple does not guarantee that Utsusemi is secure as applications delivered in AppStore. So we must do setting of security of MacOS to use Utsusemi. 1. Open "System Setting" panel on MacOS 2. Select "General" tab in "Security & Privacy" setting 3. Turn on "Anywhere" checkbox in "Allow apps downloaded from:" |image04| If not this setting, a dialog as below will open on launching Utsusemi. |image05| For macOS Sierra or later ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ If you use **Sierra** or **High Sierra** , "Anywhere" checkbox, as shown above, is disappeared. In this case, please try following steps. 1. Launch "Terminal" App in "Utilities" folder in "Applications" folder. 2. Type commands as below in the terminal and type your account password. .. code-block:: shell $ sudo spctl --master-disable 3. Reboot Mac machine. Then you find "Anywhere" checkbox and turn on it. 4. If you've already installed Utsusemi folder before, you must move the Utsusemi folder to the trash and copy it again from dmg file. 2. Installation --------------------------------- Installation package is distributed as a disk image (.dmg) file for MacOS X. Users have only to double click this file to mount, and then, drag and drop the folder that includes the whole set of applications into Application folder. 1. Double click the disk image file. |image00| 2. In the opened folder, drag and drop "Utsusemi" folder into "Application" folder. |image01| Applications to be installed ============================== You will find a set of Utsusemi software in "Utsusemi" folder in "Application" folder. You can also access them via LaunchPad. The following programs will be prepared. +----------------------------+----------------------------------------------------------------+ |Application |Description | +============================+================================================================+ |Utsusemi Environment Setting|[Environment setting] Set the environment valuables for Utsusemi| +----------------------------+----------------------------------------------------------------+ |SequenceEditor |Launch SequenceEditor | +----------------------------+----------------------------------------------------------------+ |MPlot |Launch MPlot | +----------------------------+----------------------------------------------------------------+ |M2Plot |Launch M2Plot | +----------------------------+----------------------------------------------------------------+ |SliceViewer |Launch SliceViewer3D | +----------------------------+----------------------------------------------------------------+ |D4MatSlicer |Launch D4MatSlicer | +----------------------------+----------------------------------------------------------------+ |uGao |Launch uGao plotter (under testing) | +----------------------------+----------------------------------------------------------------+ |Utsusemi Shell |Launch "Terminal" with Utsusemi environment | +----------------------------+----------------------------------------------------------------+ |MethodAssistant2 |Launch MethodAssistant2 | +----------------------------+----------------------------------------------------------------+ The details will be described later. Set up ========= Creation of necessary folders ------------------------------------------------ The following two folders must be prepared. These folders store raw data and temporary files. +-------------------------------+----------------------------------------------------------------------------------------------------------------+ |Folder (Environment valuable) |Description | +===============================+================================================================================================================+ |Data folder (DATA_DIR) |Folder to store raw data (Same as "/data" in the Linux version.) | +-------------------------------+----------------------------------------------------------------------------------------------------------------+ |Analysis folder (USR_PRIV_HOME)|Folder to include ana and tmp folders in which temporary files are stored (Same as "$HOME" in the Linux version)| +-------------------------------+----------------------------------------------------------------------------------------------------------------+ The above two folders can be prepared in arbitrary places. For example, +---------------+--------------------------+ |Folder |Example | +===============+==========================+ |Data folder |Documents/Utsusemi/DATA | +---------------+--------------------------+ |Analysis folder|Documents/Utsusemi/HOME | +---------------+--------------------------+ |image03| Environment setting and requirements --------------------------------------------- The initial setting of Utsusemi must be done by using **Utsusemi Environment Setting** . .. warning:: This setting must be done at least once after the installation. Setting items are below. - The instrument environment - Two folders to store raw data and analysis temporal information. - Logging - The number of processers for high performance on analysis If you analyze raw data set obtained from other instrument, you must change the instrument environment in this setting. However, you treat 2nd data ( after histogram creations ), you need not. Launch Environment Setting ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Laounch **Utsusemi Environment Setting** in "Utsusemi" folder in "Application" folder, or from "LaunchPad". |image06| If you meet the dialog as below, you choose "Open". |image05| Setting Items ^^^^^^^^^^^^^^^ 1. **Instrument** Choose the instrument for data analysis. Raw data folder and executable commands are changed to suitable ones. 2. **Log quiet** Turn on to decrease logs of analysis commands .. warning:: All logs write in a file */tmp/mlfsoft.log*. If something wrong happens on using Utsusemi, you should check this file. 3. **Number of thread** Some analysis command are affected by this value. Normaly you set the number of CPUs in your Mac machine. 4. **DATA_DIR** and **USR_PRIV_HOME** modify or confirm the initial setting for two folders (setting of the environment valuables) described in previous section. Push *Brows* button opens small dialog to choose a folder for each. +----------------------+-------------------------------------------------------------------------------------------------------------+------------------------+ |Environment valuable |Purpose |Example | +======================+=============================================================================================================+========================+ |DATA_DIR |Folder to store raw data (Same as "/data" in the Linux version) |Documents/Utsusemi/DATA | +----------------------+-------------------------------------------------------------------------------------------------------------+------------------------+ |USR_PRIV_HOME |Place to locate "ana" and "tmp" folders for temporary files are stored (Same as "$HOME" in the Linux version)|Documents/Utsusmei/HOME | +----------------------+-------------------------------------------------------------------------------------------------------------+------------------------+ Finishing Setting ^^^^^^^^^^^^^^^^^^ After setting, push **OK** button. Then you see confirmation dialog as below. |image07| If you meet an error dialog instead of this, check whether the given path to two folders are existed or not. After closing this dialog, following folders are automatically created in the folder specified by *USR_PRIV_HOME*. - **ana** folder - **tmp** folder and **xml** folder under **ana** folder |image08| .. warning:: If you cannot find these folders, you must make them by yourself to avoid the failure of Utsusemi launch. On the other hand, you make folders to store raw data *DATA_DIR* according to a rule described in next section. Rule for data location ---------------------------- Raw data should be stored in the folder specified by *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 |Instrument code|Example of data folder| +===============+==========+===========================+ |BL01 4SEASONS |SIK |DATA/SIK/SIK012345_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| +---------------+----------+---------------------------+ Data analysis ============== After completing the environment setting and preparing raw data, you can perform data analysis. The following applications are available from Application/Utsusemi folder. **Utsusemi Environment Setting** |icon_Env| [Environment setting] Set and confirm the environment valuables for Utsusemi. Refer to "Launch Environment Setting" section. **MPlot**, **M2Plot**, **SliceViewer** |icon_MPlot| |icon_M2Plot| |icon_SliceViewer| Launch Utsusemi Plotters. Same as ones in Linux version. +-------------+-------------------------------------+ |MPlot |1-dimentional data plotter | +-------------+-------------------------------------+ |M2Plot |2-dimentional data plotter and slicer| +-------------+-------------------------------------+ |SliceViewer3D|3-dimentional data viewer and slicer | +-------------+-------------------------------------+ **D4MatSlicer** |icon_D4mat| Launch D4MatSlicer, same as one in Linux version. **SequenceEditor** |icon_SequenceEditor| Launch SequenceEditor, same as one in Linux version. **Utsusemi Shell** |icon_Shell| Launch "Terminal" App under Utsusemi environment. In this terminal, you can execute commands defined on the selected instrument environment and any script made by yourself. Notices launching at the first time When you launch **Utsusemi Shell** at the first time, a warning dialog appears and **Utsusemi Shell** app does not launch though pushing "Open" or "OK" buttons. In this case, try launching again. **uGao** [icon_uGao] Launch uGao, which is new 2-dimentional plotter for testing. **MethodAssistant2** Launch MethodAssistant2, same as one in Linux version. For details of each application, please refer to Utsusemi Users' Manual. On macOS Sierra, High Sierra ----------------------------------- On macOS SIerra and High Sierra, sometimes the dialog as below opens on launching applications. |image11| In this case, you select "Install" to install automatically required software from the internet. Running Utsusemi on a terminal =================================== Python scripts including Utsusemi commands can be run without utilizing the above applications. In particular, if you try any new idea of data analysis, you need to utilize the Utsusemi environment on a terminal of MacOS. The following is the procedure. 1. Launch a terminal. 2. Run the following command. .. code-block:: shell $ source /Applications/Utsusemi/.opt/bin/_loadenv 3. Then, any functions of Manyo-Library or Utsusemi can be called. .. code-block:: shell $ python Python 2.7.10 (default, Oct 23 2015, 19:19:21) [GCC 4.2.1 Compatible Apple LLVM 7.0.0 (clang-700.0.59.5)] on darwin Type "help", "copyright", "credits" or "license" for more information. >>> import Manyo Manyo>>> 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.nnnn| +=======+==================+ |X.Y.Z |Release number | +-------+------------------+ |nnnn |Revision number | +-------+------------------+ 2. Command of **Utsusemi Python** Launch **Utsusemi Python**, and run the following command. .. code-block:: python import UtsusemiInfo Then, the following information is displayed. .. code-block:: shell --------------------------------------------- Utsusemi Info --------------------------------------------- version : X.Y.Z (rev nnnn) Contact person : Yasuhiro Inamura e-mail : xxxxx.yyyyy@j-parc.jp --------------------------------------------- X.Y.Z, and nnnn are release number and revision number, respectively. Uninstall ==================== Just move Utsusemi folder in Application folder to trash box. However, this does not completely all the relevant files, and some folders show below are remained. Delete them manually is you want. +------------------------+ |*DATA_DIR* folder | +------------------------+ |*USR_PRIV_HOME* folder | +------------------------+ In addition, several configuration files are remained. Although these files will be used when you re-install Utsusemi, you may delete them. +---------------------------------------+ |Home folder/Library/Utsusemi folder | +---------------------------------------+ Note that these are invisible folders. 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 About log file ----------------- All logs under Utsusemi working are recorded in a file **/tmp/mlfsoft.log** . So you copy this file to send with report. In order to copy this file, do this command from command line in "Terminal" App to copy a log file to Desktop. .. code-block:: shell $ cp /tmp/mlfsoft.log ~/Desktop For trouble shooting, you shuld remove the check of "Log quiet" on the "Utsusemi Environment Settings" to get more information in log file. |image12| .. |image00| image:: ../BinaryInstall/media/utsusemi_mac_07.png :width: 125px .. |image01| image:: ../BinaryInstall/media/utsusemi_mac_00.png :width: 400px .. |image02| image:: ../BinaryInstall/media/utsusemi_mac_09.png :width: 400px .. |image03| image:: media_en/utsusemi_mac_en_04.png :width: 400px .. |image04| image:: media_en/utsusemi_mac_en_02.png :width: 400px .. |image05| image:: media_en/utsusemi_mac_en_03.png :width: 400px .. |image06| image:: ../BinaryInstall/media/utsusemi_mac_10.png :width: 400px .. |image07| image:: ../BinaryInstall/media/utsusemi_mac_11.png :width: 300px .. |image08| image:: ../BinaryInstall/media/utsusemi_mac_06.png :width: 300px .. |image09| image:: ../BinaryInstall/media/utsusemi_mac_12.png :width: 300px .. |image10| image:: ../BinaryInstall/media/utsusemi_mac_13.png :width: 300px .. |image11| image:: ../BinaryInstall/media/utsusemi_mac_08.png :width: 300px .. |image12| image:: ../BinaryInstall/media/utsusemi_mac_14.png :width: 300px .. |icon_Env| image:: ../BinaryInstall/media/icon_Env.png :width: 64px .. |icon_MPlot| image:: ../BinaryInstall/media/icon_MPlot.png :width: 64px .. |icon_M2Plot| image:: ../BinaryInstall/media/icon_M2Plot.png :width: 64px .. |icon_SliceViewer| image:: ../BinaryInstall/media/icon_SliceViewer.png :width: 64px .. |icon_D4mat| image:: ../BinaryInstall/media/icon_D4MatSlicer.png :width: 64px .. |icon_SequenceEditor| image:: ../BinaryInstall/media/icon_SequenceEditor.png :width: 64px .. |icon_Shell| image:: ../BinaryInstall/media/icon_Shell.png :width: 64px