以下は、pvanalyze.py のソースコードを解析し、Sphinx (MyST) でビルド可能なMarkdownドキュメントです。

# ``pvanalyze.py`` のドキュメント

## ファイル概要

``pvanalyze.py`` は、太陽電池の電気的・光学的特性を評価するためのツールスクリプトです。

**概要:**
太陽電池の電気的・光学的特性を評価するツールです。

**詳細説明:**
`mode=alpha` または `mode=make_alpha` では、反射率と透過率のスペクトルから吸収スペクトルを計算し、プロットおよびExcelへの保存を行います。
`mode=analyze` では、`I-V` データからパラメータ推定、発電特性解析、量子効率計算、および結果のプロットを行います。

**主な機能:**
- 反射率/透過率から吸収スペクトルの計算と保存
- `I-V` データからの太陽電池パラメータ (`I0`, `ndiode`, `IPV`, `Rs`, `Rsh`) 推定
- 発電特性 (`Voc`, `Jsc`, `FF`, `Pmax` など) の解析
- 量子効率 (`EQE`, `IQE`) の計算
- 解析結果のプロットとExcelファイルへの保存

**関連リンク:**
`pvanalyze_usage`

## インポートされているライブラリ

### 標準ライブラリ
- `sys`: システム固有のパラメータと関数を提供します。
- `argparse`: コマンドライン引数をパースするためのモジュールです。
- `builtins`: Pythonの組み込み関数へのアクセスを提供します。
- `pathlib.Path`: ファイルパスをオブジェクト指向で操作するためのモジュールです。
- `traceback`: 例外が発生した際のトレースバック情報を取得・整形するためのモジュールです。
- `csv`: `CSV` (Comma Separated Values) ファイルを読み書きするためのモジュールです。
- `math`: 数学関数へのアクセスを提供します。

### 非標準ライブラリ
- `matplotlib.pyplot`: グラフの描画に使用されます。
- `numpy`: 数値計算、特に配列操作に使用されます。
- `openpyxl.Workbook`: 新しいExcelワークブックを作成します。
- `openpyxl.load_workbook`: 既存のExcelワークブックを読み込みます。
- `openpyxl.styles.Font`: Excelセルのフォントスタイルを定義します。
- `openpyxl.styles.PatternFill`: Excelセルの塗りつぶしパターンを定義します。

## グローバル定数とデフォルト値

このプログラムで使用される主要な物理定数、デフォルトパラメータ、およびファイル名。

- `KB` (float): ボルツマン定数 (`1.380649e-23`).
- `E_CHARGE` (float): 素電荷 (`1.602176634e-19`).
- `H` (float): プランク定数 (`6.62607015e-34`).
- `C` (float): 光速 (`2.99792458e8`).
- `PARAM_NAMES` (list[str]): 推定されるパラメータ名のリスト (`["I0", "ndiode", "IPV", "Rs", "Rsh"]`).
- `EPS_I` (float): 電流の数値的安定性のための小さな値 (`1.0e-15`).
- `DPV_NM` (float): `PV` 層のデフォルト膜厚 (nm) (`46.837`). CLIオプション `--d` のデフォルト値。
- `AREA_MM2` (float): デフォルトの面積 (mm^2) (`0.5 * 0.5 * math.pi`).
- `AREA_CM2` (float): デフォルトの面積 (cm^2) (`AREA_MM2 * 0.01`). CLIオプション `--S` のデフォルト値。
- `PHOTON_FLUX` (float): デフォルトの入射フォトンフラックス (cm^-2 s^-1) (`1.95804e18`). CLIオプション `--F0` のデフォルト値。
- `PHOTON_NM` (float): デフォルトのフォトン波長 (nm) (`1363.0`). CLIオプション `--lambda_nm` のデフォルト値。
- `PIN` (str): 入射フォトンエネルギー密度 (`W/cm^2`). コード上はデフォルトで空文字列 (`""`)。CLIオプション `--P0` のデフォルト値。
- `fontsize` (int): グラフ描画に使用されるフォントサイズ (`16`).
- `DARK_IV_FILE` (str): 暗電流 `I-V` ファイルのデフォルト名 (`"I_V SweepTest SMU1 [(1) ; 2026_03_24 14_15_24]-SY251213-1-LD0.0V.csv"`). CLIオプション `--dark` のデフォルト値。
- `PV_IV_FILE` (str): 光照射 `I-V` ファイルのデフォルト名 (`"I_V SweepTest SMU1 [(10) ; 2026_03_24 14_18_37]-SY251213-1-LD1.8V.csv"`). CLIオプション `--light` のデフォルト値。
- `R_FILE` (str): 反射スペクトルファイルのデフォルト名 (`"SY251024-1-Bi4O6S21-STO001-225oC-10mJ_R(UDS).txt"`). CLIオプション `--R` のデフォルト値。
- `T_FILE` (str): 透過スペクトルファイルのデフォルト名 (`"SY251024-1-Bi4O6S21-STO001-225oC-10mJ_T(UDS).txt"`). CLIオプション `--Tr` のデフォルト値。
- `ALPHA_FILE` (str): 吸収スペクトルExcelファイルのデフォルト名 (`"alpha_Bi2OS2.xlsx"`). CLIオプション `--alpha` のデフォルト値。

## 関数定義

### `initialize()`
概要:
    コマンドライン引数を解析し、プログラムの初期設定を行います。

詳細説明:
    `argparse` モジュールを使用して、実行モード、ファイルパス、温度、膜厚などの
    パラメータを定義し、ユーザー入力から値をパースします。

:returns: 解析された引数オブジェクトと引数パーサーオブジェクトのタプル。
:rtype: tuple[argparse.Namespace, argparse.ArgumentParser]

### `print_args_and_derived(args, E_use=None, P0_use=None)`
概要:
    解析されたコマンドライン引数と派生値を標準出力に表示します。

:param args: 解析された引数オブジェクト。
:type args: argparse.Namespace
:param E_use: 使用されるフォトンエネルギー (`eV`)。
:type E_use: float or None
:param P0_use: 使用される入射光パワー密度 (`W/cm^2`)。
:type P0_use: float or None
:returns: なし

### `read_data(infile, xmin=None, xmax=None, ndataskip=0)`
概要:
    指定された`CSV`ファイルから`I-V`データを読み込みます。

詳細説明:
    ファイル内のメタデータ（記録時間、データ名）を抽出し、電圧と電流のデータポイントをパースします。
    複数のスイープを検出し、それぞれをリストに分割します。

:param infile: 読み込む`CSV`ファイルのパス。
:type infile: str
:param xmin: `X`軸（電圧）の最小値。これより小さい値はスキップされます。
:type xmin: float or None
:param xmax: `X`軸（電圧）の最大値。これより大きい値はスキップされます。
:type xmax: float or None
:param ndataskip: データポイントをスキップする間隔。0の場合、スキップしません。
:type ndataskip: int
:returns: 各スイープの`X`軸（電圧）データのリスト、各スイープの`Y`軸（電流）データのリスト、ファイルから抽出されたメタデータのタプル。
:rtype: tuple[list[numpy.ndarray], list[numpy.ndarray], dict]
:raises ValueError: ファイルから有効な`I-V`データが見つからない場合。

### `read_alpha_from_excel(infile)`
概要:
    Excelファイルから吸収スペクトル (`alpha`) データを読み込みます。

詳細説明:
    `save_alpha_to_excel` 関数によって保存された形式のExcelファイルを想定しています。
    `alpha_spectrum` シートから波長、`R`、`Tr`、`A`、`alpha` のデータを抽出します。

:param infile: 読み込むExcelファイルのパス。
:type infile: str
:returns: 波長、反射率、透過率、吸収率、吸収係数を含む辞書。
:rtype: dict
:raises ValueError: 指定されたExcelファイルに`'alpha_spectrum'`シートが見つからない場合。
:raises ValueError: ファイルから数値の吸収スペクトルデータが見つからない場合。

### `read_optical_spectrum(infile)`
概要:
    指定されたテキストファイルから光学スペクトルデータ（反射率`R`または透過率`T`）を読み込みます。

詳細説明:
    ファイル内のタブ区切りまたはスペース区切りのデータをパースし、
    波長とスペクトル値のペアを抽出します。
    重複する波長を処理し、波長順にソートします。

:param infile: 読み込む光学スペクトルファイルのパス。
:type infile: str
:returns: 波長 (`nm`) の `numpy.ndarray`、スペクトル値 (`R`または`T`のパーセンテージ) の `numpy.ndarray`、
          ファイルから抽出されたメタデータを含む辞書のタプル。
:rtype: tuple[numpy.ndarray, numpy.ndarray, dict]
:raises RuntimeError: ファイルの読み込みに失敗した場合。
:raises ValueError: ファイルから数値のスペクトルデータが見つからない場合。

### `choose_sweep(xs_list, ys_list, sweep_index=0)`
概要:
    複数のスイープデータから指定されたインデックスの単一スイープを選択します。

:param xs_list: 各スイープの`X`軸（電圧）データのリスト。
:type xs_list: list[numpy.ndarray]
:param ys_list: 各スイープの`Y`軸（電流）データのリスト。
:type ys_list: list[numpy.ndarray]
:param sweep_index: 選択するスイープのインデックス。
:type sweep_index: int
:returns: 選択されたスイープの`X`軸データと`Y`軸データ。
:rtype: tuple[numpy.ndarray, numpy.ndarray]
:raises ValueError: スイープデータが利用できない場合。
:raises IndexError: `sweep_index` が範囲外の場合。

### `consolidate_duplicate_x(x, y)`
概要:
    `X`軸に重複する値がある場合、`Y`軸の対応する値を平均して重複を解消します。

:param x: `X`軸データ。
:type x: numpy.ndarray
:param y: `Y`軸データ。
:type y: numpy.ndarray
:returns: 重複が解消された`X`軸データと、重複が解消され平均化された`Y`軸データ。
:rtype: tuple[numpy.ndarray, numpy.ndarray]

### `smooth_polyfit(y, window_points=5, poly_order=3)`
概要:
    多項式フィッティングを用いたSavitzky-Golay風の平滑化をデータに適用します。

詳細説明:
    各データポイントを中心に指定されたウィンドウ内のデータに対して多項式フィッティングを行い、
    中心点の値を予測することで平滑化を行います。

:param y: 平滑化する`Y`軸データ。
:type y: numpy.ndarray
:param window_points: フィッティングに使用するウィンドウ内のデータポイント数。奇数である必要があります。
:type window_points: int
:param poly_order: 多項式フィッティングの次数。
:type poly_order: int
:returns: 平滑化された`Y`軸データ。
:rtype: numpy.ndarray

### `local_poly_value(x, y, x0, npts=7, order=3)`
概要:
    指定された`X`座標の周囲のデータポイントを使用して、局所的な多項式フィッティングを行い、
    `x0`における`Y`値を推定します。

:param x: `X`軸データ。
:type x: numpy.ndarray
:param y: `Y`軸データ。
:type y: numpy.ndarray
:param x0: `Y`値を推定する`X`座標。
:type x0: float
:param npts: フィッティングに使用するデータポイント数。
:type npts: int
:param order: 多項式フィッティングの次数。
:type order: int
:returns: `x0`における推定された`Y`値。
:rtype: float

### `zero_crossing_x(x, y)`
概要:
    `Y`値がゼロを横切る`X`座標を線形補間によって見つけます。

詳細説明:
    2つの連続するデータポイントの間で`Y`値の符号が変わる点、
    または`Y`値が最もゼロに近い点の`X`座標を返します。

:param x: `X`軸データ。
:type x: numpy.ndarray
:param y: `Y`軸データ。
:type y: numpy.ndarray
:returns: `Y`値がゼロを横切る`X`座標。
:rtype: float

### `interpolate_to_common_wavelength(wl_ref, y_ref, wl_target)`
概要:
    参照波長スケール上のデータをターゲット波長スケールに線形補間します。

:param wl_ref: 参照波長データ (`nm`)。
:type wl_ref: numpy.ndarray
:param y_ref: 参照`Y`軸データ。
:type y_ref: numpy.ndarray
:param wl_target: 補間対象のターゲット波長データ (`nm`)。
:type wl_target: numpy.ndarray
:returns: ターゲット波長スケールに補間された`Y`軸データ。
:rtype: numpy.ndarray

### `compute_photon_energy_eV(E_eV, lambda_nm)`
概要:
    フォトンエネルギー（`eV`）を計算します。

詳細説明:
    フォトンエネルギーが直接与えられている場合はそれを使用し、
    そうでない場合は波長から計算します。

:param E_eV: フォトンエネルギー (`eV`)。0より大きい場合はこれを使用。
:type E_eV: float
:param lambda_nm: フォトン波長 (`nm`)。`E_eV` が0の場合にこれを使用。
:type lambda_nm: float
:returns: 計算されたフォトンエネルギー (`eV`)。
:rtype: float

### `compute_p0(F0, P0, E_eV, lambda_nm)`
概要:
    入射フォトンエネルギー密度（`P0`）を計算します。

詳細説明:
    入射フォトンフラックス（`F0`）が与えられている場合はそれから計算し、
    そうでない場合は直接指定された`P0`を使用します。

:param F0: 入射フォトンフラックス (`cm^-2 s^-1`)。`None`または0の場合は`P0`を使用。
:type F0: float or None
:param P0: 入射フォトンエネルギー密度 (`W/cm^2`)。`None`または空文字列の場合は`F0`から計算。
:type P0: float or None
:param E_eV: フォトンエネルギー (`eV`)。`F0`から`P0`を計算する場合に使用。
:type E_eV: float
:param lambda_nm: フォトン波長 (`nm`)。`F0`から`P0`を計算する場合に使用。
:type lambda_nm: float
:returns: 計算された入射フォトンエネルギー密度 (`W/cm^2`)。
:rtype: float or None

### `pv_metrics_from_iv(V, I, S)`
概要:
    `I-V`データから太陽電池の主要な性能指標（`Voc`, `Jsc`, `FF`, `Pmax`など）を計算します。

:param V: 電圧データ (`V`)。
:type V: numpy.ndarray
:param I: 電流データ (`A`)。
:type I: numpy.ndarray
:param S: 電極面積 (`cm^2`)。
:type S: float
:returns: 以下の主要な太陽電池性能指標を含む辞書。
    - `Voc_V` (float): 開放電圧 (`V`)。
    - `Jsc_A_cm2` (float): 短絡電流密度 (`A/cm^2`)。
    - `Jsc_mA_cm2` (float): 短絡電流密度 (`mA/cm^2`)。
    - `Vop_V` (float): 最大出力動作電圧 (`V`)。
    - `Jop_A_cm2` (float): 最大出力動作電流密度 (`A/cm^2`)。
    - `Jop_mA_cm2` (float): 最大出力動作電流密度 (`mA/cm^2`)。
    - `Pmax_W_cm2` (float): 最大出力電力密度 (`W/cm^2`)。
    - `Pmax_mW_cm2` (float): 最大出力電力密度 (`mW/cm^2`)。
    - `FF` (float): 曲線因子。
:rtype: dict

### `fit_local_line(x, y, center_idx, npts=7)`
概要:
    指定された中心インデックスの周囲のデータポイントを用いて局所的な線形フィッティングを行います。

:param x: `X`軸データ。
:type x: numpy.ndarray
:param y: `Y`軸データ。
:type y: numpy.ndarray
:param center_idx: フィッティングの中心となるデータポイントのインデックス。
:type center_idx: int
:param npts: フィッティングに使用するデータポイント数。
:type npts: int
:returns: フィットされた直線の傾き、`Y`切片、フィッティングに使用された`X`データ、
          `Y`データ、開始インデックス、終了インデックス（排他的）のタプル。
:rtype: tuple[float, float, numpy.ndarray, numpy.ndarray, int, int]

### `estimate_rs_tangent_point(V, I)`
概要:
    `I-V`曲線から直列抵抗（`Rs`）を推定するための接点と抵抗値を計算します。

詳細説明:
    順方向バイアス領域で`dI/dV`が最大となる点を特定し、その点での接線から`Rs`を計算します。

:param V: 電圧データ (`V`)。
:type V: numpy.ndarray
:param I: 電流データ (`A`)。
:type I: numpy.ndarray
:returns: 直列抵抗推定に関する情報を含む辞書。
    - `v_rep` (float): 接点電圧 (`V`)。
    - `i_rep` (float): 接点電流 (`A`) (互換性のため)。
    - `Is` (float): 接点電流 (`A`) (互換性のため)。
    - `Rs` (float): 推定された直列抵抗 (`Ω`)。
    - `slope` (float): 接線の傾き (`A/V`)。
    - `intercept` (float): 接線の`Y`切片 (`A`)。
    - `xx` (numpy.ndarray): 接線フィッティングに使用された`X`データ。
    - `yy` (numpy.ndarray): 接線フィッティングに使用された`Y`データ。
    - `idx` (int): 接点のインデックス。
:rtype: dict

### `estimate_rsh_tangent_point(V, I)`
概要:
    `I-V`曲線から並列抵抗（`Rsh`）を推定するための接点と抵抗値を計算します。

詳細説明:
    逆方向バイアス領域で`dI/dV`が最小となる点（絶対値）を特定し、
    その点での接線から`Rsh`を計算します。

:param V: 電圧データ (`V`)。
:type V: numpy.ndarray
:param I: 電流データ (`A`)。
:type I: numpy.ndarray
:returns: 並列抵抗推定に関する情報を含む辞書。
    - `v_rep` (float): 接点電圧 (`V`)。
    - `i_rep` (float): 接点電流 (`A`) (互換性のため)。
    - `Ish` (float): 接点電流 (`A`) (互換性のため)。
    - `Rsh` (float): 推定された並列抵抗 (`Ω`)。
    - `slope` (float): 接線の傾きの絶対値 (`A/V`)。
    - `intercept` (float): 接線の`Y`切片 (`A`)。
    - `slope_fit_raw` (float): フィットされた直線の元の傾き (`A/V`)。
    - `intercept_fit_raw` (float): フィットされた直線の元の`Y`切片 (`A`)。
    - `xx` (numpy.ndarray): 接線フィッティングに使用された`X`データ。
    - `yy` (numpy.ndarray): 接線フィッティングに使用された`Y`データ。
    - `idx` (int): 接点のインデックス。
:rtype: dict

### `estimate_ndiode_representative_point(V, I, T=300.0, Ish=None)`
概要:
    `I-V`曲線からダイオード因子（`ndiode`）を推定するための代表点と値を計算します。

詳細説明:
    順方向バイアス領域で`log(abs(I))`の二階微分が最小となる点を特定し、
    その点での一次微分からダイオード因子を計算します。

:param V: 電圧データ (`V`)。
:type V: numpy.ndarray
:param I: 電流データ (`A`)。
:type I: numpy.ndarray
:param T: 温度 (`K`)。
:type T: float
:param Ish: 並列抵抗に流れる電流の推定値。これを考慮して`I`を調整します。
:type Ish: float or None
:returns: ダイオード因子推定に関する情報を含む辞書。計算できなかった場合は`None`。
    - `v_rep` (float): 代表点電圧 (`V`)。
    - `ndiode` (float): 推定されたダイオード因子。
    - `slope_logI` (float): 代表点での`log(abs(I))`の傾き (`1/V`)。
    - `curvature_logI` (float): 代表点での`log(abs(I))`の二階微分 (`1/V^2`)。
:rtype: dict or None

### `estimate_initial_params(V, I_meas, T=300.0)`
概要:
    `I-V`データから単一ダイオードモデルの初期パラメータ（`I0`, `ndiode`, `IPV`, `Rs`, `Rsh`）を推定します。

詳細説明:
    `estimate_rs_tangent_point`、`estimate_rsh_tangent_point`、
    `estimate_ndiode_representative_point` などの補助関数を用いて、
    各パラメータの初期値を経験的に決定します。

:param V: 電圧データ (`V`)。
:type V: numpy.ndarray
:param I_meas: 測定電流データ (`A`)。
:type I_meas: numpy.ndarray
:param T: 温度 (`K`)。
:type T: float
:returns: 推定された初期パラメータを含む辞書。
    - `I0` (float): 逆方向飽和電流 (`A`)。
    - `ndiode` (float): ダイオード因子。
    - `IPV` (float): 光電流 (`A`)。
    - `Rs` (float): 直列抵抗 (`Ω`)。
    - `Rsh` (float): 並列抵抗 (`Ω`)。
    - `Ish` (float): 並列抵抗に流れる電流 (`A`)。
    - `Vsh` (float): `Rsh` 推定における代表点電圧 (`V`)。
    - `Vnd` (float): `ndiode` 推定における代表点電圧 (`V`)。
:rtype: dict

### `analyze_optical(wl_R_nm, R_percent, wl_T_nm, T_percent, d_nm)`
概要:
    反射率（`R`）と透過率（`T`）のスペクトルデータから吸収率（`A`）と吸収係数（`α`）を計算します。

詳細説明:
    異なる波長スケールの`R`と`T`を共通の波長スケールに補間し、
    `R`と`T`のデータに基づいて`A`と`α`を計算します。

:param wl_R_nm: 反射率スペクトルの波長データ (`nm`)。
:type wl_R_nm: numpy.ndarray
:param R_percent: 反射率データ (`%`)。
:type R_percent: numpy.ndarray
:param wl_T_nm: 透過率スペクトルの波長データ (`nm`)。
:type wl_T_nm: numpy.ndarray
:param T_percent: 透過率データ (`%`)。
:type T_percent: numpy.ndarray
:param d_nm: `PV`層の膜厚 (`nm`)。
:type d_nm: float
:returns: 計算された光学特性値を含む辞書。
    - `wl_nm` (numpy.ndarray): 共通波長データ (`nm`)。
    - `R` (numpy.ndarray): 反射率 (`0-1`)。
    - `Tr` (numpy.ndarray): 透過率 (`0-1`)。
    - `A` (numpy.ndarray): 吸収率 (`0-1`)。
    - `alpha_cm^-1` (numpy.ndarray): 吸収係数 (`cm^-1`)。
:rtype: dict

### `quantum_efficiencies(F0, A_abs, JPV_A_cm2, Jsc_A_cm2)`
概要:
    量子効率（`EQE`と`IQE`）を計算します。

詳細説明:
    入射フォトンフラックス、吸収率、光電流（`JPV`）、短絡電流密度（`Jsc`）に基づいて、
    生成効率と収集効率を評価します。

:param F0: 入射フォトンフラックス (`cm^-2 s^-1`)。`None`または0の場合は`NaN`を返します。
:type F0: float or None
:param A_abs: 特定のエネルギーにおける吸収率。`None`または`NaN`の場合は`IQE`を`NaN`とします。
:type A_abs: float or None
:param JPV_A_cm2: 光電流密度 (`A/cm^2`)。
:type JPV_A_cm2: float
:param Jsc_A_cm2: 短絡電流密度 (`A/cm^2`)。
:type Jsc_A_cm2: float
:returns: 計算された量子効率を含む辞書。
    - `EQE_gen` (float): 生成外部量子効率。
    - `IQE_gen` (float): 生成内部量子効率。
    - `EQE` (float): 外部量子効率。
    - `IQE` (float): 内部量子効率。
:rtype: dict

### `alpha_at_energy(optical, E_eV)`
概要:
    指定されたフォトンエネルギーにおける吸収係数（`α`）を光学スペクトルデータから補間して取得します。

:param optical: `analyze_optical` または `read_alpha_from_excel` から返された光学データ辞書。
:type optical: dict or None
:param E_eV: 取得したいフォトンエネルギー (`eV`)。
:type E_eV: float
:returns: 指定されたエネルギーにおける吸収係数 (`cm^-1`)。データがない場合は`NaN`。
:rtype: float
:raises ValueError: 補間された吸収係数が`NaN`の場合。

### `absorptance_from_alpha(alpha_cm, d_nm)`
概要:
    吸収係数と膜厚から吸収率を計算します。

詳細説明:
    `A = 1 - exp(-alpha * d)` の式を用いて計算します。

:param alpha_cm: 吸収係数 (`cm^-1`)。
:type alpha_cm: float or None
:param d_nm: `PV`層の膜厚 (`nm`)。
:type d_nm: float
:returns: 計算された吸収率。
:rtype: float
:raises ValueError: `alpha_cm` が`None`または無効な値の場合。

### `save_alpha_to_excel(optical, outfile_xlsx, meta=None)`
概要:
    吸収スペクトルデータをExcelファイルに保存します。

詳細説明:
    `alpha_spectrum` というシートにフォトンエネルギー、波長、`R`、`Tr`、`A`、`alpha` のデータを書き込みます。
    `summary` シートには膜厚やファイル名、平均値などのメタデータを保存します。

:param optical: `analyze_optical` 関数から返された光学データ辞書。
:type optical: dict
:param outfile_xlsx: 保存するExcelファイルのパス。
:type outfile_xlsx: str
:param meta: 保存する追加のメタデータ。
:type meta: dict or None
:returns: なし

### `plot_alpha(optical, outfile=None, pause=False)`
概要:
    吸収係数スペクトル（`α` vs フォトンエネルギー）をプロットします。

:param optical: `analyze_optical` 関数から返された光学データ辞書。
:type optical: dict
:param outfile: プロットを保存するファイルパス。`None`の場合、画面に表示します。
:type outfile: str or None
:param pause: プロットを閉じるまで一時停止するかどうか。`True`の場合、`plt.show()` を呼び出します。
:type pause: bool
:returns: 作成された`Matplotlib Figure`オブジェクト。
:rtype: matplotlib.figure.Figure

### `estimate_ndiode_curve(V, I, T=300.0)`
概要:
    `I-V`データから電圧に対するダイオード因子（`ndiode`）の曲線を推定します。

詳細説明:
    `log(abs(I))`の一次微分を計算し、それに基づいて各電圧点におけるダイオード因子を導出します。

:param V: 電圧データ (`V`)。
:type V: numpy.ndarray
:param I: 電流データ (`A`)。
:type I: numpy.ndarray
:param T: 温度 (`K`)。
:type T: float
:returns: ダイオード因子が計算された電圧データと、各電圧に対応する推定されたダイオード因子。
:rtype: tuple[numpy.ndarray, numpy.ndarray]

### `plot_iv_comparison(dark_sweeps, light_sweeps, S, light_metrics, dark_params=None, light_params=None, outfile=None, T=300.0, pause=False)`
概要:
    暗電流`I-V`および光照射`I-V`データと、関連する推定値や解析結果を比較プロットします。

詳細説明:
    以下の4つのサブプロットを作成します。

    - `log(abs(I))-V` 曲線（暗電流と光電流）。
    - 線形`J-V`曲線（順方向と逆方向）。`Rs`と`Rsh`の接線、`Ish(0)`点を表示。
    - `ndiode-V`曲線と代表点。
    - 光起電力出力（`-J` vs `V`）。`MPP`, `Voc`, `Jsc`点を表示。

:param dark_sweeps: 暗電流測定の`I-V`スイープデータのリスト。
:type dark_sweeps: list[tuple[numpy.ndarray, numpy.ndarray]]
:param light_sweeps: 光照射測定の`I-V`スイープデータのリスト。
:type light_sweeps: list[tuple[numpy.ndarray, numpy.ndarray]]
:param S: デバイスの面積 (`cm^2`)。
:type S: float
:param light_metrics: 光照射下の`I-V`データから計算された光起電力性能指標。
:type light_metrics: dict
:param dark_params: 暗電流`I-V`データから推定された初期パラメータ。`Rs`/`Rsh`の接線表示に使用。
:type dark_params: dict or None
:param light_params: 光照射`I-V`データから推定された初期パラメータ。`I0`/`IPV`の表示に使用。
:type light_params: dict or None
:param outfile: プロットを保存するファイルパス。`None`の場合、画面に表示します。
:type outfile: str or None
:param T: 温度 (`K`)。`ndiode`曲線の計算に使用。
:type T: float
:param pause: プロットを閉じるまで一時停止するかどうか。`True`の場合、`plt.show()` を呼び出します。
:type pause: bool
:returns: 作成された`Matplotlib Figure`オブジェクト。
:rtype: matplotlib.figure.Figure

### `exec_alpha(args)`
概要:
    `alpha`または`make_alpha`モードでプログラムを実行するメイン関数。

詳細説明:
    光学スペクトルファイル（`R`と`T`）を読み込み、吸収率と吸収係数を計算し、
    結果をプロットしてExcelファイルに保存します。

:param args: コマンドライン引数。
:type args: argparse.Namespace
:returns: なし

### `exec_analyze(args)`
概要:
    `analyze`モードでプログラムを実行するメイン関数。

詳細説明:
    暗電流および光照射`I-V`ファイルを読み込み、初期パラメータと光起電力性能指標を推定し、
    量子効率を計算します。光学データが利用可能な場合はそれも考慮に入れます。
    結果を標準出力に表示し、比較プロットを作成します。

:param args: コマンドライン引数。
:type args: argparse.Namespace
:returns: なし

### `dual_print(*args, **kwargs)`
概要:
    標準出力とログファイルの両方にメッセージを出力します。

詳細説明:
    通常の`print`関数の動作を模倣し、標準出力に加えて、
    `_redirect_fp`に設定されたファイルオブジェクトにも出力します。

:param args: `print`に渡される位置引数。
:type args: tuple
:param kwargs: `print`に渡されるキーワード引数。
:type kwargs: dict
:returns: なし

### `main()`
概要:
    プログラムのエントリーポイント。

詳細説明:
    コマンドライン引数を初期化し、指定されたモードに基づいて
    対応する実行関数を呼び出します。
    実行ログは自動的にファイルにリダイレクトされます。

:returns: なし

## スクリプトの実行方法

``pvanalyze.py`` は、コマンドラインから直接実行可能なスクリプトです。

### コマンドライン引数

- `--mode` (str): 実行モード。`"analyze"`, `"alpha"`, `"make_alpha"` のいずれか (`default: "analyze"`)。
- `--dark` (str): 暗電流 `I-V` `CSV` ファイルのパス (`default: DARK_IV_FILE` で指定された値)。
- `--light` (str): 光照射 `I-V` `CSV` ファイルのパス (`default: PV_IV_FILE` で指定された値)。
- `--R` (str): 反射率スペクトルファイルのパス (`default: R_FILE` で指定された値)。
- `--Tr` (str): 透過率スペクトルファイルのパス (`default: T_FILE` で指定された値)。
- `--eq` (str): 等価スペクトル放射照度ファイルのパス (`default: None`)。
- `--alpha` (str): 吸収スペクトル (`alpha`) のExcelファイルのパス (`default: ALPHA_FILE` で指定された値)。
- `--T` (float): 温度 (`K`) (`default: 300.0`)。
- `--d` (float): `PV`層の膜厚 (`nm`) (`default: DPV_NM` で指定された値)。
- `--sweep_dark` (int): 暗電流解析に使用するスイープのインデックス (`default: 0`)。
- `--sweep_light` (int): 光照射解析に使用するスイープのインデックス (`default: 0`)。
- `--F0` (float): 入射フォトンフラックス (`cm^-2 s^-1`) (`default: PHOTON_FLUX` で指定された値)。
- `--P0` (str): 入射フォトンエネルギー密度 (`W/cm^2`) (`default: PIN` で指定された値、空文字列)。
- `--E` (float): フォトンエネルギー (`eV`)。0の場合、`--lambda_nm` を使用 (`default: 0.0`)。
- `--lambda_nm` (float): フォトン波長 (`nm`)。`--E=0` の場合に使用 (`default: PHOTON_NM` で指定された値)。
- `--S` (float): 電極面積 (`cm^2`) (`default: AREA_CM2` で指定された値)。
- `--outprefix` (str): 出力ファイル名のプレフィックス (`default: "pvanalyze"`)。

### 実行例

#### `analyze` モード
```bash
python pvanalyze.py --mode analyze --dark dark_iv.csv --light light_iv.csv --alpha alpha.xlsx --T 300 --d 50 --S 0.25 --F0 1.9e18 --outprefix analysis_result

`make_alpha` モード

python pvanalyze.py --mode make_alpha --R reflectance.txt --Tr transmittance.txt --d 50 --outprefix alpha_spectrum

入出力仕様

このプログラムは、CSV、テキストファイル、Excelファイル、および画像ファイル (.png) を読み書きします。また、実行ログをテキストファイルに出力します。

入力ファイル

CSV I-V データファイル (.csv):
- read_data() 関数によって読み込まれます。
- MetaData, RecordTime, DataName, DataValue のヘッダーを持つCSV形式を想定しています。
- DataName の行には V と I の列名が含まれ、その後の DataValue の行に数値データ（電圧と電流）が続きます。
- 例: DARK_IV_FILE, PV_IV_FILE。
光学スペクトルデータファイル (.txt):
- read_optical_spectrum() 関数によって読み込まれます。
- 波長とスペクトル値（反射率 R または透過率 T）のペアがタブ区切りまたはスペース区切りで記述されたテキストファイルを想定しています。
- "%T" や "%R" の表記から単位を推測するロジックが含まれます。
- 例: R_FILE, T_FILE。
吸収スペクトルExcelファイル (.xlsx):
- read_alpha_from_excel() 関数によって読み込まれます。
- alpha_spectrum という名前のシートに、photon_energy_eV, wavelength_nm, R, Tr, A, alpha_cm^-1 の列を持つデータを想定しています。
- このファイル形式は、save_alpha_to_excel() 関数によって生成されるものと同じです。
- 例: ALPHA_FILE。

出力ファイル

出力ファイル名には、--outprefix オプションで指定されたプレフィックスが使用されます。

吸収スペクトルExcelファイル (.xlsx):
- save_alpha_to_excel() 関数によって、make_alpha モードでのみ出力されます。
- ファイル名: {outprefix}_alpha.xlsx
- 内容: alpha_spectrum シートにフォトンエネルギー、波長、R、Tr、A、alpha データが、summary シートに膜厚やファイル名、平均値などのメタデータが保存されます。
吸収スペクトルプロット (.png):
- plot_alpha() 関数によって、alpha または make_alpha モードで出力されます。
- ファイル名: {outprefix}_alpha_E.png
- 内容: 吸収係数 (α) とフォトンエネルギーの関係を示すグラフ。
I-V比較プロット (.png):
- plot_iv_comparison() 関数によって、analyze モードで出力されます。
- ファイル名: {outprefix}_iv.png
- 内容: 暗電流・光照射I-V曲線、log(|I|)-V曲線、ndiode-V曲線、光起電力出力 (-J vs V) の比較グラフ。
実行ログファイル (.txt):
- main() 関数によって自動的に生成されます。プログラムの全ての標準出力がこのファイルに記録されます。
- alpha または make_alpha モードの場合: {outprefix}_alpha.txt
- analyze モードの場合: {outprefix}_analyze.txt

make_alpha モード

入出力仕様

入力ファイル

出力ファイル

`make_alpha` モード