tkminfit プログラム仕様

tkminfit.py

scipy.optimize.minimize ベースの最小二乗共通ランナー。

既存の tknlsq.nonlinear_lsq は scipy.optimize.least_squares 用。 このモジュールは、Nelder-Mead など minimize 系メソッドを使いたい アプリ用の薄い共通層。

主な用途: - optid=1 の非線形パラメータ最適化 - optid_lin=1 の線形ブロック最適化 - variable projection: 非線形パラメータごとに線形パラメータを内部で解く - 数値Jacobianから共分散と標準誤差を推定

tkminfit.py 技術ドキュメント

class regression.tklsq.tkminfit.MinimizeLSQResult(params: Dict[str, float], params_free: ndarray, names: List[str], free_names: List[str], optimized_names: List[str], linear_names: List[str], residuals: ndarray, jacobian: ndarray | None, cov_free: ndarray | None, stderr_free: ndarray | None, stderr: Dict[str, float | None], sigma2_resid: float | None, dof: int, N: int, p_free: int, RSS: float, objective: float, success: bool, message: str, nfev: int | None = None, nit: int | None = None, warning: str = '', raw_result: object = None, linear_result: object = None)

ベースクラス: object

minimize ベースの最小二乗最適化結果を格納するデータクラス。

最適化プロセスで得られたパラメータ、残差、共分散、標準誤差などの情報を保持します。 variable projection を使用した場合、線形最適化の結果も含まれます。

変数:

• params -- Dict[str, float]: 最適化後の全パラメータの辞書。

• params_free -- np.ndarray: 最適化された（自由な）パラメータの値のNumPy配列。

• names -- List[str]: 全パラメータ名のリスト。

• free_names -- List[str]: 最適化された（自由な）パラメータ名のリスト。

• optimized_names -- List[str]: minimize_lsq では free_names と同じ。variable_projection_lsq では非線形パラメータ名。

• linear_names -- List[str]: 線形パラメータ名のリスト。

• residuals -- np.ndarray: 最適化後の残差ベクトル。

• jacobian -- Optional[np.ndarray]: 最適化後のヤコビアン行列（自由パラメータに対する残差の偏微分）。共分散計算のために推定されます。

• cov_free -- Optional[np.ndarray]: 自由パラメータの共分散行列。

• stderr_free -- Optional[np.ndarray]: 自由パラメータの標準誤差ベクトル。

• stderr -- Dict[str, Optional[float]]: 全パラメータの標準誤差の辞書。最適化されないパラメータや共分散計算ができない場合はNone。

• sigma2_resid -- Optional[float]: 残差分散の推定値 (s^2)。

• dof -- int: 自由度 (N - p_free)。

• N -- int: データ点数（残差の要素数）。

• p_free -- int: 自由パラメータ数。

• RSS -- float: 残差平方和。

• objective -- float: 目的関数値（RSS + penalty）。

• success -- bool: 最適化が成功したかどうかの真偽値。

• message -- str: 最適化プロセスの終了メッセージ。

• nfev -- Optional[int]: 関数評価回数（最小化アルゴリズムにより提供される場合）。

• nit -- Optional[int]: イテレーション回数（最小化アルゴリズムにより提供される場合）。

• warning -- str: 共分散計算に関する警告メッセージ。

• raw_result -- object: scipy.optimize.minimize から返される生の最適化結果オブジェクト。

• linear_result -- object: variable_projection_lsq で使用される線形最小二乗の生の結果オブジェクト。

N: int

RSS: float

cov_free: ndarray | None

dof: int

free_names: List[str]

jacobian: ndarray | None

linear_names: List[str]

linear_result: object = None

message: str

names: List[str]

nfev: int | None = None

nit: int | None = None

objective: float

optimized_names: List[str]

p_free: int

params: Dict[str, float]

params_free: ndarray

raw_result: object = None

residuals: ndarray

sigma2_resid: float | None

property sigma_resid: float | None

残差の標準偏差 (s) を計算して返します。

戻り値:

float: 残差の標準偏差。sigma2_resid がNoneの場合はNone。

stderr: Dict[str, float | None]

stderr_free: ndarray | None

success: bool

warning: str = ''

regression.tklsq.tkminfit.estimate_covariance_for_params(residual_func: Callable[[Mapping[str, float]], Sequence[float] | ndarray], params_fit: Mapping[str, float], free_names: Sequence[str], *, rel_step: float = 1e-06, abs_step: float = 1e-12) → Tuple[ndarray, ndarray | None, ndarray | None, Dict[str, float | None], float | None, int, str]

任意の残差関数 residual_func(params) について、free_names で指定された自由パラメータの 共分散行列、標準誤差、および残差分散を推定します。

ヤコビアン行列は数値的に計算されます。

パラメータ:

• residual_func -- Callable[[Mapping[str, float]], ArrayLike]: パラメータ辞書を受け取り残差ベクトルを返す関数。

• params_fit -- Mapping[str, float]: 最適化後の全パラメータ値の辞書。

• free_names -- Sequence[str]: 共分散を推定する自由パラメータ名のリスト。

• rel_step -- float: 数値ヤコビアン計算のための相対ステップサイズ。

• abs_step -- float: 数値ヤコビアン計算のための絶対ステップサイズ。

戻り値:

Tuple[np.ndarray, Optional[np.ndarray], Optional[np.ndarray], Dict[str, Optional[float]], Optional[float], int, str]: - np.ndarray: 数値的に計算されたヤコビアン行列。 - Optional[np.ndarray]: 自由パラメータの共分散行列。計算できなかった場合はNone。 - Optional[np.ndarray]: 自由パラメータの標準誤差ベクトル。計算できなかった場合はNone。 - Dict[str, Optional[float]]: 全パラメータの標準誤差の辞書。最適化されないパラメータや計算できなかった場合はNone。 - Optional[float]: 残差分散の推定値 (s^2)。計算できなかった場合はNone。 - int: 自由度 (N - p_free)。 - str: 共分散計算に関する警告メッセージ。

regression.tklsq.tkminfit.minimize_lsq(residual_func: Callable[[Mapping[str, float]], Sequence[float] | ndarray], params: Mapping[str, Mapping[str, object]], *, free_names: Sequence[str] | None = None, method: str = 'Nelder-Mead', use_penalty: bool = True, maxiter: int | None = None, options: dict | None = None, callback: Callable[[int, Dict[str, float], float], None] | None = None, print_interval: int = 0, rel_step: float = 1e-06, abs_step: float = 1e-12) → MinimizeLSQResult

scipy.optimize.minimize を用いて、残差平方和（RSS）にペナルティ項を加えた目的関数を最小化します。

この関数は、与えられた residual_func を直接最適化します。 パラメータの境界制約はペナルティ項として目的関数に組み込まれることで処理されます。

residual_func:

パラメータ辞書を受け取り、残差ベクトルを返す関数。 例: residual_func(params_dict) -> residual vector

params:

tkparamio.read_param_csv() の戻り値形式で、全パラメータの定義情報。 ここから初期値、境界、optid などの情報が読み取られます。

パラメータ:

• residual_func -- Callable[[Mapping[str, float]], ArrayLike]: パラメータ辞書を受け取り、残差ベクトルを返す関数。

• params -- Mapping[str, Mapping[str, object]]: パラメータ定義情報（tkparamio.read_param_csv の戻り値形式）。

• free_names -- Optional[Sequence[str]]: 最適化する自由パラメータ名のリスト。指定しない場合、tkparamio.nonlinear_param_names(params) から取得されます。

• method -- str: scipy.optimize.minimize で使用する最適化メソッド。デフォルトは "Nelder-Mead"。

• use_penalty -- bool: パラメータの境界制約に対するペナルティ項を目的関数に含めるかどうかのフラグ。デフォルトはTrue。

• maxiter -- Optional[int]: 最大イテレーション回数。options に maxiter が指定されていない場合に適用されます。

• options -- Optional[dict]: scipy.optimize.minimize に渡す追加オプションの辞書。

• callback -- Optional[Callable[[int, Dict[str, float], float], None]]: 各イテレーション後に呼び出されるコールバック関数。 引数: (イテレーション回数, 現在の全パラメータ辞書, 現在の目的関数値)。

• print_interval -- int: 進捗状況をコンソールに出力するイテレーション間隔。0の場合は出力しません。

• rel_step -- float: 共分散計算のための数値ヤコビアン計算の相対ステップサイズ。

• abs_step -- float: 共分散計算のための数値ヤコビアン計算の絶対ステップサイズ。

戻り値:

MinimizeLSQResult: 最適化結果を格納したデータクラス。

例外:

ImportError -- scipy がインストールされていない場合。

regression.tklsq.tkminfit.pack_values(values: Mapping[str, float], names: Sequence[str]) → ndarray

指定された名前リストに従い、パラメータ値をNumPy配列にパックします。

パラメータ:

• values -- Mapping[str, float]: パラメータ名と値の辞書。

• names -- Sequence[str]: パックするパラメータ名の順序指定リスト。

戻り値:

np.ndarray: パックされたパラメータ値のNumPy配列。

regression.tklsq.tkminfit.residuals_to_objective(residuals: Sequence[float] | ndarray, *, penalty: float = 0.0) → float

残差ベクトルから目的関数値（RSS + penalty）を計算します。

残差に非有限な値（NaN, Inf）が含まれる場合、それらを非常に大きな値 (1.0e100) として扱い、目的関数値を大きくすることで最適化から除外します。

パラメータ:

• residuals -- ArrayLike: 残差の配列またはリスト。

• penalty -- float: 目的関数に加算するペナルティ値（デフォルト: 0.0）。

戻り値:

float: 計算された目的関数値。

regression.tklsq.tkminfit.solve_linear_block(y: Sequence[float] | ndarray, params: Mapping[str, Mapping[str, object]], p_current: Mapping[str, float], design_matrix_func: Callable[[Mapping[str, float], Sequence[str]], ndarray], *, lin_names: Sequence[str] | None = None, weights: Sequence[float] | ndarray | None = None) → Tuple[Dict[str, float], object]

現在の非線形パラメータのもとで、線形パラメータを線形最小二乗法で最適化します。

design_matrix_func は、現在のパラメータと線形パラメータ名のリストを受け取り、 デザイン行列 X を返すことを想定しています。これにより、観測データ y と X を用いて線形パラメータを最小二乗で解きます。

design_matrix_func は以下の形を想定します。

X = design_matrix_func(p_current, lin_names)

たとえばアプリ側で x をクロージャとして持たせます。

def design_matrix_func(p, lin_names):

return make_X(x, p, lin_names)

パラメータ:

• y -- ArrayLike: 観測データベクトル。

• params -- Mapping[str, Mapping[str, object]]: パラメータ定義情報（例: tkparamio.read_param_csv の戻り値形式）。

• p_current -- Mapping[str, float]: 現在の全パラメータ値の辞書（非線形パラメータを含む）。

• design_matrix_func -- Callable[[Mapping[str, float], Sequence[str]], np.ndarray]: 現在の非線形パラメータと線形パラメータ名リストに基づいてデザイン行列 X を生成する関数。

• lin_names -- Optional[Sequence[str]]: 線形パラメータ名のリスト。指定しない場合、tkparamio から自動的に取得されます。

• weights -- Optional[ArrayLike]: 各データ点に対する重みベクトル。tklsq.tklsq.linear_lsq に渡されます。

戻り値:

Tuple[Dict[str, float], object]: - Dict[str, float]: 線形パラメータが更新された全パラメータの辞書。 - object: tklsq.tklsq.linear_lsq から返される線形最小二乗の生の結果オブジェクト。

例外:

ValueError -- design_matrix_func が不正な形状の配列を返した場合や、次元の不整合があった場合。

regression.tklsq.tkminfit.unpack_values(p_free: Sequence[float] | ndarray, base_values: Mapping[str, float], free_names: Sequence[str]) → Dict[str, float]

自由パラメータのベクトルを基となるパラメータ辞書に展開し、新しい辞書を返します。

base_values のコピーを作成し、free_names に対応する値を p_free から上書きします。

パラメータ:

• p_free -- ArrayLike: 自由パラメータの値の配列またはリスト。

• base_values -- Mapping[str, float]: 基となる全パラメータの辞書。

• free_names -- Sequence[str]: 自由パラメータ名のリスト。p_free の順序と対応している必要があります。

戻り値:

Dict[str, float]: 自由パラメータが展開された新しい全パラメータの辞書。

regression.tklsq.tkminfit.variable_projection_lsq(y: Sequence[float] | ndarray, params: Mapping[str, Mapping[str, object]], model_func: Callable[[Mapping[str, float]], Sequence[float] | ndarray], design_matrix_func: Callable[[Mapping[str, float], Sequence[str]], ndarray], *, nonlin_names: Sequence[str] | None = None, lin_names: Sequence[str] | None = None, method: str = 'Nelder-Mead', use_penalty: bool = True, weights: Sequence[float] | ndarray | None = None, maxiter: int | None = None, options: dict | None = None, callback: Callable[[int, Dict[str, float], float], None] | None = None, print_interval: int = 0, rel_step: float = 1e-06, abs_step: float = 1e-12) → MinimizeLSQResult

変数投影法（Variable Projection）を用いて、非線形パラメータ探索中に線形パラメータを 線形最小二乗法で内部的に解くことで、目的関数を最小化します。

このアプローチにより、非線形最適化の対象となるパラメータ数を減らし、安定性と効率を向上させます。 線形パラメータは、現在の非線形パラメータの値に基づいて各イテレーションで再計算されます。

model_func:

観測データ y と比較するために、現在の全パラメータ（非線形および線形）を受け取り、 モデル予測値を返す関数。 例: y_fit = model_func(params_dict)

design_matrix_func:

現在の非線形パラメータと線形パラメータ名のリストを受け取り、デザイン行列 X を返す関数。 例: X = design_matrix_func(params_dict, lin_names)

どちらの関数も、例えば独立変数 x などをアプリ側のクロージャとして保持する想定です。

パラメータ:

• y -- ArrayLike: 観測データベクトル。

• params -- Mapping[str, Mapping[str, object]]: パラメータ定義情報（tkparamio.read_param_csv の戻り値形式）。

• model_func -- Callable[[Mapping[str, float]], ArrayLike]: 現在のパラメータ辞書に基づいてモデルの予測値ベクトルを返す関数。

• design_matrix_func -- Callable[[Mapping[str, float], Sequence[str]], np.ndarray]: 現在の非線形パラメータと線形パラメータ名リストに基づいてデザイン行列 X を生成する関数。

• nonlin_names -- Optional[Sequence[str]]: 最適化する非線形パラメータ名のリスト。指定しない場合、tkparamio.nonlinear_param_names(params) から取得されます。

• lin_names -- Optional[Sequence[str]]: 最適化する線形パラメータ名のリスト。指定しない場合、tkparamio.linear_param_names(params) から取得されます。

• method -- str: scipy.optimize.minimize で使用する最適化メソッド。デフォルトは "Nelder-Mead"。

• use_penalty -- bool: パラメータの境界制約に対するペナルティ項を目的関数に含めるかどうかのフラグ。デフォルトはTrue。

• weights -- Optional[ArrayLike]: 線形最小二乗ソルバーに渡される重みベクトル。

• maxiter -- Optional[int]: 最大イテレーション回数。options に maxiter が指定されていない場合に適用されます。

• options -- Optional[dict]: scipy.optimize.minimize に渡す追加オプションの辞書。

• callback -- Optional[Callable[[int, Dict[str, float], float], None]]: 各イテレーション後に呼び出されるコールバック関数。 引数: (イテレーション回数, 現在の全パラメータ辞書, 現在の目的関数値)。

• print_interval -- int: 進捗状況をコンソールに出力するイテレーション間隔。0の場合は出力しません。

• rel_step -- float: 共分散計算のための数値ヤコビアン計算の相対ステップサイズ。

• abs_step -- float: 共分散計算のための数値ヤコビアン計算の絶対ステップサイズ。

戻り値:

MinimizeLSQResult: 最適化結果を格納したデータクラス。

例外:

• ImportError -- scipy がインストールされていない場合。

• ValueError -- model_func の出力サイズと y のサイズが一致しない場合。