sparsetune

開発状況: v0.1.11 最終更新: 2026-07-31

sparsetune は、ユーザーの疎行列に対して利用可能な CPU / GPU 線形ソルバを 隔離環境で比較し、再現可能な性能・精度レポートと推奨構成を生成する クロスバックエンド・オートチューナーです。

ソルバそのものを再実装するのではなく、既存バックエンドを安全かつ公平に比較し、 「この行列を一度解く場合」と「同じ行列を繰り返し解く場合」のそれぞれに適した バックエンドを選びます。

[!IMPORTANT] v0.1.11 は PyPI から利用できます。実GPUでの機能検証には Google Colab GPU validation notebookを 使用できます。2026-07-31 の v0.1.11 Tesla T4 実行結果は GPU機能検証レポートにまとめています。

主な特徴

• ユーザー行列中心 — Matrix Market 形式の疎行列を渡すだけで比較
• CPU / GPU 横断比較 — SciPy（CPU）と CuPy（NVIDIA CUDA）に対応
• サブプロセス隔離 — タイムアウト、OOM、プロセスクラッシュをバックエンド単位で捕捉
• 2 種類の性能評価 — 一回の求解向け end-to-end と反復利用向け steady-state
• 独立した精度検証 — 各バックエンドの解を CPU 上で再検証
• 再現可能なレポート — ハードウェア、ドライバ、ライブラリのバージョンを記録
• チューニング結果の再利用 — tune と solve を分離し、毎回の再計測を回避

対応環境

inspect は非正方行列も受け付け、形状と構造を診断します。CG を実行する bench、tune、solve は正方行列だけを対象とします。複素数、密行列形式、 マルチ GPU、マルチ RHS、PyTorch、MPS、GMRES、BiCGSTAB、直接法は対象外です。

インストール

PyPI から CPU 版をインストールできます。

pip install "sparsetune==0.1.11"

CUDA を利用する場合は、環境に合う追加依存関係を指定します。

# CUDA 12.x
pip install "sparsetune[cuda12]==0.1.11"

# CUDA 13.x
pip install "sparsetune[cuda13]==0.1.11"

Python 3.10〜3.14をサポートし、CIで各versionを継続検証します。 必須依存関係は NumPy 1.24 以上と SciPy 1.10 以上です。SciPy 1.10/1.11 の tol と新しいSciPyの rtol の両CG呼び出し規約に対応します。CuPy は任意依存で、 import sparsetune の時点では GPU 検出などの副作用を発生させません。

Google Colab でGPU検証

このノートブックはproduction PyPIの sparsetune==0.1.11 をインストールし、割り当てられた NVIDIA GPU上でCPU/GPUの収束、相対残差、計測結果、推奨を検証してJSONへ保存します。 ColabのGPU、CPU割り当て、クロック、セッション寿命は変動するため、結果は機能検証であり、 安定した性能ベースラインではありません。

クイックスタート

1. 環境を確認する

sparsetune doctor

2. 行列を調べる

sparsetune inspect model.mtx --format table

3. バックエンドを比較する

sparsetune bench model.mtx \
  --backends scipy,cupy \
  --runs 5 \
  --rtol 1e-6 \
  --format table

4. 推奨構成を保存する

sparsetune tune model.mtx --output model.profile.json

5. 保存した構成で解く

sparsetune solve model.mtx \
  --profile model.profile.json \
  --rhs rhs.mtx \
  --output x.mtx

右辺ベクトルを省略した場合は、x = ones を真の解として b = A @ x を生成します。 --profile の代わりに --backend scipy:cpu のようにバックエンドを直接指定することも できます。

CLIのstdoutには、成功・失敗とも解ベクトルを含まない小さなJSON metrics （status、残差、反復回数、計測時間など）を出力します。解ベクトルは --output 指定時だけMatrix Market fileへ保存され、stdoutへ重複出力されません。 --quiet はprogressとmetricsを抑制し、結果はexit codeで判定できます。 Python APIの SolveResult.x は引き続き完全な解ベクトルを保持します。

CLI

代表的なベンチマークオプション:

すべてのオプションと出力スキーマは CLI 仕様を参照してください。

Python API

import sparsetune
from sparsetune import SolveStatus

A = sparsetune.load_matrix("model.mtx")

profile = sparsetune.tune(
    A,
    backends=["scipy:cpu", "cupy:cuda:0"],
    dtype="float64",
    runs=5,
)

result = sparsetune.solve(A, profile=profile)

if result.status == SolveStatus.CONVERGED:
    x = result.x
    print(result.backend, result.total_seconds)
else:
    print(result.status, result.error)

主な公開 API は list_backends()、load_matrix()、inspect()、 benchmark()、tune()、solve() です。solve() は解ベクトルだけでなく、 バックエンド、反復回数、残差、所要時間、終了ステータスを含む SolveResult を返します。

入力行列と SPD 判定

対応する Matrix Market 入力:

• coordinate 形式
• real または integer
• symmetric、general、skew-symmetric
• inspect では非正方行列も可。bench、tune、solve では正方行列

CG は対称正定値（SPD）行列向けの反復法です。sparsetune の事前診断は、 対称性と正の対角成分を確認するスクリーニングであり、正定値性を証明しません。

• screen_passed — 対称かつ対角成分が正。CG を実行
• unknown — --assume-spd 指定時のみ、ユーザー責任で実行
• failed — 非対称または非正方。CG を拒否

ベンチマーク方法

行列ファイルの読込、CSR正規化、RHS生成は親プロセスで先に行うため、どちらの モードにも含みません。setup_seconds はbackend準備、solve_seconds は求解と同期、 transfer_seconds は解の取得、total_seconds はこれらを合わせたworker内の実時間です。 steady-stateの順位付けには solve_seconds を使い、解の取得時間は含めません。

各バックエンドは独立した worker プロセスで実行されます。モードごとに1回の 計測外warmupを行い、デフォルトではその後に5回計測して中央値を採用します。 あるモードの全sampleがCPU上の独立残差検証にも合格した converged の場合だけ、 そのbackendを同モードの推奨対象にします。一方のモードの失敗は他方の推奨を 無効にしません。

推奨理由と break-even

CPU が一回の求解で最速の場合、end_to_end は次の形になります。

{
  "mode": "end-to-end",
  "backend": "scipy:cpu",
  "reason": "Fastest converged end-to-end result (0.0031 seconds)",
  "speedup": 1.7,
  "break_even_solves": null
}

GPU が反復利用で最速の場合、転送・セットアップの初期コストを回収する求解回数も 記録されます。

{
  "mode": "steady-state",
  "backend": "cupy:cuda:0",
  "reason": "Fastest converged steady-state result (0.0012 seconds)",
  "speedup": 2.4,
  "break_even_solves": 8
}

この例では、同じ行列を 8 回以上解くと GPU の初期コストを回収できる計算です。 break_even_solves は最初の求解を1回目とする正の整数で、steady-stateの節約がない 場合や比較可能なCPU結果がない場合は null です。 時間、speedup、break-even は行列と実行環境ごとに変わるため、実際の JSON レポートを 判断に使用してください。収束した GPU 結果がない場合は CPU が選ばれ、 break_even_solves は null になります。

主な終了ステータス:

• converged — 収束し、独立残差検証にも合格
• accuracy_failed — ソルバは成功を返したが、残差が許容値を超過
• max_iter / breakdown — 反復上限到達または数値的破綻
• nan_inf — 解に NaN または Inf を検出
• oom / timeout / process_crash — 隔離 worker 内の実行エラー
• unsupported / internal_error — 非対応構成または内部エラー

アーキテクチャ

CLI / Python API
        |
        v
Matrix Inspector -> Experiment Planner
        |
        v
Subprocess Runner
  |- SciPy Worker (CPU)
  `- CuPy Worker  (CUDA)
        |
        v
Independent Validator (CPU)
        |
        v
Recommender -> Profile Cache / JSON

サブプロセス分離により、バックエンド単位のタイムアウト、CUDA コンテキストの破棄、 メモリアロケータの分離、セグメンテーションフォルトからの親プロセス保護を行います。 bench、tune、プロファイル付き solve が利用するGPU可用性と実行環境IDも 検証済みのプローブサブプロセスから取得します。明示的な環境診断である list_backends() と sparsetune doctor だけは、呼び出し元プロセスでCUDAを検出します。

doctor、benchmark JSON、profile JSON は同じ実行環境fieldを使用します。CPUは cpu_model、cpu_cores_physical、blas_implementation、SciPy versionを、 GPUは gpu_uuid、gpu_model、cuda_driver、cuda_runtime、cupy_version を backend identityとして記録します。取得できないportable fieldは null です。 選択backendのidentity変更はprofile mismatch、Python/NumPy/SciPy/CPU/BLAS変更は 明示的なstale-profile opt-inが必要です。

ロードマップ

次の項目は計画であり、上記の v0.1.11 の対応範囲には含まれません。

ドキュメント

• 機能仕様書 SPEC v2.1
• 開発ワークフロー
• v0.1.11 リリース候補検証レポート
• Tesla T4 GPU機能検証レポート
• v0.1.11 リリースノート
• Google Colab GPU validation notebook

ライセンス

MIT License