=====================================================
SequenceEditor（空蟬コマンド実行環境）
=====================================================

:著者: 稲村 泰弘
:最終更新日: Dec. 16, 2016

.. contents:: 目次
	:depth: 2


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

1. 解析処理シーケンスを柔軟に組み替える機能
2. あらかじめ用意されているシーケンスや内包されるコマンドの一部パラメータの簡便な変更機能
3. シーケンス中に組み込んだ自動可視化と、非同期に任意のタイミングで行う可視化する機能

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

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


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

	+----------+-----------------------------------+
	|環境      |起動方法                           |
	+==========+===================================+
	|Win, Mac版|**SequenceEditor** アプリを起動    |
	+----------+-----------------------------------+
	|Linux版   |コマンドラインから、"Ana"と入力する|
	+----------+-----------------------------------+


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


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

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

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



GUIインターフェースと機能
====================================

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

|seq_main_display|

**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起動時に設定により読み込まれる。

|seq_commands_list|

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

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

**Edit Sequence Buttons**
---------------------------
シーケンスを編集するためのボタンである。

|seq_sequence_edit_button|

+---------+-----------------------------------------------------------------------------------------------+
|ボタン   | 役割                                                                                          |
+=========+===============================================================================================+
|Add      | **Commands List** にて選択されたコマンドをシーケンスに登録する。                              |
+---------+-----------------------------------------------------------------------------------------------+
|Delete   | **Sequence Area** で選択されたコマンドを削除する。複数選択可能。                              |
+---------+-----------------------------------------------------------------------------------------------+
|Duplicate| **Sequence Area** で選択されたコマンドをコピーし、シーケンスの最後に付け加える。複数選択可能。|
+---------+-----------------------------------------------------------------------------------------------+
|Move Up  | **Sequence Area** で選択されたコマンドを上へ移動する。                                        |
+---------+-----------------------------------------------------------------------------------------------+
|Move Down| **Sequence Area** で選択されたコマンドを下へ移動する。                                        |
+---------+-----------------------------------------------------------------------------------------------+


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

|seq_command_sequence_area|

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

	.. list-table:: Command Status
		:widths: 1 10
		:header-rows: 1
		
		* - 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**
--------------------------------
シーケンスの制御やシーケンスのファイルへの保存、読み込み、可視化を行うためのボタンである。

|seq_sequence_control_buttons|


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

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

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

	|seq_sequence_control_files_comment|

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

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

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

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

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




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

|seq_sequence_argument|

引数のラベル（ **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...** ボタンにより、可視化用コマンドのダイアログが開く。

|seq_visualization_panel|

**Visualize Software List**
	可視化ソフトウェアおよび可視化ソフトウェアへのデータ追加するコマンドの一覧。それぞれのコマンドは以下の通り。
	
	+-------------+---------------------------------+-----------------------------------------------+-----------------+
	|コマンド     |役割                             |引数（データに関しては各マニュアルを参照）     |戻り値           |
	+=============+=================================+===============================================+=================+
	|DetectMap    |DetectMapを起動                  |ElementContainerMatrix                         |なし             |
	+-------------+---------------------------------+-----------------------------------------------+-----------------+
	|MPlot        |MPlotを起動                      |ElementContainer(s)                            |MPlot固有名      |
	+-------------+---------------------------------+-----------------------------------------------+-----------------+
	|AddToMPlot   |起動中のMPlotにデータを追加      |ElementContainer(s), MPlot固有名               |なし             |
	+-------------+---------------------------------+-----------------------------------------------+-----------------+
	|M2Plot       |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:\\Users\hoge\MaskFile.xml|
	+-------------+---------------------------+

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

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




.. 1323x804

.. |seq_main_display| image:: media/seq_main_display.png 
    :width: 600px

.. 789x550

.. |seq_commands_list| image:: media/seq_commands_list.png 
    :width: 360px

.. 1026x369

.. |seq_command_sequence_area| image:: media/seq_command_sequence_area.png 
    :width: 460px

.. 1435x226

.. |seq_sequence_control_buttons| image:: media/seq_sequence_control_buttons.png 
    :width: 650px


.. 1152x521

.. |seq_sequence_argument| image:: media/seq_sequence_argument.png 
    :width: 520px

.. 888x674

.. |seq_visualization_panel| image:: media/seq_visualization_panel.png 
    :width: 400px

.. 340x194

.. |seq_sequence_control_files_comment| image:: media/seq_sequence_control_files_comment.png
	:width: 150px

.. 375x484

.. |seq_sequence_edit_button| image:: media/seq_sequence_edit_button.png
	:width: 170px


.. 22x22

.. |seq_command_execute_status_0| image:: media/seq_command_execute_status_0.png
.. |seq_command_execute_status_1| image:: media/seq_command_execute_status_1.png
.. |seq_command_execute_status_2| image:: media/seq_command_execute_status_2.png
.. |seq_command_execute_status_3| image:: media/seq_command_execute_status_3.png
.. |seq_command_execute_status_4| image:: media/seq_command_execute_status_4.png