tkbo マニュアル

1. 役割

tkbo は、離散的な候補点集合から、次に評価する点を選ぶためのベイズ最適化・適応学習パッケージです。回帰器そのものを比較・利用する tkmlr と責務を分け、tkbo は initialize → ask → tell の探索ループを担当します。

内部は次の3層に分かれます。

層	責務
surrogate	観測データから候補点の予測平均・標準偏差を返す
acquisition	予測平均・標準偏差から候補点のスコアを計算する
backend / optimizer	候補集合、観測済み点、`ask/tell` ループを管理する

2. 推奨import

from tkbo import create_optimizer

独自バックエンド等を登録するときだけ、次を追加します。

from tkbo import register_backend, register_surrogate, register_acquisition

3. 最小例

import numpy as np
from tkbo import create_optimizer

X = np.linspace(0.0, 10.0, 101).reshape(-1, 1)
y = np.full(len(X), np.nan)

initial = np.array([0, 30, 80])
y[initial] = np.sin(X[initial, 0])

optimizer = create_optimizer(
    model="sklearn_gpr",
    acquisition="ei",
    surrogate__alpha=1.0e-8,
    surrogate__n_restarts_optimizer=10,
)
optimizer.initialize(X, y=y)

suggestion = optimizer.ask(n_points=1)
index = int(suggestion.indices[0])
value = float(np.sin(X[index, 0]))  # 実際には実験・計算を実行
optimizer.tell(index, value)

y を候補数と同じ長さにし、未観測点を np.nan とする形式が最も単純です。

4. バックエンド

`model` / `backend`	意味
`sklearn_gpr`	`CustomOptimizer` + sklearn GPR surrogate
`physbo_gp`	`CustomOptimizer` + PHYSBO surrogate
`custom`	surrogate と acquisition を明示指定
`physbo`	PHYSBO native の離散探索
`random`	未観測候補からランダム選択
`grid`	元の順序で未観測候補を返す

model="sklearn_gpr" と model="physbo_gp" は、内部で backend="custom" に変換されます。

5. acquisition関数

名前	クラス	主なパラメータ	用途
`ei`	`ExpectedImprovement`	`xi`	改善量と不確かさの両方を考慮
`pi`	`ProbabilityImprovement`	`xi`	改善確率を最大化
`ucb`	`UpperConfidenceBound`	`kappa`	平均と不確かさの加重和
`lcb`	`LowerConfidenceBound`	`kappa`	最小化向けの下側信頼限界
`stein`	`SteinLiteAcquisition`	`eps`, `std_weight`, `grad_weight`	不確かさと平均勾配を使う探索heuristic
`entropy`	`EntropySearchLite`	なし	`log(std)` による不確かさ探索

stein は厳密なSVGDではなく、有限差分した予測平均の勾配を使う実務的な探索スコアです。

6. データ契約

X_candidates: shape (n_candidates, n_features) の数値配列。1次元配列は (n, 1) に変換されます。
y: 候補数と同じ長さで、未観測を NaN にするか、observed_indices と同じ長さにします。
observed_mask: 候補数と同じ長さのbool配列。
ask() の戻り値: BOResult(indices, scores, X)。
tell(indices, y_new): 候補インデックスと新しい目的値を登録します。
maximize=False: 最小化問題として扱います。

観測点が1点もない状態では、CustomOptimizer.ask() は未観測点を先頭から返し、予測平均は NaN、標準偏差は inf になります。初期点をランダムにしたい場合は random backendを使うか、初期観測を明示してください。

7. パラメータの渡し方

create_optimizer() では、surrogate用とacquisition用のパラメータを接頭辞で分離します。

optimizer = create_optimizer(
    model="sklearn_gpr",
    acquisition="ucb",
    maximize=True,
    surrogate__alpha=1.0e-8,
    surrogate__n_restarts_optimizer=20,
    acquisition__kappa=2.5,
)

接頭辞なしの引数はoptimizer backendへ渡されます。

8. 独自acquisitionの登録

import numpy as np
from tkbo.base import BaseAcquisition
from tkbo import register_acquisition

class MeanPlusUncertainty(BaseAcquisition):
    name = "mean_plus_uncertainty"

    def __init__(self, weight=2.0):
        self.weight = float(weight)

    def __call__(self, X, mean, std, y_observed=None,
                 observed_mask=None, maximize=True, **kwargs):
        mean = np.asarray(mean, dtype=float)
        std = np.asarray(std, dtype=float)
        signed_mean = mean if maximize else -mean
        return signed_mean + self.weight * std

register_acquisition("mean_plus_uncertainty", MeanPlusUncertainty)

9. CLI

python -m tkbo.cli \
  --mode ask \
  --infile data.xlsx \
  --target "max:y" \
  --features x1,x2 \
  --model sklearn_gpr \
  --acquisition ei

CLIはpandasでCSV/Excelを読み、候補・予測・提案フラグを付加した表を出力します。正確なオプションは python -m tkbo.cli --help で確認してください。

10. 依存関係

必須コア: numpy
analytic acquisition: scipy
sklearn_gpr: scikit-learn
physbo / physbo_gp: physbo
CLI表入出力: pandas, Excelでは openpyxl

11. 生成AI向けコード生成ルール

通常は create_optimizer() を使い、backendクラスを直接生成しない。
離散候補集合を必ず先に用意し、initialize() を1回呼ぶ。
未観測目的値は NaN とし、0や空文字で代用しない。
ask() が返すのは候補のインデックスであり、目的値ではない。
実験・計算後に同じインデックスを tell() へ返す。
surrogateパラメータは surrogate__、acquisitionパラメータは acquisition__ を付ける。
連続変数最適化、制約最適化、多目的Pareto最適化を、このAPIだけで実装済みと仮定しない。
PHYSBO固有スコアとtkbo側acquisitionを混同しない。独自acquisitionには model="physbo_gp" または model="sklearn_gpr" を使う。