Windows用バイナリ版インストール#

著者

稲村 泰弘

最終更新日

Apr. 5th, 2023

対応空蟬リリース

4.0 or later

概要#

本章では空蟬をWindows環境にバイナリパッケージでインストールする方法を示す。

なお、2023年4月現在で、対応しているMLFにおけるビームラインは以下の通りである。

Available beam lines for Utsusemi on Windows#

BL(code)

注意点

状況

BL01(SIK)

特になし

対応済み

BL14(AMR)

特になし

対応済み

BL15(SAS)

Dviewは含まず

対応済み

動作環境#

本章で動作を保証するWindowsは以下の通りである。

Available Windows version#

Windows

Architecture

10, 11

x86_64 (amd64)

これら以外の環境（32bit版も含め）は今後もサポートする予定はない。

事前の確認事項#

アカウント名に関して注意すべき点がある。インストールするWindowsの管理者ユーザーのアカウント名が 英数字 でなければならない。 既に日本語を利用していた場合、新たに英数字のアカウント名でユーザーを作成し、そちらでログインしてからインストールする必要がある。新たにアカウントを作成する方法などは省略する。

Account name examples#

アカウント名の条件

良い例

悪い例

英数字であること

Inamura

稲村

手順の概要#

  1. 環境構築（Minimumタイプのみ必要）

  2. インストーラによるインストール（All-in-one、Minimumタイプ）

  3. 環境設定

インストール#

インストーラのタイプ#

Windows版には、以下の2種類のインストーラがあるので、環境に合わせて利用すること。

Type of installation#

タイプ

説明

ファイル名の例

All-in-one

Python含め全て同梱されている。（推奨）

Utsusemi.4.0.230403.x86_64.msi

Minimum

Python環境はない最小限のインストーラ。Python3.9.xのみ対応。 Pythonの環境は自分で構築する必要がある。中・上級者向け。

Utsusemi_minimum.4.0.230403.x86_64.msi

空蟬本体のインストール#

ここでは、All-in-oneタイプのインストーラでのインストールを示す。なお、MinimumタイプにはあらかじめPython環境が必要であるが、要件は次節にて示す。

空蟬パッケージインストーラをダブルクリックしてインストールを行う。

../../_images/win_Utsusemi4Install00.png

なお、既に以前のバージョンの空蟬が入っている場合、一旦以前の空蟬をアンインストールしてから行うこと。

  1. インストールウィザードが現れるので、以降は基本的に「 Next 」で進めて行く。

../../_images/win_Utsusemi4Install01.png

  1. 使用許諾書の表示が表示されるので、同意して「 Next 」ボタンを押す。

../../_images/win_Utsusemi4Install02.png

  1. インストール先の確認が出る。よければ「 Next 」ボタンを押す。（デフォルトでは “C:¥¥Program Files¥Utsusemi¥”）

../../_images/win_Utsusemi4Install03.png

  1. インストール準備完了の表示が出るので、「 Install 」ボタンを押す。

../../_images/win_Utsusemi4Install04.png

  1. 途中でユーザーのアカウント制御のダイアログが出た場合、「Yes」を押す。

../../_images/win_Utsusemi4Install05.png

  1. おおよそインストールに2〜3分程度かかる。

../../_images/win_Utsusemi4Install06.png

  1. 以下のようにダイアログが出ると正常に終了している。「 Finish 」ボタンを押して終了する。

../../_images/win_Utsusemi4Install07.png

  1. スタートメニューからインストールされた Utsusemi ソフトウェアを確認できる。

../../_images/win_Utsusemi4Install08.png

Minimumタイプの場合#

Minimumタイプは、Python3.9（2023年4月現在）の環境にのみ対応している。

インストール前に必要なことは以下であるが、詳細は述べない（本章末尾のAppendix参照のこと）。

  • Python3.9及び、必要なパッケージのインストール

  • コマンドプロンプトからPython3.9が実行でき、パッケージのimportもできるようにしておく

なお、Pythonと必要なパッケージを以下に示す。

list of the packages required by a minimum BinaryInstaller for win#

Python

3.9.x

Packages

numpy, scipy, matplotlib, PySide6

結局のところ必要となる環境は、起動したコマンドプロンプト内でPython3.9インタプリタから下記のようなコマンドを実行してエラーが出ない環境である。

C:\Users\hoge>python
Python 3.9.16 (main, Mar  8 2023, 10:39:24) [MSC v.1916 64 bit (AMD64)] on win32
Type "help", "copyright", "credits" or "license" for more information
>>> import numpy
>>> import scipy
>>> import matplotlib
>>> import PySide6

インストールされるアプリケーション#

空蟬ソフトウェア群は、インストール時に指定した場所（C:¥¥Program Files¥Utsusemi¥）にある。 また、アプリケーションへのショートカットが、以下の場所に作成される。

「スタート」メニュー >> Utsusemi

../../_images/win_Utsusemi4Install08.png

ここには以下のプログラムが準備されている。詳細は後で述べる。

List of Utsusemi Applications installed#

Utsusemiアプリケーション

説明

D4MatSlicer

D4MatSlicerを起動する。

D4Mat2Slicer

D4Mat2Slicerを起動する。

M2PlotPlus

M2Plotを起動する。

MPlot

MPlotを起動する。

SequenceEditorQ

SequenceEditorを起動する。

Utsusemi Environment Settings

【環境設定】空蟬のフォルダ環境変数を設定する。

Utsusemi Shell

Utsusemi環境が設定されたターミナルを起動する。

初期設定#

空蟬における初期設定は、

  1. 必要なフォルダの作成（データフォルダ、データ処理用フォルダ、作業フォルダ）

  2. 環境変数の設定

である。

必要なフォルダの作成#

空蟬Windows版では、まず解析用データの置き場所と一時ファイル保存場所をフォルダとして準備する必要がある。

Path to folders required by Utsusemi#

設定（環境変数名）

役割

データフォルダ (DATA_DIR)

イベントデータなどRAWデータを格納するフォルダ。（Linux版では”/data”）

解析用フォルダ (USR_DIR)

空蟬が作成する一時ファイルの保存先となるana/tmpなどのフォルダを置く場所である。（Linux版では”$HOME”）

作業フォルダ (WORK_DIR)

ユーザーが作業するフォルダ（アプリケーション起動時のカレントフォルダ）

これらのフォルダの場所は任意であるが、例えば下記に示すような場所に作成・指定する。

Example of path to folders required by Utsusemi#

設定

デフォルトフォルダ

データフォルダ

C:¥ユーザー¥ユーザー名¥ドキュメント¥Utsusemi¥DATA

解析用フォルダ

C:¥ユーザー¥ユーザー名¥ドキュメント¥Utsusemi¥HOME

作業用フォルダ

C:¥ユーザー¥ユーザー名¥ドキュメント¥Utsusemi¥HOME
../../_images/win_Utsusemi4Install09.png

環境設定#

次に空蟬の環境の設定を Utsusemi Environment Settings で行う。なお、この作業はインストール後に一度は必ず行う必要がある。

このアプリケーションで設定できる内容は以下の通りである。

  • 使用する装置環境（BL01, BL11, BL14, BL15）

  • データフォルダと解析フォルダの設定

  • ログを残すかどうか

  • 高速化のための並列計算の数

  • デバッグモードのオン・オフ

よって、違う装置（ビームライン, BL）のデータを解析する場合は、この環境設定で装置環境を切り替える必要がある。

環境設定の起動#

「スタート」メニュー >> Utsusemi から、 Utsusemi Environment Settings を起動する。

../../_images/win_Utsusemi4Install10_2023.png

設定項目#

Utsusemi Environment Settings で設定できるものは以下のものである。

Environment variables for Utsusemi on Windows#

設定（環境変数）

役割

Instrument

解析に使用するデータの装置の選択を行う。 これにより、使用するRAWデータフォルダ、使用できるコマンドなどが変化する。

Log quiet

解析コマンドのログを減らす場合に使用する。普段はYESで良い。 なおmacOSでの空蟬の実行ログは通常あらわには表示されない。すべてのログは /tmp/mlfsoft.log に書き込まれる。

Font Size

GUIアプリのフォントサイズを定義する。通常は12で良いだろう。大きくしたり小さくしたりはできるが、 GUIパーツ（ボタンなど）やレイアウトが崩れる可能性があるので注意。

Number of threads

一部の解析コマンドが使用するマルチスレッドの最大値を設定する。 （通常は実行するPCのコアの数程度を設定するとい）

Debug mode

空蟬のデバッグモードの設定である。普段はNO（チェックボックスオフ）で良い。

DATA_DIR

イベントデータなどRAWデータを格納するフォルダである。（Linux版では”/data”）

USR_DIR

空蟬が作成する一時ファイルの保存先であるana/tmpなどのフォルダを置く場所である。（Linux版では”$HOME”）

WORK_DIR

ユーザーが作業するフォルダ（アプリケーション起動時のカレントフォルダ）

設定後#

環境設定での設定項目の変更後、その設定を反映するために OK ボタンを押す。正しく設定されれば、確認のダイアログが表示される。

../../_images/win_Utsusemi4Install11.png

このダイアログが出ずにエラーのダイアログが出た場合は、特に指定した DATA_DIR と USR_DIR のフォルダがあるかどうかを確認すること。この設定により、 USER_DIR の下に

  • ana フォルダ

  • その下に tmp フォルダ、および xml フォルダ

がなければ自動的に作成される。

../../_images/win_Utsusemi4Install12.png

ここで ana フォルダ、 tmp や xml フォルダが見つからないようなら設定を見直すか、自分で作成しておくこと。 これらのフォルダがない場合 空蟬は正しく動作しない可能性がある ので注意すること。

一方 DATA_DIR で設定した場所には、次節にて述べるルールでデータ（イベントデータなど）を配置する。

データの配置ルール#

環境変数 DATA_DIR で指定したフォルダに、以下のようなルールで配置する。

  1. 装置コードと同じ名前のフォルダを作成する。（”SIK”, “AMR”, “SAS”など）

  2. 装置コードのフォルダに、その装置でのRun Noのついたデータのフォルダを置く。（”SIK012345_20150301”など）

Examples of beam line RAW data folder#

BL

装置コード

配置例

BL01 四季

SIK

DATA/SIK/SIK012345_20160401

BL11 PLANET

HPN

DATA/HPN/HPN012345_20160401

BL14 アマテラス

AMR

DATA/AMR/AMR012345_20160401

BL15 大観

SAS

DATA/SAS/SAS012345_20160401

BL19 匠

ENG

DATA/ENG/ENG012345_20160401

空蟬の実行#

環境設定が終了し解析するデータの配置も終わっていれば、アプリケーションから解析が行えるようになる。

空蟬のインストールにより、以下のアプリケーションが「スタート」メニューから使用できる。簡単な説明を行う。

Utsusemi Environment Settings

【環境設定】空蟬の環境変数を設定する。詳細は前述の「環境設定」以下を参照のこと。

MPlot, M2PlotPlus

空蟬で使用されるデータ可視化ソフトウェアである。それぞれ、1次元プロッタ、2次元プロッタである。詳細は空蟬ユーザーマニュアルを参照のこと。Linux版と同じ。

D4MatSlicer, D4Mat2Slicer

D4MatSlicer、およびD4Mat2Slicerを起動する。あとはLinux版と同じ。

SequenceEditorQ

SequenceEditorを起動する。

Utsusemi Shell

空蟬環境で、Shell（コマンドライン）を起動する。この上で環境設定にて指定したビームラインに応じたコマンドを呼び出すことができる。よって、自作のスクリプトを走らせることもできる。


解析に使用するアプリケーションの詳細な説明は、空蟬ユーザーズマニュアルを参照のこと。

コマンドプロンプトからの使用#

アプリケーションを利用せずに、例えば自分で作成したPythonスクリプトを実行することも可能である。特に現場で作成したスクリプトや新しい解析のアイデアを形にしたコードなどを自由に実行するためには、コマンドプロンプト上で空蟬環境を利用する必要がある。その方法を以下に示す。

  1. Utsusemi Shell を起動する。

  2. 空蟬の設定が有効な状態でコマンドプロンプトが立ち上がるので、そのままPythonを起動するなり、他のインタプリタ（例えば iPython など）を利用する。

  3. 実行フォルダを変更しフォルダの移動、インタプリタの起動、スクリプトの実行を行うこともできる。

バージョンの確認#

インストールされた空蟬のバージョンを確認するには、以下の方法がある。バグなどの報告や、アップデートする際の目安となる。

インストーラファイル名には、数字が2種類ある。リリース番号は比較的大きな仕様の変更（機能追加）の時に付与される。同じリリース番号でも軽微な更新の場合は最終アップデート日付のみ変更される。以下のようなルールになる。

About Release number#

例

Utsusemi.X.Y.yymmdd

X.Y

リリース番号

yymmdd

最終アップデート日付

一方、 Utsusemi Shell を起動し、以下のようなコマンドを実行することでも情報を得られる。

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

もしくは、以下のようなコマンドでも可能である。

>>> import UtsusemiInfo
---------------------------------------------
               Utsusemi Info
---------------------------------------------
         version :  X.Y.yymmdd
  Contact person : Yasuhiro Inamura
          e-mail : xxxxx.yyyyy@j-parc.jp
---------------------------------------------

ファイル名と同様、X.Yがリリース番号である。

../../_images/win_Utsusemi4Install10_2023.png

アンインストール#

空蟬のアンインストールを行う場合、Windowsデフォルトのアンインストール（スタートメニュー >> コントロールパネル >> プログラム >> プログラムのアンインストール）や、空蟬パッケージインストーラを起動しアンインストールを選択する。

ただし、完全には消去されず、幾つかフォルダやファイルが残される。それらは手動で消去して良い。

C:¥¥Program Files¥Utsusemi（フォルダ）

また、幾つかの設定ファイルがフォルダに入って残されている。次回インストールした時に初期設定として呼び出されるが、消去しても良い。

C:¥¥Users¥”ユーザーネーム”¥AppData¥Roaming¥Utsusemi（フォルダ）

問題が発生した場合#

問題が発生する場合、以下の二つの場面が考えられる。

インストール直後の問題#

インストールしたのにアプリが起動しない、といったインストール直後に発生している問題の大部分は、インストールに失敗しているか、環境設定が適切になされていないか、のどちらかの原因が濃厚である。 一度アンインストールし、再度インストール、環境設定を行うこと。 それでもエラーなどが出る場合、その状況を担当者（著者）に伝えること。

過去によくあったのが、

  • 空蟬の条件（Python 3.7.x, 64bit）に合致していないPythonがインストールされている。

  • Pythonが2種類以上インストールされている。

などである。なお、2種類インストールされていた場合、大抵どちらかが壊れている可能性が高く、正しくアンインストールできないことがある。その場合は以下のような対応を行うこと。

  1. アンインストールできるPythonは、アンインストールする。

  2. 壊れてアンインストールできない方は、そのバージョンをインストールしたPythonインストーラを起動し、インストールではなく「修復」を選択し、正しくインストールされた状態にする。

  3. 改めて修復したPythonをアンインストールする。

  4. 最後に正しいPythonをインストールする。

コマンド実行中もしくは可視化ソフトウェア実行中の問題#

想定とは異なる事象、例えばデータ処理が進まない、GUIのソフトウェアが想定される動作をしない（ボタンが効かない）などあった場合、環境と空蟬のバージョン、及び症状とターミナルに表示されたログを担当者（著者）に送付すること。

症状の報告について#

症状に関しては、

  • 何をしようとして

  • どのコマンド（ソフトウェア）を使用して

  • 何をしたら

  • どうなった

の情報を担当者（著者）に報告・送付すること。

Appendix#

Minimum install用環境作成例#

Python.org利用#

Python.org (https://www.python.org/) のPythonインストーラーを利用して構築する例を簡便に示す。

  • Python.orgのDownloads (https://www.python.org/downloads/)から、python3.9.13（3.9系列でWindowsバイナリ配布されている最新版）をダウンロードしインストール。

  • インストールダイアログで Add Python to PATH にチェックを入れて環境変数PATHに設定されるようにしておく。

  • Pythonのインストール終了後、Command Promptアプリから、pipで numpy, scipy, matplotlib, PySide6をインストールする。

python -m pip install scipy
python -m pip install matplotlib
python -m pip install PySide6

  • Minimum Installerで空蝉をインストールする。（これからは All-in-oneと同じ）

Anaconda利用#

Anacondaを利用して環境を構築する例を簡便に示す。

Warning

AnacondaでPython環境を作ると一部のパッケージ(PySide6)がcondaで入れられずpipで入れることになるので、両者が混在(conda + pip)することで問題が発生する可能性もあるので注意

最新のAnacondaではPython3.10が使用されるので、Python3.9を使用する環境を作成する必要がある。その過程も含めて示す。

  • Anacondaをインストールする。

  • Python3.9環境を作成する。

    1. “Anaconda Navigator”を起動する。

    2. 左の欄にある”Environments”を選ぶ。

    3. “base(root)”や”Anaconda3”などが並んでいるが、下にある”Create”ボタンで新しい環境（本節では以降、”Python3.9”）を作成、その際に目的のPythonのバージョン3.9を選択する。

  • Python3.9環境の有効化

    1. “Anaconda prompt”起動する。

    2. conda info -e を実行し、新しい環境（環境名 “Python3.9”）があることを確認する。

    3. conda active Python3.9 を実行し、新しい環境に切り替える。

  • パッケージのインストール

    1. “Anaconda Navigator”の”Environments”から新しい環境”Python3.9”を選択する。

    2. 左の欄を用いて、 “numpy”, “scipy”, “matplotlib” をインストールする。

    3. ただし、”PySide6”は存在しないので、別途pipをインストールし、適当なコマンドプロンプト上で、python -m pip install PySide6を実行した。

  • コマンドプロンプトから上記のPython3.9環境を利用できるようにする。

    1. pathを通すために、環境の場所を確認する（通常 ホームフォルダの下の”Anaconda3\envs”の中にある C:UsershogeAnaconda3envsPython3.9 ）。

    2. 環境変数PATHに、確認したPython3.9環境のパスや、その下のパスを以下のように追加する。

C:\Users\hoge\Anaconda3\envs\Python3.9\
C:\Users\hoge\Anaconda3\envs\Python3.9\Scripts
C:\Users\hoge\Anaconda3\envs\Python3.9\Library\bin