空蟬コマンド実行環境 SequenceEditor#

著者

稲村 泰弘

最終更新日

May. 11, 2023

概要#

一般に中性子散乱の解析処理は、多段階の処理を柔軟に組み合わせた非定型処理が多く、かつ解析途中の結果を逐次確認しながら、その結果を元に解析パラメータを変更し幾度と解析を繰り返すことが求められる。 このような要望に対し、以下のような機能が求められる。

  1. 解析処理シーケンスを柔軟に組み替える機能

  2. あらかじめ用意されているシーケンスや内包されるコマンドの一部パラメータの簡便な変更機能

  3. シーケンス中に組み込んだ自動可視化と、非同期に任意のタイミングで行う可視化する機能

なお、ここでは解析処理の１単位をコマンドもしくは関数、連続したコマンドの流れをシーケンスと呼んでいる。これらの機能を実現するためのGUIソフトウェアが SequenceEditor である。

本稿では空蟬の基本コマンド実行環境である SequenceEditor の使い方を示す。なお、このソフトウェアで実行されるコマンドは facade （ファサード）関数と呼ばれる。

起動方法#

空蟬がインストールされている環境に応じて起動方法が異なるので、インストールマニュアルなどを参照のこと。

環境

起動方法(GUI)

起動方法(command)

Win, Mac版

SequenceEditor アプリを起動、

UtsusemiShell アプリ内で”Ana”と入力

Linux版

なし

コマンドラインから、”Ana”と入力する

終了方法#

アプリのメニューから Close を選択するか、アプリのCloseボタンを押す。ただしシーケンス実行中は、閉じることができないことに注意（エラーを示すダイアログが出現する）。

基本的な使い方#

  1. 起動

    起動すると下記のようなGUIが起動する。

../../_images/seq_main_display_raw.png

Launched SequenceEditor#

  1. コマンド選択と追加

    左上の Commands Tree から実行したいコマンドを選択し、 Add Button を押すと、スクリプトに加えられる。

    詳細は Commands List を参照のこと。

../../_images/seq_add_command.png

Click the command to add the sequence with parameters#

  1. コマンドのパラメータ変更

    スクリプトのコマンドをクリックすると Arguments Area にパラメータ名と入力欄が現れるので、そこに必要なパラメータを入力する。 また戻り値が必要なコマンドでは、 Return Label の欄が入力可能になるので、戻り値のラベル（変数名）を与える。 詳細は Arguments Area を参照のこと。

  2. スクリプトの作成

    必要に合わせて、2. コマンド選択と追加、3. パラメータ変更を繰り返す。スクリプト内のコマンドを削除したり順序を入れ替えたりできる。詳細は Edit Buttons を参照のこと。

../../_images/seq_sequence_raw.png

Making the sequence#

  1. スクリプトの実行

    画面上部の Start ボタンを押すとスクリプトが実行される。

    コマンドの先頭にあるアイコンが実行状態を示している。 またコマンド実行開始時刻と終了時刻もコマンドの右側の欄に表示される。 詳細は 詳細は Sequence Control Buttons や Sequence Area を参照のこと。

  2. データの可視化

    スクリプトが終了すればコマンドによって作成されたデータ（戻り値）があれば画面上部の右端 Visualize ボタンを押すことで可視化ダイアログが出現する。ここでデータにあった可視化アプリを使用することで2次元プロッタや1次元プロッタなどでデータを表示できる。 可視化ダイアログについては、 可視化ダイアログについて を参照のこと。

  3. スクリプトの保存・読み込み

    作成したスクリプトは画面上部の Save ボタンでファイルに保存できる。また以前に保存したファイルも Load ボタンで読み込むことも可能である。詳細は Sequence Control Buttons を参照のこと。

../../_images/seq_save_load.png

Buttons to control sequence#

コマンドについて#

実行できるコマンド（ファサード関数）は、装置によって異なる。空蟬環境で使用出来る基本的なPython関数は全てファサード関数として機能するようになっている。詳細は 空蟬ファサード関数 を参照のこと。

ファサード関数自体は。SequenceEditor 上から実行できるが、同時に コマンドラインから普通に実行が可能 な、ごく普通のPythonの関数でもある。つまり、GUI上（SequenceEditor）からもコマンドラインからも同じコマンドが同じパラメータで実行できる。

また、ユーザーが自由にファサード関数を作成し、SequenceEditorで利用することも可能である。ファサードの作成については別項（ SequenceEditorファサード作成入門 ）で述べる。

機能の詳細#

メイン画面上の表示情報#

../../_images/seq_main_display.png

GUI area of SequenceEditor#

Title

“Sequence Editor - XX”を表示する。XXは、編集中のシーケンスファイル名称を示す。起動時は、”New” である。

Commands List

シーケンスに登録し実行できる関数（コマンド）を表示する。階層的に表示され、トップにビームラインコード、以下装置に応じて階層化されている。一部の可視化ソフトもコマンド化されている。詳細は次項。

Commands Information

Commands Listで選択（クリックして選択）されたコマンドに対する説明や情報を表示する。

Sequence Control Buttons

シーケンス処理を実行、停止したり、データの可視化、スクリプトの読み込み、書き出しなど、シーケンスに関する制御を行うためのボタン類。

Sequence Status

シーケンス処理の実行中、停止中などの状態を表示する。

Sequence Area

シーケンスの内容、およびシーケンスの実行状態を表示する。 コマンドの流れのみならず、実行の成功、失敗、実行時の時刻情報なども表示する。 詳細は次項。

Arguments Area

シーケンスに登録されたコマンドの引数と戻り値用の変数名を入力する。 詳細は次項。

Edit Sequence Buttons

シーケンスに対しコマンドを追加したり、コマンドの削除、移動、複製などを行うためのボタンである。

各部の説明#

Commands List#

実行できるコマンドをツリー表示で見ることができる。またこのコマンド選択し Edit Sequence Buttons の追加ボタン( Add Button )を押すことでシーケンスに追加できる。これらのコマンドはSequenceEditor起動時に設定により読み込まれる。

../../_images/seq_commands_list.png

Tree view of commands#

トップのFunctionsの下にあらかじめ設定されたグループでコマンドが並べられる。この図では、 SIKの下に、Com, Cmm, DRの３つのグループと、Visualizerの下に、D1Plotterのグループが存在する。それぞれのコマンドは、グループ名（ピリオド）コマンド名で表示される。

読み込みに失敗したコマンドやグループがあると、そのグループの一覧は空となる。

なお、このコマンドのツリー構造は、設定ファイルを作成することで任意に変更できる（ 空蟬4.0.220329以降 ）。行う場合は別項（ SequenceEditorファサードグループ設定 ）を参照のこと。

Edit Sequence Buttons#

シーケンスを編集するためのボタンである。

../../_images/seq_sequence_edit_button.png

Buttons to make commands sequence#

Functions of buttons to make commands sequence#

ボタン

役割

Add

Commands List にて選択されたコマンドをシーケンスに登録する。

Delete

Sequence Area で選択されたコマンドを削除する。複数選択可能。

Duplicate

Sequence Area で選択されたコマンドをコピーし、シーケンスの最後に付け加える。複数選択可能。

Move Up

Sequence Area で選択されたコマンドを上へ移動する。

Move Down

Sequence Area で選択されたコマンドを下へ移動する。

Sequence Area#

シーケンスの内容及び実行状況を示す。

../../_images/seq_command_sequence_area.png

Command sequence area#

Command Status

シーケンスのコマンドごとの実行状態を示す。

Command Status#

Icon

Meanings

seq_command_execute_status_0

実行可能、かつ未実行

seq_command_execute_status_1

実行不可能（引数に問題あり）、かつ未実行

seq_command_execute_status_2

実行中

seq_command_execute_status_3

実行可能、かつ実行済み（正常終了）

seq_command_execute_status_4

実行可能、かつ実行済み（異常終了）
注意事項

実行済みのステップ( seq_command_execute_status_3 または seq_command_execute_status_4 )の引数を変更すると、当該コマンドの実行結果をクリアし、未実行状態( seq_command_execute_status_0 または seq_command_execute_status_1 )へ移行する。また、当該コマンドの戻り値を引数とするステップも未実行状態となる。更に、派生的に未実行へ移行した関数の戻り値を引数とする関数も、未実行状態となる。コマンドを削除した場合も同様に、削除した関数の戻り値を引数とする関数は未実行状態に移行する。コマンドの実行順を変更した場合は、当該コマンド以降のコマンドの実行結果をクリアし、未実行状態( seq_command_execute_status_0 または seq_command_execute_status_1 )へ移行する。

Time Info

そのコマンド実行を開始した時刻（Begin Time）と終了した時刻（End Time）を表示する。未実行な場合は、両方の時刻が空欄、コマンド実行中に異常終了した場合、終了時刻に Aborted と表示される。

Sequence Control Buttons#

シーケンスの制御やシーケンスのファイルへの保存、読み込み、可視化を行うためのボタンである。

../../_images/seq_sequence_control_buttons.png

Buttons to control sequence#

Clear （シーケンスクリアボタン）

シーケンスをクリアする。タイトルバーのファイル名はNewに変わる。

Load （シーケンス読み込みボタン）

シーケンス保存ボタンで保存したシーケンススクリプトファイル（拡張子 pmt）を読み込む。 このボタンを押すとファイル選択ダイアログが開くので、保存されたシーケンススクリプトファイルを選ぶ。 シーケンスにコマンドが残っている場合、既存のシーケンスコマンドの最後尾にシーケンスを追加する。

Save （シーケンス保存ボタン）

シーケンスをファイル（シーケンススクリプトファイル：拡張子 pmt）として保存する。このボタンを押すと、コメント入力ダイアログが開くので、シーケンスに関するコメントを入力する。この後ファイル保存ダイアログが開くのでファイル名をつけて保存する。先のコメントはファイルの先頭に書き込まれている。保存したファイルは、Pythonのスクリプトであるので、空蟬環境下においてはそのままPythonスクリプトとして実行できる。

../../_images/seq_sequence_control_files_comment.png

Comments dialog on saving sequence as script file#

Change Current Directory （カレントディレクトリ設定ボタン）

ファイルの読み書き（スクリプト自体、もしくはパラメータファイルなど）におけるデフォルトとなるディレクトリを指定する。設定されているディレクトリは、ボタン下の「Current Dir :」に表示されている。（カレントディレクトリの詳細は後述）

Start （シーケンス開始ボタン）

シーケンスの最初から開始(Start)する。全コマンドが実行可能な場合のみ、Startできる。

Stop （シーケンス停止ボタン）

シーケンス実行中に停止(Stop)させる。シーケンスはボタンを押した時に実行中のコマンドが終了した時に停止する。終了までに長時間かかるコマンドの場合、その間に未実行のシーケンスを編集し、Resumeボタンを押すことで再開予約を行うこともできる。この再開予約により、実行中コマンドが正常終了した時に、予約したコマンドから実行が再開される。

Resume （シーケンス再開ボタン）

開始したいコマンドを選択し、そこからシーケンスを再開する。どの行も選択されていなかった場合は、実行終了済み（正常終了）のコマンドの次のコマンドから再開する。実行不可能なコマンドがなく、かつ正常終了したコマンドがあるときのみ再開が可能である。Stopボタンを押してまだ停止していない場合は再開予約となる。 開始したいコマンドより前にみ実行のコマンドがある場合、エラーとなる。

Visualize… （可視化ボタン）

可視化用ダイアログを開く。可視化用ダイアログが他のウィンドウに隠れていた場合でも、このボタンを押すことで最前面まで出てくる。 このダイアログに関しては、別項（ 可視化ダイアログについて ）で述べる。

Arguments Area#

シーケンスに登録されたコマンドのそれぞれに対し、引数と戻り値の変数名を与える。シーケンスのコマンドが選択されると、この部分が動的に変化し、引数のラベルが表示され引数の入力が可能となる。コマンドをシーケンスに追加した直後の引数は、あらかじめコマンドで設定したデフォルト値が入力されている。

../../_images/seq_sequence_argument.png

Arguments area#

引数のラベル（ Arguments Label ）は、コマンドにあらかじめ指定してあるものである。またラベルと入力ボックス（ Arguments Box ）は15個用意されるが、不要な入力ボックスは不可視のままである。また引数の型（文字列、数値など）は、それぞれのコマンドの定義によるので、定義と異なる値が入力されるとエラーとなる。引数の型は、文字列、整数、実数、論理値（True, False）のいずれかか、対象のコマンド以前に実行されるコマンドの戻り値の変数名である。

なお、入力ボックス上にマウスのポインタを置くと、その引数の説明が小さな枠（ツールチップ）で表示される。（ Argument Tips ）

戻り値があるコマンドの場合、戻り値の入力ボックスが入力可能となる（ Return Variable Box ）。ここで使用した変数名は、このコマンド以降のシーケンス上のコマンドの引数として用いることができる。

引数や、戻り値を書き込んだら、必ず Set Button を押すこと。これにより、 Sequence Area 上のコマンドの引数に反映されるので確認できる。また Sequence Area のコマンドを選択すると、再び Arguments Area に反映される。

なお、シーケンス実行中は Arguments Area は操作できない状態となる。

可視化用ダイアログについて#

シーケンスのコマンドの戻り値の幾つかは、そのままDetectorMapやM2Plotといった空蟬の可視化ソフトにて表示することが可能である。 Visualize… ボタンにより、可視化用コマンドのダイアログが開く。

../../_images/seq_visualization_panel.png

Visualization dialog#

Visualize Software List

可視化ソフトウェアおよび可視化ソフトウェアへのデータ追加するコマンドの一覧。それぞれのコマンドは以下の通り（このあたりは装置によって異なる）。

Example items on Visualization Dialog#

コマンド

役割

引数（データに関しては各マニュアルを参照）

戻り値

DetectMap

DetectMapを起動

ElementContainerMatrix

なし

MPlot

MPlotを起動

ElementContainer(s)

MPlot固有名

AddToMPlot

起動中のMPlotにデータを追加

ElementContainer(s), MPlot固有名

なし

M2PlotPlus

M2Plot+を起動

ElmentContainerArray-Matrix

M2Plot+固有名

ChangeMap

起動中のM2Plotにデータを追加

ElmentContainerArray-Matrix,M2Plot+固有名

なし

VisContM

VisualContMを起動

ElementContainerMatrix

VisualContM固有名

AddToVisContM

起動中のVisualContMにデータを追加

ElmentContainerMatrix, タブ名,VisualContM固有名

なし
Argument Label , Argument Box , Return Variable Box

各ソフトウェアを選択すると、そのソフトウェアが必要とする引数と戻り値が示される。

Execute Button

選択し、引数などを与えた可視化コマンドを実行する。

Close Button

ダイアログを閉じる。

カレントディレクトリの設定#

ファイルの保存などでデフォルトの場所として使用できるカレントディレクトリを変更できる。

カレントディレクトリの指定により、以下のような利点がある。

  1. スクリプトファイルの読み書きダイアログ操作の省力化

    ユーザーの実行スクリプトが置かれているディレクトリをカレントディレクトリに指定すると、スクリプトの読み込みボタンでダイアログを開くと最初にカレントディレクトリが示される。

  2. パラメータとして与えるパスの省略可

    データファイルなどをまとめて入れてあるディレクトリをカレントディレクトリに指定すると、それらを開いたり読み込ませる場合に必要なパラメータ（パスやファイル指定）が楽になる。

    幾つかのコマンドは、マスクファイルやデータ保存や読み込みのためのファイルの指定に、ファイルの位置情報（Path）を必要とする。この際、使用しているシステムにおけるPathの表現方法をそのまま書くことになる。

    OS

    表記

    Linux, MacOS

    /home/hogehoge/MaskFile.xml

    Windows

    C:\UsershogeMaskFile.xml

    そこでデータファイルがあるディレクトリをカレントディレクトリとして指定すれば、ファイル名（MaskFile.xml）を書くだけで良い。

    Pathにカレントディレクトリを指定する必要がある場合、Linuxにおける表記である ./ （ピリオド＋スラッシュ）が使用される。

Appendix#