PySR（符号回帰ライブラリ）のガイド

論文と貢献について

• 論文引用: PySR が有用と感じた場合は、以下を引用してください。
  • arXiv:2305.01582
• 研究成果の発表: プロジェクト完了時は、検証ショーケースページへの PR（プルリクエスト）をご提出することを歓迎いたします！

目次

1. PySR とはなぜ必要か？
2. インストール
   • pip/conda
   • Docker
   • Apptainer
3. クイックスタート
4. トラブルシューティング
5. 詳細な例
6. 貢献者 ✨

PySR とはなぜ必要か？

PySR は、**記号回帰（Symbolic Regression）**のためのオープンソースツールです。

基本機能

• 目的: ある目的関数を最適化する、解釈可能な記号的表現を見つけること。
• 3 つの原則:
  1. できるだけ高性能であること。
  2. できるだけ柔軟な設定が可能であること。
  3. 使いやすいこと。

技術背景

• Julia ライブラリ SymbolicRegression.jl と並行して開発されています。
• 強力な検索エンジンとして SymbolicRegression.jl を利用しています。
• アルゴリズムの詳細は PySR の論文に記載されています。

応用分野

• 低次元データ: 特に効果的です。
• 深層学習との連携 (Symbolic Distillation):
  • 高次元空間へ拡張可能（詳細: arXiv:2006.11287）。
  • N ボディ問題への応用において、ニューラルネットを解析式に変換する手法として利用されています。
• 解釈可能性: 深層学習ネットワークの解釈に対して明示的で強力な方法を提供します。

インストール

pip/conda

PySR は

pip

conda

conda install -c conda-forge pysr

Docker

Docker コンテナ内で PySR を使用する場合：

1. イメージのビルド

   docker build -t pysr .
   

2. コンテナの起動 (IPython 実行)

   docker run -it --rm pysr ipython
   

   詳細な Docker セクション参照: #docker

Apptainer

Root アクセスがないクラスターでの利用には Apptainer を使用できます。

1. Dockerfile 相当の

   Apptainer.def

   の構築

   apptainer build --notest pysr.sif Apptainer.def
   

2. コンテナの起動

   apptainer run -it pysr.sif ipython
   

AI エージェントスキル

コーディングエージェントへのガイダンスとして PySR を利用する場合は、

astroautomata/PySR

npx skills add astroautomata/PySR

• グローバルインストール:

  --global

  フラグを追加してください。

クイックスタート

実践的には、表示機能の優れた IPython を Jupyter よりも推奨します。以下は Python 環境への簡易デモです。

データ準備 (NumPy)

100 データポイント×5 特徴量のデータセットを作成します。

import numpy as np

# テストデータの生成
X = 2 * np.random.randn(100, 5)

# 目的関数：y = 2.5382*cos(x_3) + x_0^2 - 0.5
y = 2.5382 * np.cos(X[:, 3]) + X[:, 0] ** 2 - 0.5

モデルの作成とトレーニング

scikit-learn スタイルのインターフェースです。

from pysr import PySRRegressor

model = PySRRegressor(
    maxsize=20,                    # 最大複雑度
    niterations=40,                # イテレーション数 (増やすほど精度向上)
    binary_operators=["+", "*"],   # 演算子定義
    unary_operators=[
        "cos", 
        "exp", 
        "sin", 
        "inv(x) = 1/x",            # カスタム演算子 (Julia 構文)
    ],
    extra_sympy_mappings={"inv": lambda x: 1 / x},  # SymPy 用のマッピング
    elementwise_loss="loss(prediction, target) = (prediction - target)^2", 
    # カスタム損失関数 (Julia 構文)
)

# データセットへのトレーニング
model.fit(X, y)

トレーニング時の挙動

• Julia プロセスが起動し、多スレッドで式の探索を行います。
• 式が出力されるため、満足したら 'q' キーを押して早期終了できます。

予測と結果の確認

# 自動選択された式による予測
predictions = model.predict(X)

# N 番目の式の予測 (例: 3 番目)
model.predict(X, 3)

# 学習された全式の表示
print(model.equations_)

出力結果の例:

4.4324794

(x0 * x0)

((x0 * x0) + -0.28087974)

((x0 * x0) + cos(x3))

((x0 * x0) + (cos(x3) * 2.4566472))

inf

(((cos(x3) + -0.19699033) * 2.5382123) + ...)

注:

pick

列の矢印は、現在選択されている式を示します（

.fit()

後でも変更可能です）。

モデルの詳細と形式変換

• model.equations_

  は Pandas DataFrame です。
• 取得可能な形式:
  • 可読形式:

    model.equations_['lambda_format']

  • SymPy 形式:

    model.sympy()

  • JAX 形式 (微分可能):

    model.jax()

  • PyTorch 形式 (微分可能):

    model.pytorch()

ウォームスタートと状態管理

• PySR は最後の探索状態を保持します（

  warm_start=True

  ）。
• 検索パラメータ（演算子変更など）に変更を加える場合は、必ず

  model.reset()

  を実行してください。

永続化 (保存・復元)

2 つのファイルが保存されます:

1. CSV: 式と損失値のリスト (

   hall_of_fame...csv

   )
2. PKL: モデルの状態 (

   hall_of_fame...pkl

   )

復元例：

model = PySRRegressor.from_file("hall_of_fame.2022-08-10_100832.281.pkl")

さらに詳しいオプション、チューニングヒント、および

denoise

select_k_features

詳細な例

以下のコードは PySR の機能を網羅して示しています（そのまま使用しないように）。各パラメータの詳細は API ページを参照ください。

model = PySRRegressor(
    populations=8,                # コア数に応じた並列処理設定
    population_size=50,           # より多様性を保つための人口サイズ
    ncycles_per_iteration=500,   # 世代あたりのサイクル数
    niterations=10000000,         # 長時間実行設定
    early_stop_condition=(
        "stop_if(loss, complexity) = loss < 1e-6 && complexity < 10"
    ),                            # 良い式を見つけたら早期停止
    timeout_in_seconds=86400,     # 24 時間経過で停止
    maxsize=50,                   # 複雑度の上限
    maxdepth=10,                  # ネスト深度の制限 (深いネスト回避)
    binary_operators=["*", "+", "-", "/"],
    unary_operators=["square", "cube", "exp", "cos2(x)=cos(x)^2"],
    
    constraints={                  # 各演算子ごとの複雑度制限
        "/": (-1, 9),
        "square": 9, 
        "cube": 9, 
        "exp": 9, 
        # "inv": (-1, 9) は分母の複雑度を制限、"exp": 9 は入力式の複雑度を制限
    },
    
    nested_constraints={           # ネスト構造への制約 (例：square(exp(x)) を禁止)
        "square": {"square": 1, "cube": 1, "exp": 0},
        "cube": {"square": 1, "cube": 1, "exp": 0},
        "exp": {"square": 1, "cube": 1, "exp": 0},
    },
    
    complexity_of_operators={"/": 2, "exp": 3},   # 演算子ごとの複雑度コスト
    complexity_of_constants=2,                    # 定数に対するペナルティ (変数より厳しく)
    select_k_features=4,                          # 重要特徴量の選別 (4 つのみ使用)
    
    progress=True,                               # プログレスバー表示
    weight_randomize=0.1,                        # ランダム重み付け頻度
    cluster_manager=None,                        # クラスター管理 (スラブ用設定可)
    
    precision=64,                                # 高精度計算 (Float64)
    warm_start=True,                             # 中断から再開機能
    
    turbo=True,                                  # 高速評価モード (実験的)
    extra_sympy_mappings={"cos2": lambda x: sympy.cos(x)**2}, 
    extra_torch_mappings={sympy.cos: torch.cos}, 
    extra_jax_mappings={sympy.cos: "jnp.cos"},   
)

Docker の詳細設定

システムのアーキテクチャに合わせて Python/Julia バージョンを指定することも可能です。

カスタムバージョンビルド例:

docker build -t pysr --build-arg JLVERSION=1.10.0 --build-arg PYVERSION=3.11.6 .

コンテナ起動 (データマウント):

docker run -it --rm -v "$PWD:/data" pysr ipython

• 現在のディレクトリがコンテナ内の

  /data

  にリンクされます。

アーキテクチャエミュレーション: 特定のプラットフォームで問題がある場合、以下を追加してください。

--platform linux/amd64

トラブルシューティング

• 注: 本稿では具体的なトラブル事例への言及がありませんでしたが、以下の点に注意してください。
  • 演算子の変更後は

    model.reset()

    を必ず実行してください。
  • Docker/Apptainer の場合、ネットワークやボリュームマウントの設定を確認してください。

貢献者 ✨

PySR はコミュニティの力で発展しています。新規貢献者を歓迎します！🚀

• 貢献者ガイド でヒントをご覧ください。
• 新しい機能のアイデアをお持ちの場合は、Issues または Discussions で共有してください。

主要な貢献者の皆様: Adil, Christopher Rowley, Mark Kittisopikul, T Coxon, Dhananjay Ashok, Johan Blåbäck, JuliusMartensen, ngam, Kaze Wong, Christopher Rackauckas, Patrick Kidger, Okon Samuel, William Booth-Clibborn, Aya Ghaleb, gca30, Niklas Heim, Atharva Sehgal, wkharold, William Moses, Ardeleanu Cristian, gm89uk, Pablo Lemos, Jerry Ling, Charles Fox, Johann Brehmer, Marius Millea, Coba, foxtran, Shah Mahdi Hasan, Dilum Aluthge, Sebastian Micluța-Câmpeanu, Tim Holy, BrotherHa, William Thompson, Tom Jelen, Miguel Crispim Romao, Andy Dienes, Harsh Singh, Pietro Monticone, Mateusz Kubica, Raúl Peralta Lozada, Roy Hvaara, Vishal Jain, spaette, Yi-Xin Liu, spinnau, Xianda Sun, Jay Wadekar, Anthony Blaom, PhD, Jgmedina95, Michael Abbott, Oscar Smith, Eric Hanson, Henrique Becker, qwertyjl, Rik Huijzer, Hongyu Wang, Zehao Jin, Tanner Mengel, Arthur Grundner, sjwetzel, Saurav Maheshkar, chris-soelistyo, Ilya Orson, Ho Fung Tsoi, LionessOfCintra, Manuel Morales, Paulo Montero Camacho, Writu Dasgupta, Anubhav Kamal, anthony-sun, Hao Guo, Trailblazer, Christos Pliakos, Sousa Neto, Leonardo Voltolini, Daniel Eduardo Conde Villatoro, Sam Beckers