PySR

Multi-population evolutionary search returning a complexity/error Pareto front.

algorithm

pysr

score

NMSE min

cost

medium

derivatives

finite_diff

equation form

EVOLUTION REGRESSION

data layout

grid tabular

Usage

import kd

dataset = kd.load_burgers()
config = kd.PySRConfig(
    terms=("u", "u_x", "u_xx"), niterations=40, seed=0,
    unary_operators=("sin", "cos", "exp", "log"),
    extra_pysr_kwargs={"deterministic": True, "parallelism": "serial"},
)
model = kd.Model(algorithm="pysr", config=config)
model.fit(dataset)
print(model.result_.equation)

Main parameters

Parameter	Default	Resume	Description
`niterations`	`40`	resume-safe	PySR's internal GP iterations per fit; the facade generations parameter maps here, and on a resume it is the number of further iterations the new segment runs from the archived populations.
`population_size`	`33`	init-only	Members per PySR population.
`populations`	`15`	init-only	Number of PySR populations.
`maxsize`	`20`	init-only	Maximum generated expression size.

All fields of PySRConfig

Field	Type	Default
`terms`	`tuple[str, ...]`	`('u', 'u_x', 'u_xx', 'mul(u, u_x)')`
`seed`	`int`	`0`
`niterations`	`int`	`40`
`population_size`	`int`	`33`
`populations`	`int`	`15`
`maxsize`	`int`	`20`
`binary_operators`	`tuple[str, ...]`	`('+', '-', '*', '/')`
`unary_operators`	`tuple[str, ...]`	`()`
`extra_pysr_kwargs`	`dict[str, Any] \\| None`	`None`

Search space

PySR is a third-party symbolic-regression package whose search is documented by its authors. Its backend uses Julia. The KD wrapper supplies numeric columns and converts the result into KD's equation representation.

For PDE data, terms names the candidate columns in KD's function-call notation. PySR combines those columns but does not differentiate or invent another input column. Use the field and axis names in the dataset; adding an axis does not expand the configured library. An unresolvable term fails the fit. Compound derivatives use u_x_t or diff_t(u_x), not u_xt.

Tabular data selects tabular mode, where feature columns supply the inputs automatically and terms is refused. Grids other than one-field u(x,t) require explicit terms. Both modes read binary_operators and unary_operators from the configuration. These operators let the search form nonlinear combinations beyond a linear fit of the original columns.

Method

KD executes the term columns into a Theta matrix and gives PySR generated placeholder names such as c0 and c1 that do not collide with dataset fields or term symbols. PySR performs its own multi-population search and returns a hall of fame with complexity, loss and expressions. One KD run contains one batch search, rather than one KD iteration per internal PySR generation. generations sets PySR's internal iteration budget.

For PDEs, conversion replaces placeholders with the terms' SymPy expressions, expands the sum, removes each additive term's numeric factor and serializes the remaining structure to KD IR. A nonzero pure-constant additive term becomes the constant term one, a column of ones, so a selected expression that is a nonzero constant becomes the law one. A fitted constant inside a unary operation, as in sin(mul(2, u)), remains part of that structure. For tables the expression stays whole, including fitted constants and additive intercepts, and an expression with no feature symbols is rejected as a constant model.

A resumed run restores PySR populations and the hall of fame and runs the new model's generations as additional internal iterations. It incurs another Julia startup. The hall of fame retains its best internal loss, while the headline expression is selected again and its KD score can move in either direction. The parameter table gives the declared resume tiers; changes to the input columns or operator vocabulary change the search identity.

Result interpretation

model.best_score_ is KD's least-squares refit NMSE, not PySR's selection loss. For PDEs, the refit supplies coefficients for the converted structural terms; best_expr_ itself is structural. A retained one carries the additive constant as its refit coefficient. For tables, PySR's fitted constants remain inside the expression and the refit supplies one outer scale. That scale is often near one, but the score measures the scaled expression's shape. Refit coefficients are available on result_.final_eval.coefficients and result_.equation.

model.result_.pareto_front() returns each convertible hall-of-fame entry with its expression, PySR complexity and loss, and, for tables, its fitted outer scale. Recorder series include pareto_complexity, pareto_loss, pareto_nmse and pareto_expressions, plus pareto_scale for tables. pareto_nmse is KD's independent re-score of each entry. PySR selects the headline expression before KD re-scores it; the KD re-score does not select a new headline. Unconvertible front rows are omitted, but an unconvertible selected expression fails the run.

Python setup

Install the optional backend with pip install "sail-kd[pysr]". A kd.TabularDataset selects tabular mode in Model.fit().

References

Cranmer (2023). "Interpretable machine learning for science with PySR and SymbolicRegression.jl". arXiv:2305.01582. Paper

Documentation: ai.damtp.cam.ac.uk/pysr

Code: MilesCranmer/PySR

Implementation notes. KD calls the published PySR package and targets its 1.5 API: the complexity, loss and sympy_format columns in equations_, and model.sympy() for the selected expression. It does not reimplement the search. The wrapper changes the input columns, reported score and, for PDEs, additive coefficients. Configured operators must have a KD IR representation; a custom operator or ^ can make conversion fail.

Additional backend settings pass unchanged through extra_pysr_kwargs. A seed sets random_state; bitwise repeatability also needs PySR's deterministic=True and serial execution. A resumed search retains the backend's state rather than starting a fresh seeded population.

Full report

The example uses the operator set recorded in the report, including exp in the returned expression. It sets these operators explicitly; the current PDE default has no unary operators.

Forward integration of this returned equation does not complete. The report shows that failure in the field-reconstruction panels; the recorded search and derivative-fit diagnostics remain available.

Full HTML report from the same run, with all figures, captions and raw result data.