Skip to content

Model and result

kd.Model runs a search and returns a kd.ExperimentResult.

import kd

model = kd.Model(algorithm="sga", generations=200, seed=42)
model.fit(kd.load_kdv())
print(model.best_expr_, model.best_score_)

algorithm takes the name of any of the seven algorithms; each one's scope and parameters are on its own page under Algorithms. Passing config= supplies that algorithm's settings and becomes the single source for them, so supplying the same settings as keywords alongside it raises. Which parameters may change on a resume is covered in Parameter tiers and resuming, and what best_score_ measures in Score conventions and comparability.

Model

High-level facade for PDE discovery (PySR-style API).

Parameters:

  • algorithm (str, default: 'sga' ) –

    Search algorithm name.

  • generations (int, default: 50 ) –

    Search-loop length (default 50).

  • population (int, default: 20 ) –

    SGA population size (number of PDE candidates). SGA-only.

  • depth (int, default: 4 ) –

    Maximum tree depth per term. SGA-only.

  • width (int, default: 5 ) –

    Maximum number of terms per PDE. SGA-only.

  • aic_ratio (float, default: 1.0 ) –

    AIC penalty ratio. SGA-only.

  • derivatives (str, default: 'finite_diff' ) –

    Derivative provider mode: "finite_diff" or "autograd" (forwards use_autograd=True to SGAConfig).

  • seed (int, default: 0 ) –

    Random seed for reproducibility. It threads into every algorithm's default config when config= is unset; otherwise the config's own seed wins. Passing the facade seed= together with config= is rejected by _validate_config_exclusivity.

  • verbose (bool, default: True ) –

    When True, print per-iteration progress to stdout.

  • config (SGAConfig | DLGAConfig | DiscoverConfig | PySRConfig | PySINDyConfig | EqGPTConfig | Llm4edConfig | None, default: None ) –

    Optional pre-built SGAConfig, DLGAConfig, DiscoverConfig, PySRConfig, EqGPTConfig, Llm4edConfig, or PySINDyConfig. When provided, it is the single source of plugin settings.

  • callbacks (list[RunnerCallback] | None, default: None ) –

    Optional list of additional RunnerCallback instances to attach to the runner. The verbose progress printer is appended automatically when verbose=True.

  • surrogate_model (Module | None, default: None ) –

    Optional pre-trained torch.nn.Module forwarded to DLGAPlugin(surrogate_model=...).

  • provider (LLMProvider | None, default: None ) –

    Optional pre-built kd.llm.LLMProvider forwarded to Llm4edPlugin(provider=...). llm4ed-only — passing it with any other algorithm raises TypeError (silent drop is a bug-attractor).

  • checkpoint_dir (str | Path | None, default: None ) –

    Optional directory for periodic checkpoints.

  • checkpoint_every (int, default: 10 ) –

    Save a per-iteration checkpoint every N iterations (0-indexed: saves at 0, N, 2N, ...; default 10).

  • checkpoint_keep_last (int | None, default: None ) –

    Retention bound on PERIODIC checkpoints. None (default) keeps every one, so that the evidence trail stays complete; an int >= 1 keeps only the N most recent periodic checkpoints, pruning older ones from both the manifest and disk.

  • phases_path (str | Path | None, default: None ) –

    Optional phases.jsonl sink (kd-runphase-v1).

  • **kwargs (Any, default: {} ) –

    Forwarded to the selected algorithm's config dataclass when the field is not already owned by a facade parameter. Unknown, cross-algorithm, colliding, or JSON-type-invalid fields raise at construction.

best_expr_ property 

best_expr_: str

Best discovered expression string (post-fit only).

best_score_ property 

best_score_: float

Best score from the last fit (post-fit only).

result_ property 

result_: ExperimentResult

Full ExperimentResult from the last fit (post-fit only).

algorithm_ property 

algorithm_: SearchAlgorithm

The fitted SearchAlgorithm plugin instance (post-fit only).

fit 

fit(
    dataset: PDEDataset | TabularDataset,
    resume_from: str | Path | None = None,
    *,
    sketch: Sketch | None = None,
    reseed: bool = False,
) -> Model

Run the search and populate post-fit attributes.

Parameters:

  • dataset (PDEDataset | TabularDataset) –

    A PDE dataset or public X -> y regression table.

  • resume_from (str | Path | None, default: None ) –

    Optional path to a checkpoint file written by a previous run (checkpoint_*.pt). The checkpoint restores search state (population / controller weights / best).

  • sketch (Sketch | None, default: None ) –

    Optional semantic search-space contract for this fit (kd.Sketch): pinned terms are deducted from the regression target and restored with their exact coefficients, and the run's result carries a sound SketchOutcome (result_.sketch_outcome) whose solution is only filled when the discovered law satisfies every sketch clause.

  • reseed (bool, default: False ) –

    Turn the resume into a BRANCH (K4). A plain resume keeps the checkpoint's random streams and continues one trajectory.

Returns:

  • Model –

    self for sklearn-style chaining.

Raises:

  • NotImplementedError –

    If algorithm is not supported.

  • TypeError –

    If sketch is neither a Sketch nor None.

  • ValueError –

    If sketch uses a clause the algorithm's capability declaration does not support, targets a non-evolution dataset, or declares an LHS differing from the dataset's resolved LHS; or if the dataset is missing the required LHS field or axis.

  • FileNotFoundError –

    If resume_from does not exist.

  • IsADirectoryError –

    If resume_from points at a directory.

  • RuntimeError –

    If a LEGACY resume_from (no config snapshot) was written by a structurally different config (state_dict shape mismatch on restore); a snapshot-bearing checkpoint hits the ValueError tier gate first.

train_surrogate 

train_surrogate(
    dataset: PDEDataset | TabularDataset,
) -> tuple[Module, TrainingResult]

Train this instrument's derivative surrogate without running a search.

Returns:

  • tuple[Module, TrainingResult] –

    (module, training_result); the module is not installed on this facade.

Raises:

  • NotImplementedError –

    The instrument accepts no injected surrogate (empty config_artifact_keys), so it trains none; or the dataset's (topology, lhs_order) is one the instrument cannot fit -- the same gate fit runs before its platform build, with the same message.

  • TypeError –

    A tabular dataset (scalar regression has no field surrogate).

  • ValueError –

    This facade already holds an injected model (field_model / surrogate_model); training here would retrain and silently discard it. Also sga under the default derivatives="finite_diff", which never consults a surrogate.

Result structure

One fit produces one ExperimentResult, and the trailing-underscore attributes above are shortcuts into it. Its contents fall into four groups, and the entry below lists every field:

  • The answer. best_expression and best_score, with score_kind and score_direction stating what that number is and which direction is better.
  • Fit quality. final_eval, an EvaluationResult carrying mse, nmse, r² and the coefficients, alongside the actual and predicted values behind them.
  • Search progress. iterations, early_stopped, and recorder, the per-iteration record that kd.VizEngine draws from.
  • Provenance. dataset_name, algorithm_name and config, plus the manifest and run_record that seal the run against its inputs.

ExperimentResult dataclass

Bases: RunResult

Serializable value object for a completed experiment.

has_pareto_front 

has_pareto_front() -> bool

Return whether the recorder contains a Pareto expression series.

load classmethod 

load(path: Path | str) -> ExperimentResult

Load a serialized result from disk.

pareto_front 

pareto_front() -> list[ParetoEntry]

Return the last complete recorder-backed Pareto front.

save 

save(path: Path | str) -> None

Persist the result to disk as RFC 8259 compliant JSON.

to_dict 

to_dict() -> dict[str, Any]

Return a JSON-safe (RFC 8259) representation of the result.