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
BiologicalNetworkSpecies 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.
HybridKinetics.NodeSpec — Type
NodeSpecSpecies node: name, kind (STATE/INPUT/LATENT), bounds, and observation flag.
HybridKinetics.EdgeSpec — Type
EdgeSpecDirected interaction. Unknown edges (known=false or UNKNOWN_NN) compile to a neural destruction head; known family values become mechanistic IR.
HybridKinetics.ReactionSpec — Type
ReactionSpecStoichiometric reaction. stoichiometry maps state-node ids to signed coefficients; regulators affect the rate but are not necessarily consumed.
HybridKinetics.EdgeKind — Type
EdgeKindDirected-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.
HybridKinetics.ACTIVATION — Constant
Source increases the target production or rate.
HybridKinetics.INHIBITION — Constant
Source decreases the target production or rate.
HybridKinetics.UNKNOWN_NN — Constant
Unknown interaction; compiles to NeuralDestructionTerm.
HybridKinetics.NodeKind — Type
NodeKindSpecies role in a BiologicalNetwork. Only STATE and LATENT nodes enter the compiled ODE; INPUT nodes are exogenous drives.
HybridKinetics.STATE — Constant
Dynamic species integrated by the compiled UDE.
HybridKinetics.INPUT — Constant
Exogenous drive; not a dynamic state.
HybridKinetics.LATENT — Constant
Unobserved dynamic species (still in the ODE).
HybridKinetics.KineticFamily — Type
KineticFamilyKnown kinetic template on an edge or reaction. Unknown mechanisms ignore the family and compile to a neural destruction head.
HybridKinetics.MASS_ACTION — Constant
Mass-action production or first-order regulation.
HybridKinetics.SATURATION — Constant
Michaelis–Menten saturation (single regulator).
HybridKinetics.HILL — Constant
Hill-type destruction.
HybridKinetics.COMPETITIVE — Constant
Competitive-inhibition destruction (two regulators).
HybridKinetics.CUSTOM_KINETIC — Constant
User evaluator or named kinetic preset.
HybridKinetics.validate_network — Function
validate_network(network) -> networkCheck node uniqueness, bounds, stoichiometry, and kinetic-metadata requirements. Called by the BiologicalNetwork constructor; safe to call again after manual edits.
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.
HybridKinetics.candidate_parents — Function
Graph in-neighbors of target (the local discovery prior).
Kinetic metadata
HybridKinetics.KineticMetadata — Type
KineticMetadataTyped 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.
HybridKinetics.InputDriveMetadata — Type
Input-driven production (e.g. damage signal drives p53).
HybridKinetics.MassActionMetadata — Type
Mass-action production or regulation.
HybridKinetics.HillMetadata — Type
Hill-type destruction kinetics.
HybridKinetics.CompetitiveMetadata — Type
Competitive inhibition destruction kinetics.
HybridKinetics.LinearDecayMetadata — Type
First-order linear decay.
HybridKinetics.SaturationMetadata — Type
Michaelis–Menten saturation kinetics (single regulator).
HybridKinetics.CustomKineticMetadata — Type
CustomKineticMetadataUser-defined or preset destruction/production kinetics. When evaluator is set, it must be a pure function (x, p, regulators) -> non-negative rate coefficient.
Compiled models
HybridKinetics.compile_mechanism — Function
compile_mechanism(network) -> CompiledMechanismLower reactions and edges to production–destruction IR (duᵢ = Pᵢ − Dᵢ·uᵢ). Unknown mechanisms become NeuralDestructionTerm.
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).
HybridKinetics.UDEModel — Type
UDEModelPositive-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}.
HybridKinetics.NeuralDestructionTerm — Type
NeuralDestructionTermUnknown destruction rate compiled to a positivity-preserving neural head. regulators are the inputs; regulator is the first (backward compatible).
HybridKinetics.ude_rhs — Function
ude_rhs(x, p, t, model::UDEModel) -> dxEvaluate the compiled production–destruction RHS. SVector states with n ≤ STATIC_STATE_THRESHOLD use the StaticArrays kernel.
HybridKinetics.ude_rhs! — Function
ude_rhs!(du, x, p, t, model, cache)In-place compiled production–destruction RHS using a preallocated cache.
HybridKinetics.parameter_schema — Function
parameter_schema(model) -> ParameterSchemaPhysical parameter names required by the compiled mechanism, plus the number of neural destruction heads.
HybridKinetics.ParameterSchema — Type
Compile-time parameter names required by a compiled mechanism.
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-freeude_rhs!with a model cache.
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.
CommonSolve.solve — Method
solve(model::UDEModel, u0, tspan, p; saveat, solver_config, cache, kwargs...)Integrate a compiled UDE with SciML defaults.
HybridKinetics.auto_sensealg — Function
auto_sensealg(model; policy=ZygoteAD(), n_observations=100)Return the recommended SciMLSensitivity adjoint (see recommend_sensealg).
HybridKinetics.default_solver_config — Function
default_solver_config(model; ad_policy=ZygoteAD())Build a solver configuration with a model-aware adjoint recommendation.
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, ...).
HybridKinetics.AbstractADPolicy — Type
AbstractADPolicyAdjoint / forward-pass policy for SolverConfig. Public subtypes are ZygoteAD and ProductionAD.
HybridKinetics.ZygoteAD — Type
Compatibility AD backend using Zygote out-of-place sensitivities.
HybridKinetics.ProductionAD — Type
ProductionADProduction 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.
Experiments
HybridKinetics.Experiment — Type
ExperimentOne biological experiment with irregular sampling, missing-data mask and arbitrary metadata. Observations are stored as (states, times).
HybridKinetics.ExperimentSet — Type
ExperimentSetA named collection of Experiments that share state dimension and labels. This is the multi-IC training input for train_experiments.
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).
HybridKinetics.write_experiment_csv — Function
write_experiment_csv(path, experiment; state_names, delim=',')Write times plus one row per state of an Experiment to CSV.
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.
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.
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.
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.
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.
HybridKinetics.TrainingConfig — Type
TrainingConfigAdam 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.
HybridKinetics.HorizonCurriculum — Type
HorizonCurriculumTyped horizon curriculum for stable long-horizon UDE training. Pass as horizon_schedule to TrainingConfig instead of a raw fraction vector.
HybridKinetics.TrainingResult — Type
TrainingResultStable, typed output for optimization runs.
HybridKinetics.TrainingRetcode — Type
TrainingRetcodeSciML-style training outcome codes returned in TrainingResult.retcode.
HybridKinetics.AbstractConstraintStrategy — Type
AbstractConstraintStrategyTraining constraint policy. StructuralPositivity relies on the compiled P,D ≥ 0 form; AugmentedLagrangianConfig adds a smooth penalty.
HybridKinetics.StructuralPositivity — Type
StructuralPositivityDefault constraint: trust the compiled production–destruction form. No extra penalty term is added to the training loss.
HybridKinetics.AugmentedLagrangianConfig — Type
AugmentedLagrangianConfigSmooth inequality-constraint policy. ρ is updated automatically from primal progress; users do not select a fixed penalty multiplier.
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:
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'sdiscover_unknown_termproduced.- Physical parameters start from a flat guess of 0.8 (
phys_initoverrides). - A warm-up
train_udeon 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 = falseskips it). train_experimentson the training experiments withtraining(default: Adam 100 then BFGS 50). One network per unknown term is trained jointly; each sees only its own regulators.- For each unknown term, in node order: its learned rate is sampled on the regulator grid of the training experiments (
sample_unknown_destruction_grid) andregress_unknown_ratefits a rational rate withdiscovery(default: the reference protocol's configuration, bootstrap 8, discovery seed 3), or with the term's ownlibrarywhentermscarries one.stability_selectionandstrictare passed through, per term.regulator_gridreplaces the grid: a vector or range (one term), aDictfrom node name to vector or range, or a function(model, params, training_set, term) -> gridcalled per term after training, which is the way to sample a regulator that is never observed;nothingkeeps the observed grid. report_production_destruction_tradeoffper term on the first training experiment, and with two or more termscross_term_collinearityon the same experiment; a pair aboveCROSS_TERM_COLLINEARITY_THRESHOLDis reported with a warning.hybrid_data_residualof 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.
HybridKinetics.DiscoveryRun — Type
DiscoveryRunEverything 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 theTrainingResultof the joint fit;terms: oneUnknownTermResultper unknown term, in node order;result[:S]selects by node name,result[i]by position, andunknown_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), anddata_residual_holdout(mean over the held-out experiments,NaNwhen none were held out);Infwhen 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.
HybridKinetics.UnknownTermResult — Type
UnknownTermResultWhat 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 theTrainingResultof 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: theDiscoveryResultof the rational-rate regression;samples: the regulator gridRand the learned rateDthe discovery used;selection_frequency: how often each library term was selected by the bootstrap of the accepted candidate,nothingwhen discovery failed;extras: the recovered monomials outside the known support, ornothingwhen 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.
HybridKinetics.report_unknown_terms — Function
report_unknown_terms(result::DiscoveryRun) -> StringThe 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.
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).nothingkeeps the regulators of the node's destruction reaction, which are its graph parents, as before.library: aDiscoveryConfigthat replaces the default graph-local discovery configuration for this term only;nothingkeeps the default. The override is honoured when the specs are passed todiscover_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.
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.
unknown_terms(result::DiscoveryRun) -> Vector{UnknownTermResult}The per-term results, in node order.
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.
HybridKinetics.CROSS_TERM_COLLINEARITY_THRESHOLD — Constant
CROSS_TERM_COLLINEARITY_THRESHOLDCross-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.
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.
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.
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).
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.
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).
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.
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).
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.
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).
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.
HybridKinetics.ImplicitSINDyPI — Type
ImplicitSINDyPIConfiguration for graph-local rational discovery through the implicit identity D(z)ẋ - N(z) = 0.
HybridKinetics.ExplicitSTLSQ — Type
Explicit polynomial STLSQ backend (dx/dt = Φ(x)ξ).
HybridKinetics.DiscoveryResult — Type
DiscoveryResultStable output type shared by explicit and implicit discovery backends. retcode is a DiscoveryRetcode; success is retcode === DiscoverySuccess.
HybridKinetics.ImplicitCandidate — Type
ImplicitCandidateImplicit SINDy-PI candidate for a rational rate D(z)ẋ − N(z) = 0 on one target.
HybridKinetics.ExplicitCandidate — Type
ExplicitCandidateExplicit STLSQ candidate (ẋ = Φ(x)ξ) for one target state.
HybridKinetics.DiscoveryRetcode — Type
DiscoveryRetcodeOutcome of discover_equations. Failures are never silent: DiscoveryResult.success is false and retcode names the failure class.
HybridKinetics.DiscoverySuccess — Constant
Support recovered; a hybrid RHS is allowed.
HybridKinetics.InsufficientSamples — Constant
Not enough finite trajectory samples for STLSQ.
HybridKinetics.DenominatorUnsafe — Constant
Discovered denominator changed sign or hit the floor.
HybridKinetics.EmptySupport — Constant
STLSQ wiped every library term.
HybridKinetics.SingularLibrary — Constant
Design matrix was singular.
HybridKinetics.DiscoveryFailed — Constant
Discovery failed for any other reason.
HybridKinetics.equation_to_function — Function
Executable closure (x) -> dx_target for a discovered candidate.
HybridKinetics.equation_to_latex — Function
equation_to_latex(candidate)LaTeX form of a discovered candidate equation.
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.
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.
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.
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.
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.
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.
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.
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.
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) -> BiologicalNetworkBuild 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).
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) -> NumThe 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).
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.
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.
HybridKinetics.library_comparison_smoke — Function
Smoke configuration of the study: one seed, one noise level, the smoke budget.
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.
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.
HybridKinetics.append_library_study_row — Function
append_library_study_row(path, row)Append row to the CSV at path, writing the header first when the file does not exist yet. The file is flushed after every row.
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.
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.
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.
HybridKinetics.library_study_default_design — Function
Default design of a fixture: LIBRARY_STUDY_DEFAULT_DESIGN for the four-state fixture, :varying for the two-state fixture.
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.