Lucen: コメントプラグマでforループを並列化するPythonコンパイラ
Show HN: Lucen a Python compiler that parallelizes for-loops via comment pragmas (github.com)
要約
Lucenは、コメントプラグマによってPythonのforループを自動的に並列化するソース・トゥ・ソース・コンパイラです。既存のフレームワークと異なり、並列化の許可箇所を指示するだけで、安全かつ効果的と判断されたループのみを並列化します。誤った結果を生成しないことを保証し、並列化できないループは元のまま実行されるため、導入のリスクがありません。
全文翻訳
Lucen
[画像: PyPI] [画像: Python] [画像: License] [画像: CI] [画像: OpenSSF Scorecard]
決して不正な結果を、決して破壊的な動作を、決して静かに無意味なことをしない。
Lucenは、コメントプラグマのペアでマークされた通常のPythonループを並列化するソース・トゥ・ソース・コンパイラです。結果が逐次実行と同じであることを証明できる場合にのみ、マークされたループをチャンク化された並列実行に書き換えます。証明できないものは、あなたが書いたPythonのまま実行されます。
[画像: lucen run でマークされたループを実行中:同じ出力、2.5倍高速]
# LUCEN START
for i in range(len(records)):
scores[i] = score(records[i])
# LUCEN END
lucen run work.py
10万件以上のレコードで、このループは12コアで5.7秒から2.3秒の実行時間(プロセスプールの起動時間を含む)に短縮され、ビット単位で同一のチェックサムが得られました(examples/scored_records.py、中央値3回)。定常状態では、BENCHMARK.mdによると、この形状は7つのインタプリタで3.2倍から3.8倍になります。プラグマは通常のコメントなので、Lucenがアンインストールされていれば、ファイルはあなたが開始したプログラムのままです。これがコメント不変性です。
保証
- 決して不正な結果を生まない。 チャンクはプライベートスラブに書き込み、結合時に離散性が監査され、チャンク順にコミットされます。辞書の挿入順序、浮動小数点数の削減ビット、エラー発生時のコンテナ状態は、すべて逐次実行とビット単位で一致します。書き込み競合が発生した場合、並列試行は破棄され、ループは逐次実行で再実行されます。
- 決して破壊的な動作をしない。 証明できないものはすべて逐次実行され、その理由は
lucen.get_fallback_report()に記録されます。例外は、その型、メッセージ、およびコンテナの正確な逐次プレフィックス状態を保持します。 - 決して静かに無意味なことをしない。 静的な事前スクリーニングと実行時プローブにより、ディスパッチオーバーヘッドに負けるループの並列化を拒否し、その旨を通知します。
これらは、7つのインタプリタ x 8つのワークロード x 4つの実行パスの行列全体で保持され、各セルはプレーンPythonに対してビット単位で同一であることがチェックされています(BENCHMARK.md)。あなたのコード自体が前提としていることは、LIMITATIONS.md のセクション1に記載されています。
インストール
pip install lucen
Python 3.9以降が必要です。3.11以降ではサードパーティのランタイム依存関係はありません。3.9および3.10では、pipは tomli をプルしますが、これは lucen.toml を読み取る際に標準ライブラリの tomllib の代わりになります。GILビルドでは、pipはネイティブRustコア(abi3、プラットフォームごとに1つのバイナリ)をインストールし、書き込みセット監査と削減フォールドを実行します。フリー・スレッド・ビルドでは、abi3コアをロードできないため、代わりにピュアPythonホイールがインストールされますが、これは同じテストスイートに合格します。
ソースから、オプションのRustツールチェーンを使用する場合:
git clone https://github.com/fcmv/lucen
cd lucen
pip install -e "'.[dev]'"
pytest
サポートされているインタプリタ
| インタプリタ | ステータス | ネイティブコア |
|---|---|---|
| CPython 3.9~3.14, GIL | Linux, macOS, WindowsでCIでゲート | はい |
| CPython 3.14t, フリー・スレッド | CIでゲート | ピュアPythonフォールバック |
| PyPy 3.11 | CIでゲート | ピュアPythonフォールバック |
| GraalPy 24.1 | ベストエフォート、ゲートなし | ピュアPythonフォールバック |
3.13tは3.14tと同じピュアPythonパスを使用し、個別にゲートされていません。
使用方法
直接起動するスクリプトの場合は、lucen run を使用します。これは、そのファイル内のマークされたループを書き換え、その後実行します:
lucen run work.py
通常の python work.py では、エントリースクリプト内のループを並列化できません。Lucenの何かが実行される頃には、そのモジュールはすでにコンパイルされているからです。自分で開始するアプリケーションの場合は、マークされたループを含むモジュールがインポートされる前にインポートフックをインストールします:
import lucen
lucen.activate()
import work
work.main()
WindowsおよびmacOSでは、プロセスバックエンドは各ワーカーでエントリーモジュールを再インポートするため、通常の if __name__ == "__main__": ガードが必要です。Lucenは、ワーカーが起動する前にガードの欠落を検出し、メッセージとともにブロックを逐次実行して修正を促します。activate() は冪等です。
レポート
lucen explain は、ファイルを実行せずに各ブロックの分類を報告します:
$ lucen explain examples/demo_workload.py
examples/demo_workload.py: 2 marked block(s) [gil interpreter assumed]
Block 1 (line 14)
+ Parallelized
Backend: PROCESS, flat chunk scheduler
Reason: all shared writes are provably or assertedly disjoint per iteration
Clauses in effect: calibrate=false
Runtime-dependent (never reported statically): argument picklability, custom-callable well-formedness, pool availability - see `lucen profile`.
拒否されたブロックは、それを停止させた依存関係を示します:
Block 1 (line 9)
x Sequential
Reason: 'scores' depends on 'scores[i - 1]': a genuine one-directional chain; no parallel execution exists for this shape in v1 (spec 5.5.2)
lucen profile script.py --per-block は、実際に実行された内容をタイミングとともに報告します。実行時のダウングレードは、標準エラー出力に1行表示され、構造化されたレコードとして保持されます:
lucen fallback: PARALLEL_UNPROFITABLE (examples/demo_workload.py:20): measured ~39 ns/iteration loses to dispatch overhead; ran SEQUENTIAL (calibrate=false overrides, spec 5.17)
for record in lucen.get_fallback_report():
print(record.error, record.file, record.line, record.message)
CIでは、lucen explain --strict --baseline baseline.json は、ブロックの分類がコミットされたベースラインに対して後退した場合、ビルドを失敗させます。
チューニング
句は # LUCEN START 行に記述します。各句は、Lucenが保持する証明をあなたの主張と交換するか、正確性を速度と交換します。決して異なる答えにはなりません。不正な句は、インポート時に大きなエラーとなり、「もしかして」の提案が表示されます。
# LUCEN START calibrate=false, timeout=5.0, on_error=collect
| 句 | 説明 |
|---|---|
backend= | バックエンドをピン留めします:thread, process, sequential、pool_size/chunks 付き |
calibrate= | 収益性ゲートを制御します(false は並列化を強制) |
reduce= | 削減操作(sum, min, ...)または custom(fn=, identity=) を指定します |
timeout= | 壁時計時間を制限します;ParallelTimeoutError を発生させます |
on_error= | 高速失敗の代わりに、イテレーションごとの例外を収集します(collect) |
strict= | このブロックのフォールバックをハードエラーに変換します |
さらに9つの句が、CPUアフィニティ、ネストされたブロック、ウェーブフロントの粒度、削減順序、進捗、フォールバックの表示、および証明を免除するエキスパートアサーション(depend, skip_runtime_check, trust)をカバーします。3番目のプラグマ # LUCEN TRUST をヘルパーの def の上に置くと、そのヘルパーが並列化下で安全であることをアサートします。docs/pragmas.md が完全なリファレンスです。すべての受け入れ可能な形式、プロジェクト全体のデフォルトと上限のための lucen.toml スキーマ、およびオプトインの実験的機能が含まれています。
仕組み
スキャナー -> リライター -> セレクター -> コード生成 -> ディスパッチ
(プラグマ) (分類) (ルーティング) (ツイン) (実行 + 監査 + コミット)
コード生成は、ブロックごとに2つの関数を生成します。ワーカー用のチャンク関数と、フォールバックパスでもある逐次ツインです。これにより、逐次的な動作は構築によって元のループになります。ディスパッチは、永続的なプール上でチャンクを実行し、結合時に書き込み離散性を監査し、削減を正確な要素順序でフォールドし、チャンク順にコミットします。ループ本体はあなたのPythonのままで、適格な本体をネイティブカーネルにコンパイルすることはROADMAP L1です。
docs/architecture.md には、ステージ図、アナライザが認識する依存関係の形状、およびバックエンド選択ルールがあります。技術仕様 は、すべてのセマンティクスの権威であり、監査およびウェーブフロントプロトコルはモデルチェックされています。
パフォーマンス
12コアi5-12450HXでのウォームアップ後の5回の実行の中央値、7つのインタプリタ全体。 "Native Python" は、プラグマがコメントになっている同一のファイルです。"Lucen" は、ゲートがオンになっている出荷製品です。
[画像: Lucenのワークロード別スピードアップ、CPython 3.11 (12コア)]
| ワークロード | ネイティブPython (ms) | Lucen, ゲートオン (ms) | 手書き最適化 (ms) |
|---|---|---|---|
| 軽量マップ (1M) | 67.7~93.3 | 32.1~50.4 | 48.8 |
| 中量マップ (40k) | 102.9~138.1 | 30.1~44.0 | 24.1 |
| 重量マップ (20k) | 1028.8~1258.0 | 282.5~401.1 | 244.0 |
| 軽量削減 (1M) | 54.1~77.6 | 29.4~35.8 | 27.6 |
| 重量削減 (20k) | 1028.0~1273.0 | 284.4~412.2 | 243.2 |
| 認識済みDAG (100k) | 10.4~14.4 | 6.6~9.2 | 7.8 |
| バッファマップ (1M, array) | 75.9~106.3 | 52.8~67.1 | 26.6 |
| ネスト重量 (4k) | 61.6~79.0 | 16.6~27.4 | 13.7 |
並列化が有効な場合、Lucenは逐次実行と比較して2.5倍から4.3倍高速に実行されます。手動でチューニングされた concurrent.futures コードと比較すると、中央値で18%遅く、測定された28個のセル全体で5%から67%遅くなります。並列化が有効でない場合、ゲートは同等の速度で逐次実行のままです。軽量削減は唯一の例外であり、4%から14%のプローブオーバーヘッドを伴います。
最後の列に関する注意点:手書きの比較コードは専門家レベルでAI生成されたものであり、その並列浮動小数点削減はテストされたすべてのインタプリタで逐次Pythonとは異なるビットを生成します。Lucenの削減は、どこでもビット単位で同一です。
完全なタイミング行列、正しさ行列、および生のJSONは:BENCHMARK.md。
制限事項
- ヘルパーの純粋性は、ソースが読み取り可能な場合にのみ証明されます。 状態を持つC拡張または動的にディスパッチされる呼び出し可能なものは、文書化された信頼を保持し、ワーカーごとに異なる場合があります。
typed_buffersはコストモデルに含まれていません。 配列出力マップは、フラグを付けてbackend=processを強制しない限り、逐次実行されます。- 軽量削減は4%から14%のプローブオーバーヘッドを伴います。これは、削減がまだツインプローブの高速パスを使用できないためです。
- 認識済みDAGウェーブフロントはデフォルトで逐次実行されます。 その並列形式は、
backend=thread下のフリー・スレッド・ビルドでのみ効果があります。 - フリー・スレッド・ビルドにはネイティブコアがありません。ピュアPythonフォールバックがそれらをカバーします。
- プラグマペアにつき1つのループまたは内包表記のみ、
asyncボディなし、ジェネレータ式は並列化されません。
完全なインベントリと、信頼境界の背後にあるレッドチームの発見は、LIMITATIONS.md にあります。各項目に対する計画作業はROADMAP.md にあります。
ドキュメント
すべてはドキュメントサイトにあります:プラグマと句のリファレンス、すべてのセマンティクスの権威であるアーキテクチャ、技術仕様、APIリファレンス、用語集、論文、アーキテクチャ決定記録、およびTLA+モデル。examples/ は実行可能で、仕様自体の作業済みDAGも含まれています。
STABILITY.md は、セマンティックバージョニングの対象となるものを述べています。プラグマの文法、句の語彙、lucen.toml スキーマ、パブリックAPI、およびCLI契約は安定しています。ルーティング決定、生成されたコード、およびレポートの文言は安定していません。
ヘルプの入手方法
使用方法に関する質問はGitHubディスカッションで尋ね、再現可能なバグはGitHubイシューとして提出してください。SUPPORT.md に詳細があります。どちらの場合も、まず lucen explain と lucen profile で「なぜこのブロックは並列化されなかったのか」という質問のほとんどに自分で答えることができます。セキュリティ問題は、公開イシューではなく、SECURITY.md に報告してください。
貢献
pip install -e "'.[dev]'" && pytest から始めてください。実行パイプラインへの変更は、不変性スイートによって評価され、ベンチマーク証拠なしにルーティング変更は着陸しません。CONTRIBUTING.md には基準とプロセスがあり、AI_USAGE_GUIDELINE_FOR_PR.md はAI支援貢献に関するポリシーがあります。決定はGOVERNANCE.md に記載されているとおりに行われ、CODE_OF_CONDUCT.md はすべてのプロジェクトスペースを規制します。
ライセンス
Apache-2.0。 LICENSE を参照してください。