空蟬の環境#

ここでは、インストールされた空蟬の環境について述べる。環境変数や使用するディレクトリなどは、空蟬のインストール時に作成されるが、それらの役割を理解してもらうのがこの項の趣旨である。

空蟬の構成#

空蟬のコードは、主に二つの部分で構成されている。

万葉ライブラリ部（C++）
Pythonコード部

万葉ライブラリとはC++で作成されたMLFでの標準データ処理基盤環境である。データの入れ物（コンテナ）の定義やコンテナに対する各種機能、新しい機能を実現するための関数作成のテンプレートなどが用意された開発用フレームワークでもある。そのコンテナや機能はPythonから呼び出すことができる。（詳細は MLFデータ解析フレームワーク”万葉ライブラリ”利用マニュアル）

空蟬における万葉ライブラリ部は、空蟬環境で使用できる大部分の機能が含まれている根幹部分である。万葉ライブラリのコンテナ機能を活かし高速に処理するためにC++コードで書かれており、インストールにより万葉ライブラリの中に含まれる形となる。よって空蟬の、主にデータリダクションに関する基本機能は、万葉ライブラリと同様にPythonから簡単に呼び出し使用することが可能である。

一方Pythonコード部、主にユーザーから見て空蟬の機能をより使いやすくすることを目的に作成されている。万葉ライブラリ部の機能関数の呼び出しをより簡単にするための補助的な機能をファサード関数として担い、同時にデータの可視化やグラフィカルインターフェースを持つアプリケーションも含んでいる。

万葉ライブラリ部の機能呼び出し（ファサード関数）
可視化（データプロット）
グラフィカルインターフェース（アプリケーション）

構造の概念図

コードなどの配置#

上記のように、空蟬は主に二つの部分がある。

万葉ライブラリ部
Pythonコード部

それぞれの配置先に関して特に指定はない。極論すれば、下記のように万葉ライブラリ内やPythonコード部の空蝉パッケージがimportできれば良い。

$ python3
>>> import Manyo # 万葉ライブラリ
Manyo>>> import Manyo.Utsusemi # 万葉ライブラリの空蝉パッケージ
Manyo>>> import utsusemi # 空蝉Pythonコード部のパッケージ

従ってそれぞれのフォルダがどこにあろうとも、正しく環境変数（ MANYO_PATH , PYTHONPATH , LD_LIBRARY_PATH など）が設定されていれば良い。

空蝉の万葉ライブラリ部の置き場所（インストール先）も、万葉ライブラリのコア部分の置き場所 MANYO_PATH の下となっている。

${MANYO_PATH}/Manyo/Utsusemi/ # import される空蝉モジュール
${MANYO_PATH}/lib/libUtsusemi.so # 空蝉モジュールの共用ライブラリ
${MANYO_PATH}/include/manyo/Utsusemi/

なお、万葉ライブラリのimportに必要な最小限の環境変数は LD_LIBRARY_PATH と PYTHONPATH であるが、それらは MANYO_PATH を利用して以下のようになる。

Pathes to use Manyo Library#
LD_LIBRARY_PATH	${MANYO_PATH}/lib
PYTHONPATH	${MANYO_PATH}

export LD_LIBRARY_PATH=${MANYO_PATH}/lib
export PYTHONPATH=${MANYO_PATH}:${PYTHONPATH}

これらの設定により、

import Manyo
import Manyo.Utsusemi

のように万葉ライブラリ内の空蝉モジュールをインポートできるようになる。

一方Pythonコードは、すべて utsusemi ディレクトリ（空蟬ベースディレクトリ UTSUSEMI_BASE_DIR ）に格納されている。また、空蟬を用いるビームライン固有のコード群は、その直下のディレクトリ

${UTSUSEMI_BASE_DIR}/XXX
(/opt/mlfsoft/python-utsusemi/utsusemi/XXX)

に配置される。

これらを利用するのに必要となる最小限の環境変数は PYTHONPATH のみであるが、それらは UTSUSEMI_BASE_DIR および UTSUSEMI_INST_CODE を利用して以下のようになる。

Pathes to use Utsusemi Python codes#
PYTHONPATH	${UTSUSEMI_BASE_DIR}
	${UTSUSEMI_BASE_DIR}/facade
	${UTSUSEMI_BASE_DIR}/${UTSUSEMI_INST_CODE}/facade

ここで ${UTSUSEMI_INST_COCE} は SIK や SAS などのビームラインのコードであり、このフォルダの中にはそのビームライン専用のコードが配置されている。

export UTSUSEMI_BASE_DIR=/path/to/utsusemi # /opt/mlfsoft/python-utsusemi/utsusemi
export UTSUSEMI_INST_CODE=XXX # ex. SIK, AMR, HPN, ...
export PYTHONPATH=${UTSUSEMI_BASE_DIR}:${UTSUSEMI_BASE_DIR}/facade:${UTSUSEMI_BASE_DIR}/${UTSUSEMI_INST_CODE}/facade:${PYTHONPATH}

すなわち、 import utsusemi が実行できること、またいくつか存在する facade フォルダ内のモジュールをダイレクトに import できること、が必須条件となっている。

それらのフォルダの構成図を示す。

基本的な配置構造として、 utsusemi 以下にあるディレクトリは

ana , vis , facade

の3つである。また装置固有のコードなどを含める XXX は、空蟬ディレクトリ配下にあり、XXX 以下のディレクトリも空蟬ベースディレクトリ同様に ana , vis , facade を含めることにしている。

Utsusemi Python folders#
utsusemi（空蟬ベースディレクトリ）以下のディレクトリ
ana	SequenceEditorQ.py	データリダクション用グラフィカルインターフェースソフトウェア
ana	Reduction	データリダクションモジュールを収める
vis		可視化用コードを収める
facade		SequenceEditorで扱うコマンドファサードを収める
XXX	facade, ana など	装置固有のコードやパラメータを収める。

特に、 XXX 以下の XXX/ana/xml にはヒストグラム化に必要となる装置固有パラメータである、

WiringInfo
DetectorInfo

などがあるので、留意しておく必要がある。

必要な環境変数#

空蟬をパッケージとしてみた場合、必要な環境変数は空蟬ベースディレクトリ( utsusemi )へのパスを、Pythonの環境変数 PYTHONPATH に登録するだけである。しかし MLFソフトウェアとして動作させる（MLFのデータの場所など）ために、他にも幾つかの環境変数の設定が必要である。

その環境変数を以下に示した。

空蟬用環境変数	役割
MANYO_PATH	万葉ライブラリの実行に必要なパスを与える。 “/opt/mlfsoft/manyo”など。
UTSUSEMI_BASE_DIR	空蟬のPythonコード（python-utsusemi）の場所を与える “/opt/mlfsoft/python-utsusemi”など。
UTSUSEMI_INST_CODE	実行する環境の装置のコードを与える。 “SIK”, “AMR”, “HPN”など。
UTSUSEMI_DATA_DIR	RAWデータの場所を与える。”/data”など。
UTSUSEMI_USR_DIR	ユーザーのホームフォルダを与える。この中にana/xmlやana/tmpが存在することが期待される。 facade/があればSequenceEditorからの検索パスが通る。デフォルトは${HOME}でよい。 “/home/hoge”など。
UTSUSEMI_WORK_DIR	ユーザーのワークフォルダを与える。 ${UTSUSEMI_USR_DIR}と同じでよい。
UTSUSEMI_LOG_QUIET	これに”y”を与えると空蟬コードが出力するテキストを抑制する
UTSUSEMI_MULTH	マルチスレッド数を指定する。処理によっては使用メモリが非常に増大するので注意。
UTSUSEMI_DEBUGMODE	空蟬をデバッグモードで走らせる。通常より大量のコメントが表示され、テンポラリファイルも作成される。

システム環境変数	役割
PYTHONPATH	空蟬のPythonコード実行に必要なパスを全て与える。通常は、PYTHONPATH = ${MANYO_PATH}: ${UTSUSEMI_BASE_DIR}:${UTSUSEMI_BASE_DIR}/facade: ${UTSUSEMI_BASE_DIR}/${UTSUSEMI_INST_CODE}/facade: ${UTSUSEMI_USR_DIR}/facade
LD_LIBRARY_PATH	空蟬のC++コード実行に必要なパスを全て与える。通常はLD_LIBRARY_PATH=${MANYO_PATH}/lib
PATH	実行ファイルの置き場所。通常はPAHT=${MANYO_PATH}/bin:${PATH}

参考のために、これらの環境変数を設定するために使用しているシェルスクリプト（Linux用）を載せる。 Linuxでは、このスクリプトを起動時（ログイン時）に走らせることで、空蟬環境として起動させることが可能である。

# Utsusemi Environment
export UTSUSEMI_INST_CODE=SIK
export UTSUSEMI_DATA_DIR=/data
export UTSUSEMI_USR_DIR=${UTSUSEMI_USR_DIR-${HOME}}
export UTSUSEMI_WORK_DIR=${UTSUSEMI_USR_DIR}
export UTSUSEMI_LOG_QUIET=n
export UTSUSEMI_MULTH=8
export UTSUSEMI_DEBUGMODE=n

# Path to MLF Software
MLFSOFT_PATH=/opt/mlfsoft

# Path to Manyo-lib
export MANYO_PATH=${MLFSOFT_PATH}/manyo

# PythonPath to utsusemi
PYUTSUSEMI_PATH=${MLFSOFT_PATH}/python-utsusemi

# PythonPath to uGao
PYUGAO_PATH=${MLFSOFT_PATH}/python-ugao

# External Library path
UTSUSEMI_EXT_LIBRARY_PATH=/usr/local/lib

# Utsusemi Environment
export UTSUSEMI_BASE_DIR=${PYUTSUSEMI_PATH}/utsusemi

# Python Path
PYTHONPATH=${MANYO_PATH}:${PYUTSUSEMI_PATH}:${UTSUSEMI_BASE_DIR}/facade
PYTHONPATH=${UTSUSEMI_BASE_DIR}/${UTSUSEMI_INST_CODE}/facade:${UTSUSEMI_USR_DIR}/facade:${PYTHONPATH}
PYTHONPATH=${PYTHONPATH}:${PYUGAO_PATH}
export PYTHONPATH

# Shared Library Path
export LD_LIBRARY_PATH=${MANYO_PATH}/lib:${UTSUSEMI_EXT_LIBRARY_PATH}:${LD_LIBRARY_PATH}

# Executable path
export PATH=${MANYO_PATH}/bin:${PATH}

考慮すべきディレクトリ#

また空蟬を動作させる場合に必要なディレクトリを以下に示す。動作時にはこれらのディレクトリが存在している必要がある。特にデータは確実にRun Numberごとのフォルダとして、置いておく。

ディレクトリ（環境変数）	具体例	内容
${UTSUSEMI_DATA_DIR}/${UTSUSEMI_INST_CODE}	“/data/SIK”	対象となる装置のRAWデータの場所。ここにSIK001234_20150809といったRun Numberごとのフォルダが配される。
${UTSUSEMI_USR_DIR}/ana	“/home/hoge/ana”	空蟬環境で動作するいくつかのコードが利用する。実際にはこのフォルダ内のxmlフォルダやtmpフォルダが使用される。

データフォルダの配置の概要#

データフォルダ（例えば SIK001234_20210412 ）を配置する場合、必ずビームラインのコード（ SIK や DNA など）のフォルダを作成し、その下に配置する。

また、空蟬はデータフォルダが複数のフォルダに分散していても機能する。ただ、その場合、

/data/SIK
/data/SIK00
/data/SIK01
...
/data/SIK99

というふうに装置コード＋二桁数字（０埋め）のフォルダである必要がある。

空蟬の環境

Contents