Quick Installation Guide for macOS Big Sur and Monterey#

Author:

Yasuhiro Inamura, Ryoichi Kajimoto

Last update:

May. 27th, 2022

Utsusemi version:

4.0 or later

Supported macOS#

The following macOS are supported

  • 11.x (Big Sur) and 12.x (Monterey) on Intel CPU

  • 12.x (Monterey) on Apple Silicon(M1)

macOS

11.x(Big Sur)

12.x(Monterey)

Intel

Enable

Enable

AppleSilicon(M1)

Enable

Not verified

Installation#

Utsusemi Installer for macOS is distributed as a installer package (.pkg) file for macOS. Users have only to double click this file to install the whole set of Utsusemi applications with Python3 into Application folder.

Security Settings Before Installation#

Because Utsusemi Binary software is not regarded as “Safety Application” by Apple ( not installed through AppStore ), you must set the security level down on macOS to install Utsusemi.

Warning

If already Utsusemi has been installed before this security treatment, you must uninstall it to delete Utsusemi folder in Applications folda.

  1. Launch Terminal application in Utilities in Applications folder.

  2. On terminal console, type command below. At that time, you are required to input your password.

$ sudo spctl --master-disable
  1. Open System Preferences, and go Security & Privacy .

  2. Select General tab in Security & Privacy settings.

  3. Because of the command of 2., the checkbox Anywhere on Allow apps downloaded from: area appears. If the checkbox is not checked, check it.

    image14

Installation#

  1. Double click the installer package file.

    image00

    If you see the dialog as below after double click,

    image01err

    you have a right-click, or ctrl + left-click, on the installer package file to show the short-cut menu as below,

    image01menu

    then click “Open”. After this, you will see the confirmation dialog to open this file actually. Push “Open”.

    image01confirm

  2. In installation dialogs, you push “Continue”.

    image02

  3. If you are asked where you want to install Utsusemi, you choose the storage for installation and push “Continue”.

    image03

  4. Push “Install” to the default path ( /Application/Utsusemi )

    image04

  5. Input the password of your account for authorization to install.

    image05

  6. Installation starts.

    image06

  7. After installation finishes, push “Close”.

    image07

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.

image08

Application

Description

D4MatSlicer

Launch D4MatSlicer

D4Mat2Slicer

Launch D4Mat2Slicer

M2PlotPlus

Launch M2PlotPlus

MPlot

Launch MPlot

SequenceEditor

Launch SequenceEditor

UtsusemiEnvironmentSetting

[Environment setting] Set the environment valuables for Utsusemi

UtsusemiShell

Launch “Terminal” with Utsusemi environment

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_DIR)

Folder to include ana and tmp folders in which temporary files are stored (Same as “$HOME” in the Linux version)

These two folders are automatically made at the location below by the launching of Utsusemi Environment Setting app. Of cause, you can choose the other location, but recent macOS security prohibits to read/write data files in the “Desktop”, the “Documents” and some shared folders from Utsusemi. Home folder is OK for the present.

Folder

Location to be made

Data folder

<HomeFolder>/Utsusemi/DATA

Analysis folder

<HomeFolder>/Utsusemi/HOME

image09

If you do not know how to open home folder, you select a “Home” item from “Go” menu.

image09r1

Environment setting and requirements#

The initial setting of Utsusemi must be done by using UtsusemiEnvironmentSettings application.

Warning

This setting must be done at least once after the installation.

Setting items are below.

  • The instrument environment required for your data treatments

  • Two folders to store raw data and analysis temporal information.

  • Logging

  • Font size for GUI applications.

  • The number of processers for high performance on analysis

  • Swiching debug-mode on/off

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 ), like saved data file (.dmp or .mdb file), you need not.

Launch Environment Setting#

Laounch UtsusemiEnvironmentSettings in “Utsusemi” folder in “Application” folder, or from “LaunchPad”.

image08

image10

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. Font Size

    Set the font size for GUI applications. Normaly 12 points. You can change it to lager or smaller, but GUI layout or shapes maybe collapse by given value.

  4. Number of thread

    Some analysis command are affected by this value. Normaly you set the number of CPUs in your Mac machine.

  5. Utsusemi_debugmode

    Turn on/off the debug mode in Utsusemi ( Default is off )

  6. DATA_DIR and USR_DIR

    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_DIR

    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.

image11

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

    image12

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.

SequenceEditor

Launch SequenceEditor, same as one in Linux version.

UtsusemiEnvironmentSetting

[Environment setting] Set and confirm the environment valuables for Utsusemi. Refer to “Launch Environment Setting” section.

MPlot, M2PlotPlus

Launch Plotters ( including uGao package ) used from Utsusemi. Same as ones in Linux version.

MPlot

1-dimentional data plotter

M2PlotPlus

2-dimentional data plotter and slicer

D4MatSlicer , D4Mat2Slicer

Launch D4MatSlicer and D4Mat2Slicer, same as one in Linux version.

UtsusemiShell

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.

For details of each application, please refer to Utsusemi Users’ Manual.

Note

At current version (220520), SequenceEditor , D4mat , D4mat2 are launched through the Terminal application, which means that double clicks on these icons launch Terminal first and then SequenceEditor are launched in the Terminal app. If you close these Terminal, the GUI application concerned with closed Terminal is down too.

Launch from UtsusemiShell#

If you are used to linux, you choose UtsusemiShell to launch GUI applications. This application launchs a terminal application with Utusemi environment, so you can execute all commands produced by Utsusemi and lanch GUI applications.

image15

===========================================
  Welcome to Utsusemi Environment for SIK
===========================================
 Ana   : Sequencer
 M2Plot: M2PlotPlus
 D4mat : D4MatSlicer
 D4mat2: D4Mat2Slicer
===========================================
hoge@localhost %

For example, you type Ana here to launch SequenceEditor .

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.

To execute your own scripts, there are two ways.

  1. Launch UtsusemiShell

  2. Launch a Terminal application and prepare Utsusemi environment.

By UtsusemiShell , as described above, a simple Terminal app is launched with Utsusemi environment.

If you want to use the specified terminal, preparations are below.

  1. Launch your specified terminal.

  2. Run the following command.

    $ source /Applications/Utsusemi/.opt/bin/_loadenv
    
  3. Then, any functions of Manyo-Library or Utsusemi can be called.

    $ python
    Python 3.9.12 (main, May 16 2022, 19:19:31)
    [Clang 13.0.0 (clang-1300.0.29.30)] 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.nnnnnn

    X.Y.Z

    Release number

    nnnnnn

    Latest date for update

  2. Command of Utsusemi Shell

    Launch Utsusemi Shell, and run the following command.

    >>> import utsusemi
    >>> utsusemi.__version__
    '4.0.0'
    

    Or,

    import UtsusemiInfo
    

    Then, the following information is displayed.

    ---------------------------------------------
                   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.

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_DIR 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#

Data treatment logs produced by some GUI applications launched through terminal ( SequenceEditor, D4mat, D4mat2 ) are shown on the terminal concerned with GUI app. If you need log text of executing the commands or application, you must copy texts on the terminal.

The other 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.

$ cp /tmp/mlfsoft.log ~/Desktop