Metadata-Version: 2.4
Name: jijzept_solver
Version: 2.0.0b1
Summary: A client for JijZept Solver API.
Author-email: "Jij Inc." <info@j-ij.com>
License: JijZept Solver Terms of Use
        
        Please read these terms and conditions carefully before using JijZept Solver.
        
        1. Interpretation and Definitions
        
        The words in which the initial letter is capitalized have meanings defined under the following conditions. The following definitions shall have the same meaning regardless of whether they appear in the singular or in the plural.
        
        For these Terms and Conditions:
        
        (a) "JijZept Solver" means a mathematical optimization solver provided by Jij Inc., including its web API and client software for accessing it. This term also includes sample programs provided by Us.
        (b) Company (referred to as either "the Company", "We", "Us" or "Our" in this Agreement) refers to Jij Inc., #403, CIC, 3-3-6 Shibaura, Minato-ku, Tokyo, 108-0023, JAPAN.
        (c) "Access Information" means the API hostname and access token issued for using JijZept Solver.
        
        2. Acknowledgment
        
        These are the Terms and Conditions governing the use of JijZept Solver and the agreement that operates between the User and the Company.
        These Terms and Conditions set out the rights and obligations of all users regarding the use of JijZept Solver.
        
        Your use of JijZept Solver is conditioned on Your acceptance of and compliance with these Terms and Conditions. These Terms and Conditions apply to all users who use JijZept Solver.
        
        3. Copyright
        
        (a) All intellectual property rights, including copyrights (the rights outlined in Articles 27 and 28 of the Copyright Act of Japan), trademarks, patents, etc., related to JijZept Solver belong to the Company or third parties who have granted licenses to us and are not transferred to you by agreeing to these Terms of Use.
        (b) This license does not entitle you to receive provision or disclosure of source code for any part of JijZept Solver. However, this does not apply to sample programs, OSS, etc., that we voluntarily release to the public or that we are required to release based on a license from third parties.
        
        4. JijZept Solver Service Agreement
        
        You must enter into a separate JijZept Solver service agreement to access JijZept Solver.
        
        5. Prohibitions
        
        (a) Analyzing the structure, functions of JijZept Solver by reverse engineering, decompiling, disassembling, or other means or to obtain its source code.
        (b) Duplicating or adapting all or part of the client software contained in the Software without the Company's prior consent.
        (c) Publishing a copy of JijZept Solver on a computer network that can be accessible by a third party.
        (d) Disclosing access information to a third party or publishing them.
        (e) Other use beyond the scope permitted by these Terms of Use.
        
        6. Limitation of liability
        
        (a) The Company does not guarantee the accuracy, effectiveness, or optimality of the calculation results of JijZept Solver.
        (b) The Company shall not be liable for any failure of the Software to operate when the User uses or uses the Software for the User's customer by incorporating or linking it with the User-provided Software.
        (c) The User shall be responsible for confirming and examining the suitability of the relevant foreign laws and regulations applicable to the use of the Software. The Company shall not be liable for any legal liabilities related to the appropriate foreign laws and regulations.
        
        Enacted 13 June 2025.
        
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Requires-Dist: certifi>=2025.0.0
Requires-Dist: grpcio<2.0.0,>=1.69.0
Requires-Dist: ommx<3.0.0,>=2.0.0
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: requests; extra == "dev"
Dynamic: license-file

# JijZept Solver

Jij 製の数理最適化ソルバーである JijZept Solver を 、Web API 経由で実行するための クライアントパッケージです。以下に使用方法を説明します。 / Client package for executing JijZept Solver, Jij's mathematical optimization solver, via Web API. The following explains how to use it.

## Quick Start

### アクセストークンの取得 / Obtaining Access Token

JijZept Solver(無償WebAPI版) を使用するには、事前にアクセストークンを取得する必要があります。無償版の利用申請方法は以下の通りです。 / To use JijZept Solver (Free Web API version), you need to obtain an access token in advance. The application method for the free version is as follows.

#### 利用申請方法 / Application Method

1. 以下リンク先のフォームから利用申請を行ってください。 / Please apply for usage from the form at the following link.

   **申請フォーム / Application Form**: [JijZept Solver(無償WebAPI版) 利用申請フォーム / JijZept Solver (Free Web API version) Usage Application Form](https://docs.google.com/forms/d/e/1FAIpQLScLTRxXGaN7egRkoYcq2ZvFoFXRyYInsmPXlyxk9pF11E9--g/viewform)

2. 申請されたメールアドレス宛に、アクセスに必要な情報（API サーバーのホスト名、アクセストークン）が届きます。 / The information required for access (API server hostname, access token) will be sent to the email address you applied with.

### インストール / Installation

JijZept Solver のクライアントパッケージをインストールします。2.x 系はベータ版のため `--pre` の指定が必要です。 / Install the JijZept Solver client package. The `--pre` flag is required while the 2.x series is in beta:

```bash
pip install --pre jijzept-solver
```

### 環境変数の設定 / Environment Variable Setup

上記利用申請により入手した、以下の値を環境変数に設定します / Set the following values obtained from the above application as environment variables:

- **`JIJZEPT_SOLVER_SERVER_HOST`**: API サーバーのホスト名 / API server hostname

- **`JIJZEPT_SOLVER_ACCESS_TOKEN`**: アクセストークン / Access token

### 設定例 / Configuration Examples

環境変数の設定例 / Environment variable configuration example:

```bash
export JIJZEPT_SOLVER_SERVER_HOST="API サーバーのホスト名 / API server hostname"
export JIJZEPT_SOLVER_ACCESS_TOKEN="アクセストークン / Access token"
```

または Python コード内で設定する例 / Or example of setting within Python code:

```python
import os

os.environ["JIJZEPT_SOLVER_SERVER_HOST"] = (
    "API サーバーのホスト名 / API server hostname"
)
os.environ["JIJZEPT_SOLVER_ACCESS_TOKEN"] = "アクセストークン / Access token"
```

### リクエスト実行例 / Request Execution Example

実行例の中で JijModeling を使用するため、事前にインストールしておきます（この例は jijmodeling 2.x の API を使用しています）。 / Install JijModeling in advance as it is used in the execution example (the example uses the jijmodeling 2.x API).

```bash
pip install jijmodeling
```

ナップサック問題を解く例 / Example of solving a knapsack problem:

```python
import logging
import jijzept_solver
import jijmodeling as jm

logging.basicConfig(level=logging.INFO)

# ナップサック問題を定義 / Define knapsack problem
problem = jm.Problem("Knapsack", sense=jm.ProblemSense.MAXIMIZE)
v = problem.Float("v", ndim=1)  # アイテムの価値 / Item values
w = problem.Float("w", ndim=1)  # アイテムの重さ / Item weights
W = problem.Float("W")  # ナップサックの容量 / Knapsack capacity
x = problem.BinaryVar("x", shape=v.len_at(0))  # 決定変数 / Decision variables

# 目的関数：価値の最大化 / Objective function: maximize value
problem += (v * x).sum()

# 重量制約 / Weight constraint
problem += problem.Constraint("weight", (w * x).sum() <= W)

# インスタンスデータから OMMX インスタンスを作成 / Create OMMX instance from data
instance = problem.eval(
    {
        "v": [10, 13, 18, 31, 7, 15],  # アイテムの価値 / Item values
        "w": [11, 15, 20, 35, 10, 33],  # アイテムの重さ / Item weights
        "W": 47,  # ナップサックの容量 / Knapsack capacity
    }
)

# APIにリクエストを実行 / Execute API request
solution = jijzept_solver.solve(instance, time_limit=2.0)

print(f"Value of the objective function: {solution.objective}")
```

## API リファレンス / API Reference

JijZept Solver を使用して最適化問題を解きます。 / Solve optimization problems using JijZept Solver.

**パラメータ:** / **Parameters:**

- `instance` (Instance): 解きたい問題の OMMX インスタンス / The OMMX instance to solve.
- `time_limit` (float, optional): 求解の制限時間（秒）。省略した場合は、API プランの上限時間が適用されます。API プランの上限を超える値はエラーになります。 / Time limit in seconds. If omitted, the maximum time limit of the API plan is applied. Values exceeding the API plan maximum are rejected.
- `gap_limit` (float, optional): 相対最適性ギャップの許容値。例: 0.01 は 1%（デフォルト 0.0001）。 / Relative optimality gap tolerance, e.g. 0.01 for 1% (default 0.0001).
- `presolve` (bool, optional): presolve（前処理）を有効にするかどうか（デフォルト: 有効）。 / Enable presolve (default: enabled).
- `structure` (Structure, optional): 問題の構造情報。構造に応じた推奨オプションのプリセットも適用されます。明示的に指定した引数はプリセットより優先されます。 / Structure describing problem structure. Also applies the structure's recommended option preset; explicitly passed arguments override the preset.
- `initial_state` (State, optional): ソルバーが探索を開始する初期解（`ommx.v1.State`）。初期解には、この API を通じて JijZept Solver が生成した解を使用することを推奨します。 / Optional initial solution as `ommx.v1.State`. When using `initial_state`, we recommend a solution generated by JijZept Solver through this API.

**戻り値:** / **Return Value:**

- `Solution`: OMMX ソリューション / OMMX solution

**例:** / **Example:**

```python
solution = jijzept_solver.solve(instance, time_limit=2.0)
```
