.. _CUI_UtsusemiSqeCalc:

運動量エネルギー空間への射影に関連するコマンド
================================================

.. contents:: 目次
    :depth: 2

単結晶を試料とした非弾性散乱測定を行なった場合、４次元空間情報（Q1, Q2, Q3, hw）に変換（射影）することが必要となる。その処理は以下のようなステップを踏む。

1. 測定データのデータリダクション（ヒストグラム化、補正処理など）
2. 試料の格子定数及び、入射中性子方向に対する試料の方位情報を準備（次の射影に必要）
3. 測定データのQ空間への射影（Projection）
4. 射影されたデータの可視化（スライスやプロット）

これらの作業は、先頭のデータリダクション以外は **VisualContM** （ :ref:`「VisualContMマニュアル」<VisualContM>` ）というGUIのソフトウェアで行うこともできるが、全てのステップは *Python* のスクリプトで作成することができるよう、コマンドが準備されている。

本章では、そのコマンドの使用例とリファレンスを記述する。

空蟬における射影作業で用いられるコマンド（クラス）は、 **UtsusemiSqeCalc** である。

----------------
サンプルコード
----------------
ここでは、 **UtsusemiSqeCalc** クラスをPythonから使用するサンプルコードを示す。

なお、本節では *DAT* はデータリダクション済みのデータとする。もっともシンプルには以下のようなスクリプトで得られるデータである。

.. code-block:: python
    
    ## Data Reduction
    import DR
    DAT = DR.GetDataOfMonochroEi2(373,45.56,0.2,-4.0,40.0,"mask.txt", 0.0 )

またスクリプト内のコマンド（メソッド）のリファレンスは、次節に記している。

サンプルコード 1
-------------------

全ての情報（試料、射影、スライス）を与える場合を示す。

.. code-block:: python
    
    # -*- coding: utf-8 -*-
    import Manyo.Utsusemi as mu
    import Manyo
    
    ## Projection for single crystal
    sqe = mu.UtsusemiSqeCalc()                     # コマンド利用の準備
    sqe.SetTarget(DAT)                             # 処理するデータを設定
    
    ## Parameters
    LC = [4.8,8.4,2.9,90.0,90.0,90.0]              # 格子定数 a, b, c, alpha, beta, gamma
    Uvect = [0.0, 1.0, 0.0]                        # U-vector
    Vvect = [0.0, 0.0, 1.0]                        # V-vector
    Rotations = "Y:-5.0"                           # U,V-vectorの回転指定
    Proj_Ax1 = [1.0, 0.0, 0.0, 0.0, "Qa(rlu)"]     # 射影情報とラベル
    Proj_Ax2 = [0.0, 1.0, 0.0, 0.0, "Qb(rlu)"]
    Proj_Ax3 = [0.0, 0.0, 1.0, 0.0, "Qc(rlu)"]
    Proj_Ax4 = [0.0, 0.0, 0.0, 1.0, "Energy(meV)"]
    
    ## Set parameters
    sqe.SetLatticeConstants( LC )                   # 格子定数設定
    sqe.SetUVvector( Uvect, Vvect )                 # U-vector, V-vector設定
    sqe.SetRotationSteps( Rotations )               # U,V-vectorの回転指定
    ## Do projection                                # 射影計算実行
    sqe.Projection( Proj_Ax1, Proj_Ax2, Proj_Ax3, Proj_Ax4 )
    
    ## Slicing
    v=sqe.PutQRange()                              # 射影後の角軸の領域を取り出し
    ax1=[ "T" ,v[0], v[1] ]                        # 各軸のスライス情報リスト
    ax2=[ "T" ,v[2], v[3] ]                        # "X" : x軸方向（範囲とbin幅）
    ax3=[ "X" ,v[4], v[5], 0.02 ]                  # "Y" : y軸方向（範囲とbin幅）
    ax4=[ "Y" ,v[6], v[7], 0.2 ]                   # "T" : 厚み方向（範囲）
    dfold = []                                     # 畳み込み情報
    sqe.Slice(ax1,ax2,ax3,ax4,dfold)               # スライス実行
    eca=Manyo.ElementContainerArray()              # 空のコンテナを準備
    sqe.SetSlicedElementContainerArray(eca)        # コンテナにスライス結果をコピー
    
    ## Plot sliced data
    #import vis.M2Plot as mp
    #p=mp.M2Plot(eca)                               # M2Plotでそのまま表示可能
    
    ## Save sliced data as PNG figure file          # 表示させずに画像だけ保存も可能（詳細は別項）
    import vis.CuiD2Chart as cd2
    titles=["Test Data","SubTitle","Qb(rlu)","Energy(meV)"]
    z_range=[0.0, 40.0]
    filename = "TestData.png"
    plt = cd2.CuiD2Chart(eca, Titles=titles)
    plt.MakePlot( z_range )
    plt.SaveFile( filename )
    
    ## Save projection parameters
    sqe.SaveXtalParam( "XtalParam.xml" )           # 上記の情報をXtalParam.xmlに書き出す

参考までに、上のスクリプトと同等の処理を行うためのパラメータを表示している *VisualContM* のパネルを示しておく。

|fig01|


サンプルコード 2
-------------------

全ての情報をXtalParam.xmlから与える場合を示す。

.. code-block:: python
    
    # -*- coding: utf-8 -*-
    import Manyo.Utsusemi as mu
    import Manyo
    
    ## Projection for single crystal
    sqe = mu.UtsusemiSqeCalc()                     # コマンド利用の準備
    sqe.SetTarget(DAT)                             # 処理するデータを設定
    
    sqe.LoadXtalParam( "XtalParam.xml" )           # XtalParamを読み込む
    sqe.Projection()                               # XtalParamの情報で射影計算を実行
    
    ## Slicing
    sqe.Slice()                                    # XtalParamの情報でスライス実行
    eca=Manyo.ElementContainerArray()              # 空のコンテナを準備
    sqe.SetSlicedElementContainerArray(eca)        # コンテナにスライス結果をコピー
    
    ## Plot sliced data
    import vis.M2Plot as mp
    p=mp.M2Plot(eca)                               # M2Plotでそのまま表示


----

-----------------------------
UtsusemiSqeCalcリファレンス
-----------------------------
以下に **UtsusemiSqeCalc** で使用できるコマンド（メソッド）のうち、主要なものを示す。

.. py:class:: UtsusemiSqeCal
    
    データリダクション処理済みのデータを与えて、試料及び測定情報（格子定数、ビームに対する方位情報）を与えることでQ空間への射影処理を行い、射影後のデータのスライスまで行うクラスである。


.. py:method:: UtsusemiSqeCalc.SetTarget( ecm )
    
    処理を行うデータを与える
    
    :param ElementContainerMatrix ecm: 処理を行う非弾性散乱データ。
    :return: None
    :rtype: None

.. py:method:: UtsusemiSqeCalc.SetLatticeConstants( latticeConstants )
    
    格子定数を与える
    
    :param list latticeConstants: 格子定数 [ a, b, c, α, β, γ ]
    :return: 成功か否か
    :rtype: bool

.. py:method:: UtsusemiSqeCalc.SetUVvector( uv, vv )
    
    結晶の方位を決める U-vector と V-vectorを与える
    
    :param list uv: U-vector [ uv_x, uv_y, uv_z ]
    :param list vv: V-vector [ vv_x, vv_y, vv_z ]
    :return: 成功か否か
    :rtype: bool

.. py:method:: UtsusemiSqeCalc.SetRotationSteps( steps )
    
    実際の試料セッティングに合わせて、与えられた結晶の方位 U-vector と V-vectorを回転させる軸と角度を与える。
    軸は、"X", "Y", "Z"、角度は、軸:角度　（デリミタはコロン）。複数の回転角を与える場合はカンマ区切りで並べる。
    
    例：
    
    +------------------------+-------------+
    |Y軸周りに-5度           | Y:-5        |
    +------------------------+-------------+
    |Z軸周りに10度           | Z:10.0      |
    +------------------------+-------------+
    |上の両方（カンマ区切り）| Y:-5,Z:10.0 |
    +------------------------+-------------+
    
    :param str steps: 角度と方位
    :return: 成功か否か
    :rtype: bool

.. py:method:: UtsusemiSqeCalc.Projection( ax1, ax2, ax3, ax4 )
    
    射影に使用する軸を指定する。3つのQ軸( ax1, ax2, ax3 )と、1つのエネルギー軸( ax4 )で構成され、それぞれの軸を格子定数の a, b, c, Energy のベクトルと、ラベルの5つの要素を持つリストで与える。
    
    例：
    
    ax1 = [ 1.0, 0.0, 0.0, 0.0, "Qa(rlu)" ]
    
    ax4 = [ 0.0, 0.0, 0.0, 1.0, "Energy(meV)" ]
    
    
    :param list ax1: ax1軸の指定
    :param list ax2: ax2軸の指定
    :param list ax3: ax3軸の指定
    :param list ax4: ax4軸の指定
    :return: 成功か否か
    :rtype: bool

.. py:method:: UtsusemiSqeCalc.Projection()
    
    LoadXtalParamなどで、すでに登録済みの射影情報を用いて射影を行う。
    
    :return: 成功か否か
    :rtype: bool

.. py:method:: UtsusemiSqeCalc.SaveXtalParam( filepath )
    
    試料情報や射影情報をファイルに保存する（XtalParam.xml）。
    
    :param str filepath: XtalParam.xmlのパス
    :return: 成功か否か
    :rtype: bool

.. py:method:: UtsusemiSqeCalc.LoadXtalParam( filepath )
    
    試料情報や射影情報を保存されたファイル（XtalParam.xml）から読み込む。
    
    :param str filepath: XtalParam.xmlのパス
    :return: 成功か否か
    :rtype: bool

.. py:method:: UtsusemiSqeCalc.PutQRange()
    
    射影されたデータのQの最大範囲を取り出す。戻り値は サイズが8のvector<Double> となり、
    
    [ Ax1の最小値, Ax1の最大値, Ax2の最小値, ... , Ax4の最大値 ]
    
    という形になる。
    
    :return: Qの最大範囲
    :rtype: vector<Double>

.. py:method:: UtsusemiSqeCalc.Slice( ax1_info, ax2_info, ax3_info, ax4_info, folding_info[, isAve=True])
    
    射影されたデータを与える軸情報でスライスする。それぞれの軸で、以下のようなフォーマットで軸情報を与える
    
    **[ "A", min, max, (width) ]**
    
    +-----+------+----------------------------------------------------+
    |要素 |タイプ|説明                                                |
    +=====+======+====================================================+
    |"A"  |str   |軸の役割, X軸なら"X"、Y軸なら"Y"、Thickness軸なら"T"|
    +-----+------+----------------------------------------------------+
    |min  |float |範囲の最小値                                        |
    +-----+------+----------------------------------------------------+
    |max  |float |範囲の最大値                                        |
    +-----+------+----------------------------------------------------+
    |width|float |bin幅、ただしAが"X"か"Y"の時のみ有効                |
    +-----+------+----------------------------------------------------+
    
    例：
    
    +----------------------+------------------------+
    |X軸方向は長さ4のリスト|[ "X", -1.8, 2.6, 0.02 ]|
    +----------------------+------------------------+
    |T軸方向は長さ3のリスト|[ "T", -0.1, 0.1 ]      |
    +----------------------+------------------------+
    
    また畳み込みを行う場合は
    
    [ ax1_fold, ax2_fold, ax3_fold, ax4_fold ]
    
    ax1_foldなどには、以下のような数値を入れる。
    
    +---+--------------------+
    |-1 |（負の値）使用しない|
    +---+--------------------+
    |0.0|その軸=0で折りたたむ|
    +---+--------------------+
    |x  |その軸=xで折りたたむ|
    +---+--------------------+
    
    :param list ax1_info: Ax1軸の情報
    :param list ax2_info: Ax2軸の情報
    :param list ax3_info: Ax3軸の情報
    :param list ax4_info: Ax4軸の情報
    :param list folding_info: 畳み込み情報
    :param bool isAve: スライス時の強度は平均値とするか(True)、積算するか(False)
    :return: 成功か否か
    :rtype: bool

.. py:method:: UtsusemiSqeCalc.Slice([isAve=True])
    
    すでに与えられた軸情報を用いて、射影されたデータをスライスする
    
    :param bool isAve: スライス時の強度は平均値とするか(True)、積算するか(False)
    :return: 成功か否か
    :rtype: bool


.. |fig01| image:: media/CuiForINS_VisContM01.png
    :width: 300px