# Construct a phosphorylation cycle with prescribed equilibria

A kinase adds phosphate groups one at a time; a phosphatase removes them. Both enzymes bind substrate in intermediate complexes, and their shared finite inventories couple all sites. This package constructs the full sequential, distributive mass-action system, rather than replacing it with a Michaelis–Menten curve. An n-site model has 3n+3 species, 6n elementary channels and three conserved totals.

The key design input is an odd list of distinct numbers x>1. Each produces an equilibrium free-enzyme ratio u=(x²−1)/8. The positive-polynomial recurrence and conversion construct rate constants realizing all 2n−1 requested ratios in one compatibility class. The paper's external upper bound excludes any further positive equilibria. The code independently audits all real roots of the denominator-cleared equation for each configured finite example.

## Run and edit

Tested with Python 3.11. Create a virtual environment, install `pip install -r requirements.txt`, then run `python example.py` and `python -m unittest -v`. Use `python example.py --output replay` for a separate output directory. Exact calculations use Fraction and SymPy; dynamics use SciPy. Default execution takes seconds on the development machine. `FULL_SOURCE_CENSUS=True` extends the exact source census from n≤6 to n≤10 and may take tens of minutes. It is not needed for the default five-state example.

Edit the inputs at the top of `example.py`: auxiliary roots, enzyme-total ratio, rate-speed sweep, substrate-total offsets, trajectory horizon and declared physical units. Specify rational strings to preserve exact arithmetic. Arbitrary positive prescribed u can be represented through x=√(1+8u) in the theorem; this implementation's design interface accepts rational x, not arbitrary irrational algebraic inputs. Rational u need not have rational x. The number of sites follows from the root-list length. Duplicate roots are rejected: a repeated-root limit is not a list of distinct equilibria.

`PrescribedStates` builds geometry; `KineticFreedom` chooses the three independent positive kinetic parameters per site without moving the states; `EquilibriumChart` reconstructs the steady-state polynomials from arbitrary positive rates and independently checks physical roots; `Reactor` supplies all elementary fluxes, the stoichiometric matrix, class coordinates, analytic Jacobian and trajectories. These are separate paper-local components. Import them into a sweep or subclass/wrap the reactor for a different experimental protocol. An altered reaction mechanism requires a new conservation law and equilibrium derivation; merely reusing these formulas would not justify it.

## What the default shows

For x=(2,3,4,5,6), r=5, the totals are (ET,FT,ST)=(10,2,12). All twelve concentrations at each of the five equilibria are rational. Fresh exact Routh arrays give unstable-eigenvalue counts (0,1,0,1,0); ambient Jacobian zero modes from conservation are removed first. The readout includes free fully phosphorylated substrate **and its phosphatase complex**. The opposing catalytic currents are nonzero at stationarity: these are driven steady states, not thermodynamic equilibria.

The six rational probes freshly certify five roots throughout ST∈[12−1/500,12+1/500]. A wider ±1/100 attempt is explicitly not certified; that failure does not prove the larger region impossible. Continuation locations and return trajectories are numerical diagnostics. No basin of attraction, arbitrary preparation, or global stability is certified by those traces. Sensitivity and slow recovery make the narrow design margin visible.

Clearing denominators can produce negative ratios and nonphysical positive candidates. The root audit checks u>0, poles, and (r−u)L(u)>0. The exceptional u=r case is handled separately: if B(r)=rD(r), a positive quadratic substrate equation selects its state. The symmetric one-site example tests this branch so a generic solver does not silently discard a real equilibrium. Exact isolation is computationally expensive at large degree; the implementation has no universal performance guarantee.

Three-site coefficient counterexamples also show that r exceeding every requested ratio is insufficient: clustered x values fail at r=.64 and work at r=.66. Direct coefficient positivity is checked. The paper's stronger sufficient inequality is a design aid, not a necessary condition.

`source_arithmetic_replay.json` freshly replays the original checker: 64 states through n=8, interlacing/positivity instances, generic determinant checks, and exact stability through n=6 by default. The paper reports an n≤10 census. Its all-n stability statement is a conjecture here; the later stable-capacity paper is a separate result and is not silently substituted. Nondegeneracy implies an open parameter neighborhood, but gives no numerical radius for arbitrary simultaneous rate-and-total changes. The ±1/500 certificate concerns substrate total alone. Lean is not rerun.

## Units, outputs and provenance

The illustrative conversion is 0.1 micromolar per concentration unit and 10 seconds per time unit. Association constants divide by both units; unimolecular constants divide by the time unit. Thus the benchmark totals become 1, 0.2 and 1.2 micromolar. This is an interpretable scaling of a mathematical witness, not an experimentally calibrated enzyme system; bound enzyme is substantial and the substrate-excess approximation is inappropriate.

Outputs include exact rates/states, the physical-root audit with isolating intervals, exceptional-chart example, exact window checks, physical rate CSV, kinetic sweep, full-species trajectories, conservation/solver comparisons, figures and runtime/source hashes. `source_provenance.json` identifies the unchanged original rational kernel and the source checker's small execution-wrapper adaptations. The reusable reactor is extracted from the companion example for the same elementary mechanism; no later-paper theorem is needed. Saved scientific JSON/CSV are replayable; figure byte identity may depend on rendering software.

MIT is proposed for newly authored example code, pending the owner's license decision. No license grant is made by this README; source provenance is retained.