Diagnosing Sign, Scale, and Indexing Errors

Why Small Implementation Errors Matter

A model can have biologically sensible equations on paper and still produce implausible trajectories because the code implements a different system. In a two-compartment model, a single transfer flux must leave one compartment and enter the other. Reversing its sign, multiplying the wrong state, or writing a derivative into the wrong vector position can all break that correspondence. The resulting trajectory may look smooth while representing the wrong biology.

This tutorial uses a simple amount model to make three checks concrete: the sign of each derivative contribution, the scale of expected state changes, and the mapping between biological states and vector indices. These checks complement dimensional audits: correct units do not guarantee correct signs or indices.

Reference Model and Diagnostic Invariants

Let \(A_1(t)\) and \(A_2(t)\) be amounts in compartments 1 and 2, measured in mg. Material transfers from compartment 1 to compartment 2 at rate \(k_{12}A_1\), and in the reverse direction at rate \(k_{21}A_2\). Material is eliminated from compartment 1 at rate \(k_{10}A_1\). The rate constants are nonnegative and measured in \(\mathrm{h}^{-1}\). There are no external inputs in this example.

The sign pattern gives a useful check before any numerical solution is examined. For example, the forward transfer \(k_{12}A_1\) decreases \(A_1\) but increases \(A_2\). Adding the equations cancels both internal transfer terms:

Thus, in the absence of external input, total amount can decrease through elimination but not through internal transfer alone. This identity is a direct consequence of the stated balances, not an assumption that the two amounts are individually constant. If \(k_{10}=0\), total amount is conserved; if \(k_{10}>0\), its instantaneous rate of loss is determined by the amount in compartment 1.

For nonnegative initial amounts and nonnegative rates, the reference model also points inward at a zero boundary: if \(A_1=0\), then \(dA_1/dt=k_{21}A_2\geq 0\); if \(A_2=0\), then \(dA_2/dt=k_{12}A_1\geq 0\). These boundary checks help identify a sign error that would make an amount decrease through zero in a setting where the model should preserve nonnegativity.

Check the Signs by Following Each Flux

A reliable sign audit starts with the physical direction of each flux, not with the appearance of the final equation. For every modeled process, write down its source and destination. Subtract the flux from the source balance and add it to the destination balance. A loss such as elimination has a source but no modeled destination, so it contributes only a negative term. Finally, add the compartment balances: internal transfers should cancel from the total.

Check Whether the State Scale Is Plausible

A scale check asks whether the magnitude and direction of the computed changes are reasonable for the states, rates, and time interval. It is not enough that the solver returns finite values. In the numerical example, the initial changes per hour are tens of mg, compared with amounts of tens to hundreds of mg. Over \(0.1\) h, changes of a few mg are plausible; a jump of hundreds of mg would need an explanation in the model or its inputs.

A useful first estimate comes directly from the right-hand sides. At the stated initial values, the fractional rate of change in compartment 1 is \((-33\ \mathrm{mg/h})/(100\ \mathrm{mg})=-0.33\ \mathrm{h}^{-1}\); in compartment 2 it is \((28\ \mathrm{mg/h})/(20\ \mathrm{mg})=1.4\ \mathrm{h}^{-1}\). These are initial rates, not constant fractional changes over the whole simulation. They indicate that compartment 2 can change more rapidly in relative terms because its initial amount is smaller.

The rate constants also give rough time scales. Without return transfer, the combined loss rate from compartment 1 is \(k_{12}+k_{10}=0.35\ \mathrm{h}^{-1}\), corresponding to a characteristic time \(1/0.35\approx2.86\) h. The reverse transfer rate has a characteristic time \(1/k_{21}=10\) h. These are scale guides, not exact half-lives for the coupled system. If a plotted trajectory changes nearly all its amount within a few seconds, while all rates are on an hourly scale and there are no fast inputs, check the time units, rate units, and state scaling before interpreting that behavior.

Trace the State Vector and Its Derivative

In code, the state vector is an ordered list. Every read from that vector and every derivative written to the derivative vector must use the same documented ordering. For this example, let \(y[0]=A_1\) and \(y[1]=A_2\), using zero-based indices. Then the returned derivative must satisfy \(dy[0]/dt=dA_1/dt\) and \(dy[1]/dt=dA_2/dt\). The biological names, the indices, and the order of returned derivatives are three parts of one contract.

An indexing bug can leave the signs looking superficially reasonable while applying a flux to the wrong state. A useful check is to substitute distinct, easily recognized state values and calculate every flux by hand. Equal compartment amounts can conceal a swap, so diagnostic values should generally differ.

A Practical Diagnostic Sequence

These checks work best in a fixed order: first establish what each state and flux means, then test the right-hand side at a chosen state, and finally compare a short segment of the simulated trajectory with those expectations. This keeps a numerical symptom from being mistaken for a biological conclusion.

A hand calculation and total-balance check are especially effective for sign errors. A state-index map and deliberately unequal test values are more direct for indexing errors. Expected state scales can reveal problems that survive both checks, such as a time-unit mismatch or output mapping error. Plotting is useful for seeing where a trajectory becomes implausible, but a smooth plot alone cannot verify the equations.

Common Pitfalls and Limits of These Checks

• Assuming a smooth trajectory is correct. A solver can accurately integrate an incorrectly coded right-hand side. Check the equations and their balance identities, not only the appearance of the plot.
• Checking only whether amounts are positive. Positivity does not prove that transfer terms are correct. The reversed-sign example can produce positive values initially while violating the total balance.
• Using equal states to test indexing. If \(A_1=A_2\), swapping the two state values may not change a calculation that uses them in the same way. Use distinct values and inspect each term separately.
• Treating a rough scale estimate as an exact prediction. Initial derivatives describe local change. In a coupled model, rates change as states change, so a linear short-step estimate should not be extrapolated far into the simulation.
• Blaming the solver for every implausible result. Incorrect signs, units, indices, initial conditions, or observation mappings can produce bad outputs even when integration itself is functioning as intended.

These diagnostics are targeted, not exhaustive. A correct sign pattern and plausible scale do not prove that the biological model is appropriate, nor do they rule out parameter, input, or observation errors. They provide a disciplined way to detect implementation mismatches in this two-compartment balance before interpreting its predictions.