---
sd_hide_title: true
hide-toc: true
---

# NEC

(clients-NECVA2Client)=

## NEC Vector Annealing (VA) サービス 2.0

[NEC](https://jpn.nec.com/nec-vector-annealing-service/) の提供する QUBO ソルバーです。ベクトル型スーパーコンピュータ SX-Aurora TSUBASA 上で動作します。

Amplify SDK の提供する {py:class}`~amplify.NECVA2Client` を使用することで、リクエストパラメータの自動検出・自動設定を行いながら NEC Vector Annealing サービス 2.0 API を呼び出すことができます。

:**ソルバー仕様**:

    ```{list-table}
    :width: 100%
    :widths: 2 3
    * - クライアントクラス
      - {py:class}`amplify.NECVA2Client`
    * - [実行パラメータ](amplify.NECVA2Client.parameters){sup}`1`
      - {py:class}`amplify.NECVA2Client.Parameters`
    * - [実行結果](amplify.Result.client_result){sup}`2`
      - {py:class}`amplify.NECVA2Client.Result`
    * - [実行時間](amplify.Result.execution_time) ([詳細](#clients-NECVA2Client-exectime))
      - {py:attr}`amplify.NECVA2Client.Result.Timing.execution_time`
    * - API 方式{sup}`3`
      - SAC サービスクライアント (Python)
    * - API リファレンス
      - [{bdg-info}`📖 User Guide`](/../_static/nec_vector_annealing_service_2.0_user_guide_v4.pdf)
    ```
    1: [API リファレンス「3-3-2 solve_paramsのパラメータ」](/../_static/nec_vector_annealing_service_2.0_user_guide_v4.pdf)に相当します  
    2: [API リファレンス「3-4.レスポンス」](/../_static/nec_vector_annealing_service_2.0_user_guide_v4.pdf)に相当します  
    3: 追加インストールの必要はありません

    ```{csv-table}
    :header-rows: 1
    :stub-columns: 1
    :width: 100%
    :widths: 1 1 1 1 1
    ,バイナリ変数,イジング変数,整数変数,実数変数
    目的関数,2次,\-,\-,\-
    等式制約,\*,\-,\-,\-
    不等式制約,\*,\-,\-,\-
    ```

    \*: 後述する1次または2次の特別な制約条件に対応しています。

:**クライアントクラス**:

    [クライアントクラスの共通インターフェース](#client-common-interface) に加えて以下のアトリビュートを持ちます。

    ```{list-table}
    :width: 100%
    :header-rows: 1
    :widths: 1 1 3
    * - アトリビュート
      - データ型
      - 詳細
    * - {py:attr}`~amplify.NECVA2Client.set_fixed`
      - {py:class}`bool`
      - {py:obj}`True` に設定すると、モデルの持つ制約条件の中から fixed 制約を可能な限り検出してフリップオプションの `fixed` パラメータに与えます (デフォルト: {py:obj}`True`)
    * - {py:attr}`~amplify.NECVA2Client.set_onehot`
      - {py:class}`bool`
      - {py:obj}`True` に設定すると、モデルの持つ制約条件の中から onehot 制約を可能な限り検出してフリップオプションの `onehot` パラメータに与えます (デフォルト: {py:obj}`True`)
    * - {py:attr}`~amplify.NECVA2Client.set_andzero`
      - {py:class}`bool`
      - {py:obj}`True` に設定すると、モデルの持つ制約条件の中から andzero 制約を可能な限り検出してフリップオプションの `andzero` パラメータに与えます (デフォルト: {py:obj}`True`)
    * - {py:attr}`~amplify.NECVA2Client.set_orone`
      - {py:class}`bool`
      - {py:obj}`True` に設定すると、モデルの持つ制約条件の中から orone 制約を可能な限り検出してフリップオプションの `orone` パラメータに与えます (デフォルト: {py:obj}`True`)
    * - {py:attr}`~amplify.NECVA2Client.set_supplement`
      - {py:class}`bool`
      - {py:obj}`True` に設定すると、モデルの持つ制約条件の中から supplement 制約を可能な限り検出してフリップオプションの `supplement` パラメータに与えます (デフォルト: {py:obj}`True`)
    * - {py:attr}`~amplify.NECVA2Client.set_maxone`
      - {py:class}`bool`
      - {py:obj}`True` に設定すると、モデルの持つ制約条件の中から maxone 制約を可能な限り検出してフリップオプションの `maxone` パラメータに与えます (デフォルト: {py:obj}`True`)
    * - {py:attr}`~amplify.NECVA2Client.set_minmaxone`
      - {py:class}`bool`
      - {py:obj}`True` に設定すると、モデルの持つ制約条件の中から minmaxone 制約を可能な限り検出してフリップオプションの `minmaxone` パラメータに与えます (デフォルト: {py:obj}`True`)
    ```

    フリップオプションの各制約は、係数を含めて以下の形と一致する制約条件式が設定されたときのみ検出されます。
    $q_1, q_2, \dots , q_N$ （$N$ は自然数）を互いに独立なバイナリ変数、$m, n, k$ を整数定数とします。
    ```{list-table}
    :width: 100%
    :header-rows: 1
    :widths: 1 3
    * - {py:obj}`True` に設定する  
    アトリビュート
      - 検出する制約条件の形
    * - {py:attr}`~amplify.NECVA2Client.set_fixed`
      - $q_1 + k = k$  
      $q_1 + k = k + 1$
    * - {py:attr}`~amplify.NECVA2Client.set_onehot`
      - $q_1 + q_2 + \cdots + q_N + k = k + 1$
    * - {py:attr}`~amplify.NECVA2Client.set_andzero`
      - $q_1 + q_2 + \cdots + q_N + k \leq k + N - 1$  
      $n q_1 q_2 + k = k$
    * - {py:attr}`~amplify.NECVA2Client.set_orone`
      - $q_1 + q_2 + \cdots + q_N + k \geq k + 1$  
      $n (q_1 - 1)(q_2 - 1) + k = k$
    * - {py:attr}`~amplify.NECVA2Client.set_supplement`
      - $n (q_1 - q_2 q_3) + k = k$
    * - {py:attr}`~amplify.NECVA2Client.set_maxone`
      - $q_1 + q_2 + \cdots + q_N + k \leq n \quad (0 \leq n - k \leq N)$
    * - {py:attr}`~amplify.NECVA2Client.set_minmaxone`
      - $m \leq q_1 + q_2 + \cdots + q_N + k \leq n \quad (0 \leq m - k, n - k \leq N)$
    ```

    ```{note}
    フリップオプションが有効であるかにかかわらず、制約条件は必要に応じてペナルティ関数として目的関数に追加されます。
    ```
(clients-NECVA2Client-exectime)=

:**実行時間**:

    NEC VA 2.0 は VA の各サンプリングの実行時間を返却しますが、一方で求解全体に要した実行時間は返却されません。{py:class}`~amplify.NECVA2Client` では、サンプリング時間に加えて、独自に SAC サービスクライアントの `solve_qubo()` API のレスポンス時間 ({py:attr}`~amplify.NECVA2Client.Result.Timing.solve_qubo_time`) 、このうち VA の実行に係る時間 ({py:attr}`~amplify.NECVA2Client.Result.Timing.execution_time`) およびキュー待ち時間 ({py:attr}`~amplify.NECVA2Client.Result.Timing.queue_time`)を計測し返却します。これらは実行結果クラスの {py:attr}`~amplify.NECVA2Client.Result.timing` アトリビュートに格納されます。

    ```{list-table}
    :width: 100%
    :header-rows: 1
    :widths: 2 3
    * - アトリビュート
      - 詳細
    * - {py:attr}`amplify.NECVA2Client.Result.Result.time`
      - VA の各サンプリングの実行時間
    * - {py:attr}`amplify.NECVA2Client.Result.Timing.solve_qubo_time`
      - `solve_qubo()` Python API のレスポンス時間
    * - {py:attr}`amplify.NECVA2Client.Result.Timing.execution_time`
      - VA の実行時間 (ネットワークオーバーヘッド・キュー待ち時間等を含む)
    * - {py:attr}`amplify.NECVA2Client.Result.Timing.queue_time`
      - キュー待ち時間
    ```

:**設定例**:

    ```{testcode}
    from amplify import NECVA2Client

    client = NECVA2Client()

    # API トークンを設定
    client.token = "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

    # 速度優先モードで実行
    client.parameters.vector_mode = "speed"
    ```

:**実行例**:

    ```python
    from amplify import VariableGenerator, Model, solve

    # 決定変数と目的関数を定義
    g = VariableGenerator()
    q = g.array("Binary", 2)
    f = q[0] * q[1] + q[0] - q[1] + 1

    # モデルを作成
    model = Model(f)

    # ソルバーを実行
    result = solve(model, client)

    # API の実行時間を表示
    print(result.execution_time)
    ```

    ソルバーのバージョンを取得:

    ```python
    >>> client.version
    '2.0.2'
    ```