# Excitation RK4 Sparse
量子力学的な励起ダイナミクスを計算するための疎行列ベースのRK4ソルバー。
## 機能
- CSR形式の疎行列サポート
- OpenMPによる並列化（動的スケジューリング最適化）
- Python/C++のハイブリッド実装
- 包括的なベンチマーク機能
- 2準位系と調和振動子のテストケース
- 詳細なパフォーマンス分析
- 解析解との比較
- メモリ最適化
- キャッシュライン境界を考慮したアライメント
- 疎行列パターンの再利用
## バージョン情報
- 現在のバージョン: v0.2.0
- ステータス: 安定版
- 最終更新: 2024-01-08
- **新機能**: プロジェクト構造の大幅改善、性能問題の解決
## 必要条件
- Python 3.10以上
- C++17対応コンパイラ
- CMake 3.16以上
- pybind11
- Eigen3
- OpenMP（推奨）
## インストール
### 開発用インストール（推奨）
```bash
git clone https://github.com/1160-hrk/excitation-rk4-sparse.git
cd excitation-rk4-sparse
# C++ライブラリのビルド
./tools/build.sh --clean
# Pythonパッケージのインストール
pip install -e .
```
### クイックテスト
```bash
# 自動テストの実行
python tools/test_examples.py
```
## 使用例
### 基本的な使用法
```python
from excitation_rk4_sparse import ExcitationRK4Sparse
from excitation_rk4_sparse.bindings import ExcitationRK4SparseCpp
# Python実装
solver_py = ExcitationRK4Sparse()
result_py = solver_py.solve(H0, mux, muy, Ex, Ey, psi0, dt, True, stride, False)
# C++実装（高速）
solver_cpp = ExcitationRK4SparseCpp()
result_cpp = solver_cpp.solve(H0, mux, muy, Ex, Ey, psi0, dt, True, stride, False)
```
### 例題
すべての例は新しい構造で整理されています：
1. **基本例**
```bash
python examples/basic/example_rk4.py # 簡単な2準位系
```
2. **量子システム例**
```bash
python examples/quantum/two_level_excitation.py # 2準位励起
python examples/quantum/harmonic_oscillator.py # 調和振動子
```
3. **ベンチマーク**
```bash
python examples/benchmarks/benchmark_comparison.py
```
## ベンチマーク
以下のスクリプトで様々なベンチマークを実行できます：
1. 実装間の比較
```bash
python examples/benchmark_comparison.py # 基本的な比較
python examples/benchmark_ho.py # 調和振動子系での比較
```
2. 詳細なプロファイリング
```bash
python examples/profile_comparison.py # CPU使用率、メモリ使用量など
```
## 性能
最新の最適化により期待される高性能を実現：
| システムサイズ | Python [ms] | C++ [ms] | 速度比 |
|-------------:|------------:|----------:|-------:|
| 50レベル | 12.8 | 0.5 | **23.65x** |
| 100レベル | 14.5 | 0.9 | **15.69x** |
| 200レベル | 17.3 | 1.8 | **9.81x** |
| 500レベル | 12.2 | 2.9 | **4.29x** |
## 最適化の特徴
### v0.2.0での主要改善
1. **条件付きデバッグ出力**: I/Oオーバーヘッドの除去
2. **適応的並列化**: 小規模データでのOpenMPオーバーヘッド回避
3. **最適化されたスケジューリング**: 静的スケジューリングによる効率化
### コア技術
1. **メモリアライメント**
- キャッシュライン境界（64バイト）に合わせたアライメント
- 作業バッファの効率的な配置
2. **適応的並列化**
- 閾値ベースの条件分岐（10,000要素以上で並列化）
- 静的スケジューリング最適化
3. **疎行列最適化**
- 非ゼロパターンの事前計算
- データ構造の再利用
- 効率的な行列-ベクトル積
## ドキュメント
包括的なドキュメントが利用可能です：
- **開発ガイド**
- [プロジェクト構造変更とマイグレーション](docs/development/project_restructure_migration.md)
- [ビルドシステム設定](docs/development/build_configuration.md)
- **トラブルシューティング**
- [性能回帰問題の分析と解決](docs/troubleshooting/performance_regression_analysis.md)
- **ベンチマーク結果**
- [性能測定結果](docs/benchmarks/performance_results.md)
## ライセンス
MITライセンス
## 作者
- Hiroki Tsusaka
- IIS, UTokyo
- tsusaka4research "at" gmail.com
```bash
pip install -e .
Raw data
{
"_id": null,
"home_page": "https://github.com/1160-hrk/excitation-rk4-sparse",
"name": "excitation-rk4-sparse",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "quantum dynamics rk4 sparse physics simulation",
"author": "Hiroki Tsusaka",
"author_email": "tsusaka4research@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/34/46/91258c193010fd2c7f9201c44a6f899753d4c0588b9ea227181b96ea81d1/excitation-rk4-sparse-0.2.0.tar.gz",
"platform": null,
"description": "# Excitation RK4 Sparse\n\n\u91cf\u5b50\u529b\u5b66\u7684\u306a\u52b1\u8d77\u30c0\u30a4\u30ca\u30df\u30af\u30b9\u3092\u8a08\u7b97\u3059\u308b\u305f\u3081\u306e\u758e\u884c\u5217\u30d9\u30fc\u30b9\u306eRK4\u30bd\u30eb\u30d0\u30fc\u3002\n\n## \u6a5f\u80fd\n- CSR\u5f62\u5f0f\u306e\u758e\u884c\u5217\u30b5\u30dd\u30fc\u30c8\n- OpenMP\u306b\u3088\u308b\u4e26\u5217\u5316\uff08\u52d5\u7684\u30b9\u30b1\u30b8\u30e5\u30fc\u30ea\u30f3\u30b0\u6700\u9069\u5316\uff09\n- Python/C++\u306e\u30cf\u30a4\u30d6\u30ea\u30c3\u30c9\u5b9f\u88c5\n- \u5305\u62ec\u7684\u306a\u30d9\u30f3\u30c1\u30de\u30fc\u30af\u6a5f\u80fd\n - 2\u6e96\u4f4d\u7cfb\u3068\u8abf\u548c\u632f\u52d5\u5b50\u306e\u30c6\u30b9\u30c8\u30b1\u30fc\u30b9\n - \u8a73\u7d30\u306a\u30d1\u30d5\u30a9\u30fc\u30de\u30f3\u30b9\u5206\u6790\n - \u89e3\u6790\u89e3\u3068\u306e\u6bd4\u8f03\n- \u30e1\u30e2\u30ea\u6700\u9069\u5316\n - \u30ad\u30e3\u30c3\u30b7\u30e5\u30e9\u30a4\u30f3\u5883\u754c\u3092\u8003\u616e\u3057\u305f\u30a2\u30e9\u30a4\u30e1\u30f3\u30c8\n - \u758e\u884c\u5217\u30d1\u30bf\u30fc\u30f3\u306e\u518d\u5229\u7528\n\n## \u30d0\u30fc\u30b8\u30e7\u30f3\u60c5\u5831\n- \u73fe\u5728\u306e\u30d0\u30fc\u30b8\u30e7\u30f3: v0.2.0\n- \u30b9\u30c6\u30fc\u30bf\u30b9: \u5b89\u5b9a\u7248\n- \u6700\u7d42\u66f4\u65b0: 2024-01-08\n- **\u65b0\u6a5f\u80fd**: \u30d7\u30ed\u30b8\u30a7\u30af\u30c8\u69cb\u9020\u306e\u5927\u5e45\u6539\u5584\u3001\u6027\u80fd\u554f\u984c\u306e\u89e3\u6c7a\n\n## \u5fc5\u8981\u6761\u4ef6\n- Python 3.10\u4ee5\u4e0a\n- C++17\u5bfe\u5fdc\u30b3\u30f3\u30d1\u30a4\u30e9\n- CMake 3.16\u4ee5\u4e0a\n- pybind11\n- Eigen3\n- OpenMP\uff08\u63a8\u5968\uff09\n\n## \u30a4\u30f3\u30b9\u30c8\u30fc\u30eb\n\n### \u958b\u767a\u7528\u30a4\u30f3\u30b9\u30c8\u30fc\u30eb\uff08\u63a8\u5968\uff09\n```bash\ngit clone https://github.com/1160-hrk/excitation-rk4-sparse.git\ncd excitation-rk4-sparse\n\n# C++\u30e9\u30a4\u30d6\u30e9\u30ea\u306e\u30d3\u30eb\u30c9\n./tools/build.sh --clean\n\n# Python\u30d1\u30c3\u30b1\u30fc\u30b8\u306e\u30a4\u30f3\u30b9\u30c8\u30fc\u30eb\npip install -e .\n```\n\n### \u30af\u30a4\u30c3\u30af\u30c6\u30b9\u30c8\n```bash\n# \u81ea\u52d5\u30c6\u30b9\u30c8\u306e\u5b9f\u884c\npython tools/test_examples.py\n```\n\n## \u4f7f\u7528\u4f8b\n\n### \u57fa\u672c\u7684\u306a\u4f7f\u7528\u6cd5\n```python\nfrom excitation_rk4_sparse import ExcitationRK4Sparse\nfrom excitation_rk4_sparse.bindings import ExcitationRK4SparseCpp\n\n# Python\u5b9f\u88c5\nsolver_py = ExcitationRK4Sparse()\nresult_py = solver_py.solve(H0, mux, muy, Ex, Ey, psi0, dt, True, stride, False)\n\n# C++\u5b9f\u88c5\uff08\u9ad8\u901f\uff09\nsolver_cpp = ExcitationRK4SparseCpp()\nresult_cpp = solver_cpp.solve(H0, mux, muy, Ex, Ey, psi0, dt, True, stride, False)\n```\n\n### \u4f8b\u984c\n\u3059\u3079\u3066\u306e\u4f8b\u306f\u65b0\u3057\u3044\u69cb\u9020\u3067\u6574\u7406\u3055\u308c\u3066\u3044\u307e\u3059\uff1a\n\n1. **\u57fa\u672c\u4f8b**\n```bash\npython examples/basic/example_rk4.py # \u7c21\u5358\u306a2\u6e96\u4f4d\u7cfb\n```\n\n2. **\u91cf\u5b50\u30b7\u30b9\u30c6\u30e0\u4f8b**\n```bash\npython examples/quantum/two_level_excitation.py # 2\u6e96\u4f4d\u52b1\u8d77\npython examples/quantum/harmonic_oscillator.py # \u8abf\u548c\u632f\u52d5\u5b50\n```\n\n3. **\u30d9\u30f3\u30c1\u30de\u30fc\u30af**\n```bash\npython examples/benchmarks/benchmark_comparison.py\n```\n\n## \u30d9\u30f3\u30c1\u30de\u30fc\u30af\n\u4ee5\u4e0b\u306e\u30b9\u30af\u30ea\u30d7\u30c8\u3067\u69d8\u3005\u306a\u30d9\u30f3\u30c1\u30de\u30fc\u30af\u3092\u5b9f\u884c\u3067\u304d\u307e\u3059\uff1a\n\n1. \u5b9f\u88c5\u9593\u306e\u6bd4\u8f03\n```bash\npython examples/benchmark_comparison.py # \u57fa\u672c\u7684\u306a\u6bd4\u8f03\npython examples/benchmark_ho.py # \u8abf\u548c\u632f\u52d5\u5b50\u7cfb\u3067\u306e\u6bd4\u8f03\n```\n\n2. \u8a73\u7d30\u306a\u30d7\u30ed\u30d5\u30a1\u30a4\u30ea\u30f3\u30b0\n```bash\npython examples/profile_comparison.py # CPU\u4f7f\u7528\u7387\u3001\u30e1\u30e2\u30ea\u4f7f\u7528\u91cf\u306a\u3069\n```\n\n## \u6027\u80fd\n\n\u6700\u65b0\u306e\u6700\u9069\u5316\u306b\u3088\u308a\u671f\u5f85\u3055\u308c\u308b\u9ad8\u6027\u80fd\u3092\u5b9f\u73fe\uff1a\n\n| \u30b7\u30b9\u30c6\u30e0\u30b5\u30a4\u30ba | Python [ms] | C++ [ms] | \u901f\u5ea6\u6bd4 |\n|-------------:|------------:|----------:|-------:|\n| 50\u30ec\u30d9\u30eb | 12.8 | 0.5 | **23.65x** |\n| 100\u30ec\u30d9\u30eb | 14.5 | 0.9 | **15.69x** |\n| 200\u30ec\u30d9\u30eb | 17.3 | 1.8 | **9.81x** |\n| 500\u30ec\u30d9\u30eb | 12.2 | 2.9 | **4.29x** |\n\n## \u6700\u9069\u5316\u306e\u7279\u5fb4\n\n### v0.2.0\u3067\u306e\u4e3b\u8981\u6539\u5584\n1. **\u6761\u4ef6\u4ed8\u304d\u30c7\u30d0\u30c3\u30b0\u51fa\u529b**: I/O\u30aa\u30fc\u30d0\u30fc\u30d8\u30c3\u30c9\u306e\u9664\u53bb\n2. **\u9069\u5fdc\u7684\u4e26\u5217\u5316**: \u5c0f\u898f\u6a21\u30c7\u30fc\u30bf\u3067\u306eOpenMP\u30aa\u30fc\u30d0\u30fc\u30d8\u30c3\u30c9\u56de\u907f\n3. **\u6700\u9069\u5316\u3055\u308c\u305f\u30b9\u30b1\u30b8\u30e5\u30fc\u30ea\u30f3\u30b0**: \u9759\u7684\u30b9\u30b1\u30b8\u30e5\u30fc\u30ea\u30f3\u30b0\u306b\u3088\u308b\u52b9\u7387\u5316\n\n### \u30b3\u30a2\u6280\u8853\n1. **\u30e1\u30e2\u30ea\u30a2\u30e9\u30a4\u30e1\u30f3\u30c8**\n - \u30ad\u30e3\u30c3\u30b7\u30e5\u30e9\u30a4\u30f3\u5883\u754c\uff0864\u30d0\u30a4\u30c8\uff09\u306b\u5408\u308f\u305b\u305f\u30a2\u30e9\u30a4\u30e1\u30f3\u30c8\n - \u4f5c\u696d\u30d0\u30c3\u30d5\u30a1\u306e\u52b9\u7387\u7684\u306a\u914d\u7f6e\n\n2. **\u9069\u5fdc\u7684\u4e26\u5217\u5316**\n - \u95be\u5024\u30d9\u30fc\u30b9\u306e\u6761\u4ef6\u5206\u5c90\uff0810,000\u8981\u7d20\u4ee5\u4e0a\u3067\u4e26\u5217\u5316\uff09\n - \u9759\u7684\u30b9\u30b1\u30b8\u30e5\u30fc\u30ea\u30f3\u30b0\u6700\u9069\u5316\n\n3. **\u758e\u884c\u5217\u6700\u9069\u5316**\n - \u975e\u30bc\u30ed\u30d1\u30bf\u30fc\u30f3\u306e\u4e8b\u524d\u8a08\u7b97\n - \u30c7\u30fc\u30bf\u69cb\u9020\u306e\u518d\u5229\u7528\n - \u52b9\u7387\u7684\u306a\u884c\u5217-\u30d9\u30af\u30c8\u30eb\u7a4d\n\n## \u30c9\u30ad\u30e5\u30e1\u30f3\u30c8\n\n\u5305\u62ec\u7684\u306a\u30c9\u30ad\u30e5\u30e1\u30f3\u30c8\u304c\u5229\u7528\u53ef\u80fd\u3067\u3059\uff1a\n\n- **\u958b\u767a\u30ac\u30a4\u30c9**\n - [\u30d7\u30ed\u30b8\u30a7\u30af\u30c8\u69cb\u9020\u5909\u66f4\u3068\u30de\u30a4\u30b0\u30ec\u30fc\u30b7\u30e7\u30f3](docs/development/project_restructure_migration.md)\n - [\u30d3\u30eb\u30c9\u30b7\u30b9\u30c6\u30e0\u8a2d\u5b9a](docs/development/build_configuration.md)\n\n- **\u30c8\u30e9\u30d6\u30eb\u30b7\u30e5\u30fc\u30c6\u30a3\u30f3\u30b0**\n - [\u6027\u80fd\u56de\u5e30\u554f\u984c\u306e\u5206\u6790\u3068\u89e3\u6c7a](docs/troubleshooting/performance_regression_analysis.md)\n\n- **\u30d9\u30f3\u30c1\u30de\u30fc\u30af\u7d50\u679c**\n - [\u6027\u80fd\u6e2c\u5b9a\u7d50\u679c](docs/benchmarks/performance_results.md)\n\n## \u30e9\u30a4\u30bb\u30f3\u30b9\nMIT\u30e9\u30a4\u30bb\u30f3\u30b9\n\n## \u4f5c\u8005\n- Hiroki Tsusaka\n- IIS, UTokyo\n- tsusaka4research \"at\" gmail.com\n\n```bash\npip install -e .\n\n\n",
"bugtrack_url": null,
"license": null,
"summary": "High-performance sparse matrix RK4 solver for quantum excitation dynamics",
"version": "0.2.0",
"project_urls": {
"Bug Reports": "https://github.com/1160-hrk/excitation-rk4-sparse/issues",
"Documentation": "https://github.com/1160-hrk/excitation-rk4-sparse/tree/main/docs",
"Homepage": "https://github.com/1160-hrk/excitation-rk4-sparse",
"Source": "https://github.com/1160-hrk/excitation-rk4-sparse"
},
"split_keywords": [
"quantum",
"dynamics",
"rk4",
"sparse",
"physics",
"simulation"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "1de436a1d1047ee90fdc0a23184da057d09efd5d0db70336e6f952c5a6dee0ff",
"md5": "0976038aa22b7c340f3b2d2d225d011d",
"sha256": "3bedb43c1e915e214f3c0c0a603e5e2424e26cc9db3a0ae5a74daf3cd047df2a"
},
"downloads": -1,
"filename": "excitation_rk4_sparse-0.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "0976038aa22b7c340f3b2d2d225d011d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 1670239,
"upload_time": "2025-07-09T08:38:31",
"upload_time_iso_8601": "2025-07-09T08:38:31.386876Z",
"url": "https://files.pythonhosted.org/packages/1d/e4/36a1d1047ee90fdc0a23184da057d09efd5d0db70336e6f952c5a6dee0ff/excitation_rk4_sparse-0.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "344691258c193010fd2c7f9201c44a6f899753d4c0588b9ea227181b96ea81d1",
"md5": "cee41c4097ff4e07afed85d802a51d10",
"sha256": "82f906dbaaeb0c5544a567777ceeaabb701caaf252308c0a7b21bfb19f7881c1"
},
"downloads": -1,
"filename": "excitation-rk4-sparse-0.2.0.tar.gz",
"has_sig": false,
"md5_digest": "cee41c4097ff4e07afed85d802a51d10",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 8616,
"upload_time": "2025-07-09T08:38:34",
"upload_time_iso_8601": "2025-07-09T08:38:34.466415Z",
"url": "https://files.pythonhosted.org/packages/34/46/91258c193010fd2c7f9201c44a6f899753d4c0588b9ea227181b96ea81d1/excitation-rk4-sparse-0.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-09 08:38:34",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "1160-hrk",
"github_project": "excitation-rk4-sparse",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "pybind11",
"specs": [
[
">=",
"2.10"
]
]
},
{
"name": "pytest",
"specs": [
[
">=",
"7.0"
]
]
},
{
"name": "cmake",
"specs": [
[
">=",
"3.14"
]
]
},
{
"name": "numpy",
"specs": []
},
{
"name": "scipy",
"specs": []
}
],
"lcname": "excitation-rk4-sparse"
}
JSON
