====== xrayUtilities の準備 ======

python のライブラリとして提供されているxrayUtiliesを使用するための環境構築の方法の一例を紹介しています。
xrayUtilities を使いたいと思っていて、もしまだ xrayUtilities を使う準備が整っていなかったら、ここの記述を参考に準備して下さい。

===== - CUI 環境の導入または確認 =====

ここでは以下の python を使うための準備や、
実際に python で書かれたプログラムを実行するのは
CUI (Character User Interface, 文字列でコマンド等を指定して実行するユーザーインターフェイス) から行うことを想定しています。
Windows なら PowerShell (もしくは cmd), Linux なら sh / csh / bash 等、Mac なら Terminal を開いて動いているシェル... を使うのが普通だと思います。

自分の環境でこうしたものが使えることを確認し、もし無い、あるいは他のものが良い、という場合にはそれをインストールするなど準備をする必要があります
(Windows については、[[https://git-scm.com/install/|git-bash]] の使用が一案です)。

===== - 作業場所(フォルダ/ディレクトリ)の作成 =====

まず最初に作業場所を作って、xrayUtilities を使って作業する時のプログラムファイルや結果を記録したファイル、この後説明する「仮想環境」の設定を保持するホルダなどを
まとめておいておけるようにするのがおすすめです。
Windows ならファイルエクスプローラを使って「新規フォルダ」を作っても構いません。Windows も含めて一般に、CUI の中でコマンドを使って作成しても構いません。
CUI から作成するなら

  > mkdir [作業場所の名前]

とすれば大丈夫です。例えば xrayUtilsWork という名前にするなら

  > mkdir xrayUtilsWork

です。
場所を作ったら、「その場所に移動」して作業することになります。
CUI 上で

  > cd xrayUtilsWork

とすると移動できるはずです。
このほか CUI で「どこにいるか確認する」「ファイルの場所を移動する」「その場所にあるファイルを確認する」「ファイルを消す」...については
簡単に調べられますので web で検索してみて下さい。ファイルやフォルダの操作(作ったり消したり移動したり)は、Windows なら エクスプローラで行っても構いません。  

===== - python の導入または確認 =====

<summary> python 導入済みなら不要です </summary>
xrayUtilities は python のライブラリなので、python が使える環境が必要です。
それぞれの環境に応じてインストールして下さい。
すでにインストールされている場合、そのバージョンによっては不具合が出るかもしれません。
この文章を書いている時点では 3.11 で動作を確認しています。

python を起動する際の名前はそのバージョンに応じて変わる可能性が有ります
(python3.11 とか、python3.12 とか)。\\
以下では python の**<color #ed1c24>起動コマンドを常に python3 と書きます</color>**が、
これは適宜自分の環境での起動コマンド名に読み替えて下さい。


===== - 仮想環境の準備 =====

仮想環境は必須では無いですが準備して使用されることを強くお勧めします。

仮想環境を準備するなら、先に作った作業場所(xrayUtilsWork とか)の中で以下のコマンドを実行します。

  > python3 -m venv xuEnv

  * 「> python3 ...」のように、先頭に「>」を付けて書いた時は、CUI 環境内で「python3 ...」と入力して最後に「Enter」キーを押すことを意味します。
  * 「-m venv」はpythonに「仮想環境を作る」ことを指示するコマンドです。
  * 「xuEnv」は、仮想環境の名前です。好きに決めて構いません。
  * これを実行すると、実行したその場所に xuEnv という名前の(自分が付けた名前の)フォルダ/ディレクトリができます。\\
    ですので、元々その場所にあるフォルダと同じ名前を指定することはできないことも注意して下さい。

python やそのライブラリは、依存関係が強く、
その際に特定のバージョン(以上)のバージョンのライブラリやパッケージ、ツール類を要求されることも多いです。
一つの目的のためだけに準備しているのなら、その目的に必要なものを入れればいいので問題ないのですが、
昨今、python は様々な場面で利用されるので、「他の目的のために使用しようとしたら、
同じライブラリに対して求められているバージョンが異なっていて両立しない」ということが起こりえます(まま起こります)。

また、python にはバージョン管理ツールが複数あって、「このパッケージはこのツール(例えば pip, 例えば conda)でないと入らない」ということがたまにあります。
ここでは xrayUtilities を pip で入れる説明をしますので、これが自分が使っているバージョン管理ツールと干渉して困るということも起こりえます。

これに対して「仮想環境」を準備して、ライブラリ類をインストールすると、
その時にインストールしたものはその仮想環境内にいるときだけ認識されるので他の仮想環境で導入したものとの干渉を避けることができます
((但し、仮想環境に入っていない時にインストールしたものは、どの仮想環境に入っていても共通で認識されます。便利なときも、問題になるときも有りますので要注意です))。

===== - 仮想環境の起動(仮想環境に入る) =====

仮想環境を使うなら次の手順が必須です

準備の操作でできた xuEnv というフォルダ/ディレクトリの中には bin というフォルダ/ディレクトリが有り、
その中に仮想環境を起動するためのスクリプトファイルはここに置かれています。
このスクリプトを動かすと仮想環境に入れます。
但し、自分が使っている CUI がどんなものかによって起動スクリプトとその起動の仕方は変わります
((  * もしかすると「bin」は「Scripts」かも
  * ファイル名の区切りは、OS や CUI に依存して変わります。ここでは '\' (バックスラッシュ)にしていますが、'/' かもしれません。
  * Windows で、ps1 ファイルが動かないと言われたときには設定で ps1 を実行できないようなっているかもしれません。
    ps1 の実行を一時的に許可するなら次のように入力して下さい。

  > Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass

  * ps1 の実行を今後ずっと許可してもいいと思うなら次のようにして下さい。

  > Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned
))。

CUI の中で、仮想環境(ここでは xuEnv)を作ったときと同じフォルダ/ディレクトリ(ここでは xrayUtilsWork)にいるものとして、

PowerShellを使うなら
  > xuEnv\bin\Activate.ps1

sh / bash 等(いわゆる b-shell 系の shell)を使うなら
  > source xuEnv\bin\activate

csh / tcsh 等(いわゆる c-shell 系の shell)を使うなら
  > source xuEnv\bin\activate.csh

正しく実行できると、コマンド入力行の「>」より前(通常「プロンプト」と呼びます)の表示の先頭に、仮想環境の名前が入って例えば次のようになります。

  (xuEnv)tabuchi> 

こうなったら成功で、以降、この表示がある行で入力したコマンドは(パッケージ類のインストールの操作も含めて)仮想環境の中で実行したことになります。

===== - xrayUtilities のインストール =====

公式 web ページから持ってきてインストールすることもできますが、
依存関係等の問題等を避けるために python のパッケージ管理(ここでは pip)に任せて導入することをお勧めします。

  (xuEnv)...> pip install xrayUtilities

とするだけです。
  
===== - xrayUtilities を実行する時必要になるパッケージのインストール =====

大半は xrayUtilities のインストールの時に一緒に入ると思います。
もし足りなくて、あとでこのページの「使用例」を実行してみて動かなかったら、
足りないものはエラーメッセージに書かれているはずです。それを pip でインストールして下さい。

例えば
  (xuEnv)...> pip install numpy matplotlib
などとすることになります。
xrayUtilities が要求する、典型的なパッケージは、h5py, scipy, numpy, lmfit, matplotlib です。
これらを予め全部入れておくのも良いかもしれません。
  (xuEnv)...> pip install h5py scipy numpy lmfit matplotlib
すでに入っているモノがあったとしても無視されるだけなので問題ありません。

===== - テキストエディタの準備 =====

python のプログラムは、プレーンテキストと呼ばれるシンプルに文字だけが書かれたファイル(テキストファイル)の形で作成します。
そのためには何かテキストエディタを準備して作成/編集することになります。

これは、テキストエディタなら何でも構いません。Window 附属のメモ帳アプリの様な極めてシンプルなものでも全く問題ありません。
vscode 等の様な高機能のものを使うのも手です。
ただ、「普段あまりプログラムを書いたことはないが、xrayUtilities を触ってみるために導入する」ということだと、
高級すぎて(いろいろできすぎて)目がまわってしまうかもしれません。

===== - 書いたプログラムの実行 =====

ここまでの準備があると、自分でプログラムを書いたり、使用例をダウンロードしてそれを実行することができます。
CUI 環境の中で、実行したいプログラムがある場所に移動して、実行することになります。
例えば、ここで例として作った作業環境のフォルダ(xrayUtilsWork)の中です。

xrayUtilsWork 等に移動した後、そこにある、例えば、 example-01.py を実行するには

  (xuEnv)...> python3 example-01.py

と入力します。
xrayUtilities を使う時には、python のプログラムの中から、cif ファイル等のファイルを読もうとするときがあります。
その時には、プログラムの中にファイルがある場所を次のように正確に書くか、

  GaAs_2 = xu.materials.Crystal.fromCIF( "C:\Users\tabuchi\xrayUtilsWork\GaAs.cif" )

もしくは、python のプログラムを実行する場所(example-01.py がある場所)に一緒に置いておくようにして下さい。

==== - 後日再開する時 ====

しばらく作業して、一旦終了した後、後日再開する時には
「仮想環境の起動」だけ行えば十分です
(( xuEnv がある場所に移動して、スクリプトを起動する ))。

xrayUtilitis や関連パッケージ等は xuEnv の中にインストールされたままになっていますので
再インストールの作業は不要です。

仮想環境に入れたら、作業していた場所( xrayUtilsWork とか )に移動して、作業を再開して下さい。