API reference

This reference covers KD's dataset, model, result and analysis entry points, with signatures and parameters from the library. Common entry points are imported from kd, including kd.Model and kd.load_kdv. Batch execution, surrogate transport and plugin interfaces also expose names through kd.harness, kd.models and kd.search; each page gives the import location.

Descriptions come from the library's own docstrings, cut to reference length. Where a parameter carries more than a sentence of contract, the guide pages in the user guide and design documentation explain it: resume tiers in Parameter tiers and resuming, what the scores mean in Score conventions, term syntax in Equation representation.

Model and result

Name	Summary
`kd.Model(algorithm, generations[, ...])`	High-level facade for PDE discovery (PySR-style API).
`kd.ExperimentResult(best_expression, best_score[, ...])`	Serializable value object for a completed experiment.
`kd.SearchInterrupted`	Stop signal delivered into a running search by its embedding process.

Algorithm settings

Name	Summary
`kd.instrument_schemas()`	Return agent-facing schemas for facade plugins in registration order.
`kd.instrument_schema_digest()`	Hash mode and call-configuration declarations, excluding descriptive prose.
`kd.mode_accepts(mode, topology[, ...])`	Route from published declarations, without loading or inspecting data.
`kd.ModeVerdict(accepts, reason[, ...])`	Declaration-level applicability and parameters required for this input.
`kd.SGAConfig(num, p_var[, ...])`	Configuration for the SGA search algorithm.
`kd.DLGAConfig(mode, library[, ...])`	DLGA Stage I (constant-coefficient) configuration.
`kd.DiscoverConfig(n_iterations, seed[, ...])`	Configuration for a DISCOVER (RL + optional PINN) search run.
`kd.EqGPTConfig(sparsity_alpha, seed[, ...])`	Static configuration for the EqGPT plugin.
`kd.Llm4edConfig(temperature, max_tokens[, ...])`	Static configuration for the LLM4ED plugin.
`kd.PySRConfig(terms, seed[, ...])`	Frozen configuration for a PySR symbolic-regression run.
`kd.PySINDyConfig(terms, threshold[, ...])`	Frozen configuration for a PySINDy STLSQ fit.

Datasets

Name	Summary
`kd.PDEDataset(name, task_type[, ...])`	Complete PDE dataset specification.
`kd.load(source, coords[, ...])`	Load a catalog dataset or a file, recording provenance for files.
`kd.load_tabular(path, name)`	Load float64 columns, validating names and shapes through the tabular bridge.
`kd.inspect_file(path)`	Describe arrays in a file before choosing a dataset layout or mapping.
`kd.TabularDataset(X, y[, ...])`	A scalar regression dataset: features `X`, target `y`, metadata.
`kd.FieldData(name, values[, ...])`	Field data container.
`kd.AxisInfo(name, values[, ...])`	Coordinate axis information.
`kd.DataTopology(value, names[, ...])`	Data layout topology.
`kd.TaskType(value, names[, ...])`	Type of discovery task.
`kd.DatasetReport(name, topology[, ...])`	Structured result of `kd.preview_report` (JSON-dumpable, answer-blind).
`kd.FieldReport(name, dtype[, ...])`	Per-field facts of one dataset field.
`kd.AxisReport(name, n[, ...])`	Per-axis facts of one dataset axis.
`kd.SourceReport(path, container[, ...])`	What a data file holds before any interpretation.
`kd.ArrayReport(key, shape[, ...])`	One array inside a file, as `kd.inspect_file` describes it.
`kd.DatasetSource(path, sha256[, ...])`	Where a file-loaded dataset came from and how it was read.

Dataset catalog

Name	Summary
`kd.DatasetSpec(id, loader[, ...])`	Static metadata and loader pointer for a discoverable dataset.
`kd.list_datasets()`	Return built-in dataset specs sorted by stable dataset id.
`kd.list_datasets_answer_blind()`	Return the catalog as JSON-safe rows with the ground truth withheld.
`kd.get_dataset(dataset_id)`	Return the dataset spec for `dataset_id`.
`kd.DATASET_CATALOG`	—
`kd.list_remote_datasets()`	Return remote dataset specs sorted by stable dataset id.
`kd.load_from_hub(dataset_id, cache_dir[, ...])`	Fetch `dataset_id` from Hugging Face Hub and return a `PDEDataset`.
`kd.generate_advection_data(speeds, waves[, ...])`	Generate synthetic advection equation data.
`kd.generate_burgers_data(nx, nt[, ...])`	Generate synthetic Burgers equation data.
`kd.generate_diffusion_data(alpha, waves[, ...])`	Generate synthetic diffusion equation data.
`kd.add_noise(dataset, level[, ...])`	Return a copy of `dataset` with relative Gaussian noise on every field.
`kd.load_kdv(data_dir)`	Load KdV (Korteweg-de Vries) equation dataset.
`kd.load_burgers(data_dir)`	Load the Burgers equation reference dataset from SGA-PDE (Chen et al.).
`kd.load_burgers_2d(data_dir)`	Load the EqGPT 2D viscous Burgers benchmark (.mat), a 2+1D dataset.
`kd.load_chafee_infante(data_dir)`	Load Chafee-Infante equation dataset.
`kd.load_wave(data_dir)`	Load the wave equation benchmark (EqGPT), a second-order LHS dataset.
`kd.load_klein_gordon(data_dir)`	Load the Klein-Gordon benchmark (EqGPT), a second-order LHS dataset.
`kd.load_allen_cahn(data_dir)`	Load the Allen-Cahn reaction-diffusion benchmark (EqGPT).
`kd.load_convection_diffusion(data_dir)`	Load the convection-diffusion benchmark (EqGPT).
`kd.load_eq_6_2_12(data_dir)`	Load the EqGPT Eq. 6.2.12 mixed-derivative benchmark (CSV).
`kd.load_pde_compound(data_dir)`	Load PDE_compound (Eq. S5 from SGA-PDE paper).
`kd.load_pde_divide(data_dir)`	Load PDE_divide (Eq. S4 from SGA-PDE paper).
`kd.load_llm4ed_heat(cache_dir, offline)`	Load the LLM4ED heat-equation mirror dataset from Hugging Face Hub.
`kd.load_llm4ed_fisher(cache_dir, offline)`	Load the LLM4ED Fisher mirror dataset from Hugging Face Hub.
`kd.load_llm4ed_fisher_nonlinear(cache_dir, offline)`	Load the LLM4ED nonlinear-Fisher mirror dataset from Hugging Face Hub.
`kd.load_tlc_cc(target)`	Load the TLC-CC chromatography dataset (real-world experimental data).
`kd.load_wave_breaking(case, data_dir)`	Load wave-tank surface-elevation data (real-world experimental data).
`kd.load_wave_breaking_datasets(path, case_filter)`	Load wave-tank cases as SCATTERED datasets in sorted case-name order.

Terms and equations

Name	Summary
`kd.evaluate_terms(dataset, terms[, ...])`	Evaluate candidate terms against a dataset, fail-loud.
`kd.validate_terms(dataset, terms[, ...])`	Classify each term as valid / rejected WITHOUT fitting.
`kd.verify_equation(eq, executor[, ...])`	Verify an equation on a dataset using its reported coefficients unchanged.
`kd.block_dispersion(dataset, terms[, ...])`	Refit the terms on separate grid blocks and measure coefficient spread.
`kd.forward_error(dataset, terms[, ...])`	Integrate the equation from the data's first time slice and compare.
`kd.ForwardError(value, reason[, ...])`	Outcome of `forward_error`.
`kd.law_signature(eq)`	Build a versioned signature from an equation's active law.
`kd.format_pde(terms, coefficients[, ...])`	Build a formatted PDE equation from term strings and coefficients.
`kd.FormattedEquation(latex, unicode[, ...])`	Rendered PDE equation plus the underlying SymPy objects.
`kd.render_lhs_label(lhs_spec)`	Render an LHS spec to the legacy serialized lhs_label string.
`kd.LhsSpec(field, axis[, ...])`	Structured left-hand-side specification for an evolution equation.
`kd.Sketch(lhs_spec, vocabulary[, ...])`	A versioned evolution-law template with pinned, anchored, and hole clauses.
`kd.EvaluationResult(mse, nmse[, ...])`	Result from evaluating an expression or term list.
`kd.TermValidationReport(results, valid[, ...])`	Structured result of `validate_terms` (JSON-dumpable, no fitting).
`kd.TermRejection(term, reason)`	A single rejected term and the reason it was rejected.
`kd.VerificationReport(signature, form[, ...])`	JSON-serializable measurements for one equation on one dataset.
`kd.VerifyPolicy(nmse_max, coeff_atol[, ...])`	Thresholds used when reporting and comparing empirical verification.
`kd.SKETCH_EXIT_VERIFY`	—
`kd.InvalidTermsError(rejected)`	Raised when one or more terms are rejected and cannot be fitted.
`kd.EvaluationFailedError`	Raised when the final fit is invalid (solver failure / non-finite MSE).

Recovery scores

Name	Summary
`kd.judge_recovery(rhs, u_t[, ...])`	Judge one reconstructed RHS against a known truth law, numerically.
`kd.RecoveryVerdict(structure_ok, coefficients_ok[, ...])`	Three-axis aggregate recovery judgment (charter §5.4-3, projection form).
`kd.span_floor(u_t, truth_columns)`	Oracle B: the best NMSE reachable inside the truth span, plus its fit.
`kd.term_set_jaccard(actual, truth)`	Jaccard similarity of two term-label sets:
`kd.load_bearing_recall(verdict, nmse_threshold)`	Share of truth terms the reconstruction individually depends on.
`kd.wilson_interval(successes, trials[, ...])`	Wilson score interval for a binomial proportion.
`kd.rate_summary(successes, trials[, ...])`	`successes / trials` with its Wilson interval, as one record.
`kd.RateSummary(successes, trials[, ...])`	One benchmark cell's rate, ready for a report row.
`kd.paired_exact_test(only_a, only_b)`	Two-sided exact McNemar p-value on the discordant pairs.

Figures

Name	Summary
`kd.preview(dataset, file)`	Print a sanity-check summary of PDE data or a regression table.
`kd.preview_report(dataset)`	Build a typed report of PDE data or a regression table without printing.
`kd.VizEngine(output_dir, style)`	Orchestrates rendering of universal, plugin, and comparison plots.

Checkpoints

Name	Summary
`kd.load_checkpoint_manifest(directory)`	Load + fully verify a directory's manifest, returning entries in order.
`kd.CheckpointManifestEntry(filename, kind[, ...])`	A frozen, JSON-safe manifest entry (`kd-ckptman-v1`).
`kd.CheckpointManifestError`	Raised on any `kd-ckptman-v1` manifest contract violation.
`kd.KIND_FINAL`	—
`kd.FINAL_STATUS_COMPLETED`	—
`kd.resolve_checkpoint(checkpoint_dir, iteration)`	The archive under `checkpoint_dir` for `iteration` (the latest when None).
`kd.eligible_checkpoint_iterations(checkpoint_dir)`	The iterations that can be resumed from `checkpoint_dir`, ascending, unique.
`kd.ResolvedCheckpoint(path, iteration)`	The archive file a segment restores and the iteration it holds.
`kd.CheckpointSelectionError`	No eligible archive answers the request.

Batch experiments

Name	Summary
`kd.harness.ExperimentPlan(name, entries)`	An ordered execution matrix of plan entries with a content identity.
`kd.harness.PlanEntry(instrument, dataset_ref[, ...])`	One declarative episode: an instrument applied to a dataset at a seed.
`kd.harness.run_plan(plan, datasets[, ...])`	Pre-flight, then run every plan entry serially into a fresh store.
`kd.harness.PlanRunResult(store_root, outcomes)`	The outcome of a whole batch: the store root plus every episode outcome.
`kd.harness.EpisodeOutcome(entry_index, entry[, ...])`	The sealed result of running one plan entry.
`kd.harness.merge_stores(sources, root[, ...])`	Merge sealed stores into a new store at `root`; return it reloaded.
`kd.harness.EvidenceStore(root, plan[, ...])`	A fresh-dir, append-only, tamper-evident batch evidence directory.
`kd.harness.build_consensus(store, datasets[, ...])`	Aggregate a sealed evidence store into a consensus report tree.
`kd.harness.ConsensusReport(provenance, datasets[, ...])`	The full consensus report tree for one sealed evidence store.
`kd.harness.render_consensus_markdown(report, store)`	Render the report as a deterministic Markdown document (pure function).
`kd.harness.SKETCH_SIDECAR_FILENAME`	—
`kd.harness.ProcessSupervisor(command, env[, ...])`	Launch a command in its own session and supervise its whole process group.
`kd.harness.run_supervised(command, env[, ...])`	Launch a process group and block until cleanup or the post-SIGKILL bound.
`kd.harness.ProcessResult(pid, returncode[, ...])`	Observed leader termination, group cleanup, timing and sampled memory.
`kd.harness.ProcessEnding(value, names[, ...])`	Escalation stage reached while the leader was observed alive.
`kd.harness.build_capped_command(command, memory_max_gb)`	Prefix a command with a systemd user scope enforcing memory and no swap.
`kd.harness.check_memory_cap_available()`	Run a capped user scope to check whether memory caps are available.

Surrogate models

Name	Summary
`kd.models.save_field_model(model, path)`	Write `model` as a `kd-surrogate-v1` file and return its path.
`kd.models.load_field_model(path)`	Rebuild the `FieldModel` a `kd-surrogate-v1` file describes.

Plugin interfaces

Name	Summary
`kd.search.SurrogateTrainer(args, kwargs)`	Plugin face for training the derivative surrogate as a standalone action.