Algorithm settings
Each algorithm has its own config class. Once kd.Model(config=...) receives
one it is the single source of that algorithm's settings, and passing the same
settings as kd.Model keywords alongside it raises. Every field of every class
is documented below. The main parameters of each, with their defaults and resume
tiers, are tabulated on the algorithm's own page, read from
the same definitions.
| 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. |
instrument_schemas() -> list[dict[str, Any]]
Return agent-facing schemas for facade plugins in registration order.
instrument_schema_digest() -> str
Hash mode and call-configuration declarations, excluding descriptive prose.
mode_accepts(
mode: Mapping[str, Any],
*,
topology: str,
form: str,
lhs_order: int,
field_names: Sequence[str],
spatial_axes: Sequence[str],
) -> ModeVerdict
Route from published declarations, without loading or inspecting data.
dataclass
Declaration-level applicability and parameters required for this input.
dataclass
Configuration for the SGA search algorithm.
class-attribute
instance-attribute
aic_ratio: float = 1.0
AIC penalty ratio.
class-attribute
instance-attribute
autograd_train_epochs: int = 1000
Maximum training epochs for the auto-trained FieldModel. Only used when
use_autograd=True and field_model is None.
class-attribute
instance-attribute
autograd_train_lr: float = 0.001
Learning rate for the auto-trained FieldModel. Only used when
use_autograd=True and field_model is None.
class-attribute
instance-attribute
autograd_train_patience: int | None = None
Early-stopping patience for the auto-trained FieldModel (epochs without
validation improvement). None (default) disables early stopping, so the
surrogate trains the full autograd_train_epochs budget — the v1 / paper
reference semantics (sgapde/metann.py fixed-step training, no early stop).
Requires autograd_train_val_ratio > 0 (there is no validation signal to
monitor otherwise). Only used when use_autograd=True and
field_model is None; ignored in finite-diff mode (same handling as
autograd_train_epochs).
class-attribute
instance-attribute
autograd_train_val_ratio: float = 0.0
Fraction of data held out for validation while auto-training the
FieldModel. 0.0 (default) trains on ALL data — the v1 / paper reference
semantics (full-data training, no val split). Set > 0 only when using
autograd_train_patience for early stopping. Only used when
use_autograd=True and field_model is None; ignored in finite-diff
mode (same handling as autograd_train_epochs).
class-attribute
instance-attribute
d_tol: float = 1.0
Tolerance step size for STRidge sweep.
class-attribute
instance-attribute
dedup_mode: DedupMode = 'pre_prune'
Deduplication strategy for genetic offspring.
class-attribute
instance-attribute
depth: int = 4
Maximum tree depth for each term.
class-attribute
instance-attribute
field_model: FieldModel | None = None
Optional pre-trained FieldModel surrogate (skips auto-training when
use_autograd=True). Must have matching coord_names /
field_names. Ignored when use_autograd=False.
class-attribute
instance-attribute
lam: float = 0.0
Ridge lambda (0 = OLS).
class-attribute
instance-attribute
maxit: int = 10
Max steps of the inner per-candidate STRidge tolerance sweep
(train_sweep in sga/train.py).
class-attribute
instance-attribute
normalize: int = 2
Column norm order for STRidge normalization.
class-attribute
instance-attribute
num: int = 20
Population size (number of PDE candidates).
class-attribute
instance-attribute
p_cro: float = 0.5
Crossover probability between PDEs.
class-attribute
instance-attribute
p_mute: float = 0.3
Mutation probability per node.
class-attribute
instance-attribute
p_rep: float = 1.0
Replace probability (chance of replacing a term).
class-attribute
instance-attribute
p_var: float = 0.5
Probability that a node is a variable (vs. operator).
class-attribute
instance-attribute
restart_interval: int | None = None
Number of committed generations between population re-draws.
class-attribute
instance-attribute
seed: int = 0
Random seed for reproducibility.
class-attribute
instance-attribute
str_iters: int = 10
STRidge internal iterations per tolerance level.
class-attribute
instance-attribute
use_autograd: bool = False
Derivative source for the Layer 2 terminals (u_x, u_t): with autograd, SGA
trains (or reuses) a FieldModel surrogate and reads them through
AutogradProvider; otherwise they come from finite differences. The facade
spells the two settings derivatives="autograd" and
derivatives="finite_diff". Layer 1 (raw u leaf) and Layer 3 (tree
d / d^2 operators) are unchanged.
class-attribute
instance-attribute
width: int = 5
Maximum number of terms per PDE.
dataclass
DLGA Stage I (constant-coefficient) configuration.
class-attribute
instance-attribute
add_rate: float = 0.4
Probability that a newly built random term is appended to a candidate, from 0 to
1. The term is added only if the candidate is below max_modules and does not
already contain it.
class-attribute
instance-attribute
auto_upgrade_threshold: float
Reserved for the planned mode="auto" escalation: the best NMSE above which
the search would hand over to an adaptive, variable-coefficient stage. It has no
effect today, because "constant" is the only implemented mode, and the 1e-3
default is an untuned placeholder.
class-attribute
instance-attribute
crossover_rate: float = 0.8
Probability that a pair of surviving candidates exchanges one term during crossover, from 0 to 1. Survivors are paired off in order, and each pair either swaps one randomly chosen term or passes through unchanged.
class-attribute
instance-attribute
delete_rate: float = 0.5
Probability that one term is dropped from a candidate, from 0 to 1. A candidate
that is down to a single term is left unchanged. The draw is independent of
add_rate, so one candidate can gain and lose a term in the same generation.
class-attribute
instance-attribute
epsilon: float = 0.001
Complexity penalty in the genetic fitness NMSE + epsilon * length, where
length is the total number of tokens across the candidate's terms. Raise it
to push the search toward shorter equations; the useful value is problem-
dependent, and the packaged presets span 1e-6 to 1e-3.
class-attribute
instance-attribute
genes_prob: float = 0.6
Probability, from 0 to 1, of adding one more term while a random candidate
equation is built. Generation stops once the candidate reaches max_modules
terms.
class-attribute
instance-attribute
lhs_auto_select: bool = False
When False, every candidate is fitted against the time derivative of the order
target_lhs_order names (u_t for 1, u_tt for 2) and no other. When True,
every candidate is fitted against both u_t and u_tt, as the original
DLGA-PDE code does, and the branch with the lower NMSE is kept (the original code
compares raw MSE); the returned law's left-hand side can then be the order the
dataset does not declare. A fit given a sketch uses the left-hand side the
sketch states and does not read this flag.
class-attribute
instance-attribute
library: list[str]
Ordered vocabulary of tokens that candidate terms are built from, defaulting to
["u", "u_x", "u_xx", "u_xxx"]. Each term is a product of tokens drawn from
this list, and the ordering matters: one of the mutation operators shifts a token
to an adjacent entry.
class-attribute
instance-attribute
max_module_length: int = 5
Maximum number of tokens multiplied together inside a single term.
class-attribute
instance-attribute
max_modules: int = 5
Maximum number of additive terms allowed in one candidate equation.
class-attribute
instance-attribute
mode: Literal['constant', 'adaptive', 'auto']
Coefficient mode of the search; only "constant" (constant-coefficient
equations) is implemented. The values "adaptive" and "auto" pass
configuration validation but raise NotImplementedError when the algorithm is
constructed.
class-attribute
instance-attribute
mutation_rate: float = 0.4
Probability that a mutation shifts one factor of one term along library, from
0 to 1. The shift is to an adjacent entry, except for a factor sitting at the
first entry, which is redrawn from the whole library.
class-attribute
instance-attribute
partial_prob: float = 0.6
Probability, from 0 to 1, of extending a randomly built term with one more
factor. The term stops growing once it reaches max_module_length.
class-attribute
instance-attribute
pop_size: int = 400
Number of candidate equations in each generation of the genetic search, which is also how many candidates the platform evaluates per iteration.
class-attribute
instance-attribute
seed: int = 0
Random seed of the genetic search: it seeds the generator behind the initial population and every crossover, mutation, add and delete draw, and is also forwarded to the surrogate network's training. Runs differing only in this value explore different candidates.
class-attribute
instance-attribute
solver: Literal['svd_null_space', 'ols'] = 'svd_null_space'
Solver used to fit each candidate's coefficients against the left-hand side:
"svd_null_space" takes the null space of the augmented system (total least
squares), "ols" uses ordinary least squares.
class-attribute
instance-attribute
surrogate_activation: Literal["tanh", "sin", "relu"] = "sin"
Activation applied after each hidden layer of the fitted network: tanh,
sin, or relu. The default sin stays smooth under the repeated
differentiation the search relies on, which relu does not.
class-attribute
instance-attribute
surrogate_hidden_sizes: list[int]
Widths of the hidden layers in the neural network fitted to the field data, one hidden layer per entry (default five layers of 50 units). The search differentiates this network for the derivatives it scores, so its capacity bounds their accuracy.
class-attribute
instance-attribute
surrogate_lr: float = 0.001
Learning rate of the Adam optimizer used to fit the network to the field data.
class-attribute
instance-attribute
surrogate_max_epochs: int = 50000
Maximum number of epochs to spend fitting the network, one full-batch Adam step per epoch. It trades run time against derivative accuracy: dropping the default 50000 to a few thousand finishes much sooner with coarser derivatives.
class-attribute
instance-attribute
surrogate_patience: int | None = None
Number of consecutive epochs without validation-loss improvement after which the
fit stops early. None, the default, disables early stopping and runs the full
surrogate_max_epochs budget; other values need surrogate_val_ratio above
0 to take effect.
class-attribute
instance-attribute
surrogate_restore_best: bool = True
If True, the weights from the epoch with the lowest validation loss are restored
at the end of the fit instead of keeping the last epoch's weights. Has no effect
when surrogate_val_ratio is 0, since there is no validation loss to rank
epochs by.
class-attribute
instance-attribute
surrogate_val_ratio: float = 0.2
Fraction of the samples held out to measure validation loss while fitting the
network, from 0 up to but not including 1. Setting it to 0 trains on every sample
and leaves surrogate_patience and surrogate_restore_best with no signal
to act on.
class-attribute
instance-attribute
target_lhs_order: int = 1
Set to the dataset's left-hand-side order; 2 for u_tt.
classmethod
burgers_preset(**overrides: Any) -> DLGAConfig
DLGAConfig for the Burgers equation (epsilon=1e-3).
classmethod
chafee_preset(**overrides: Any) -> DLGAConfig
DLGAConfig for Chafee-Infante (epsilon=1e-5).
classmethod
kdv_preset(**overrides: Any) -> DLGAConfig
DLGAConfig for the KdV equation (epsilon=1e-6).
classmethod
kg_preset(**overrides: Any) -> DLGAConfig
DLGAConfig for the Klein-Gordon equation (u_tt LHS, epsilon=1e-3).
classmethod
wave_preset(**overrides: Any) -> DLGAConfig
DLGAConfig for the wave equation (u_tt LHS, epsilon=1e-3).
dataclass
Configuration for a DISCOVER (RL + optional PINN) search run.
class-attribute
instance-attribute
attention: bool = False
When True, the controller applies additive (Bahdanau) attention over a sliding
window of its own recent outputs before producing token logits. The window length
is attn_length.
class-attribute
instance-attribute
attn_length: int = 10
Length of the attention window, in past controller steps. It has no effect when
attention is False.
class-attribute
instance-attribute
baseline: str = 'R_e'
Value subtracted from the rewards in the policy-gradient loss. "R_e" (the
default) uses the risk-seeking reward quantile itself, "ewma_R" a moving
average of the mean kept reward, and "combined" the quantile plus a moving
average of the gap between the two.
class-attribute
instance-attribute
batch_size: int = 16
Number of candidate expressions sampled per search iteration, and the batch the
policy-gradient update is computed from; larger batches give a steadier signal at
more compute per iteration. On tabular data, kd.Model defaults to 500 with
epsilon=0.05 to retain multiple reward-bearing samples after invalid candidates
are removed.
class-attribute
instance-attribute
diagnostic_scaffold: bool = False
Attach the diagnostic scaffold prior, which restricts sampling in the first
search cycle to a root token from diagnostic_scaffold_root_tokens whose two
branches draw on disjoint token sets. Off by default; True also requires
DISCOVER_ENABLE_DIAGNOSTICS=1 in the environment, because the scaffold builds
an assumed equation shape into the search.
class-attribute
instance-attribute
diagnostic_scaffold_diffusion_tokens: tuple[str, ...] = ()
Token names the scaffold keeps to the left branch of the root: each one is
excluded from sampling while the right branch is filled. Read only when
diagnostic_scaffold is True, and a name also listed as neutral is exempt.
class-attribute
instance-attribute
diagnostic_scaffold_neutral_tokens: tuple[str, ...] = ()
Token names the scaffold never excludes, so they stay samplable in both branches
even when they also appear in the diffusion or reaction list. Read only when
diagnostic_scaffold is True; a name shared with
diagnostic_scaffold_root_tokens is rejected.
class-attribute
instance-attribute
diagnostic_scaffold_reaction_tokens: tuple[str, ...] = ()
Token names the scaffold keeps to the right branch of the root: each one is
excluded from sampling while the left branch is filled. Read only when
diagnostic_scaffold is True, and a name also listed as neutral is exempt.
class-attribute
instance-attribute
diagnostic_scaffold_root_tokens: tuple[str, ...] = (
"add",
"sub",
)
Token names the scaffold allows at the root of a sampled expression; at the first
sampling step every other token is excluded, so the tree starts from one of
these. Defaults to ("add", "sub") and is read only when
diagnostic_scaffold is True; a set in which no name exists in the token
library fails when the search is built.
class-attribute
instance-attribute
embedding_dim: int = 4
Width of the learned embedding used for each categorical observation channel. It
has no effect unless use_embedding is True, which replaces the one-hot inputs
with embeddings of this size.
class-attribute
instance-attribute
entropy_gamma: float = 1.0
Per-position decay of the entropy bonus: the entropy at position t of a
sampled sequence is weighted by entropy_gamma ** t. The default 1.0 weights
every position equally; values below 1 concentrate the exploration bonus on the
first tokens.
class-attribute
instance-attribute
entropy_weight: float = 0.005
Weight of the entropy bonus added to the policy-gradient loss, which rewards a less peaked sampling distribution. Must be non-negative; raise it when the controller commits to one expression family too early, set 0.0 to drop the bonus.
class-attribute
instance-attribute
epsilon: float = 0.1
Risk-seeking quantile: the policy-gradient update keeps the batch rewards at
or above the 1 - epsilon quantile (RSPGStrategy), so a smaller value is a
greedier update off fewer samples. Ties at the quantile are all kept, so the
retained share can exceed epsilon (an all-equal batch keeps everything). Must
lie in (0, 1]. With the R_e baseline the advantage is reward - quantile,
so batch_size * epsilon must exceed 1 or the quantile is the batch maximum and
the reward term of the loss is identically zero. The default 0.10 is sized for
the default batch of 16; the packaged PDE presets pair 0.01-0.02 with batches of
500-1000. On tabular data, kd.Model defaults to 0.05 with a batch of 500 so
multiple samples can have nonzero advantage after invalid candidates are removed.
The batch_size * epsilon > 1 rule applies to the remaining valid batch.
class-attribute
instance-attribute
gamma: float = 0.5
Decay of the moving-average baseline: the running value keeps weight gamma
and the new batch contributes 1 - gamma. In the range 0 to 1, and only read
when baseline is "ewma_R" or "combined".
class-attribute
instance-attribute
initializer: Literal['xavier', 'zeros'] = 'xavier'
Parameter initialization scheme, either "xavier" or "zeros". "xavier"
draws all parameters from a Xavier/uniform baseline; "zeros" also zeroes the
LSTM cell parameters and the output bias, making the initial token distribution
uniform.
class-attribute
instance-attribute
learning_rate: float = 0.001
Step size of the Adam optimizer that updates the controller network. A run resumed from a checkpoint adopts this value rather than the one saved with the checkpoint.
class-attribute
instance-attribute
library: LibraryConfig
Operator/terminal table the controller samples expression trees from. It
carries three lists: operators (the function set, default ["add",
"mul", "sub", "div", "sin", "cos", "diff_x", "diff2_x"]), state_vars
(default ["u"]) and coord_vars (default ["x", "t"]). Library
lays the tokens out in the order coord_vars, state_vars, operators, and that
order fixes the token indices the controller's logits and the sampling priors
address.
class-attribute
instance-attribute
magnitude_filter: bool = False
When True, a fit whose active coefficients include any magnitude below
5e-5 or above 1e4 is marked invalid, so it scores zero reward and is
dropped from controller training. Defaults to False, which accepts a fit at
any coefficient magnitude.
class-attribute
instance-attribute
max_diff_order: int | None = 4
Highest cumulative derivative order allowed in a sampled expression; candidates
above it are rejected before evaluation. Orders accumulate along a chain, so
diff2_x(diff_x(u)) counts as 3, and None disables the check.
class-attribute
instance-attribute
max_length: int = 15
Maximum number of tokens in a sampled expression tree, default 15. The length prior forbids any operator that could not still finish the tree within this budget, so a sample never exceeds it; the same bound also caps the complexity of the frontier rows the plugin publishes.
class-attribute
instance-attribute
min_length: int = 2
Minimum length of a sampled expression, in tokens. The sampler is forbidden from ending an expression before this many tokens, and any candidate that still comes out shorter is rejected before evaluation.
class-attribute
instance-attribute
n_iterations: int = 2000
With pinn set, the number of search generations before the first PINN phase,
which must be smaller than Model(generations=...) for any PINN phase to run;
without pinn, kd.Model ignores this field and warns on a non-default value.
The default 2000 is not smaller than the facade's default of 50 generations. On
the standalone paths, where Model(generations=...) does not exist, it is the
number of search iterations the entry point runs, one controller batch per
iteration, and the length of a PINNCycleRunner cycle unless
PINNConfig.cycle_n_iterations sets the later cycles.
class-attribute
instance-attribute
num_layers: int = 1
Number of stacked LSTM layers in the controller. Layers beyond the first take the previous layer's hidden state as their input.
class-attribute
instance-attribute
num_units: int = 16
Number of hidden units in each LSTM layer of the controller. It also sets the
width of the attention projections when attention is enabled.
class-attribute
instance-attribute
observe_action: bool = False
When True, the token sampled at the previous step is added to the controller
input, as a one-hot vector or as an embedding when use_embedding is set.
class-attribute
instance-attribute
observe_dangling: bool = False
When True, the count of unfilled argument slots in the partial expression tree is
appended to the controller input as a single numeric value. This channel is
always a raw count, so use_embedding does not apply to it.
class-attribute
instance-attribute
observe_parent: bool = True
When True, the parent token of the position about to be sampled is added to the
controller input, as a one-hot vector or as an embedding when use_embedding
is set. At least one of the four observation channels must be enabled.
class-attribute
instance-attribute
observe_sibling: bool = True
When True, the left sibling token of the position about to be sampled is added to
the controller input, as a one-hot vector or as an embedding when
use_embedding is set. At least one of the four observation channels must be
enabled.
class-attribute
instance-attribute
pinn: PINNConfig | None = None
Settings for the optional PINN surrogate, which alternates symbolic search with
training a network on the data and takes derivatives from that trained network.
None (the default) searches on finite-difference derivatives. kd.Model
takes a PINNConfig or a JSON object of its fields; the network is retrained
after generation n_iterations and then every
PINNConfig.cycle_n_iterations generations.
class-attribute
instance-attribute
repeat_max: int = 5
Maximum combined number of times the repeat_tokens may appear in one
expression; on reaching the count those tokens are removed from the sampling
distribution for the rest of that expression. Read only when use_repeat_prior
is true.
class-attribute
instance-attribute
repeat_tokens: list[str]
Token names counted by the repeat limit, sharing one budget: their occurrences
are pooled and compared against repeat_max. Read only when
use_repeat_prior is true, and every name must exist in the token library.
class-attribute
instance-attribute
reward_alpha: float = 0.01
Weight of the complexity penalty in the reward (1 - reward_alpha * complexity)
/ (1 + sqrt(nmse)). Larger values push the search toward shorter equations;
since the reward is clipped at 0, a large value flattens long candidates to zero
reward.
class-attribute
instance-attribute
seed: int = 0
Random seed of the search: torch.manual_seed is called with this value when
the algorithm is constructed and again before the engine is built, so it governs
both the controller's weight initialization and every token sampled from it. It is
the only seeding entry and overrides a torch.manual_seed the caller made
beforehand.
class-attribute
instance-attribute
soft_length_loc: float | None = None
Target expression length in tokens: past position soft_length_loc the
sampling logits of operator tokens are reduced by (t - soft_length_loc)**2 / (2
* soft_length_scale), so sampling tends to terminate near that length.
None, the default, leaves the prior off.
class-attribute
instance-attribute
soft_length_scale: float = 5.0
Width of the length penalty past soft_length_loc, which is (t -
soft_length_loc)**2 / (2 * soft_length_scale): larger values make the pull
toward the target length gentler. Must be positive, and is read only when
soft_length_loc is set.
class-attribute
instance-attribute
stability_queue_capacity: int = 10
With pinn set and stability_selection greater than 0, the maximum number
of distinct candidates kept in the reward-ordered per-cycle pool that stability
selection draws from; without pinn, the pool is not read and kd.Model warns
on a non-default value. It must be at least as large as stability_selection.
class-attribute
instance-attribute
stability_selection: int = 0
With pinn set, the number of distinct top-reward candidates from the final
search cycle that enter bootstrap stability selection, which re-fits each candidate
on resampled rows and keeps the one that wins the most resamples; without
pinn, no selection runs and kd.Model warns on a non-default value. 0
(the default) skips the step and keeps the best-reward candidate.
class-attribute
instance-attribute
token_bias_tokens: tuple[str, ...] = ()
Token names whose sampling probability is shifted by token_bias_weight,
identically at every step of every sampled expression. The bias applies only when
this list is non-empty and token_bias_weight is not 0.0; a name absent
from the token library is skipped.
class-attribute
instance-attribute
token_bias_weight: float = 0.0
Amount added to the log-probability of every token in token_bias_tokens, the
same at each sampling step. Positive values make those tokens more likely and
negative values less likely; 0.0 (the default) leaves the bias off.
class-attribute
instance-attribute
use_diff_child_prior: bool = True
If True, restrict the child of a derivative token to a state variable or another
derivative token; coordinate variables and every other operator are forbidden in
that position. This keeps constant terms such as diff_x(x) out of the search.
class-attribute
instance-attribute
use_diff_descendant_prior: bool = True
If True, forbid add and sub anywhere inside the subtree of a derivative
token, so no sampled candidate differentiates a sum.
class-attribute
instance-attribute
use_embedding: bool = False
When True, the categorical observation channels enter the controller as learned
embeddings of width embedding_dim instead of one-hot vectors. The dangling-
slot count is unaffected and stays a single numeric input.
class-attribute
instance-attribute
use_inverse_prior: bool = True
If True, forbid a unary token from being the direct child of its own inverse, so
cancelling pairs such as exp(log(u)) and sqrt(n2(u)) are never sampled.
Only pairs whose two tokens are both in the library are constrained.
class-attribute
instance-attribute
use_repeat_prior: bool = True
If True, stop a token from being sampled again once it has already appeared
repeat_max times in the expression being built. The tokens subject to the
limit are named in repeat_tokens; with the defaults this caps add at five
and so bounds the number of additive terms.
class-attribute
instance-attribute
use_trig_prior: bool = True
If True, forbid trigonometric and derivative tokens anywhere inside the subtree
of another trigonometric or derivative token. This rules out compositions such as
sin(cos(u)) and, because derivative tokens are included, nested derivatives
such as diff_x(diff_x(u)).
classmethod
burgers_preset(**overrides: Any) -> DiscoverConfig
Config matching DISCOVER reference for the Burgers equation.
classmethod
chafee_preset(**overrides: Any) -> DiscoverConfig
Config matching DISCOVER reference for the Chafee-Infante equation.
dataclass
Static configuration for the EqGPT plugin.
class-attribute
instance-attribute
asset_dir: Path | None = None
Directory holding the pretrained GPT checkpoint at
gpt_model/PDEGPT_wave_breaking.pt, consulted when weights_path is unset.
With both unset the directory is read from the KD_EQGPT_ASSET_DIR environment
variable, and with that unset too the checkpoint is downloaded once from the KD
Hub mirror (kd.data.remote.fetch_eqgpt_weights) into the Hugging Face cache.
class-attribute
instance-attribute
case_filter: str | None = None
Wave_multicase only: substring matched against the wave-breaking case names:
every case whose name
contains it is scored, and a candidate's reward is the mean over the cases that
could be scored. Setting it selects multi-case wave mode; None (default)
keeps the single-case path.
class-attribute
instance-attribute
coeff_points_per_window: int = 100
Wave_multicase only: number of x sample points per camera window on the grid
used for the final
coefficient fits. This grid stays separate from the reward grid
(reward_points_per_window): scoring runs on the reward grid, the reported
coefficients are fitted on this one.
class-attribute
instance-attribute
exploration_rate: float = 0.2
Probability of drawing the next token uniformly from the legal tokens instead of from the model's distribution, from 0 to 1. The draw is made independently at every token position.
class-attribute
instance-attribute
finetune_lr: float = 1e-05
Learning rate of the Adam optimizer that fine-tunes the model on the pool of best candidates. A resumed run adopts the current value: the restored optimizer keeps its moment estimates but takes its learning rate from this field.
class-attribute
instance-attribute
finetune_steps: int = 5
Number of gradient steps taken on the pool of best candidates after each iteration. Each step is one full pass over the pool, and the reported fine-tuning loss is the mean over the steps.
property
is_steady: bool
True when the plugin runs its homogeneous free-pivot path.
property
is_wave_multicase: bool
True when the plugin runs in multi-case wave mode.
class-attribute
instance-attribute
masked_tokens: frozenset[int]
Extra vocabulary token ids the sampler must never emit. They are added to the masks the algorithm derives on its own from the declared axes, the derivative order the data supports, and the tokens the platform can represent, so this parameter only ever widens the mask.
class-attribute
instance-attribute
max_length: int = 49
Maximum number of tokens in a sampled sentence, counting the pinned
start_words prefix; it must stay below the model's context length, and the
default 49 is the largest value the pretrained model accepts. Sampling stops
there if no end token is drawn first, and the value must exceed
len(start_words).
class-attribute
instance-attribute
primary_case: str | None = None
Wave_multicase only: name of the case, among those case_filter selects, whose
coefficient fit is
reported as the run's final result. When None (default) the first selected
case in sorted order is used; a name outside the selection, or a value given
without case_filter, is rejected.
The dataset passed to fit must equal this case's data: axis order, field
names and every coordinate and field value are compared; the name may differ.
class-attribute
instance-attribute
reward_points_per_window: int = 50
Wave_multicase only: number of x sample points per camera window on the grid
used to score
candidates. The grid covers three camera windows, so each time slice contributes
three times this value; it must be a positive integer.
class-attribute
instance-attribute
samples_per_epoch: int = 400
Number of candidate sentences drawn from the model per iteration; the platform uses it as the batch size for each search iteration. Sentences that cannot be converted into a valid expression are dropped, so fewer candidates may reach scoring.
class-attribute
instance-attribute
seed: int = 0
Random seed of candidate sampling: it seeds the generator that hands every
sampling call its own sub-seed, exploration draws included. A run resumed from a
checkpoint restores the saved generator state instead, and falls back to this
value when the checkpoint carries none. A run resumed with reseed=True
branches: it keeps the checkpoint's search state but re-derives the generator
from this value, so the branch draws the stream a fresh run on this seed would
draw, from the checkpoint's fine-tuned model and elite pool rather than a cold
one.
instance-attribute
sparsity_alpha: float
Weight of the term-count penalty in the reward: a candidate's R^2 is
multiplied by 1 - sparsity_alpha * log10(number of distinct terms). It has no
default because the value is problem-specific; the Burgers and wave presets pin
0.02 and the steady presets 1.0.
class-attribute
instance-attribute
start_words: tuple[str, ...] = ('S', 'ut', '+')
Vocabulary words pinned at the head of every sampled sentence, so generation
always continues from the same prefix. The default ("S", "ut", "+") fixes the
left-hand side to the time derivative, and the prefix is removed from the right-
hand side the algorithm reports.
class-attribute
instance-attribute
steady: bool = False
Run the time-independent EqGPT search, where each candidate is a homogeneous
relation whose terms sum to zero rather than an equation with a fixed left-hand
side. The first term's coefficient is pinned to 1 and the remaining coefficients
are fitted by least squares on a surrogate network the algorithm trains itself;
enabling it requires start_words=("S",) and steady_activation, and
excludes case_filter.
class-attribute
instance-attribute
steady_activation: Literal['sin', 'rational'] | None = None
Activation function of the surrogate network trained in steady mode, either
"sin" or "rational". The choice also selects that network's weight
initialization; it is required when steady is True and must stay None
otherwise.
class-attribute
instance-attribute
steady_boundary_delete_num: int | None = None
Width, in grid cells, of the border removed from the steady evaluation domain;
None (the default) keeps every dataset point. A point survives only if it
sits at least this many cells from every edge with a fully populated surrounding
block, so the data must lie on a grid; it requires steady=True and excludes
steady_polar_eval.
class-attribute
instance-attribute
steady_boundary_grid: tuple[float, ...] | None = None
Grid used only for boundary deletion, given as six numbers in the order
(x_start, x_stop, x_step, y_start, y_stop, y_step). Each axis is built with
np.arange(start, stop + step, step). When None (the default), the grid
uses the distinct coordinate values in the data, so a grid row or column with
no data point is missing from it. The eitech and smile presets set this field;
it requires steady_boundary_delete_num.
class-attribute
instance-attribute
steady_constant_column: bool = False
Add a constant column to the term matrix used to score and refit steady
candidates, letting the recovered relation carry a constant offset. Requires
steady=True.
class-attribute
instance-attribute
steady_polar_eval: bool = False
Score steady candidates on a generated polar domain instead of the dataset's own
points. The domain is 100 radii from 0.5 to 1.45 crossed with 100 angles over the
full circle, converted to (x, y); it requires steady=True and excludes
steady_boundary_delete_num.
class-attribute
instance-attribute
steady_surrogate_seed: int = 525
Random seed for the steady surrogate; it fixes both the network's initial weights
and the split of the data into training and validation points. It is separate
from seed, which drives candidate sampling, and a value other than the
default 525 requires steady=True.
class-attribute
instance-attribute
steady_train_iters: int = 50000
Number of optimizer iterations used to train the steady surrogate over the full
training sample, 50000 by default. The whole budget runs unless the loss becomes
non-finite, in which case training rolls back to the last finite weights and
stops; a value other than the default requires steady=True.
class-attribute
instance-attribute
steady_train_points: int = 10000
Number of dataset points sampled to train the steady surrogate network, 10000 by
default. The sample is capped at one below the number of available points so a
validation point remains; a value other than the default requires
steady=True.
class-attribute
instance-attribute
steady_validate_points: int = 1000
Number of points held out from the training sample to validate the steady
surrogate, 1000 by default. Training keeps the checkpoint with the lowest
validation loss; the count is capped by whatever points steady_train_points
leaves, and a value other than the default requires steady=True.
class-attribute
instance-attribute
top_k: int = 10
Maximum size of the running pool of best candidates, which is held sorted by reward and deduplicated by reward value. The same pool is the corpus the model is fine-tuned on after every iteration, so this sets both the pool cap and the fine- tuning batch.
class-attribute
instance-attribute
v1_asset_dir: Path | None = None
Directory holding the pretrained per-case surrogate checkpoints used to evaluate
candidate terms in multi-case wave mode; one checkpoint is loaded per selected
case. When None (default), the directory is taken from the
KD_V1_WAVE_ASSETS environment variable, and if neither is set the tree is
downloaded once from the KD Hub mirror
(kd.data.remote.fetch_wave_surrogate_tree).
class-attribute
instance-attribute
variables: tuple[str, ...] | None = None
Coordinate axis names of the dataset; an explicit value must name exactly the
dataset's axes, or the run is refused before the search starts, so this field
cannot restrict the search to fewer axes. None (the default) takes the axes
from the dataset. Vocabulary tokens naming an axis outside this set are masked
out of sampling.
class-attribute
instance-attribute
wave_pkl_path: Path | None = None
Path to the pickle file of wave-breaking cases that case_filter selects from.
When None (default), it resolves to data/hf-
knowledgediscover/WaveBreaking.pkl under the project root, and a missing file
raises FileNotFoundError.
class-attribute
instance-attribute
weights_path: Path | None = None
Path to the pretrained GPT checkpoint file, taking precedence over asset_dir
and the KD_EQGPT_ASSET_DIR environment variable. When set, the file must
exist: a missing path raises FileNotFoundError instead of falling back to the
other two sources.
classmethod
burgers_preset(**overrides: Any) -> EqGPTConfig
EqGPTConfig for the Burgers equation (sparsity_alpha=0.02).
classmethod
steady_preset(
dataset: Literal["eitech", "smile", "disk"],
**overrides: Any,
) -> EqGPTConfig
Build one of the three published steady EqGPT configurations.
classmethod
wave_preset(**overrides: Any) -> EqGPTConfig
EqGPTConfig for the wave-breaking multi-case showcase.
dataclass
Static configuration for the LLM4ED plugin.
class-attribute
instance-attribute
base_url: str | None = None
Optional endpoint override for the default provider.
property
config: dict[str, Any]
JSON-safe config dict prefixed {"algorithm": "llm4ed", ...}.
class-attribute
instance-attribute
extra_body: dict[str, Any] | None = None
Optional request body options forwarded unchanged to the default provider.
None omits the SDK keyword; unused when a provider is injected.
class-attribute
instance-attribute
init_num: int = 20
The number of equations the init PROMPT asks the LLM to generate (EDL
optimzier_utils.py:108, prompt-text only). Does NOT change the returned
batch size, which is n like every round (EDL GENERATION_NUM = args.N
covers initialization). Default 20.
class-attribute
instance-attribute
max_llm_calls_per_propose: int = 50
Plugin-owned upper bound on resample complete() calls within one
propose. kd guardrail.
class-attribute
instance-attribute
max_llm_calls_per_run: int = 200
Whole-run call budget fed to the default chain's BudgetedProvider. kd
guardrail.
class-attribute
instance-attribute
max_tokens: int = 1024
LLM max decode tokens. Default 1024 (kd-side pin; EDL does not fix a value).
class-attribute
instance-attribute
model: str = 'gpt-4o-mini'
LLM model id for the default OpenAICompatProvider (transport; unused when a
provider is injected).
class-attribute
instance-attribute
pool_size: int = 5
Elite pool capacity k (EDL PriorityQueue). Default 5.
class-attribute
instance-attribute
reward_limit: float = 0.5
filter_score drops candidates with score <= reward_limit. Default
0.5 (EDL).
class-attribute
instance-attribute
samples_per_epoch: int = 8
Per-round proposal count -- the Runner's per-iteration batch size (EDL --N /
GENERATION_NUM; the reference script uses 8). Default 8. Read by the
plugin's runner_batch_size property.
class-attribute
instance-attribute
seed: int = 0
Base seed for the monotonic per-call LLM seed counter.
class-attribute
instance-attribute
stop_threshold: float = 0.995
is_done fires when best_reward >= stop_threshold. Default 0.995
(EDL); reward direction is max, range ~(0, 1].
class-attribute
instance-attribute
tape_record_path: str | None = None
Optional JSONL path. When set (and no provider is injected), the default chain
wraps the transport in a TapeRecordingProvider so every real
request/response is recorded to this path -- the offline replay fixture for CI +
the manual real-backend recovery step. None records nothing.
class-attribute
instance-attribute
temperature: float = 0.8
LLM sampling temperature. Default 0.8 (EDL Burgers, NOT the generic 1.0).
Packed into LLMParams per call.
dataclass
Frozen configuration for a PySR symbolic-regression run.
Fields:
- terms: the Theta library -- the candidate term columns (kd funcall
IR) PySR regresses over. Must be non-empty.
- seed: random seed forwarded to PySR's random_state. Weak
reproducibility only: PySR upstream warns that random_state
without deterministic=True and serial execution does not pin
run-to-run results (observed in smoke), so under kd defaults the
seed makes runs statistically similar, not bit-identical -- and the
run manifest's seed inherits this weaker meaning for PySR runs.
For full determinism pass extra_pysr_kwargs={"deterministic":
True, "parallelism": "serial"}, at a significant speed cost.
- niterations: number of PySR internal GP iterations (algebraic
generations inside PySR); the facade generations parameter maps
here. It controls only PySR's own evolutionary loop, never the kd runner
loop. On a resume it is the number of FURTHER iterations the new segment
runs from the archived populations (an increment, not a total).
- population_size / populations / maxsize: PySR GP knobs
(per-population members, number of populations, max expression size).
- binary_operators / unary_operators: operator sets exposed to
PySR. PDE defaults omit unary operators to avoid fitted constants
nested inside structural terms; tabular defaults retain sin/cos/exp/log.
Explicit operator sets are preserved. Adding "^" or a
custom operator may cause the downstream from_sympy conversion to
fail hard.
- extra_pysr_kwargs: a pass-through seam splatted into the underlying
PySRRegressor constructor. The caller owns the JSON-safe (and
PySR-valid) responsibility for whatever it puts here; defaults to
None (never a shared mutable {}). A timeout_in_seconds here
is the upper bound of every fit's time limit, re-applied to each
segment: a wall-clock deadline announced to the plugin can shorten a
fit below it, never lengthen it.
class-attribute
instance-attribute
binary_operators: tuple[str, ...] = ('+', '-', '*', '/')
Binary operators allowed in the PySR expression grammar.
class-attribute
instance-attribute
extra_pysr_kwargs: dict[str, Any] | None = None
Additional PySR backend options; typed configuration keys are refused.
class-attribute
instance-attribute
terms: tuple[str, ...] = ("u", "u_x", "u_xx", "mul(u, u_x)")
Ordered catalog of candidate columns for PDE regression.
class-attribute
instance-attribute
unary_operators: tuple[str, ...] = ()
Unary operators allowed in the PySR expression grammar.
dataclass
Frozen configuration for a PySINDy STLSQ fit.
class-attribute
instance-attribute
degree: int = 2
Highest total degree of the polynomial library, used only on tabular data;
must be at least 1. The library holds the constant term one listed first,
followed by every monomial of the feature columns of degree 1 through
degree.
class-attribute
instance-attribute
extra_optimizer_kwargs: dict[str, Any] | None = None
Extra keyword arguments forwarded to the underlying PySINDy optimizer for
settings with no field of their own, such as the ridge parameter alpha.
threshold, max_iter, normalize_columns and unbias are rejected
here, because a shadowed value would leave the recorded configuration describing
a fit that never ran. Set those fields directly instead.
class-attribute
instance-attribute
max_iter: int = 20
Upper bound on the number of thresholding rounds the fit runs, in iterations;
must be greater than 0. It caps the solver's own convergence loop rather than a
search budget, so kd.Model(generations=...) leaves it unchanged and it can
only be set here.
class-attribute
instance-attribute
normalize_columns: bool = False
Whether the fit rescales the library columns to comparable magnitude before
thresholding, so a term's units alone do not decide whether it survives. Turning
it on moves the scale that threshold acts on, so the two are chosen together;
reported coefficients are returned in the original units either way.
relative_threshold requires it to be on.
class-attribute
instance-attribute
relative_threshold: bool = False
Whether threshold is read as a fraction of the regression target's L2
norm instead of an absolute coefficient magnitude. A term then survives a
thresholding round when its coefficient times its column norm reaches
threshold times the target norm, so rescaling a column or the target leaves
the selected terms unchanged. Requires normalize_columns=True. With
anchored terms, the norm is that of the target left after the anchored columns
are projected out.
class-attribute
instance-attribute
seed: int = 0
Random seed recorded in the run manifest next to the dataset fingerprint. This fit is deterministic and never draws on the value, so changing it alone does not change the result.
class-attribute
instance-attribute
terms: tuple[str, ...] = ("u", "u_x", "u_xx", "mul(u, u_x)")
Ordered catalog of candidate right-hand-side terms; each entry becomes one column of the regression matrix, in the order given. The catalog must be non-empty and its entries must stay distinct once canonicalized; the fit reports the terms whose coefficients survive thresholding.
class-attribute
instance-attribute
threshold: float = 0.1
Coefficient magnitude below which a candidate term is dropped during the
sequentially thresholded fit; must be finite and at least 0. A value too large
for the data leaves nothing selected, which raises an error quoting the current
threshold instead of returning an empty equation. With relative_threshold
on, it is instead a dimensionless fraction of the target's L2 norm.
class-attribute
instance-attribute
unbias: bool = True
Whether the fit ends with an unregularized least-squares refit over the terms that survived thresholding, undoing the shrinkage the sparse fit introduces. The result reports the coefficients from that final refit, so this setting is visible in the published coefficient values.