# pvfit.py ドキュメント
このドキュメントは、Pythonスクリプト ``pvfit.py`` の機能、使用法、および内部構造をSphinx (MyST) 形式で記述したものです。
## 概要
``pvfit.py`` は、太陽電池や他の半導体デバイスの電流-電圧（IV）特性を、拡張一ダイオードモデル（SDM）を用いてフィッティング、初期値推定、またはシミュレーションするためのツールです。複数の輸送メカニズム（ダイオード、トンネル誘起フォワードエミッション (TFE)、非理想フォワード電流 (FN)、空間電荷制限電流 (SCLC)）を組み合わせて利用できます。
## 詳細説明
``pvfit.py`` は、以下の主要な機能を提供することで、IV特性分析の柔軟性と精度を向上させます。
- **モデルの選択**: フォワードバイアスとリバースバイアスのモデルを独立に選択できます。
- **メカニズムの組み合わせ**: ダイオード、TFE、FN、SCLCの各メカニズムを任意に組み合わせることが可能です。
- **安定した数値解法**: 接合電圧 ``Vd`` を未知数とする根探しアルゴリズム（Brentのメソッド）を用いることで、数値計算の安定化を図っています。
- **パラメータの自動固定**: モデルに未使用のパラメータは自動的に固定され、最適化の効率が向上します。
- **効率的な計算**: ``forwardIV`` と ``reverseIV`` が同一の場合、再計算を回避して処理を効率化します。
- **アニメーション表示**: 最適化途中のIVカーブをアニメーション表示し、フィッティングの進捗をリアルタイムで視覚的に確認できます（常に有効）。
- **パラメータ誤差推定**: 線形近似に基づくパラメータ誤差を推定し、フィッティング結果の信頼性を提供します。
- **信頼区間の表示**: モデル電流の標準偏差から信頼性区間を水色領域で表示し、モデルの予測範囲を示します。
``mode=init`` の初期値推定は、以下の手順で行われます。
- 入力IVデータを電圧昇順にソートします。
- 電流-電圧（I-V）データを局所多項式で平滑化します。
- ``dI/dV`` から直列抵抗 ``Rs`` と並列抵抗 ``Rsh`` を推定します。
- 短絡電流 ``ISC`` は、``V=0`` 近傍の多項式から推定します。
- 光生成電流 ``IPV`` は ``-ISC`` とします。
- 開回路電圧 ``VOC`` は、``I(V)=0`` となる多項式の根から推定します。
- シャント電流 ``Ish`` は、``V<0`` の代表点 ``Vsh`` における電流から推定します。
- 逆飽和電流 ``I0`` は ``ISC - Ish`` とします（シャント電流は差し引きません）。
- TFE初期値は、``V<0`` の十分に負側で ``ln(abs(I))-V`` を一次近似し、``E00 = 1/abs(slope)``、``A_tfe = abs(I) * exp(+V/E00)`` を代表点から推定します。
- ダイオード理想因子 ``ndiode`` は固定初期値 ``1.5`` を使用します。
- FN / SCLC の初期値は結果に影響しない極小値に設定されます。
**注意**: ``mode=init`` の初期値はフィッティング用の頑健な初期値です。物理的に厳密な意味づけは ``mode=fit`` で精密化することを推奨します。
関連リンク:
pvfit_usage
## 非標準ライブラリ
``pvfit.py`` は以下の非標準ライブラリを使用します。
- ``openpyxl``: Excelファイルの読み書きに使用されます。
- ``matplotlib``: IVカーブのプロットおよびアニメーション表示に使用されます。
- ``numpy``: 数値計算、特に配列操作と数学関数に使用されます。
- ``scipy``: 最適化アルゴリズム（``minimize``、``brentq``）および数値微分に使用されます。
## CLIオプション
``pvfit.py`` は、実行時に以下のコマンドラインオプションを受け付けます。
- ``--mode {analyze,init,fit,sim}``: 実行モードを指定します。デフォルトは ``fit``。
- ``init``: 初期パラメータ推定モード。
- ``fit``: データにパラメータをフィッティングするモード。
- ``sim``: IVカーブをシミュレートするモード。
- ``analyze``: データと推定された初期パラメータの簡単な分析とプロット。
- ``--method METHOD``: ``scipy.optimize.minimize`` で使用する最適化手法を指定します（例: ``Nelder-Mead``, ``Powell``, ``BFGS``, ``L-BFGS-B``）。デフォルトは ``Nelder-Mead``。
- ``--infile INFILE``: 入力IV CSVファイルのパスを指定します。``init``, ``fit``, ``analyze`` モードで必須です。
- ``--temperature TEMPERATURE``: モデルに使用する温度をケルビン (K) で指定します。デフォルトは ``300.0``。
- ``--xmin XMIN``: データクリッピング、フィッティング、プロットに使用する最小電圧 (V) を指定します。
- ``--xmax XMAX``: データクリッピング、フィッティング、プロットに使用する最大電圧 (V) を指定します。
- ``--ndataskip NDATASKIP``: データの読み込み時にスキップするデータ点の数を指定します（``n+1`` 点ごとにデータを保持）。デフォルトは ``0``。
- ``--forwardIV FORWARDIV``: フォワードバイアス側の輸送メカニズムを指定します（例: ``diode`` または ``diode+tfe+sclc``）。デフォルトは ``diode``。
- ``--reverseIV REVERSEIV``: リバースバイアス側の輸送メカニズムを指定します（例: ``diode+tfe`` または ``diode+fn``）。デフォルトは ``diode+tfe``。
- ``--dv_blend DV_BLEND``: 接合電圧 ``Vd`` のフォワードモデルとリバースモデル間のシグモイド遷移幅 (V) を指定します。デフォルトは ``0.05``。
- ``--ninterval_print NINTERVAL_PRINT``: フィッティング反復中のコンソール出力間隔を指定します。デフォルトは ``10``。
- ``--ninterval_plot NINTERVAL_PLOT``: フィッティング反復中のアニメーション更新間隔を指定します。デフォルトは ``10``。
- ``--nmaxiter NMAXITER``: 最大最適化反復回数を指定します。デフォルトは ``1000``。
- ``--tol TOL``: 最適化の許容誤差（``xatol`` および ``fatol``）を指定します。デフォルトは ``1.0e-7``。
- ``--fix [FIX ...]``: フィッティング中に固定するパラメータ名のリストをスペース区切りで指定します（例: ``I0 ndiode``）。
- ``--outprefix OUTPREFIX``: 出力ファイル名のプレフィックスを指定します。デフォルトは ``pvfit``。
- ``--I0 I0``, ``--ndiode NDDIODE``, ..., ``--K_sclc K_SCLC``: 各パラメータの初期値を上書きします。
## データ形式
### 入力IV CSVファイル
入力IV CSVファイルは、以下の構造を持つことを想定しています。
- ファイルの先頭にメタデータ行が含まれる場合があります。例えば、``MetaData,RecordTime,2023-10-26 10:00:00`` のような形式です。
- データセクションの開始を示す ``DataName`` 行が続きます。
- 各データ行は ``DataValue,V,I`` の形式で、電圧 ``V`` と電流 ``I`` をカンマ区切りで記述します。
- 例: ``DataValue,0.1,-1.23e-6``
### 出力パラメータCSVファイル
出力パラメータCSVファイルは、以下の列を持ちます。
- ``varname``: パラメータ名
- ``value``: パラメータ値
- ``optid``: 最適化の対象かどうか（``0``: 固定, ``1``: 自由）
- ``error``: 推定誤差
### 出力IV Excelファイル
出力IV Excelファイルには、以下のシートが含まれます。
- ``iv_data``: 以下の列を含むIVデータ。
- ``V``: 電圧
- ``I_input``: 入力電流（測定データ）
- ``I_init``: 初期モデル電流
- ``I_fit``: フィッティング後モデル電流
- ``abs_I_input``, ``abs_I_init``, ``abs_I_fit``: 各電流の絶対値
- ``log10_abs_I_input``, ``log10_abs_I_init``, ``log10_abs_I_fit``: 各電流の絶対値の常用対数
- ``init_params``: 初期パラメータ名と値。
- ``final_params``: 最終パラメータ名、値、および推定誤差。
- ``summary``: ファイル名、レコード時間、データ点数、残差平方和（``RSS_logy``）などのサマリー情報。
## 入出力
### 入力
- **IVデータ**: CLIオプション ``--infile`` で指定されたCSVファイルから電圧と電流データを読み込みます。
### 出力
- **ログファイル**: 実行中のメッセージ、引数、パラメータの進捗状況などが ``<outprefix>_<mode>.txt`` として出力されます。
- **パラメータCSVファイル**:
- 入力ファイルがある場合: ``<infile_stem>-parameters.csv``
- シミュレーションモードの場合: ``sim-parameters.csv``
- 推定された、またはフィッティングされたパラメータとその固定状態が保存されます。
- **IVデータExcelファイル**:
- ``<outprefix>-fitted.xlsx``
- 測定IVデータ、初期モデルIVデータ、フィッティング後モデルIVデータ、およびパラメータサマリーが保存されます。
- **IVカーブプロット画像**:
- ``<outprefix>-iv.png``
- 線形スケールおよび対数絶対値スケールでプロットされたIVカーブが保存されます。
## 例外処理
``pvfit.py`` は、主に以下の状況でエラーを検出・報告します。
- **引数の無効性**: ``validate_args()`` 関数により、コマンドライン引数が期待される形式や範囲にない場合に :py:exc:`ValueError` が発生します。
- 例: ``--infile`` が ``init``, ``fit``, ``analyze`` モードで未指定。
- 例: ``--xmin`` が ``--xmax`` より大きい。
- 例: 温度が ``0 K`` 以下。
- 例: 対数スケールパラメータに ``0`` 以下の値が指定された。
- 例: 未知のパラメータ名が ``--fix`` で指定された。
- **データ読み込みの失敗**: ``read_data()`` 関数により、入力CSVファイルに有効なデータが見つからない場合や、クリッピング後にデータ点が残らない場合に :py:exc:`ValueError` が発生します。
- **最適化の失敗**: ``minimize`` 関数内部でのエラーや、根探しアルゴリズム（``brentq``）での収束失敗は、部分的に処理され、エラー推定時に警告が表示されることがあります。
- **一般的な実行時エラー**: ``main()`` 関数全体が ``try...except Exception`` ブロックで囲まれており、予期せぬエラーが発生した場合は、スタックトレースが出力され、スクリプトは終了コード ``1`` で終了します。
## 関数リファレンス
### initialize()
- **概要**: コマンドライン引数パーサーを初期化し、引数を解析します。
- **詳細説明**: 各種実行モード (analyze, init, fit, sim)、最適化手法、入力ファイル、温度、データクリッピング範囲、スキップ間隔、フォワード/リバースIVモデル、ブレンド電圧幅、プロット/プリント間隔、最大イテレーション数、許容誤差、固定パラメータなどの引数を定義します。
- **引数**: なし
- **戻り値**:
- ``args`` (:py:class:`argparse.Namespace`): 解析された引数を含むオブジェクト。
- ``parser`` (:py:class:`argparse.ArgumentParser`): ``ArgumentParser`` オブジェクト。
- **rtype**: ``tuple[argparse.Namespace, argparse.ArgumentParser]``
### print_args_and_derived(args)
- **概要**: コマンドライン引数とその派生値をコンソールに出力します。
- **詳細説明**: ユーザーが指定した入力値と、プログラム内部で決定される追加の設定（例：使用されるパラメータ、自動固定されるパラメータ）を一覧表示し、設定の確認を容易にします。
- **引数**:
- ``args`` (:py:class:`argparse.Namespace`): 解析されたコマンドライン引数を含むオブジェクト。
- **戻り値**:
- なし
- **rtype**: ``None``
### validate_args(args)
- **概要**: コマンドライン引数の有効性を検証します。
- **詳細説明**: モードごとの必須引数、数値引数の範囲、パラメータ名の整合性などをチェックし、無効な引数が存在する場合は :py:exc:`ValueError` を発生させます。
- **引数**:
- ``args`` (:py:class:`argparse.Namespace`): 解析されたコマンドライン引数を含むオブジェクト。
- **戻り値**:
- なし
- **rtype**: ``None``
- **例外**:
- :py:exc:`ValueError`: 無効な引数が見つかった場合。
### read_data(infile, xmin=None, xmax=None, ndataskip=0)
- **概要**: 指定されたCSVファイルからIVデータ（電圧と電流）を読み込みます。
- **詳細説明**: ファイルからメタデータを抽出し、電圧昇順にデータをソートし、指定された電圧範囲でクリッピングし、データスキップ間隔を適用します。
- **引数**:
- ``infile`` (:py:class:`str`): 入力IV CSVファイルのパス。
- ``xmin`` (:py:class:`float` or ``None``): データをクリップする最小電圧 (V)。``None`` の場合、下限なし。
- ``xmax`` (:py:class:`float` or ``None``): データをクリップする最大電圧 (V)。``None`` の場合、上限なし。
- ``ndataskip`` (:py:class:`int`): 読み込み時にスキップするデータ点の数（``n+1`` 点ごとにデータを保持）。
- **戻り値**:
- ``V`` (:py:class:`numpy.ndarray`): 読み込まれた電圧データのNumPy配列。
- ``I`` (:py:class:`numpy.ndarray`): 読み込まれた電流データのNumPy配列。
- ``info`` (:py:class:`dict`): ファイル名と記録時間を含む辞書。
- **rtype**: ``tuple[numpy.ndarray, numpy.ndarray, dict]``
- **例外**:
- :py:exc:`ValueError`: 有効なデータが見つからない場合、またはクリッピング後にデータ点が残らない場合。
### load_param_csv(csv_path)
- **概要**: パラメータ設定CSVファイルからパラメータ値と固定設定を読み込みます。
- **詳細説明**: CSVファイルには ``varname``, ``value``, ``optid`` の列が含まれると想定されます。``optid`` が ``0`` の場合、そのパラメータは固定されます。
- **引数**:
- ``csv_path`` (:py:class:`str`): 読み込むCSVファイルのパス。
- **戻り値**:
- ``params`` (:py:class:`dict`): 読み込まれたパラメータ名と値の辞書。
- ``fix_set`` (:py:class:`set`): 固定されるパラメータ名のセット。
- **rtype**: ``tuple[dict, set]``
### save_param_csv(csv_path, params, fix_set, errors=None, rss=None)
- **概要**: 現在のパラメータ値、固定設定、推定誤差、およびRSSをCSVファイルに保存します。
- **詳細説明**: ``PARAM_NAMES`` にリストされている全てのパラメータと、追加の診断情報（``VOC_est`` など）が保存されます。
- **引数**:
- ``csv_path`` (:py:class:`str`): 保存するCSVファイルのパス。
- ``params`` (:py:class:`dict`): 保存するパラメータ名と値の辞書。
- ``fix_set`` (:py:class:`set`): 固定されたパラメータ名のセット。
- ``errors`` (:py:class:`dict` or ``None``): 各パラメータの推定誤差を含む辞書。``None`` の場合、誤差は ``0.0`` として保存。
- ``rss`` (:py:class:`float` or ``None``): 残差平方和 (Residual Sum of Squares)。``None`` の場合、保存しない。
- **戻り値**:
- なし
- **rtype**: ``None``
### save_iv_to_excel(outfile_xlsx, V, I_input, I_init, I_fit, info, params_init=None, params_final=None, rss=None, errors=None)
- **概要**: IVデータ、初期パラメータ、最終パラメータ、およびサマリー情報をExcelファイルに保存します。
- **詳細説明**: 測定データ、初期モデル電流、フィッティング後のモデル電流が線形および対数絶対値スケールで保存されます。パラメータシートには初期値と最終値、および推定誤差が含まれます。
- **引数**:
- ``outfile_xlsx`` (:py:class:`str`): 出力するExcelファイルのパス。
- ``V`` (:py:class:`numpy.ndarray`): 電圧データのNumPy配列。
- ``I_input`` (:py:class:`numpy.ndarray` or ``None``): 測定された電流データのNumPy配列。``None`` の場合、保存しない。
- ``I_init`` (:py:class:`numpy.ndarray` or ``None``): 初期モデルによって計算された電流データのNumPy配列。``None`` の場合、保存しない。
- ``I_fit`` (:py:class:`numpy.ndarray` or ``None``): フィッティング後のモデルによって計算された電流データのNumPy配列。``None`` の場合、保存しない。
- ``info`` (:py:class:`dict`): ファイル名や記録時間などの情報を含む辞書。
- ``params_init`` (:py:class:`dict` or ``None``): 初期パラメータ値を含む辞書。``None`` の場合、保存しない。
- ``params_final`` (:py:class:`dict` or ``None``): フィッティング後の最終パラメータ値を含む辞書。``None`` の場合、保存しない。
- ``rss`` (:py:class:`float` or ``None``): 残差平方和 (Residual Sum of Squares)。``None`` の場合、保存しない。
- ``errors`` (:py:class:`dict` or ``None``): 各パラメータの推定誤差を含む辞書。``None`` の場合、保存しない。
- **戻り値**:
- なし
- **rtype**: ``None``
### solve_root_poly(x, y, target_y=0.0, order=3)
- **概要**: データ点 (x, y) に多項式をフィッティングし、指定された ``target_y`` に対応する ``x`` の根を近似的に見つけます。
- **詳細説明**: データ点数が少ない場合は、線形補間または多項式の次数を調整して対処します。複数の実根がある場合は、入力 ``x`` の平均に最も近い根を選択します。
- **引数**:
- ``x`` (:py:class:`numpy.ndarray`): 独立変数データ点の配列。
- ``y`` (:py:class:`numpy.ndarray`): 従属変数データ点の配列。
- ``target_y`` (:py:class:`float`): 根を見つけたい目標のy値。
- ``order`` (:py:class:`int`): 多項式フィッティングの次数。
- **戻り値**:
- ``float``: ``target_y`` に対応する ``x`` の推定根。
### local_poly_value(x, y, x0, npts=7, order=3)
- **概要**: 指定された点 ``x0`` の近傍のデータ点に局所多項式をフィッティングし、``x0`` におけるy値を推定します。
- **詳細説明**: ``npts`` で指定された数の最も近いデータ点を使用します。
- **引数**:
- ``x`` (:py:class:`numpy.ndarray`): 独立変数データ点の配列。
- ``y`` (:py:class:`numpy.ndarray`): 従属変数データ点の配列。
- ``x0`` (:py:class:`float`): y値を推定したい目標のx値。
- ``npts`` (:py:class:`int`): 局所フィッティングに使用するデータ点の数。
- ``order`` (:py:class:`int`): 多項式フィッティングの次数。
- **戻り値**:
- ``float``: ``x0`` における推定y値。
### smooth_polyfit(y, window_points=5, poly_order=3)
- **概要**: Savitzky-Golayフィルターに似た局所多項式フィッティングにより、配列 ``y`` を平滑化します。
- **詳細説明**: 各データ点に対して、その点と近傍の ``window_points`` 数（奇数）のデータ点に ``poly_order`` 次の多項式をフィッティングし、中央の点の値を推定します。
- **引数**:
- ``y`` (:py:class:`numpy.ndarray`): 平滑化するデータ点の配列。
- ``window_points`` (:py:class:`int`): 各局所フィッティングに使用するウィンドウの点の数（奇数であるべき）。
- ``poly_order`` (:py:class:`int`): 各局所フィッティングで使用する多項式の次数。
- **戻り値**:
- ``numpy.ndarray``: 平滑化されたデータ点の配列。
### sigmoid_blend(x, dV)
- **概要**: シグモイド関数を用いて、2つのモデル間のブレンド係数を計算します。
- **詳細説明**: ``x`` が ``0.0`` の場合に ``0.5``、``x`` が正で十分に大きい場合に ``1.0``、``x`` が負で十分に小さい場合に ``0.0`` に近づく値を返します。``dV`` はブレンドの遷移幅を決定します。``dV`` が非常に小さい場合、ステップ関数に近づきます。
- **引数**:
- ``x`` (:py:class:`numpy.ndarray` or ``float``): ブレンドの基準となる電圧または汎用的な値。
- ``dV`` (:py:class:`float`): シグモイド遷移の幅を制御するパラメータ。
- **戻り値**:
- ``numpy.ndarray`` or ``float``: ``x`` に応じたブレンド係数。``0`` から ``1`` の間の値を取ります。
### j_diode(Vd, I0, ndiode, temperature)
- **概要**: 理想ダイオードモデル（Shockley方程式）の電流成分を計算します。
- **引数**:
- ``Vd`` (:py:class:`numpy.ndarray` or ``float``): ダイオード接合にかかる電圧。
- ``I0`` (:py:class:`float`): 逆飽和電流。
- ``ndiode`` (:py:class:`float`): ダイオード理想因子（エミッタ係数）。
- ``temperature`` (:py:class:`float`): 温度 (K)。
- **戻り値**:
- ``numpy.ndarray`` or ``float``: ダイオード電流。
### j_tfe_forward(Vd, A_tfe, E00)
- **概要**: 熱アシストトンネルフィールドエミッション (TFE) 電流のフォワードバイアス成分を計算します。
- **詳細説明**: TFEは通常、低温や欠陥の多い材料で支配的になるメカニズムです。この関数は、``Vd > 0`` の領域でTFEによる電流を計算します。
- **引数**:
- ``Vd`` (:py:class:`numpy.ndarray` or ``float``): ダイオード接合にかかる電圧。
- ``A_tfe`` (:py:class:`float`): TFE電流の振幅係数。
- ``E00`` (:py:class:`float`): TFEの特性エネルギーまたは係数。
- **戻り値**:
- ``numpy.ndarray`` or ``float``: TFEフォワード電流。
### j_tfe_reverse(Vd, A_tfe, E00)
- **概要**: 熱アシストトンネルフィールドエミッション (TFE) 電流のリバースバイアス成分を計算します。
- **詳細説明**: この関数は、``Vd < 0`` の領域でTFEによる電流を計算します。
- **引数**:
- ``Vd`` (:py:class:`numpy.ndarray` or ``float``): ダイオード接合にかかる電圧。
- ``A_tfe`` (:py:class:`float`): TFE電流の振幅係数。
- ``E00`` (:py:class:`float`): TFEの特性エネルギーまたは係数。
- **戻り値**:
- ``numpy.ndarray`` or ``float``: TFEリバース電流。
### j_fn_forward(Vd, A_fn, B_fn)
- **概要**: Fowler-Nordheimトンネル電流 (FN) のフォワードバイアス成分を計算します。
- **詳細説明**: このメカニズムは、高注入レベルや特定の欠陥メカニズムによって引き起こされる電流をモデル化するために使用できます。``Vd > 0`` の領域で定義されます。
- **引数**:
- ``Vd`` (:py:class:`numpy.ndarray` or ``float``): ダイオード接合にかかる電圧。
- ``A_fn`` (:py:class:`float`): FN電流の振幅係数。
- ``B_fn`` (:py:class:`float`): FN電流の指数関数的電圧依存性を制御する係数。
- **戻り値**:
- ``numpy.ndarray`` or ``float``: FNフォワード電流。
### j_fn_reverse(Vd, A_fn, B_fn)
- **概要**: Fowler-Nordheimトンネル電流 (FN) のリバースバイアス成分を計算します。
- **詳細説明**: このメカニズムは、高注入レベルや特定の欠陥メカニズムによって引き起こされる電流をモデル化するために使用できます。``Vd < 0`` の領域で定義されます。
- **引数**:
- ``Vd`` (:py:class:`numpy.ndarray` or ``float``): ダイオード接合にかかる電圧。
- ``A_fn`` (:py:class:`float`): FN電流の振幅係数。
- ``B_fn`` (:py:class:`float`): FN電流の指数関数的電圧依存性を制御する係数。
- **戻り値**:
- ``numpy.ndarray`` or ``float``: FNリバース電流。
### j_sclc_trap_transition(Vd, K_sclc, m_sclc, Vtfl, dV=1e-3)
- **概要**: トラップ制限空間電荷制限電流（SCLC）とトラップフリーSCLCの間の遷移をモデル化する電流成分を計算します。
- **詳細説明**: このモデルは、電圧に応じてトラップが満たされることで、電流が異なる電圧依存性を示す領域を表現します。具体的には、トラップ制限領域では ``Vd^m_sclc`` に、トラップフリー領域では ``Vd^2`` に従います。シグモイド関数を用いて両者間の滑らかな遷移を実現します。
- **引数**:
- ``Vd`` (:py:class:`numpy.ndarray` or ``float``): ダイオード接合にかかる電圧。
- ``K_sclc`` (:py:class:`float`): SCLCの振幅係数（トラップ制限領域の係数）。
- ``m_sclc`` (:py:class:`float`): トラップ制限領域でのSCLCの電圧依存性指数。
- ``Vtfl`` (:py:class:`float`): トラップが満たされる閾値電圧。
- ``dV`` (:py:class:`float`): 遷移の幅を制御する電圧（シグモイド関数の傾き）。
- **戻り値**:
- ``numpy.ndarray`` or ``float``: トラップ遷移を考慮したSCLC電流。
### j_sclc(Vd, K_sclc)
- **概要**: 空間電荷制限電流 (SCLC) を計算します。
- **詳細説明**: SCLCは、高抵抗材料におけるキャリア注入が空間電荷によって制限されるときに発生します。この電流は電圧の2乗に比例し、電圧の符号によって方向が決まります。
- **引数**:
- ``Vd`` (:py:class:`numpy.ndarray` or ``float``): ダイオード接合にかかる電圧。
- ``K_sclc`` (:py:class:`float`): SCLCの振幅係数。
- **戻り値**:
- ``numpy.ndarray`` or ``float``: SCLC電流。
### parse_mech_mode(mode_str)
- **概要**: 輸送メカニズムのモード文字列を解析し、使用するメカニズムのセットを返します。
- **詳細説明**: モード文字列はカンマ (``,``) またはプラス (``+``) で区切られたメカニズム名（例: ``diode+tfe``）を含みます。無効なメカニズム名が指定された場合は :py:exc:`ValueError` を発生させます。
- **引数**:
- ``mode_str`` (:py:class:`str` or ``None``): 解析するモード文字列（例: ``diode``, ``diode+tfe``, ``none``）。
- **戻り値**:
- ``set``: 使用するメカニズム名のセット。
- **rtype**: ``set``
- **例外**:
- :py:exc:`ValueError`: 未知の輸送メカニズム名が指定された場合。
### used_params_from_modes(forwardIV, reverseIV)
- **概要**: 指定されたフォワードおよびリバースIVモデルで使用されるパラメータ名を決定します。
- **詳細説明**: 共通のパラメータ (``Rs``, ``Rsh``, ``IPV``) に加えて、有効な輸送メカニズム (diode, tfe, fn, sclc) に関連するパラメータを特定します。
- **引数**:
- ``forwardIV`` (:py:class:`str`): フォワードバイアスモデルのメカニズムを示す文字列（例: ``diode``, ``diode+tfe``）。
- ``reverseIV`` (:py:class:`str`): リバースバイアスモデルのメカニズムを示す文字列（例: ``diode+tfe``, ``diode+fn``）。
- **戻り値**:
- ``set``: 使用されるパラメータ名のセット。
- **rtype**: ``set``
### junction_current_forward(Vd, p, mode_set, temperature)
- **概要**: フォワードバイアス条件における総接合電流を計算します。
- **詳細説明**: ``mode_set`` で指定されたメカニズムに基づいて、対応する電流成分（ダイオード、TFE、FN、SCLC）を合計します。
- **引数**:
- ``Vd`` (:py:class:`numpy.ndarray` or ``float``): ダイオード接合にかかる電圧。
- ``p`` (:py:class:`dict`): パラメータ値を含む辞書。
- ``mode_set`` (:py:class:`set`): フォワードバイアスで使用するメカニズムのセット。
- ``temperature`` (:py:class:`float`): 温度 (K)。
- **戻り値**:
- ``numpy.ndarray`` or ``float``: 総接合電流。
### junction_current_reverse(Vd, p, mode_set, temperature)
- **概要**: リバースバイアス条件における総接合電流を計算します。
- **詳細説明**: ``mode_set`` で指定されたメカニズムに基づいて、対応する電流成分（ダイオード、TFE、FN、SCLC）を合計します。
- **引数**:
- ``Vd`` (:py:class:`numpy.ndarray` or ``float``): ダイオード接合にかかる電圧。
- ``p`` (:py:class:`dict`): パラメータ値を含む辞書。
- ``mode_set`` (:py:class:`set`): リバースバイアスで使用するメカニズムのセット。
- ``temperature`` (:py:class:`float`): 温度 (K)。
- **戻り値**:
- ``numpy.ndarray`` or ``float``: 総接合電流。
### same_sign(a, b)
- **概要**: 2つの数値が同じ符号を持つかどうかを判定します。
- **詳細説明**: 両方が正または両方が負の場合に ``True`` を返します。片方または両方がゼロの場合の動作は、厳密には考慮されていません。
- **引数**:
- ``a`` (:py:class:`float`): 1つ目の数値。
- ``b`` (:py:class:`float`): 2つ目の数値。
- **戻り値**:
- :py:class:`bool`: ``a`` と ``b`` が同じ符号を持つ場合は ``True``、そうでない場合は ``False``。
### model(V, p, forwardIV="diode", reverseIV="diode+tfe", dV=0.05, temperature=300.0)
- **概要**: 拡張一ダイオードモデル（SDM）に基づいて電流-電圧（IV）カーブを計算します。
- **詳細説明**: 与えられた外部電圧 ``V``、パラメータ ``p``、および選択された輸送メカニズム (``forwardIV``, ``reverseIV``) を使用して対応する電流 ``I`` を計算します。接合電圧 ``Vd`` を未知数とする根探しアルゴリズム（Brentのメソッド）を用いて安定的にモデル電流を求めます。フォワードとリバースで異なるモデルが指定された場合、シグモイド関数 (``sigmoid_blend``) を使って ``Vd`` が ``0V`` 付近でスムーズにブレンドされます。
- **引数**:
- ``V`` (:py:class:`numpy.ndarray`): 外部印加電圧の配列。
- ``p`` (:py:class:`dict`): モデルパラメータを含む辞書。主要なキーは ``I0``, ``ndiode``, ``IPV``, ``Rs``, ``Rsh``, ``A_tfe``, ``E00``, ``A_fn``, ``B_fn``, ``K_sclc``。
- ``forwardIV`` (:py:class:`str`): フォワードバイアス領域で使用する輸送メカニズムを示す文字列。例: ``diode``, ``diode+tfe+sclc``。
- ``reverseIV`` (:py:class:`str`): リバースバイアス領域で使用する輸送メカニズムを示す文字列。例: ``diode+tfe``, ``diode+fn``。
- ``dV`` (:py:class:`float`): フォワードモデルとリバースモデルをブレンドする際の電圧幅。``Vd=0V`` 付近での遷移の鋭さを制御します。
- ``temperature`` (:py:class:`float`): シミュレーションの温度 (K)。
- **戻り値**:
- ``numpy.ndarray``: 各外部電圧 ``V`` に対応する総電流の配列。
### estimate_voc_local_quadratic(V, I, nlsq_points=5)
- **概要**: IVデータから開回路電圧（VOC）を局所二次多項式フィッティングで推定します。
- **詳細説明**: 電流がゼロに最も近い点の近傍データを使用して、二次多項式をフィッティングし、その多項式の根から ``VOC`` を求めます。データ点が少ない場合は、線形補間を使用します。
- **引数**:
- ``V`` (:py:class:`numpy.ndarray`): 電圧データの配列。
- ``I`` (:py:class:`numpy.ndarray`): 電流データの配列。
- ``nlsq_points`` (:py:class:`int`): 局所フィッティングに使用するデータ点の数。
- **戻り値**:
- ``float``: 推定された開回路電圧 ``VOC``。
### estimate_initial_params(V, I_meas, temperature)
- **概要**: IVデータからSDM（拡張一ダイオードモデル）の初期パラメータを推定します。
- **詳細説明**: データ平滑化、``dI/dV`` 解析、多項式根探し、負電圧領域でのTFE近似を用いて、最適化に適した頑健な初期値を導出します。
- **引数**:
- ``V`` (:py:class:`numpy.ndarray`): 測定された電圧データ点の配列。
- ``I_meas`` (:py:class:`numpy.ndarray`): 測定された電流データ点の配列。
- ``temperature`` (:py:class:`float`): 測定時の温度 (K)。
- **戻り値**:
- ``dict``: 推定された初期パラメータを含む辞書。
### pack_free_params(params, fix_set)
- **概要**: 辞書形式の全パラメータから、最適化対象の自由パラメータのみをNumPy配列にパックします。
- **詳細説明**: ``fix_set`` に含まれるパラメータは除外されます。``LOG_PARAMS`` に含まれるパラメータは ``log10`` 変換されて配列に格納されます。
- **引数**:
- ``params`` (:py:class:`dict`): 全パラメータ（固定および自由）を含む辞書。
- ``fix_set`` (:py:class:`set`): 固定されるパラメータ名のセット。
- **戻り値**:
- ``numpy.ndarray``: 最適化に使用される自由パラメータのNumPy配列。
### unpack_free_params(p_free, base_params, fix_set)
- **概要**: 自由パラメータのNumPy配列を、固定パラメータと組み合わせて辞書形式の全パラメータにアンパックします。
- **詳細説明**: ``base_params`` は固定パラメータの値を決定するために使用されます。``LOG_PARAMS`` に含まれるパラメータは ``10**`` 変換されて辞書に格納されます。
- **引数**:
- ``p_free`` (:py:class:`numpy.ndarray`): 最適化中の自由パラメータのNumPy配列。
- ``base_params`` (:py:class:`dict`): 固定パラメータの基準値を含む辞書。
- ``fix_set`` (:py:class:`set`): 固定されたパラメータ名のセット。
- **戻り値**:
- ``dict``: 更新された全パラメータを含む辞書。
### signed_log10_current(I, eps=1.0e-15)
- **概要**: 符号を保持したまま電流を圧縮する補助関数。
- **詳細説明**: ``sign(I) * log10(abs(I)+eps)`` を返します。電流値がゼロに近い場合に計算が不安定になることを防ぐため、``abs(I)`` に ``eps`` を加えます。
- **引数**:
- ``I`` (:py:class:`numpy.ndarray` or ``float``): 電流値の配列または単一値。
- ``eps`` (:py:class:`float`): 絶対値計算時に加算される微小量。ゼロ除算や対数関数の引数が負になるのを防ぐ。
- **戻り値**:
- ``numpy.ndarray`` or ``float``: 符号を保持したログスケールの電流値。
### objective(p_free, V, I_meas, args, base_params, fix_set)
- **概要**: 最適化のための目的関数（残差平方和）を計算します。
- **詳細説明**: 測定電流とモデル電流の符号を保持した圧縮表現 ``sign(I) * log10(abs(I)+EPS_I)`` の残差平方和を使用します。
- **引数**:
- ``p_free`` (:py:class:`numpy.ndarray`): 最適化中の自由パラメータのNumPy配列。
- ``V`` (:py:class:`numpy.ndarray`): 測定された電圧データ点の配列。
- ``I_meas`` (:py:class:`numpy.ndarray`): 測定された電流データ点の配列。
- ``args`` (:py:class:`argparse.Namespace`): コマンドライン引数パーサーから得られた設定を含むオブジェクト（例: ``forwardIV``, ``reverseIV``）。
- ``base_params`` (:py:class:`dict`): 固定パラメータの基準値を含む辞書。
- ``fix_set`` (:py:class:`set`): 固定されたパラメータ名のセット。
- **戻り値**:
- ``float``: 目的関数の値（残差平方和）。
### get_jacobian(p_free, V, temperature, args, base_params, fix_set)
- **概要**: モデルのヤコビ行列を数値的に計算します。
- **詳細説明**: 各自由パラメータを微小量 ``eps`` だけ摂動させ、``log10(abs(I))`` の変化を計算して偏微分（ヤコビ行列の要素）を近似します。
- **引数**:
- ``p_free`` (:py:class:`numpy.ndarray`): 最適化された自由パラメータのNumPy配列。
- ``V`` (:py:class:`numpy.ndarray`): 測定された電圧データ点の配列。
- ``temperature`` (:py:class:`float`): シミュレーションの温度 (K)。
- ``args`` (:py:class:`argparse.Namespace`): コマンドライン引数パーサーから得られた設定を含むオブジェクト。
- ``base_params`` (:py:class:`dict`): 固定パラメータの基準値を含む辞書。
- ``fix_set`` (:py:class:`set`): 固定されたパラメータ名のセット。
- **戻り値**:
- ``numpy.ndarray``: 各データ点に対する各自由パラメータの偏微分からなるヤコビ行列。
### estimate_errors(res, V, I_meas, temperature, args, base_params, fix_set)
- **概要**: フィッティング結果からパラメータの誤差とモデル電流の信頼区間を推定します。
- **詳細説明**: ヤコビ行列と残差平方和を用いて共分散行列を計算し、誤差伝播によって各パラメータの誤差とモデル電流の ``log10`` スケールでの標準偏差を算出します。
- **引数**:
- ``res`` (:py:class:`scipy.optimize.OptimizeResult`): ``scipy.optimize.minimize`` の結果オブジェクト。最適化されたパラメータ (``res.x``) と目的関数の値 (``res.fun``) を含む。
- ``V`` (:py:class:`numpy.ndarray`): 測定された電圧データ点の配列。
- ``I_meas`` (:py:class:`numpy.ndarray`): 測定された電流データ点の配列。
- ``temperature`` (:py:class:`float`): シミュレーションの温度 (K)。
- ``args`` (:py:class:`argparse.Namespace`): コマンドライン引数パーサーから得られた設定を含むオブジェクト。
- ``base_params`` (:py:class:`dict`): 固定パラメータの基準値を含む辞書。
- ``fix_set`` (:py:class:`set`): 固定されたパラメータ名のセット。
- **戻り値**:
- ``errors_dict`` (:py:class:`dict`): 各パラメータ名とその推定誤差の辞書。
- ``sigma_log_I`` (:py:class:`numpy.ndarray`): モデル電流の ``log10`` 値の標準偏差の配列。
- **rtype**: ``tuple[dict, numpy.ndarray]``
### initialize_plot(V, I_meas, I_sim, title=None)
- **概要**: 最適化プロセスのための初期プロットを設定し、アニメーションオブジェクトを返します。
- **詳細説明**: リアルタイムでのフィッティング進捗状況を表示するために使用されます。線形スケールと対数絶対値スケールの2つのサブプロットが作成されます。
- **引数**:
- ``V`` (:py:class:`numpy.ndarray`): 電圧データの配列。
- ``I_meas`` (:py:class:`numpy.ndarray`): 測定された電流データの配列。
- ``I_sim`` (:py:class:`numpy.ndarray`): 初期シミュレーション電流データの配列。
- ``title`` (:py:class:`str` or ``None``): プロットのメインタイトル。``None`` の場合、タイトルは設定されない。
- **戻り値**:
- ``fig`` (:py:class:`matplotlib.figure.Figure`): ``matplotlib.figure.Figure``。
- ``axes`` (:py:class:`numpy.ndarray`): ``matplotlib.axes.Axes`` の配列。
- ``anim`` (:py:class:`dict`): アニメーションに使うオブジェクトの辞書。
- **rtype**: ``tuple[matplotlib.figure.Figure, numpy.ndarray, dict]``
### plot_iv(fig, axes, V, I_meas, I_start, I_final, info, mode, sigma_log=None, mode_label="", outfile=None, pause=False)
- **概要**: 測定データとモデルIVカーブをプロットします。
- **詳細説明**: 線形スケールと対数絶対値スケールの2つのサブプロットを作成します。``sigma_log`` が提供された場合、モデル電流の信頼区間を水色領域で表示します。
- **引数**:
- ``fig`` (:py:class:`matplotlib.figure.Figure` or ``None``): プロットに使う ``matplotlib.figure.Figure`` オブジェクト。``None`` の場合、新しい ``Figure`` を作成。
- ``axes`` (:py:class:`numpy.ndarray` or ``None``): プロットに使う ``matplotlib.axes.Axes`` オブジェクトの配列。``None`` の場合、新しい ``Axes`` を作成。
- ``V`` (:py:class:`numpy.ndarray`): プロットする電圧データの配列。
- ``I_meas`` (:py:class:`numpy.ndarray` or ``None``): 測定された電流データの配列。``None`` の場合、測定データはプロットされない。
- ``I_start`` (:py:class:`numpy.ndarray` or ``None``): 初期モデルによって計算された電流データの配列。``None`` の場合、初期モデルはプロットされない。
- ``I_final`` (:py:class:`numpy.ndarray`): 最終モデルによって計算された電流データの配列。
- ``info`` (:py:class:`dict`): ファイル名やレコード時間などの情報を含む辞書。プロットのタイトルに使用。
- ``mode`` (:py:class:`str`): 現在の実行モード（例: ``init``, ``fit``, ``sim``）を示す文字列。プロットのタイトルに使用。
- ``sigma_log`` (:py:class:`numpy.ndarray` or ``None``): モデル電流の ``log10`` 値の標準偏差の配列。信頼区間を表示するために使用。``None`` の場合、信頼区間は表示されない。
- ``mode_label`` (:py:class:`str`): プロットのタイトルに追加するモードのラベル。
- ``outfile`` (:py:class:`str` or ``None``): プロットを保存するファイルパス。``None`` の場合、保存しない。
- ``pause`` (:py:class:`bool`): プロットを表示後に一時停止するかどうか。``True`` の場合、ユーザーのキー入力を待つ。
- **戻り値**:
- なし
- **rtype**: ``None``
### setup_parameters(params, args, csv_fix, args_fix, forwardIV, reverseIV)
- **概要**: パラメータ辞書を最終的に設定し、固定されるパラメータを決定します。
- **詳細説明**: コマンドライン引数で上書きされた値、CSVファイルから読み込まれた値、デフォルト値、および未使用のモデルメカニズムに基づいて自動的に固定されるパラメータを統合します。
- **引数**:
- ``params`` (:py:class:`dict`): 現在のパラメータ値を含む辞書。
- ``args`` (:py:class:`argparse.Namespace`): 解析されたコマンドライン引数を含むオブジェクト。
- ``csv_fix`` (:py:class:`set`): CSVファイルで固定されたパラメータ名のセット。
- ``args_fix`` (:py:class:`list`): コマンドライン引数で固定されたパラメータ名のリスト。
- ``forwardIV`` (:py:class:`str`): フォワードバイアスモデルのメカニズムを示す文字列。
- ``reverseIV`` (:py:class:`str`): リバースバイアスモデルのメカニズムを示す文字列。
- **戻り値**:
- ``params`` (:py:class:`dict`): 最終的なパラメータ値の辞書。
- ``fix_set`` (:py:class:`set`): 最終的に固定されるパラメータ名のセット。
- ``used`` (:py:class:`set`): 使用されるパラメータ名のセット。
- ``auto_fixed`` (:py:class:`set`): 自動的に固定されたパラメータ名のセット。
- **rtype**: ``tuple[dict, set, set, set]``
- **例外**:
- :py:exc:`ValueError`: 不明な固定パラメータ名が指定された場合。
### print_parameter_repeat(params, fix_set, used, auto_fixed, title="")
- **概要**: 現在のモデルパラメータとその固定状態をコンソールに出力します。
- **詳細説明**: これは、``print_args_and_derived`` の「Derived values」セクションに似ていますが、最終的に決定された各パラメータの具体的な値と、それが固定されているかどうかの状態を詳細に示します。
- **引数**:
- ``params`` (:py:class:`dict`): 最終的なパラメータ値を含む辞書。
- ``fix_set`` (:py:class:`set`): 固定されるパラメータ名のセット。
- ``used`` (:py:class:`set`): モデルで使用されるパラメータ名のセット。
- ``auto_fixed`` (:py:class:`set`): モデルによって自動的に固定されたパラメータ名のセット。
- ``title`` (:py:class:`str`): 出力の前に表示されるタイトル文字列。
- **戻り値**:
- なし
- **rtype**: ``None``
### exec_fit(V, I_meas, info, csv_path, params, fix_set, args)
- **概要**: ``fit`` モードの本体処理。最適化、誤差推定、保存、最終プロットまでをまとめて実行する。
- **詳細説明**: この関数は、``scipy.optimize.minimize`` を用いてSDMパラメータを測定データにフィッティングします。フィッティング中には、コンソールへの進捗表示とリアルタイムのIVカーブアニメーションが行われます。最適化後、パラメータの誤差が推定され、結果がCSVファイルに保存され、最終的なプロットが表示されます。
- **引数**:
- ``V`` (:py:class:`numpy.ndarray`): 測定された電圧データ点の配列。
- ``I_meas`` (:py:class:`numpy.ndarray`): 測定された電流データ点の配列。
- ``info`` (:py:class:`dict`): ファイル名やレコード時間などの情報を含む辞書。プロットのタイトルに使用。
- ``csv_path`` (:py:class:`pathlib.Path`): パラメータを保存するCSVファイルのパス。
- ``params`` (:py:class:`dict`): 初期パラメータ値を含む辞書。
- ``fix_set`` (:py:class:`set`): 固定されるパラメータ名のセット。
- ``args`` (:py:class:`argparse.Namespace`): コマンドライン引数パーサーから得られた設定を含むオブジェクト。
- **戻り値**:
- ``params`` (:py:class:`dict`): 最適化後のパラメータ値の辞書。
- ``rss`` (:py:class:`float`): 残差平方和。
- ``errors`` (:py:class:`dict`): 各パラメータの推定誤差の辞書。
- ``sigma_log_curve`` (:py:class:`numpy.ndarray`): モデル電流の ``log10`` 値の標準偏差の配列。
- **rtype**: ``tuple[dict, float, dict, numpy.ndarray]``
### dual_print(*args, **kwargs)
- **概要**: 標準出力とログファイルの両方にメッセージを出力します。
- **詳細説明**: 組み込みの ``print`` 関数をオーバーライドするために使用され、すべての出力がコンソールと指定されたログファイルの両方に書き込まれます。
- **引数**:
- ``args`` (:py:class:`tuple`): ``print`` 関数に渡される可変長引数。
- ``kwargs`` (:py:class:`dict`): ``print`` 関数に渡されるキーワード引数。
- **戻り値**:
- なし
- **rtype**: ``None``
### main()
- **概要**: スクリプトのエントリーポイント。コマンドライン引数を解析し、IVフィッティングツールを実行します。
- **詳細説明**: この関数は、初期値推定 (``init``)、モデルフィッティング (``fit``)、またはシミュレーション (``sim``) のいずれかのモードで動作します。データ読み込み、パラメータ管理、最適化、結果のプロットを行います。
- **引数**: なし
- **戻り値**:
- なし
- **rtype**: ``None``