以下は、draw_unit_cell.py プログラムのSphinx（MyST）でビルド可能なMarkdownドキュメントです。

# ``draw_unit_cell.py`` ドキュメント

## 概要

結晶学における単位格子を3Dで可視化する機能を提供します。

## 詳細説明

任意の格子定数と角度から単位格子の形状を計算し、``Matplotlib`` を使用して描画します。
基本ベクトル（``a``, ``b``, ``c``）の描画には、パースペクティブを考慮したカスタム3D矢印クラスを使用します。

## 使用方法

### 前提条件

このプログラムを実行するには、以下のPythonライブラリが必要です。

- ``numpy``
- ``matplotlib``

### インストール

これらのライブラリは ``pip`` を使用してインストールできます。

```bash
pip install numpy matplotlib

実行方法

プログラムはPythonインタープリタを使用して直接実行できます。

python draw_unit_cell.py

実行すると、指定された格子定数と角度に基づいた単位格子の3Dプロットが表示され、同時に unit_cell.png という画像ファイルが現在のディレクトリに保存されます。

引数

このプログラムはコマンドライン引数を定義していません。 描画される単位格子のパラメーターは、ソースコード内の main() 関数でハードコードされています。

コード解説

非標準ライブラリ

このプログラムは以下の非標準ライブラリを使用しています。

• numpy: 数値計算、特にベクトル演算や行列演算に使用されます。

• matplotlib: 2Dおよび3Dグラフィックのプロットに使用されます。mpl_toolkits.mplot3d は3Dプロット機能を提供します。

クラス

Arrow3D

Matplotlib の3Dプロットでカスタムの3D矢印を描画するためのクラス。

FancyArrowPatch を継承し、3D空間内の座標を2Dスクリーン座標に変換して描画することで、常に適切なパースペクティブで矢印が表示されるようにします。

__init__(self, xs, ys, zs, *args, **kwargs)

Arrow3D クラスのコンストラクタ。

• xs: list[float] または tuple[float]: 矢印のX座標のリストまたはタプル。

• ys: list[float] または tuple[float]: 矢印のY座標のリストまたはタプル。

• zs: list[float] または tuple[float]: 矢印のZ座標のリストまたはタプル。

• args: FancyArrowPatch に渡される追加の引数。

• kwargs: FancyArrowPatch に渡される追加のキーワード引数。

draw(self, renderer)

矢印をレンダリングします。

3D座標を2Dスクリーン座標に変換し、変換された座標を使用して矢印を描画します。

• renderer: matplotlib.backend_bases.RendererBase: Matplotlib のレンダラーオブジェクト。

• 戻り値: None

do_3d_projection(self, renderer=None)

3Dプロジェクションを実行し、矢印の深度を計算します。

3D座標を2Dスクリーン座標に変換し、Z軸方向の最小値（深度）を返すことで、3Dビューにおけるオブジェクトの描画順序を適切に管理します。

• renderer: matplotlib.backend_bases.RendererBase: Matplotlib のレンダラーオブジェクト（オプション）。

• 戻り値: numpy.float: 矢印のZ軸方向の最小値（深度）。

関数

draw_vector(ax, vec, color, label, fontsize)

3D空間にベクトルと対応するラベルを描画します。

Arrow3D クラスを利用して、原点から指定されたベクトルまでの矢印を描画し、ベクトルの先端にラベルを配置します。

• ax: matplotlib.axes.Axes: 3Dプロットの Axes オブジェクト。

• vec: numpy.ndarray: 描画するベクトルの3D座標（[x, y, z]）。

• color: str: 矢印とラベルの色。

• label: str: ベクトルに付けるラベル。

• fontsize: int: ラベルのフォントサイズ。

• 戻り値: None

lattice_vectors(a, b, c, alpha, beta, gamma)

格子定数と角度から基本格子ベクトルを計算します。

結晶学で用いられる格子定数 (a, b, c) と軸間角 (alpha, beta, gamma) を用いて、直交座標系における3つの基本格子ベクトル (va, vb, vc) を計算します。 cz の計算では、負の平方根を避けるための安全策が講じられています。

• a: float: 格子定数 a の長さ。

• b: float: 格子定数 b の長さ。

• c: float: 格子定数 c の長さ。

• alpha: float: b 軸と c 軸の間の角度（度数）。

• beta: float: a 軸と c 軸の間の角度（度数）。

• gamma: float: a 軸と b 軸の間の角度（度数）。

• 戻り値: tuple[numpy.ndarray, numpy.ndarray, numpy.ndarray]: 3つの基本格子ベクトル (va, vb, vc)。各ベクトルは [x, y, z] の形式の numpy.ndarray。

set_equal_aspect(ax, points)

3Dプロットのアスペクト比を均等に設定し、描画範囲を調整します。

描画される点の最大・最小座標に基づいて、X, Y, Z軸の表示範囲を同じにします。

• ax: matplotlib.axes.Axes: 3Dプロットの Axes オブジェクト。

• points: numpy.ndarray: 描画される全ての点のNumpy配列。形状は (N, 3)。

• 戻り値: None

draw_unit_cell_plot(a, b, c, alpha, beta, gamma, elev=5.90, azim=-67.55, fontsize=24, color='blue')

指定された格子定数と角度を持つ単位格子を3Dで描画します。

lattice_vectors() 関数を使用して基本格子ベクトルを計算し、それらから単位格子の8つの頂点を生成します。 その後、Matplotlib を用いて単位格子の辺、頂点、および基本格子ベクトルを3D空間に描画します。 この関数内で、Matplotlib の draw_event に接続されたハンドラが定義されており、インタラクティブにプロットの視点（elev と azim）を変更した際に、その角度をターミナルに出力します。これはプログラムの直接実行時にのみ意味を持つ機能です。

• a: float: 格子定数 a の長さ。

• b: float: 格子定数 b の長さ。

• c: float: 格子定数 c の長さ。

• alpha: float: b 軸と c 軸の間の角度（度数）。

• beta: float: a 軸と c 軸の間の角度（度数）。

• gamma: float: a 軸と b 軸の間の角度（度数）。

• elev: float: プロットの仰角（デフォルト: 5.90）。

• azim: float: プロットの方位角（デフォルト: -67.55）。

• fontsize: int: ラベルのフォントサイズ（デフォルト: 24）。

• color: str: ベクトルの色（デフォルト: 'blue'）。

• 戻り値: None

main()

メインの実行ルーチン。特定の格子定数で単位格子を描画します。

描画パラメーターを辞書 params に設定し、それらのパラメーターを使用して draw_unit_cell_plot() 関数を呼び出します。

• 戻り値: None

入出力

入力

• 内部的なパラメーター: プログラムは、main() 関数内で定義された以下のハードコードされたパラメーターを使用します。

  • 格子定数: a=5.0, b=5.5, c=4.5

  • 角度: alpha=80, beta=70, gamma=100

  • 描画視点: elev=5.90, azim=-67.55

  • フォントサイズ: fontsize=24

  • 色: color='blue'

出力

• 標準出力: プログラムの実行開始時に、設定された格子定数と角度がターミナルに表示されます。 例:

  Drawing unit cell with a=5.0, b=5.5, c=4.5
  Angles: alpha=80, beta=70, gamma=100
  

  また、描画ウィンドウがインタラクティブに操作された場合、現在の elev と azim の値がターミナルに出力されます。

• 画像ファイル: 現在のディレクトリに unit_cell.png という名前のPNG画像ファイルが保存されます。このファイルには描画された単位格子の3Dプロットが含まれます。解像度は300 dpiで、背景は透明です。

• グラフィカルウィンドウ: Matplotlib によって生成された3Dプロットが表示されるインタラクティブなウィンドウが表示されます。

エラーハンドリング

コードからは明示的なエラーハンドリング機構（try-except ブロックなど）は確認できません。 ただし、lattice_vectors() 関数において、cz の計算で np.sqrt(max(0, ...)) を使用することで、平方根の内部が負になることを防ぐ安全策が講じられています。

注意事項

コードからは特定の注意事項は確認できません。

ライセンス

コードからはライセンス情報は確認できません。