sparsetune 0.1.0

Cross-backend sparse linear solver auto-tuner

sparsetune

開発状況: v0.1.0 リリース候補 最終更新: 2026-07-26

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

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

[!IMPORTANT] CLI と Python API は実装済みですが、v0.1.0 はまだ PyPI に公開されていません。 現在はソースからインストールして利用してください。

主な特徴

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

対応環境

項目	v0.1.0
Python	3.10 以上
CPU バックエンド	SciPy (scipy:cpu)
GPU バックエンド	CuPy (cupy:cuda:N)
GPU	NVIDIA CUDA 12.x / 13.x
ソルバ	各バックエンドのネイティブ CG
入力	Matrix Market coordinate（real / integer）

v0.1.0 では正方行列のみを対象とし、複素数、密行列形式、マルチ GPU、 マルチ RHS、PyTorch、MPS、GMRES、BiCGSTAB、直接法は対象外です。

インストール

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

git clone https://github.com/takurot/sparse-tune.git
cd sparse-tune
pip install .

PyPI 公開後は pip install sparsetune でインストールできます。CUDA を利用する場合は、 環境に合う追加依存関係を指定します。

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

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

必須依存関係は NumPy 1.24 以上と SciPy 1.10 以上です。CuPy は任意依存で、 import sparsetune の時点では GPU 検出などの副作用を発生させません。

クイックスタート

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

コマンド	説明
sparsetune inspect <matrix>	形状、非ゼロ要素数、対称性などを表示
sparsetune bench <matrix>	利用可能なバックエンドを比較
sparsetune tune <matrix>	比較結果と推奨構成をプロファイルに保存
sparsetune solve <matrix>	プロファイルまたは指定バックエンドで求解
sparsetune doctor	Python、ライブラリ、CUDA、GPU の情報を表示
sparsetune --version	バージョンを表示

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

オプション	デフォルト	説明
--backends	scipy,cupy	比較するバックエンド
--dtype	float64	float32 または float64
--measure	end-to-end,steady-state	計測モード
--runs	5	試行回数。中央値を採用
--rtol	1e-6	相対収束許容値
--atol	0.0	絶対収束許容値
--max-iter	10000	最大反復回数
--timeout	300.0	バックエンドごとの制限時間（秒）
--assume-spd	無効	SPD と仮定して CG を実行
--format	json	json、table、csv

すべてのオプションと出力スキーマは 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
• 正方行列

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

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

ベンチマーク方法

モード	評価する時間	想定用途
end-to-end	CSR 正規化、転送、前処理、求解、結果転送	行列を一度だけ解く
steady-state	デバイス上に行列を保持した状態での求解	同じ行列を繰り返し解く

各バックエンドは独立した worker プロセスで実行されます。デフォルトでは 5 回計測し、 中央値を採用します。推奨対象になるのは、CPU 上で計算した独立残差検証にも合格した converged の結果だけです。

推奨理由と break-even

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

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

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

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

この例では、同じ行列を 8 回以上解くと GPU の初期コストを回収できる計算です。 時間、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 コンテキストの破棄、 メモリアロケータの分離、セグメンテーションフォルトからの親プロセス保護を行います。

ロードマップ

バージョン	予定内容
v0.1.0	リリース準備中: SciPy / CuPy、ネイティブ CG、隔離実行、CLI、プロファイル
v0.1.1	PyPI 公開、README、CI/CD
v0.2.0	PyTorch CUDA、GMRES / BiCGSTAB、メモリ測定改善
v0.3.0	MPS 実験対応、統一 CG、AMGX の検討

ドキュメント

• 機能仕様書 SPEC v2.1
• 開発ワークフロー
• v0.1.0 検証レポート
• v0.1.0 リリースノート

ライセンス

MIT License