# はじめに

🌐 **日本語** | [English](intro_en.md)

**JijZept Tools** は、最適化計算における開発ワークフローを支援する SDK (Software Development Kit) です。
数理最適化ワークフローを素早く検証し、実験の管理・可視化・チューニングなどの開発プロセスを効率化することを目的としています。

---

## 主な特徴

1. **ブラックボックス最適化**  
   - BOCS (Bayesian Optimization for Combinatorial Structures)
   - Factorization Machine を用いた最適化手法

2. **ワークフロー管理**  
   - 直観的なノード単位の処理フロー (DAG) を定義し、ステート管理とともに一貫した実行を行う `WorkflowGraph` 機能

3. **モデルユーティリティ**  
   - JijModeling や ommx などの外部ライブラリと連携し、バイナリ変数や整数変数を連続化する関数など、最適化モデルを扱う上で役立つツールを提供

4. **実験ダッシュボード (experimental)**  
   - `minto`で管理された実験結果を可視化・インタラクティブに分析  

5. **今後の拡張予定**  
   - 列生成法などの数理最適化アルゴリズムの追加
   - 実験管理ツール (Experiment Tracking, パラメータ管理、可視化など) のさらなる拡充
   - 他の最適化ソルバやフレームワークとの連携強化

---

## 簡単な使い方

### ブラックボックス最適化

```python
import numpy as np
from jijzepttools.blackbox_optimization import BOCSWorkflow

# 最適化対象の (X, y) データを用意
X = np.random.binomial(1, 0.5, size=(100, 10))
y = np.sum(X, axis=1)

# BOCSWorkflow のインスタンス化
bocs = BOCSWorkflow(random_seed=42)

# ブラックボックス関数とソルバを定義
def blackbox_func(x):
    return np.sum(x)

def solver(instance):
    # instanceには QUBO やパラメータが渡される想定
    # ここでは簡単のため乱数でスピンを返す
    return np.random.binomial(1, 0.5, size=10)

# 反復回数を指定して最適化を実行
X_new, y_new = bocs.run(X, y, blackbox_func, solver, n_iter=5)
print("最終的な X:", X_new)
print("最終的な y:", y_new)
```

### ワークフロー管理

```python
from jijzepttools.workflow.workflow import WorkflowGraph
import dataclasses

@dataclasses.dataclass
class MyState:
    counter: int = 0

def increment(x, state: MyState):
    state.counter += 1
    return x + 1

workflow = WorkflowGraph(MyState)

# Node 1 → Node 2 → END の流れを定義
workflow.add("process1", increment).add("process2", lambda x: x * 2)

# 入力値 5 と初期ステートを渡して実行
result = workflow.run(5, MyState())
print(result)  # => 12 (例)
```

### 実験ダッシュボード (experimental)

```python
from jijzepttools.experimental.dashboard import dashboard
import minto

# minto.Experiment で管理している実験データを可視化
exp = minto.Experiment("my_experiment", auto_saving=False)
# いくつかの実験を実行して結果を記録した後...

# pygwalker を使ってデータフレームをインタラクティブに分析
dashboard(exp)
```