API reference

Every exported name is documented here. Unexported helpers mentioned in the guide (for example HybridKinetics.report_production_destruction_tradeoff, HybridKinetics.run_recovery_suite, HybridKinetics.assess_functional_identifiability) are internal and may change between minor versions.

Network specification

HybridKinetics.BiologicalNetwork — Type
BiologicalNetwork

Species graph (NodeSpec), directed interactions (EdgeSpec), and stoichiometric reactions (ReactionSpec). Unknown edges and reactions compile to neural destruction terms; known families become mechanistic IR.

The interaction graph, which candidate_parents and the graph-local library read, holds one edge per EdgeSpec and, in addition, one edge from each regulator of every reaction with known = false to each species that reaction changes. A network that declares its unknown term as a reaction alone therefore has the same graph parents as one that also declares the edge. Regulators of known reactions add no edges.

source
HybridKinetics.EdgeSpec — Type
EdgeSpec

Directed interaction. Unknown edges (known=false or UNKNOWN_NN) compile to a neural destruction head; known family values become mechanistic IR.

source
HybridKinetics.ReactionSpec — Type
ReactionSpec

Stoichiometric reaction. stoichiometry maps state-node ids to signed coefficients; regulators affect the rate but are not necessarily consumed.

source
HybridKinetics.EdgeKind — Type
EdgeKind

Directed-edge semantics used when an EdgeSpec is compiled. ACTIVATION and INHIBITION become mechanistic IR when known=true; UNKNOWN_NN always compiles to a neural destruction head.

source
HybridKinetics.NodeKind — Type
NodeKind

Species role in a BiologicalNetwork. Only STATE and LATENT nodes enter the compiled ODE; INPUT nodes are exogenous drives.

source
HybridKinetics.KineticFamily — Type
KineticFamily

Known kinetic template on an edge or reaction. Unknown mechanisms ignore the family and compile to a neural destruction head.

source
HybridKinetics.validate_network — Function
validate_network(network) -> network

Check node uniqueness, bounds, stoichiometry, and kinetic-metadata requirements. Called by the BiologicalNetwork constructor; safe to call again after manual edits.

source
HybridKinetics.state_nodes — Function
state_nodes(network) -> Vector{Int}

1-based node indices that are dynamic (STATE or LATENT). Input nodes are excluded from the compiled ODE state.

source

Kinetic metadata

HybridKinetics.KineticMetadata — Type
KineticMetadata

Typed compile-time metadata for edges and reactions. Replaces ad-hoc Dict{Symbol,Any} fields with SciML-style explicit structs while retaining backward-compatible dict coercion during the 0.x migration.

source
HybridKinetics.CustomKineticMetadata — Type
CustomKineticMetadata

User-defined or preset destruction/production kinetics. When evaluator is set, it must be a pure function (x, p, regulators) -> non-negative rate coefficient.

source

Compiled models

HybridKinetics.compile_mechanism — Function
compile_mechanism(network) -> CompiledMechanism

Lower reactions and edges to production–destruction IR (duᵢ = Pᵢ − Dᵢ·uᵢ). Unknown mechanisms become NeuralDestructionTerm.

source
HybridKinetics.build_ude_model — Function
build_ude_model(rng, network=DEFAULT_EXAMPLE_NETWORK) -> (model, params)

Compile network into a UDEModel and default ComponentVector parameters (phys + nn).

source
HybridKinetics.UDEModel — Type
UDEModel

Positive-by-construction production/destruction UDE. The invariant form duᵢ = Pᵢ(u,p,t) - Dᵢ(u,p,t)uᵢ, with Pᵢ,Dᵢ ≥ 0, points inward at every zero-state boundary and therefore preserves the biological positive orthant.

The public wrapper is a concrete, unparameterized struct so JET can specialize train_ude(::..., ::UDEModel) without a UnionAll. nn, st, compiled, and impl stay existential: the linear A/B allocation fixture uses stored packed-parameter indices on a dedicated unrolled path instead of dispatching through those fields. Specialized kernels live on UDEModelImpl{N,NN,ST,C}.

source
HybridKinetics.NeuralDestructionTerm — Type
NeuralDestructionTerm

Unknown destruction rate compiled to a positivity-preserving neural head. regulators are the inputs; regulator is the first (backward compatible).

source
HybridKinetics.ude_rhs — Function
ude_rhs(x, p, t, model::UDEModel) -> dx

Evaluate the compiled production–destruction RHS. SVector states with n ≤ STATIC_STATE_THRESHOLD use the StaticArrays kernel.

source
HybridKinetics.ude_rhs! — Function
ude_rhs!(du, x, p, t, model, cache)

In-place compiled production–destruction RHS using a preallocated cache.

source
HybridKinetics.parameter_schema — Function
parameter_schema(model) -> ParameterSchema

Physical parameter names required by the compiled mechanism, plus the number of neural destruction heads.

source

SciML interface

HybridKinetics.build_ude_function — Function
build_ude_function(model; inplace=false, cache=nothing)

Build an SciMLBase.ODEFunction for a compiled UDEModel.

  • inplace=false (default for adjoints): Zygote-safe out-of-place RHS.
  • inplace=true: allocation-free ude_rhs! with a model cache.
source
SciMLBase.ODEProblem — Method
ODEProblem(model::UDEModel, u0, tspan, p; inplace, cache, kwargs...)

Construct a SciML-native ODEProblem from a compiled biological UDE.

Use inplace=true with SolverConfig(ad_policy=ProductionAD()) for allocation-free forward integration. Use the default out-of-place path for Zygote-based adjoint training.

source
CommonSolve.solve — Method
solve(model::UDEModel, u0, tspan, p; saveat, solver_config, cache, kwargs...)

Integrate a compiled UDE with SciML defaults.

source
HybridKinetics.auto_sensealg — Function
auto_sensealg(model; policy=ZygoteAD(), n_observations=100)

Return the recommended SciMLSensitivity adjoint (see recommend_sensealg).

source
HybridKinetics.SolverConfig — Type
SolverConfig(; algorithm=Tsit5(), ad_policy=ZygoteAD(), sensealg, ...)

ODE integrator and adjoint settings used by train_ude, predict_ude, and SciMLBase.solve(::UDEModel, ...).

source
HybridKinetics.ProductionAD — Type
ProductionAD

Production forward pass using the in-place compiled RHS (ude_rhs!) with a preallocated cache when sensealg = nothing. Adjoint training continues to use the out-of-place RHS because Zygote cannot differentiate through the mutating cache path today.

source

Experiments

HybridKinetics.Experiment — Type
Experiment

One biological experiment with irregular sampling, missing-data mask and arbitrary metadata. Observations are stored as (states, times).

source
HybridKinetics.ExperimentSet — Type
ExperimentSet

A named collection of Experiments that share state dimension and labels. This is the multi-IC training input for train_experiments.

source
HybridKinetics.experiment_from_csv — Function
experiment_from_csv(path; time_column=1, u0=nothing, name=:experiment,
                    state_names=nothing, delim=',')

Load a time-series table into an Experiment. The first numeric column is time unless time_column is set; remaining columns are states (rows of observations).

source
HybridKinetics.generate_experiment_set — Function
generate_experiment_set(rng; network, initial_conditions, tspan, n_points, ...)

Build one compiled ground-truth model, then an ExperimentSet from that stored model. This is the multi-IC entry used by the reference example.

source

Training

HybridKinetics.train_ude — Function
train_ude(p_init, data, t_data, u0, tspan, model)
train_ude(p_init, data, t_data, u0, tspan, nn, st; model, network)

Fit physical (and optional neural) parameters of a compiled UDE to one trajectory. mask (default: every entry observed) drops the unobserved entries of data from the loss on every horizon slice; without it a NaN entry makes the loss non-finite. Use train_experiments for masked multi-replicate data.

source
HybridKinetics.train_experiments — Function
train_experiments(p_init, set, model; config, execution, ...)

Fit a UDE to an ExperimentSet. Adam follows execution.batch_size. BFGS always refines the joint loss over every experiment, not the last minibatch.

source
train_experiments(p_init, set, model; config, seed, ...)

Joint fit over every experiment in set.

config.restarts above 1 fits that many draws of the neural term and returns the one that reached the lowest final loss, with every attempt's loss in the result's metadata under restart_losses. Restart one is p_init as given; each later one redraws the neural block from seed and keeps the physical guess, so a set of restarts repeats exactly. Anything already trained into the neural block of p_init — a warm-up, say — is therefore kept only by restart one; wrap the whole fit instead if the warm-up should be repeated per restart, as train_experiments_with_warmup and discover_unknown_terms do.

source
HybridKinetics.predict_ude — Function
predict_ude(p, u0, tspan, saveat, model::UDEModel; solver_config, cache)

Integrate the compiled UDE and return the state trajectory at saveat.

source
HybridKinetics.TrainingConfig — Type
TrainingConfig

Adam then optional BFGS settings for train_ude / train_experiments. frozen_phys names physical parameters whose raw values are held fixed (gradient zeroed; restored after BFGS). Use this to pin a known production rate; it does not remove k_prod↔D(z) Jacobian collinearity.

source
HybridKinetics.HorizonCurriculum — Type
HorizonCurriculum

Typed horizon curriculum for stable long-horizon UDE training. Pass as horizon_schedule to TrainingConfig instead of a raw fraction vector.

source

One-call workflow

HybridKinetics.discover_unknown_terms — Function
discover_unknown_terms(network, experiments; terms=unknown_terms(network),
                       training=TrainingConfig(adam_iterations=100, bfgs_iterations=50, log_every=10^6),
                       discovery=rate_discovery_config(), holdout=2,
                       rng=MersenneTwister(0), phys_init=nothing, warmup=true,
                       known_support=nothing, stability_selection=nothing,
                       strict=false, seed=nothing, regulator_grid=nothing,
                       verbose=true)

Train the hybrid model of network on experiments, discover a rational expression for each of its unknown destruction terms, and return an DiscoveryRun. The steps are those of examples/unknown_inhibition.jl, in the same order and with the same defaults:

  1. build_ude_model(rng, network); the network must have at least one unknown destruction term (unknown_terms(network) lists them; one per node). With one term every number below is the one 0.15's discover_unknown_term produced.
  2. Physical parameters start from a flat guess of 0.8 (phys_init overrides).
  3. A warm-up train_ude on the first training experiment, of every unknown term at once, with the training config's settings (Adam iterations and learning rate, gradient clip, constraint, solver, frozen parameters), no BFGS, and the horizon curriculum 35%, 70%, 100% (warmup = false skips it).
  4. train_experiments on the training experiments with training (default: Adam 100 then BFGS 50). One network per unknown term is trained jointly; each sees only its own regulators.
  5. For each unknown term, in node order: its learned rate is sampled on the regulator grid of the training experiments (sample_unknown_destruction_grid) and regress_unknown_rate fits a rational rate with discovery (default: the reference protocol's configuration, bootstrap 8, discovery seed 3), or with the term's own library when terms carries one. stability_selection and strict are passed through, per term. regulator_grid replaces the grid: a vector or range (one term), a Dict from node name to vector or range, or a function (model, params, training_set, term) -> grid called per term after training, which is the way to sample a regulator that is never observed; nothing keeps the observed grid.
  6. report_production_destruction_tradeoff per term on the first training experiment, and with two or more terms cross_term_collinearity on the same experiment; a pair above CROSS_TERM_COLLINEARITY_THRESHOLD is reported with a warning.
  7. hybrid_data_residual of the model with every discovered rate substituted against the first training experiment, the mean over the training experiments, and the mean over the held-out experiments.

holdout is the number of experiments at the end of experiments that are held out of training and used only for the held-out residual (the reference protocol holds out 2 of 9). Residuals and the identifiability diagnostics use each experiment's observation mask, so unobserved entries do not count. known_support, the true implicit support when the data are synthetic (for example HybridKinetics.hill_rate_support(2)), is used only to list the extra terms in the report; with several terms give a Dict from node name to support. production_param names the production rate parameter the per-term identifiability diagnostic compares each term's scale against: a Symbol for every term, a Dict from node name to Symbol, or :auto (the default), which is :k_prod when the model has that parameter (the 0.15 behaviour) and otherwise the rate parameter of the one production reaction of the term's node, when there is exactly one. seed is recorded in the report and not used otherwise; verbose prints training progress and the report.

source
HybridKinetics.DiscoveryRun — Type
DiscoveryRun

Everything discover_unknown_terms computes. This is the container for the whole run; UnknownTermResult is the per-term type inside it.

  • network, model, params, training: the hybrid model, its trained parameters, and the TrainingResult of the joint fit;
  • terms: one UnknownTermResult per unknown term, in node order; result[:S] selects by node name, result[i] by position, and unknown_terms(result) returns the vector;
  • residuals: data_residual (the hybrid model with every discovered rate substituted, against the first training experiment), data_residual_train (mean over the training experiments), and data_residual_holdout (mean over the held-out experiments, NaN when none were held out); Inf when a discovery failed;
  • cross_term: the pairwise cross-term collinearity, one entry per pair of unknown terms (nodes, terms, collinearity); empty with one term;
  • training_indices, holdout_indices: which experiments trained the model and which were held out;
  • settings: the values printed in the reproduction section of the report.

report_unknown_terms(result) returns the report as a string and show prints it. With one unknown term the report is the four-section report of 0.15; with several it has one shared fit section, one block per term, and a cross-term section.

source
HybridKinetics.UnknownTermResult — Type
UnknownTermResult

What discover_unknown_terms computed for one unknown term; result[:S], result[1] and unknown_terms(result) return these:

  • node: the name of the node whose destruction term this is;
  • network, model, params, training: the hybrid model, its trained parameters and the TrainingResult of the joint fit (shared by all terms);
  • term: the compiled neural destruction term;
  • identifiability: the production/destruction trade-off report of this term on the first training experiment;
  • discovery: the DiscoveryResult of the rational-rate regression;
  • samples: the regulator grid R and the learned rate D the discovery used;
  • selection_frequency: how often each library term was selected by the bootstrap of the accepted candidate, nothing when discovery failed;
  • extras: the recovered monomials outside the known support, or nothing when no truth was given;
  • settings: the values printed in the reproduction section of the report.

symbolic(result[:S]) and export_mtk_system(model; discovered = result[:S]) accept it.

source
HybridKinetics.report_unknown_terms — Function
report_unknown_terms(result::DiscoveryRun) -> String

The report of a discover_unknown_terms result. With one unknown term it is the four-section report (identifiability, fit, discovery, reproduction) that discover_unknown_term printed in 0.15, unchanged. With several terms it prints one shared fit section, then one block per term with that term's identifiability and discovery sections, then the cross-term section, then the reproduction section.

source
HybridKinetics.UnknownTerm — Type
UnknownTerm(node; regulators = nothing, library = nothing)

One unknown destruction term, on the node named node (a Symbol). The term is the rate D_node(u) in du_node/dt = P_node(u) − D_node(u)·u_node; a neural network learns it from data and a rational expression is then recovered for it.

  • regulators: the node names the term may depend on (one or two). nothing keeps the regulators of the node's destruction reaction, which are its graph parents, as before.
  • library: a DiscoveryConfig that replaces the default graph-local discovery configuration for this term only; nothing keeps the default. The override is honoured when the specs are passed to discover_unknown_terms(...; terms = ...).

Pass a vector of specs to BiologicalNetwork(...; unknown = [...]) to mark the corresponding destruction reactions unknown, or read the specs of an existing network with unknown_terms(network). Two specs on the same node are an error, and so is a spec on a node without a destruction reaction.

source
HybridKinetics.unknown_terms — Function
unknown_terms(network) -> Vector{UnknownTerm}

The unknown destruction terms of network, one UnknownTerm per node whose destruction reaction (or UNKNOWN_NN edge) is marked unknown, in node order, with the regulators the term actually uses. library is nothing; a per-term override is given to discover_unknown_terms through terms.

source
unknown_terms(result::DiscoveryRun) -> Vector{UnknownTermResult}

The per-term results, in node order.

source
HybridKinetics.cross_term_collinearity — Function
cross_term_collinearity(model, p, u0, tspan, times; mask, rel_step = 1e-3)

Pairwise diagnostic for models with several unknown destruction terms. For each term the output of its network is scaled by 1 ± rel_step, the model is simulated on times, and the central finite difference of the trajectory is the term's sensitivity vector over the observed entries (mask, all by default). For each pair of terms the value is the absolute cosine between the two sensitivity vectors. A value near one means that, in these data, scaling one term looks like scaling the other, so the two scales are not separately determined at this fit. It is the same construction as the scale collinearity of production_destruction_tradeoff, applied between terms rather than between a term and the production rate, and like it a local statement at p, not a structural identifiability result; it says nothing about the terms' functional form beyond their scale.

Returns a vector with one entry per pair, (; nodes, terms, collinearity), empty when the model has fewer than two unknown terms.

source
HybridKinetics.CROSS_TERM_COLLINEARITY_THRESHOLD — Constant
CROSS_TERM_COLLINEARITY_THRESHOLD

Cross-term collinearity above which discover_unknown_terms warns that the scales of a pair of unknown terms are not separately determined. Set from the multi-term study of 0.16 (benchmarks page, "Two unknown terms"): over 35 multi-unknown runs (two two-term fixtures at noise 0, 0.02 and 0.05 and a three-term fixture at noise 0, five seeds each) every run in which the extra term had no measurable cost had all its pairs at or below 0.425, and every run with a measurable cost (a learned rate 1.4 to 6.3 times further from the truth than the single-unknown control, or a lost support) had at least one pair at or above 0.498; the threshold is the midpoint of that gap.

source

Removed in 0.16 (each raises an error that names its replacement):

HybridKinetics.discover_unknown_term — Function
discover_unknown_term(args...; kwargs...)

Removed in 0.16. Call discover_unknown_terms(network, experiments; ...), which returns a DiscoveryRun; with one unknown term its numbers are identical and its report is the same text. Per-term contents are result[:S] (by node) or result[1]. See the migration section of the how-to page.

source
HybridKinetics.report_unknown_term — Function
report_unknown_term(args...; kwargs...)

Removed in 0.16. Call report_unknown_terms(result); with one unknown term it returns the same text. See the migration section of the how-to page.

source

Symbolic discovery

HybridKinetics.regress_unknown_rate — Function
regress_unknown_rate(R, times, D; network, config, ...)

Discover a scalar destruction rate D(r) with graph-local implicit SINDy-PI. R is n_regulators × n and D is 1 × n. stability_selection = StabilitySelection() enables the optional pruning stage (off by default).

source
HybridKinetics.discover_equations — Function
discover_equations(p_trained, model::UDEModel; kwargs...)
discover_equations(p_trained, model, set::ExperimentSet; kwargs...)
discover_equations(X, times, network; kwargs...)

Recover graph-local equations from a trained UDE, several experiments, or raw trajectories. Failures set DiscoveryResult.retcode; pass strict=true to throw. The raw-data method accepts targets to recover a subset of state rows.

source
discover_equations(X, times, network; config, ...)

UDE-free discovery from observed trajectories. Derivatives are estimated by central finite differences unless derivatives is supplied. Pass targets to recover a subset of state rows (used for rate-only unknown-edge discovery).

source
discover_equations(p_trained, nn, st; ...)

Discover graph-local rational dynamics with SINDy-PI's implicit identity D(z)ẋ - N(z)=0. Unknown numerator and denominator coefficients are learned jointly; no fixed-denominator rational atoms or Taylor approximations are used.

source
HybridKinetics.sample_unknown_destruction — Function
sample_unknown_destruction(model, p, X; term=nothing)

Evaluate compiled neural destruction D at trajectory columns of X (the rate used inside du = P - D·u, not a raw Lux call).

source
HybridKinetics.estimate_derivatives — Function
estimate_derivatives(X, times; method=:central)

Central finite differences on trajectory samples (one-sided at endpoints). No external derivative package required.

source
HybridKinetics.local_basis — Function
local_basis(network, target; scope=:graph, degree=3, ...)

Monomial library for one target. scope=:graph uses graph parents (the product prior); scope=:global uses every other dynamic node (ablation).

source
HybridKinetics.DiscoveryConfig — Type
DiscoveryConfig(; backend=ImplicitSINDyPI(), basis_scope=:graph, ...)

Discovery options. basis_scope=:graph is the product prior; :global is the internal ablation that adds every other dynamic node to the library.

source
HybridKinetics.DiscoveryResult — Type
DiscoveryResult

Stable output type shared by explicit and implicit discovery backends. retcode is a DiscoveryRetcode; success is retcode === DiscoverySuccess.

source
HybridKinetics.DiscoveryRetcode — Type
DiscoveryRetcode

Outcome of discover_equations. Failures are never silent: DiscoveryResult.success is false and retcode names the failure class.

source
HybridKinetics.export_rhs — Function
export_rhs(result::DiscoveryResult)

Full-state RHS (x) -> du assembled from discovery candidates. Unknown-edge recovery should use compose_hybrid_rhs instead: this exports a discovered ẋ, not a compiled hybrid with known P.

source
HybridKinetics.compose_hybrid_rhs — Function
compose_hybrid_rhs(model, p, term, rate_fn)

ODE right-hand side that keeps compiled known terms and replaces neural destruction term with rate_fn of the regulator vector.

source
compose_hybrid_rhs(model, p, pairs)

Right-hand side that keeps the compiled known terms and replaces every neural destruction term in pairs (a vector of term => rate_fn) with its rate function of the regulator vector. With one pair this is the single-term compose_hybrid_rhs.

source
HybridKinetics.hybrid_data_residual — Function
hybrid_data_residual(model, p, term, rate_fn, u0, tspan, times, data; mask)

RMSE of compose_hybrid_rhs versus observations (not versus UDE ẋ). This is a locked UDE claim field.

source
hybrid_data_residual(model, p, pairs, u0, tspan, times, data; mask)

RMSE of the hybrid right-hand side with several unknown terms (pairs is a vector of (term, rate_fn) tuples) versus observations. One pair reduces to the single-term method.

source
HybridKinetics.StabilitySelection — Type
StabilitySelection(; n_boot=100, τ=0.8, seed=7)

Optional pruning stage for implicit discovery, passed as stability_selection = StabilitySelection() to regress_unknown_rate or discover_equations. After the candidate has been fitted as usual, the training rows of the regression are resampled with replacement n_boot times, the thresholded fit is repeated on every resample, and a term of the candidate is kept only if it is selected in at least a fraction τ of the resamples; the coefficients of the kept terms are then refitted on the training rows. Terms are never added, only removed, and the stage is skipped when it would remove every numerator term or make the denominator unsafe. The frequency of every library term is reported through stability_selection_report. Off by default (stability_selection = nothing), in which case discovery output is unchanged. tau is accepted as an alias of τ. Cost: n_boot thresholded fits on the training rows.

source
HybridKinetics.stability_selection_report — Function
stability_selection_report(result::DiscoveryResult)

Report of the stability-selection stage of result, or nothing when the stage was off. The report has n_boot, τ, seed, and reports, one entry per discovered target with applied, reason, and terms, where every library term carries its side (numerator or denominator), label, selection frequency, whether it was in_candidate before the stage, and whether it was kept.

source
HybridKinetics.format_stability_selection — Function
format_stability_selection(result::DiscoveryResult)

Plain-text table of stability_selection_report(result): one line per library term with its side, label, selection frequency, and whether it was in the candidate and kept. Returns "stability selection: off" when the stage was off.

source

Catalyst input and symbolic output

Exported wrappers whose implementations live in the extensions HybridKineticsCatalystExt (using Catalyst) and HybridKineticsSymbolicsExt (using Symbolics); see the Extensions page.

HybridKinetics.network_from_reactionsystem — Function
network_from_reactionsystem(rs; unknown) -> BiologicalNetwork

Build a BiologicalNetwork from a Catalyst ReactionSystem: the same species in Catalyst's order, the known kinetics compiled from the rate laws Catalyst exposes, the interaction graph derived from the reactions, and the reaction or reactions named by unknown marked as unknown destruction terms (one per node). unknown is a reaction's index in Catalyst.reactions(rs) or the string of its description metadata ([description = "..."] in the DSL), or a vector of those; unknown = nothing compiles every reaction as known kinetics (a ground-truth model).

Each Catalyst reaction is split into one HybridKinetics term per species it changes. Supported rates (the factor Catalyst multiplies by the mass-action term): a parameter k (first-order loss of a single substrate; constant production k, 0 --> X, which adds the parameter input that multiplies it and is meant to be fixed at 1; mass action from one substrate k, Y --> X); k * Y for a species Y that is not a substrate (k * Y, 0 --> X); hill(Y, v, K, n) with parameters v, K and a literal integer n on a single substrate of stoichiometry 1 (Hill destruction); mm(Y, v, K) on a single substrate (Michaelis-Menten destruction) or with no substrate (Michaelis-Menten production). Any other rate, a full rate law written with =>, or a shape the compiler has no term for raises an ArgumentError naming the reaction and the rate. The unknown reaction must consume exactly one species with stoichiometry 1 and produce nothing; its regulators are the species of its rate (the consumed species itself when the rate has none). Requires using Catalyst (extension HybridKineticsCatalystExt).

source
HybridKinetics.symbolic — Function
symbolic(candidate, names) -> Num
symbolic(result::DiscoveryResult, names; index = 1) -> Num
symbolic(result::DiscoveryRun; node = nothing, index = 1) -> Num
symbolic(result::UnknownTermResult; index = 1) -> Num

The discovered rational rate as a Symbolics.Num in the named variables: names gives one symbol per variable of the candidate's library (for regress_unknown_rate, the regulators in order; for discover_equations, the network's states); a per-term result uses the names of its regulators, and a DiscoveryRun needs node unless it has one term. Requires using Symbolics (extension HybridKineticsSymbolicsExt).

source

Benchmark thresholds

HybridKinetics.RECOVERY_THRESHOLDS (not exported since 0.17) holds the recovery thresholds of the reference protocol; loosening one is a breaking change. The Benchmarks page lists them.

Library comparison study

Unexported. The multi-seed, multi-noise comparison of the graph-local, global, and wrong-graph discovery libraries described on the Benchmarks page.

HybridKinetics.library_comparison_study — Function
library_comparison_study(; seeds=LIBRARY_STUDY_SEEDS,
                         noise_levels=LIBRARY_STUDY_NOISE_LEVELS,
                         libraries=LIBRARY_STUDY_LIBRARIES,
                         variants=(:study,), fixture=:four_state,
                         kind=:protocol,
                         skip=(seed, noise, library, variant) -> false,
                         on_row=nothing, verbose=false, kwargs...)

Tidy table of the library comparison study: one row (a NamedTuple with the columns in LIBRARY_STUDY_COLUMNS) per seed, noise level, variant, and library. Each (seed, noise level) pair is one library_comparison_run, so its variants and libraries share one training. Rows for which skip returns true are not computed, and a pair whose rows are all skipped is not trained, which lets a script resume from rows it has already written. on_row and the remaining keywords are passed to library_comparison_run. The default study is five seeds, three noise levels, and all three libraries (15 trainings per fixture). The smoke configuration used in the test suite is kind = :smoke with one seed and one noise level. Not exported.

source
HybridKinetics.library_comparison_run — Function
library_comparison_run(; seed, noise_σ, kind=:protocol, fixture=:four_state,
                       variants=(:study,), libraries=LIBRARY_STUDY_LIBRARIES,
                       holdout_ics=LIBRARY_STUDY_HOLDOUT_ICS,
                       training_call=fit_unknown_destruction,
                       stability_selection=nothing, design=nothing,
                       fixed_production=false, normalise_rate=false,
                       n_sample_points=nothing, on_row=nothing,
                       on_discovery=nothing)

One study run: one training of fixture at seed and noise_σ, then one row per requested variant and library with the columns in LIBRARY_STUDY_COLUMNS. For the four-state fixture with design = :constant and the :study variant the discoveries are those of evaluate_trained_graph_local(; kind, seed, noise_σ), unchanged.

design is the sample coordinate design (LIBRARY_STUDY_DESIGNS): for the four-state fixture :constant keeps S at 0.4 on every sample and :varying spreads S over its observed range; nothing selects the fixture's default (LIBRARY_STUDY_DEFAULT_DESIGN for the four-state fixture). The two-state fixture always varies S and accepts only :varying. The design is recorded in the design column.

Three settings of the two-state fixture, all off by default, exist to test where the reference protocol's extra terms 1 and R come from: fixed_production = true trains with the production rate k_prod frozen at its true value (training_call receives frozen_phys and phys_init); normalise_rate = true divides the learned rate samples by the fitted production rate before discovery (the residuals scale the discovered rate back); n_sample_points replaces the 80 points of the regulator grid. They are refused for the four-state fixture. on_discovery is called with (; seed, noise, fixture, variant, library, discovery) for every discovery, for example to record stability-selection frequencies.

data_residual is the hybrid residual on the first training experiment, holdout_residual the mean hybrid residual on the held-out experiments (two fixed initial conditions with the seed seed + LIBRARY_STUDY_HOLDOUT_SEED_OFFSET for the four-state fixture; experiments 8 and 9 of the 7/2 split for the two-state fixture), and nn_rate_rmse the relative error of the learned rate against the true Hill rate on the sample coordinates. train_time_s is the wall time of the training call and run_time_s the wall time of the training run including sampling; both are the same for the rows of one run. stability_selection is passed to every discovery (off by default). on_row is called with each row as soon as it exists. Not exported.

source
HybridKinetics.library_study_summary — Function
library_study_summary(rows; metrics=(:support_f1, :extra_terms, :holdout_residual))

Median and interquartile range of each metric per fixture, design, variant, library, and noise level. Returns one NamedTuple per group with fixture, design, variant, library, noise, n, and for each metric <metric>_median, <metric>_q25, <metric>_q75, computed over the finite values only. Groups follow LIBRARY_STUDY_FIXTURES, LIBRARY_STUDY_DESIGNS, LIBRARY_STUDY_VARIANTS, and LIBRARY_STUDY_LIBRARIES; noise levels are sorted.

source
HybridKinetics.format_library_study_summary — Function
format_library_study_summary(summary; metrics=(:support_f1, :extra_terms, :holdout_residual))

Markdown table of a library_study_summary: one row per group, cells as median [q25, q75]. The fixture, design, and variant columns are shown when the summary has more than one fixture, design, or variant.

source
HybridKinetics.read_library_study_csv — Function
read_library_study_csv(path)

Rows written by append_library_study_row, as NamedTuples with the columns in LIBRARY_STUDY_COLUMNS. Files written before the fixture and variant columns existed are read with fixture = :four_state and variant = :study; files written before the design column existed (0.11) are read with the design those runs used (:constant for the four-state fixture, :varying for the two-state fixture). An absent or empty file gives an empty vector.

source
HybridKinetics.library_study_training_set — Function
library_study_training_set(kind; seed, noise_σ, initial_conditions)

Experiment set of the trained-model library check: the four-state network with the true Hill term, integrated from initial_conditions with the budget's time span and point count, and additive Gaussian observation noise of standard deviation noise_σ drawn from MersenneTwister(seed). The defaults are the budget's own seed, noise, and initial conditions, so library_study_training_set(kind) is the set evaluate_trained_graph_local trains on. Not exported.

source
HybridKinetics.LIBRARY_STUDY_DESIGNS — Constant

Sample coordinate designs of the four-state fixture: :constant keeps the target state S at 0.4 on every sample (the library check's design); :varying spreads S over the range observed in the training experiments. The two-state fixture always varies S.

source
HybridKinetics.designed_trained_graph_local_coordinates — Function
designed_trained_graph_local_coordinates(n_sample_points; x_seed=619,
                                         design=:constant, s_range=nothing)

Locked 4×n designed coordinates (S, R, Q, Z). Not occupancy, not a fill grid, and not functional-identifiability domain.z. Independent of any stored evidence.X.

design = :constant (the library check's design) fixes the target state S at 0.4 on every sample. design = :varying spreads S over s_range = (lo, hi) in a fixed shuffled order (randperm seeded by x_seed), as the two-state fixture of the library comparison study does, so that the S column of a library is not a multiple of the constant term. R, Q, and Z are the same under both designs.

source