Metadata-Version: 2.4
Name: kaiwu
Version: 1.4.1
Summary: Kaiwu SDK for CIM or QUBO.
Author: Qboson Inc
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: numpy==2.2.6
Requires-Dist: pandas==2.2.3
Requires-Dist: requests==2.32.3
Requires-Dist: pyjwt[crypto]==2.10.1
Requires-Dist: portion==2.6.1
Requires-Dist: Deprecated==1.2.18
Requires-Dist: matplotlib==3.10.3
Requires-Dist: httpx==0.28.1
Requires-Dist: nest-asyncio==1.6.0
Requires-Dist: kaiwu-community==1.0.7
Dynamic: author
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# Kaiwu SDK Enterprise

Kaiwu SDK Enterprise is a Python SDK for building and solving QUBO and Ising optimization problems with Kaiwu classical optimizers and CIM services.

This package is the enterprise distribution. A valid license is required before using licensed features.

## Requirements

- Python >= 3.10
- Windows, Linux, or macOS

## Installation

Install from PyPI:

```bash
pip install kaiwu
```

Install a specific version:

```bash
pip install kaiwu==1.4.1
```

## Quick Start

### Solve an Ising Matrix

```python
import numpy as np
import kaiwu as kw

matrix = -np.array(
    [
        [0.0, 1.0, 0.0, 1.0, 1.0],
        [1.0, 0.0, 0.0, 1.0, 1.0],
        [0.0, 0.0, 0.0, 1.0, 1.0],
        [1.0, 1.0, 1.0, 0.0, 1.0],
        [1.0, 1.0, 1.0, 1.0, 0.0],
    ]
)

optimizer = kw.classical.SimulatedAnnealingOptimizer(
    initial_temperature=100,
    alpha=0.99,
    cutoff_temperature=0.001,
    iterations_per_t=10,
    size_limit=10,
)

solutions = optimizer.solve(matrix)
print(solutions)
```

### Solve a QUBO Matrix

`solve_qubo()` accepts a `QuboModel`. If you already have a QUBO matrix, convert it first:

```python
import numpy as np
import kaiwu as kw

qubo_matrix = -np.array(
    [
        [0.0, -1.0, 0.0, 1.0, 1.0],
        [-1.0, 0.0, 0.0, 1.0, 1.0],
        [0.0, 0.0, 0.0, 1.0, 1.0],
        [1.0, 1.0, 1.0, 0.0, 1.0],
        [1.0, 1.0, 1.0, 1.0, 0.0],
    ]
)

# QUBO matrix conversion uses the upper-triangular convention.
qubo_model = kw.core.qubo_matrix_to_qubo_model(np.triu(qubo_matrix))

optimizer = kw.classical.SimulatedAnnealingOptimizer(
    initial_temperature=100,
    alpha=0.99,
    cutoff_temperature=0.001,
    iterations_per_t=10,
    size_limit=10,
)

solution, objective = optimizer.solve_qubo(qubo_model)
print(solution)
print(objective)
```

### Use CIMOptimizer

`CIMOptimizer` submits or queries CIM tasks. Set a checkpoint directory before creating the optimizer.

```python
import numpy as np
import kaiwu as kw

kw.common.CheckpointManager.save_dir = "tmp"

qubo_matrix = np.array(
    [
        [0.0, 1.0, 0.0],
        [0.0, 0.0, -2.0],
        [0.0, 0.0, 0.0],
    ]
)
qubo_model = kw.core.qubo_matrix_to_qubo_model(np.triu(qubo_matrix))

optimizer = kw.cim.CIMOptimizer(
    task_name="qubo_cim_example",
    wait=False,
    task_mode=kw.cim.TaskMode.OPTIMIZATION,
)

solution, objective = optimizer.solve_qubo(qubo_model)
print(solution, objective)
```

When `wait=False`, unfinished tasks may return `(None, None)`. Use `wait=True` if the program should wait for the task result.

## Main Modules

- `kaiwu.classical`: classical optimizers, including simulated annealing, tabu search, and brute force search
- `kaiwu.cim`: CIM task optimizer and task modes
- `kaiwu.preprocess`: matrix precision analysis and precision reduction tools
- `kaiwu.hybrid`: hybrid optimization tools
- `kaiwu.sampler`: sampler implementations
- `kaiwu.hobo`: higher-order binary optimization tools

## Logging

Enable debug logs when needed:

```python
import kaiwu as kw

kw.common.set_log_level("DEBUG")
```
