レギュレーション

from hackb_judge import Problem, Evaluator  # optional, type-only

def solve(problem: Problem, evaluate: Evaluator) -> object:
    ...

pip install hackb-judge で IDE 補完が効きます。実行時依存はありません。

• problemREQUIRED

  TYPE

  Problem (TypedDict)

  ジャッジサーバが solve の第 1 引数として渡す TypedDict です。次のキーを持ちます。
  EXAMPLE

  {
      "problem_id": "sphere-5d",
      "search_space": {
          "variables": [
              {"name": "x1", "type": "continuous", "lower": -5.12, "upper": 5.12},
              {"name": "x2", "type": "continuous", "lower": -5.12, "upper": 5.12},
          ],
      },
      "budget": 100,
      "seed": 42,
      "initial_data": [
          {"x": {"x1": 0.0, "x2": 0.0}, "y": 0.0},
      ],
  }

  • problem_idREQUIRED

    TYPE

    str

    問題の識別子。提出コードからは識別用途のみで利用できます。
    EXAMPLE

    "sphere-5d"

  • search_spaceREQUIRED

    TYPE

    SearchSpace

    探索空間定義。各次元の名前 (key) と取り得る範囲 (連続値なら [low, high]、離散なら候補の列挙) を含みます。evaluate に渡す x dict のキーはこの定義に従う必要があります。
    EXAMPLE

    {
        "variables": [
            # 連続値: float, lower <= x <= upper
            {"name": "lr",        "type": "continuous",  "lower": 1e-5, "upper": 1.0},
            # 整数: int (両端含む)
            {"name": "layers",    "type": "integer",     "lower": 1,    "upper": 8},
            # カテゴリカル: choices からひとつ
            {"name": "optimizer", "type": "categorical", "choices": ["sgd", "adam"]},
            # バイナリ: 0 or 1
            {"name": "dropout",   "type": "binary"},
        ],
    }

  • budgetREQUIRED

    TYPE

    int

    目的関数の評価可能回数。solve 中の evaluate 呼び出しの上限です。超過した呼び出しはエラーとして拒否されます。
    EXAMPLE

    100

  • seedREQUIRED

    TYPE

    int

    ジャッジ側で採点に使う乱数シード。提出コード側でも乱数を使う場合は、このシードを利用することで再現性を担保できます。
    EXAMPLE

    1

  • initial_dataOPTIONAL

    TYPE

    list[InitialPoint]

    DEFAULT

    []

    事前にラベル付けされた観測サンプル。各要素は x（search_space に従う dict）と y（観測値 float）の 2 キーを持つ dict です。問題によっては空リストとなります。
    EXAMPLE

    [
        {"x": {"x1": 0.5,  "x2": -0.3}, "y": 0.34},
        {"x": {"x1": -1.2, "x2":  0.8}, "y": 2.08},
    ]

• evaluateREQUIRED

  TYPE

  Callable[[dict[str, Any]], float]

  未知の目的関数 f を 1 点ずつ評価する callable です。amplify-bbopt のようなデコレータ系ライブラリにも、この callable を black_box 関数としてそのまま渡せます。

  • x は search_space で定義された全次元のキーを含む dict でなければなりません。値は各次元の型・範囲に従う必要があります。
  • 返り値は有限のスカラー (NaN / ±inf 不可) です。観測には観測ノイズが乗っている場合があります。
  • 1 回の呼び出しが 1 点の評価としてカウントされ、budget を超えると ValueError として拒否されます。
  • x が search_space に違反した場合は ValueError が送出されます。提出コードはこれを捕捉して再評価しても構いません (ただし呼び出し回数はカウントされます)。
  • 目的関数 f 本体および真値ラベルは提出コードからは見えません。ジャッジサーバ内のサンドボックス境界の外で実行されます。
  EXAMPLE

  # 1 点ずつ評価。ジャッジ側で budget をカウントする。
  y = evaluate({"x1": 0.5, "x2": -0.3})
  # y は float (例: 0.34)。NaN / ±inf は返らない。
  
  # search_space 違反は ValueError として上がる (呼び出しは消費される)。
  try:
      evaluate({"x1": 99.0, "x2": 0.0})
  except ValueError:
      ...
  
  # budget 超過時も ValueError。
  for _ in range(budget + 1):
      evaluate(sample_x())  # 最後の 1 回が ValueError

問題ごとの search_space / budget / initial_data の具体値は、コンテスト開始後に各問題の詳細ページから確認できます。