Tutorial: recovering an unknown inhibition

This page walks through examples/unknown_inhibition.jl, the reference example of the package. The example is also the protocol that the recovery benchmarks run: seed 103, nine initial conditions generated once, 50 points each over t in [0, 8], Adam 100 / BFGS 50, and symbolic discovery on a regulator grid.

Run it with

julia --project=. examples/unknown_inhibition.jl

It takes 10 to 15 minutes. With HYBRIDKINETICS_SMOKE=1 ADAM_ITERS=2 BFGS_ITERS=0 in the environment it uses one initial condition with 8 points and two Adam steps, which checks the installation in about two minutes but does not produce a meaningful fit.

One call

discover_unknown_terms runs the whole workflow: it builds the hybrid model, trains it, samples the learned destruction rate, discovers a rational expression for it, computes the identifiability diagnostic and the residuals, and prints the report. The block below is the reference protocol in four statements (the network builder is defined in the next section):

using HybridKinetics, Random

rng = MersenneTwister(103)
truth = (k_prod = 0.9, vmax = 1.8, K = 0.55, k_rs = 1.0, k_r = 0.6)
set = HybridKinetics.reference_protocol_experiment_set(rng, unknown_inhibition_network(known = true);
    truth_params = truth)                      # nine experiments, 50 points each
result = discover_unknown_terms(unknown_inhibition_network(known = false), set;
    rng = rng, known_support = HybridKinetics.hill_rate_support(2), seed = 103)

By default the last two experiments are held out (holdout = 2), training uses Adam 100 then BFGS 50, and discovery uses the reference configuration (bootstrap 8, discovery seed 3). known_support tells the report which recovered monomials are extra relative to the true Hill support; it is only available for synthetic data. The call took 7.5 minutes on a busy 4-core machine and printed:

IDENTIFIABILITY
  unknown_holes: 1
  unidentifiable_edge: true
  coefficients_are_biological_constants: false
  production_param: k_prod
  the production rate (k_prod) and the scale of the unknown term are not separately identifiable from these data
  local diagnostic (Fisher condition number and scale collinearity); not a structural identifiability proof
  collinearity: 0.9972
FIT
  hybrid_data_residual: 0.001778
  hybrid_data_residual_train: 0.001264
  hybrid_data_residual_holdout: 0.002513
  support_recall: not scored (needs the synthetic ground truth)
DISCOVERY
  equations:
dx[1]/dt = (0.23265*1 + -1.2838*x[1] + 7.5747*x[1]^2) / (1 + -0.39858*x[1] + 4.0869*x[1]^2)
  support_f1: not scored (needs the synthetic ground truth)
  extras: 1, r
  canonical_hill_from_nn: false
  acceptance_criteria: scale warning raised, hybrid residual at most 0.3, support recall at least 0.99
REPRODUCTION
  seed: 103
  n_ics: 9
  n_points: 50
  adam_iters: 100
  bfgs_iters: 50
  bootstrap: 8
  discovery_seed: 3
  protocol_kind: protocol
  smoke: false

result is a DiscoveryRun: result.params are the trained parameters, result[:S].discovery the DiscoveryResult of the unknown term on S, result[:S].identifiability the trade-off report, result.residuals the three residuals above, and report_unknown_terms(result) the text. The held-out residual (experiments 8 and 9, never used for training) is about twice the training residual; both are far below the acceptance threshold of 0.3. The rest of this page is what the one call does, step by step, with the reference example examples/unknown_inhibition.jl, which trains on all nine experiments.

What the one call does

The network

Two species. S is produced in proportion to R (mass action, rate k_prod) and degraded by a Hill-type mechanism driven by R; R is produced from S (rate k_rs) and decays linearly (rate k_r). The network is built twice: once fully known, to generate the synthetic data, and once with the Hill degradation marked known = false, to fit.

using HybridKinetics, Random

function unknown_inhibition_network(; known::Bool, hill_order::Int = 2)
    nodes = [NodeSpec(name = :S), NodeSpec(name = :R)]
    reactions = [
        ReactionSpec(name = :produce_s,
            stoichiometry = Dict(1 => 1.0), regulators = [2],
            metadata = MassActionMetadata(rate_param = :k_prod)),
        ReactionSpec(name = :hill_deg,
            stoichiometry = Dict(1 => -1.0), regulators = [2],
            known = known, family = HILL,
            metadata = HillMetadata(vmax_param = :vmax, k_param = :K,
                hill_order = hill_order)),
        ReactionSpec(name = :produce_r,
            stoichiometry = Dict(2 => 1.0), regulators = [1],
            metadata = MassActionMetadata(rate_param = :k_rs)),
        ReactionSpec(name = :decay_r,
            stoichiometry = Dict(2 => -1.0), regulators = Int[],
            metadata = LinearDecayMetadata(rate_param = :k_r))]
    return BiologicalNetwork(nodes, EdgeSpec[]; reactions = reactions)
end

truth_net = unknown_inhibition_network(; known = true)
ude_net = unknown_inhibition_network(; known = false)
model, params = build_ude_model(MersenneTwister(0), ude_net)
(compile_mechanism(ude_net).nstates, HybridKinetics.count_unknown_destructions(model))
(2, 1)
ReactionRoleIn the hybrid model
R -> S productionknown mass actioncompiled production term
R degrades Sunknownneural destruction term
S -> R productionknown mass actioncompiled production term
R linear decayknowncompiled destruction term

The step-by-step chain below works on exactly one unknown destruction term, and the example checks this with HybridKinetics.assert_single_unknown_destruction(model). The one-call discover_unknown_terms handles several, one per node ("Two unknown terms" at the end of this page).

Synthetic data

The example generates nine experiments from the known network with the truth parameters k_prod = 0.9, vmax = 1.8, K = 0.55, k_rs = 1.0, k_r = 0.6 and no observation noise. The ground-truth model is compiled once and every initial condition is integrated from that model. The block below generates the same set with the one-experiment smoke settings so that it runs quickly here:

truth = (k_prod = 0.9, vmax = 1.8, K = 0.55, k_rs = 1.0, k_r = 0.6)
set = HybridKinetics.reference_protocol_experiment_set(
    MersenneTwister(103), truth_net; smoke = true, truth_params = truth)
(length(set.experiments), size(first(set.experiments).observations))
(1, (2, 8))

The example also writes the first experiment to a CSV file in a temporary directory and reads it back with experiment_from_csv, to show that measured data enter through the same path.

Training

Training has two stages. A warm-up fit on the first experiment uses Adam with a horizon curriculum (35%, 70%, then 100% of the time span), and the joint fit over all experiments continues from the warm-up parameters with Adam followed by BFGS on the full-set loss. The physical parameters start from a flat guess of 0.8.

warm = train_ude(HybridKinetics.pack_parameters(guess, params.nn),
    first_exp.observations, first_exp.times, first_exp.u0, tspan, model;
    config = TrainingConfig(adam_iterations = 100, bfgs_iterations = 0,
        horizon_schedule = HorizonCurriculum(fractions = [0.35, 0.7, 1.0])))
trained = train_experiments(warm.params, set, model;
    config = TrainingConfig(adam_iterations = 100, bfgs_iterations = 50))

(Illustrative; the docs build does not train.)

Identifiability

Before discovery, the example computes the production/destruction trade-off for the first experiment:

ident = HybridKinetics.report_production_destruction_tradeoff(
    model, trained.params, first_exp.observations, first_exp.times,
    first_exp.u0, tspan; term = term)

ident.unidentifiable_edge is true when the Fisher condition number over the physical parameters exceeds 1e6 or when the trajectory sensitivity to k_prod is collinear (cosine at least 0.95) with the sensitivity to a multiplicative rescaling of the unknown term. In this example the cosine is about 0.997: observed concentrations cannot separate the production rate from the scale of the destruction term, so the recovered coefficients are not biological constants. The reference protocol treats a raised warning as required output, not as a failure.

Discovery

The learned destruction rate is sampled on a grid of regulator values derived from the training data, and a rational function of the regulator is fitted by implicit sparse regression:

term = only(HybridKinetics.neural_destruction_terms(model))
r_range = HybridKinetics._regulator_grid(set, term)
R, D, term = HybridKinetics.sample_unknown_destruction_grid(model, trained.params, term;
    r_range = r_range)
discovery = regress_unknown_rate(R, range(0.0, 1.0; length = size(R, 2)), D;
    config = HybridKinetics.reference_protocol_discovery_config(), strict = true)

regress_unknown_rate treats the samples as a function-regression problem in the regulator (the time argument is a dummy index). With strict = true a failed discovery throws; with strict = false it returns a DiscoveryResult whose retcode explains the failure (see How-to).

The same regression on exact Hill samples recovers the true monomials with no nuisance terms, which is what the analytical benchmarks check:

r = collect(range(0.1, 2.0; length = 120))
times = collect(range(0.0, 1.0; length = length(r)))
D = HybridKinetics.hill_rate_truth(r; vmax = 1.7, K = 0.6, n = 2)
clean = regress_unknown_rate(reshape(r, 1, :), times, reshape(D, 1, :);
    config = HybridKinetics.rate_discovery_config(bootstrap = 0, seed = 1),
    verbose = false, strict = true)
clean.equations
"dx[1]/dt = (4.7222*x[1]^2) / (1 + 2.7778*x[1]^2)"

Resimulation and the report

The discovered rate replaces the neural term inside the compiled ODE and the hybrid model is integrated again from the first initial condition:

rate_fn = equation_to_function(discovery.candidates[1])
rhs = compose_hybrid_rhs(model, trained.params, term, rate_fn)
residual = hybrid_data_residual(model, trained.params, term, rate_fn,
    first_exp.u0, tspan, first_exp.times, first_exp.observations)

residual is the root-mean-square difference between that simulation and the observations. The example then prints a four-section report:

IDENTIFIABILITY
  unknown_holes: 1
  unidentifiable_edge: true
  coefficients_are_biological_constants: false
  production_param: k_prod
  the production rate (k_prod) and the scale of the unknown term are not separately identifiable from these data
  local diagnostic (Fisher condition number and scale collinearity); not a structural identifiability proof
  collinearity: 0.9972
FIT
  hybrid_data_residual: 0.001777
  support_recall: not scored (needs the synthetic ground truth)
DISCOVERY
  equations:
dx[1]/dt = (0.24118*1 + -1.3569*x[1] + 7.7609*x[1]^2) / (1 + -0.3862*x[1] + 4.1863*x[1]^2)
  support_f1: not scored (needs the synthetic ground truth)
  extras: 1, r
  canonical_hill_from_nn: false
  acceptance_criteria: scale warning raised, hybrid residual at most 0.3, support recall at least 0.99
REPRODUCTION
  seed: 103
  n_ics: 9
  n_points: 50
  adam_iters: 100
  bfgs_iters: 50
  bootstrap: 8
  discovery_seed: 3
  protocol_kind: protocol
  smoke: false

The values above come from a run in September 2026 (reproduced for 0.11 by discover_unknown_terms(...; holdout = 0), which gives the same report line for line). Read it as follows:

  • The scale warning was raised, so the coefficients of the discovered rate are not biological constants.
  • The hybrid model reproduces the first trajectory with a residual of about 0.002.
  • The rational rate has the x^2 / (K + x^2) structure of the true Hill term. The extras line lists the nuisance monomials that remain (a constant and a linear term). Support recall and F1 are not scored by the example because they need the synthetic truth; the recovery suite scores them (see Benchmarks).
  • The reproduction section records every setting needed to rerun the protocol.

Held-out validation

The example trains on all nine experiments. discover_unknown_terms with its default holdout = 2, and the recovery suite (HybridKinetics.run_recovery_suite with sections = (:ude_discovery,)), train on experiments 1 to 7, derive the discovery grid from those seven, and then report the residual on experiments 8 and 9 (the suite also reports the destruction-rate error there). Those held-out numbers are reported as evidence; they are not part of the acceptance criteria. See Concepts for the definitions.

Next: How-to recipes and Concepts.

Two unknown terms

Since 0.16 the same call handles several unknown destruction terms, one per node. Marking works as before, with ReactionSpec(known = false), or with UnknownTerm specs handed to the network constructor. The three-state network below has A and B produced from C, C decaying linearly, and each of A and B degraded by a Hill term in the other; both Hill terms are unknown, so the two neural terms sit on adjacent nodes and each one's regulator is the other unknown node.

truth = HybridKinetics.build_two_term_coupled_network(; unknown = ())
net = BiologicalNetwork(truth.nodes, EdgeSpec[]; reactions = truth.reactions,
    unknown = [UnknownTerm(:A), UnknownTerm(:B)])
set = generate_experiment_set(MersenneTwister(103); network = truth,
    initial_conditions = HybridKinetics.multi_term_study_ics(3),
    tspan = (0.0, 8.0), n_points = 50, noise_σ = 0.0,
    truth_params = HybridKinetics.TWO_TERM_COUPLED_TRUTH)
result = discover_unknown_terms(net, set; rng = MersenneTwister(103), seed = 103,
    known_support = Dict(:A => HybridKinetics.hill_rate_support(2),
        :B => HybridKinetics.hill_rate_support(2)))
result[:A].discovery.equations
result[:B].discovery.equations
result.cross_term

The report now has one shared fit section, one block per term with that term's identifiability diagnostic and discovery, and a cross-term section with the collinearity of the pair, explained on the Concepts page. What two terms cost, and when they cannot be separated, is measured on the Benchmarks page.