# Introduction

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

**JijZept Tools** is an SDK (Software Development Kit) that supports development
workflows in optimization computing.
Its goal is to let you quickly validate mathematical optimization workflows and to
streamline development processes such as experiment management, visualization, and
tuning.

---

## Main Features

1. **Black-box optimization**  
   - BOCS (Bayesian Optimization for Combinatorial Structures)
   - Optimization methods using Factorization Machines

2. **Workflow management**  
   - The `WorkflowGraph` feature, which lets you define an intuitive node-based
     processing flow (DAG) and run it consistently together with state management

3. **Model utilities**  
   - Tools that help you work with optimization models — for example, functions that
     relax binary and integer variables into continuous ones — integrating with
     external libraries such as JijModeling and ommx

4. **Experiment dashboard (experimental)**  
   - Visualize and interactively analyze experiment results managed with `minto`

5. **Planned extensions**  
   - Additional mathematical optimization algorithms such as column generation
   - Further expansion of experiment management tools (experiment tracking, parameter
     management, visualization, etc.)
   - Stronger integration with other optimization solvers and frameworks

---

## Quick Start

### Black-box optimization

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

# Prepare the (X, y) data to optimize
X = np.random.binomial(1, 0.5, size=(100, 10))
y = np.sum(X, axis=1)

# Instantiate BOCSWorkflow
bocs = BOCSWorkflow(random_seed=42)

# Define the black-box function and the solver
def blackbox_func(x):
    return np.sum(x)

def solver(instance):
    # `instance` is expected to receive a QUBO and parameters
    # For simplicity, return random spins here
    return np.random.binomial(1, 0.5, size=10)

# Run the optimization for a given number of iterations
X_new, y_new = bocs.run(X, y, blackbox_func, solver, n_iter=5)
print("Final X:", X_new)
print("Final y:", y_new)
```

### Workflow management

```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)

# Define the flow: Node 1 → Node 2 → END
workflow.add("process1", increment).add("process2", lambda x: x * 2)

# Run with input value 5 and an initial state
result = workflow.run(5, MyState())
print(result)  # => 12 (example)
```

### Experiment dashboard (experimental)

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

# Visualize experiment data managed with minto.Experiment
exp = minto.Experiment("my_experiment", auto_saving=False)
# After running some experiments and recording results...

# Use pygwalker to interactively analyze the DataFrame
dashboard(exp)
```