Introduction to Reaction Order Polyhedra and the Biocircuits Explorer workbench

2.1What is a Reaction Order Polyhedron?

A Reaction Order Polyhedron is a geometric object that organizes the asymptotic regimes an equilibrium binding network can enter at different parameter scales. It does not replace numerical parameter choices; it gives you a structural map before you start scanning them.

The input to an ROP analysis is a binding network:

• A finite set of base species \( X_{1}, \ldots, X_{n} \).
• A finite set of complexes — stoichiometric combinations such as \(AB\), \(AAB\), \(ABCD\). A complex is an integer vector \( a \in \mathbb{N}^{d} \setminus \{0\}\) with size \( |a|_{1} = \sum_{i} a_{i} \le \mu \), where \(\mu\) is the maximum allowed complex size.
• A finite set of reversible association reactions \( C_{a} + C_{b} \rightleftharpoons C_{a+b} \) with equilibrium constants.
• A stoichiometry matrix \(N\) (rows are reactions) and a conservation-law matrix \(L\) whose rows encode the conserved totals \( q_{i} = \sum_{j} L_{ij}\,x_{j} \).
• A choice of which totals act as inputs \(u\), which are fixed conserved totals \(q\), and which complex concentration plays the role of the output \(y\).

What comes out is usually not a single equilibrium curve but a polyhedral structure in log-concentration / log-parameter space. A vertex corresponds to a complete asymptotic regime: the dominant species in each conserved pool has been fixed. Faces and edges record ties or switches between dominant terms, which become transitions between regimes.

The geometry is polyhedral because the equilibrium equations

are non-linear in concentrations but split into log-linear regions in the asymptotic limit. When one term dominates each total, species concentrations are approximated by monomials, and the output becomes a linear function of the log-parameters. The polyhedron maps which monomial wins where; unlike a single numerical curve, it also shows how parameter space is divided into regimes.

2.2Why dominance, why log-log?

At chemical equilibrium, every species concentration is determined by mass action plus conservation. Each conserved total is a sum of monomials in the free concentrations of the base species:

For the simplest example \( A + B \rightleftharpoons AB \) with \( K = [AB] / ([A]\,[B]) \), the total of \(A\) is a sum of two monomials in the free concentrations \([A]\) and \([B]\):

The central observation behind ROP is that away from switching boundaries, these sums usually have one dominant monomial. Moving in log-concentration space crosses boundaries where that dominant term changes. Inside one regime, the dominant approximation gives power-law relationships among concentrations.

In log-log coordinates this relationship is easier to read. If the output \(y\) and input \(u\) satisfy \( y \asymp C\,u^{\rho} \) in some regime, then \( \log y = \rho \log u + \mathrm{const.} \) The slope is exactly the reaction order:

Two facts make this useful:

1. Within a regime, \( \rho \) is an integer (or a simple rational arising from stoichiometry), because the dominating monomial is a single product of integer powers.
2. Across a one-dimensional input scan, the response is piecewise linear in log-log: a sequence of straight segments with integer slopes, joined at turning points where one monomial overtakes another.

A chosen one-dimensional input scan can therefore be summarized by a finite program of reaction orders:

Each entry is a slope; each transition is a turning point on the polyhedron. For multi-input / multi-output slices the analogous object is a sequence of gain matrices \( G_{\ell} = \partial \log y / \partial \log u \).

2.3The objects on the polyhedron

Biocircuits Explorer mostly follows the vocabulary used in the ROP papers. Some of these objects appear directly on the canvas; others are the computation behind result tables and plots.

Reaction-order matrix

The Jacobian of \(\log x\) with respect to \(\log(q, k)\). Its entries are the local reaction orders. Vertices, faces and the polyhedron itself are organized around how this matrix changes.

Assignment

A choice of one dominating species per conserved total: in pool \(i\), species \(j\) holds (almost) all the mass.

Assignment polytope  \(\mathrm{AssignP}(L)\)

The convex hull of every legal assignment — a coarse outer envelope, the Cartesian product of one simplex per total.

Dominance regime

An assignment that is actually realizable by some \( x \in \mathbb{R}^{n}_{>0} \). Some assignments are spurious; only the realizable ones are real regimes.

Dominance polytope  \(\mathrm{DomP}(L)\)

The convex hull of the dominance regimes. This is the tight polyhedral envelope of the dominance modes \( A(x) = \Lambda_{Lx}^{-1} L\, \Lambda_{x} \). Every vertex is an achievable regime.

Vertices · faces · edges

Vertices = complete asymptotic regimes (one winner per total). Faces = partial regimes with ties between several species. Edges = one-step transitions where a tie resolves. Walking around the polytope is walking through the regimes a real circuit visits as parameters change.

Supports

The set of monomial terms that survive in a given regime. Supports change from vertex to vertex.

Input/output projection

Choosing a scanned input \(u\) and an output \(y\) projects the polyhedron onto the \((\log u, \log y)\) plane. The image is the SISO regime structure.

SISO path

The sequence of vertices the system visits as the scanned input is swept from \(0\) to \(\infty\). The reaction-order program \( b = (\rho_{1}, \ldots, \rho_{L}) \) reads off the slopes along that path.

Asymptotic vs. singular regimes

Inside a vertex \( \rho \) is a finite integer. On certain faces it can be infinite or undefined (vertical jumps in log-log). The app keeps the distinction — singular tokens \(\pm \infty\) and NaN are not collapsed into a finite reaction order.

Capability periodic table

A two-coordinate index \((d, \mu)\) — the number of base species and the maximum complex size — where each cell corresponds to a finite search space. Cells carry a capability envelope: mechanisms realized, strength extrema, robustness extrema, minimal witness networks, and certificates of un-reachability.

Sign words

Run-length-compressed three-state programs over \(\{-, 0, +\}\). The zero state is real (saturation / invariance) and is preserved during sign compression. Mechanism classes include activation from zero \(0 \to +\), settling to zero \(+ \to 0\), direct reversal \(+ \to -\), and zero-mediated reversal \(+ \to 0 \to -\).

2.4What the polyhedron tells you about a circuit

Once the polyhedron is built and a SISO (or MIMO) projection is chosen, several practically useful objects fall out:

• Response orders. The slopes \(\rho_{\ell}\) along the SISO path are the local Hill-like exponents. A regime with \(\rho \approx 0\) is saturated; \(\rho \approx 1\) is linear; \(\rho > \mu\) is ultrasensitive relative to the maximum complex size.
• Sensitive vs. saturated regions. The polyhedron helps locate these regions in log-parameter space, often before doing a dense numerical sweep.
• Switching loci / turning points. Faces of the polyhedron — projected to the input axis — give the inputs at which qualitative behavior changes. A boundary has the affine log-space form \[ a_{u}\,\log u + a_{q}^{\top}\!\log q + a_{K}^{\top}\!\log K + c = 0, \] so a turning point sits at \[ \log u^{\ast} \;=\; -\,\frac{a_{q}^{\top}\!\log q + a_{K}^{\top}\!\log K + c}{a_{u}}. \] Whether a switch is controlled by binding constants, by conserved totals, or mixed, is a built-in mechanistic classification.
• Upper-bound reachability. Conservation gives \( x_{a} \le U_{a}(q) = \min_{\,i:\,a_{i}>0}\, q_{i}/a_{i} \). Whether the output's vertex sits at this bound tells you whether the circuit can be driven to its stoichiometric ceiling.
• Robust regions. A program may be strong but fragile, weak but robust, or both. The polyhedron provides the geometry used to compute volume-fraction robustness scores (R-index); the value still depends on the chosen parameter domain and filters.
• Achievable behavior families. Different mechanisms can produce the same regime graph and sign word; the periodic table groups them into classes (activation, repression, settling to zero, zero-mediated reversal, multi-turn programs, MIMO rank expansion). The atlas workflow searches this family space.

2.5A worked example: \(A + B \rightleftharpoons AB\)

Take the simplest non-trivial binding network, with equilibrium constant

Scan \(q_{A}\) as the input \(u\), hold \(q_{B}\) fixed, take \(y = [AB]\) as the output. The conservation matrix is

so each row of the dominance-mode matrix \(A(x)\) is a one-simplex: for the \(q_{A}\) row, mass sits somewhere between \(A\) and \(AB\); for the \(q_{B}\) row, between \(B\) and \(AB\). The four assignments are the four corners of the resulting square — and for this network all four are achievable, so the dominance polytope is the square. The vertices read:

• \((A, B)\): both species mostly free. \([AB] \approx K\,q_{A}\,q_{B}\), so \(\rho = 1\).
• \((AB, B)\): \(A\) is mostly bound, \(B\) mostly free. \([AB] \approx q_{A}\), so \(\rho = 1\) but the output is now hitting the \(A\) ceiling.
• \((A, AB)\): \(B\) mostly bound, \(A\) mostly free. \([AB] \approx q_{B}\), constant in \(u\), so \(\rho = 0\) — saturation.
• \((AB, AB)\): both totals collapse on the same complex; the limiting species switches between \(A\) and \(B\).

As \(u = q_{A}\) is increased, a SISO scan typically walks \( (A,B) \to (AB,B) \to (A,AB) \), reading off the reaction-order program

or, after run-length sign compression, a typical settling-to-zero response \( S(b) \,:\, + \to 0 \). Each vertex of the square is a regime; each edge is a turning point; the whole square is the dominance polytope for this circuit. Increasing \(\mu\) or \(d\) inflates the square into higher-dimensional polyhedra with richer vertex structure — the kind of design space the periodic table is built to chart.

3.1Nodes, ports, wires

The web app opens to a blank canvas. You build an analysis by placing nodes and wiring their ports:

• Add a node. Click Add Node in the toolbar and choose from the categorized menu (Utilities, Input, Parameters, Process, Results).
• Connect ports. Each node has typed input sockets on the left and output sockets on the right. Click an output, drag to a matching input.
• Run. Most nodes have a Run button. The toolbar's Run Connected executes the whole connected subgraph in dependency order; Cloud Compute sends heavy work to a remote backend.
• Save. Save Workspace exports the whole canvas — nodes, parameters, wires — as portable JSON.

3.2Node families

The same five families recur:

Input

reaction-network for hand-entered reactions; network-id-definition to load a compressed network ID; sbml-import to bring in a model from an SBML file.

Process

model-builder turns reactions into a symbolic model (\(N\), \(L\), session ID). atlas-builder assembles a library of networks from an atlas spec. sbml-export writes a connected reaction source back out as SBML.

Parameters

siso-params, scan-1d-params, scan-2d-params, rop-cloud-params, rop-poly-params, fret-params, atlas-spec, atlas-query-config.

Results

model-summary, vertices-table, regime-graph, siso-result, qk-poly-result, scan-1d-result, scan-2d-result, rop-cloud-result, rop-poly-result, fret-result, atlas-query-result, atlas-inverse-result.

Utilities

markdown-note for free-form notes you keep next to a workspace.

3.3Navigating & shortcuts

• Pan. Hold Space and drag, or drag with the middle / right mouse button, or scroll / two-finger swipe.
• Zoom. Ctrl/⌘ + scroll (or pinch on a trackpad).
• Select. Drag on empty canvas to rubber-band select; Shift+click a node to add/remove it. Drag any selected node to move the whole selection together.
• Align. With two or more nodes selected, an alignment toolbar appears (align edges/centers, distribute).
• Edit. Ctrl/⌘+Z undo, Ctrl/⌘+Shift+Z redo, Delete remove selection, Ctrl/⌘+A/C/V/D select-all / copy / paste / duplicate.
• Cheatsheet. Press ? any time for the full shortcut list; Esc clears the selection.

4.1Build a model and inspect its regimes

Start here. This is the prerequisite for every other recipe.

1. Enter your reactions

   Add a reaction-network node. For each reaction, type a line like E + S <-> C_ES and a dissociation constant Kd. Add as many lines as you need.

2. Build the model

   Wire reaction-network → model-builder. Press Run. The builder fixes the symbolic order of species, complexes, totals and constants and returns a session ID downstream nodes will reuse.

3. Inspect the model

   Wire model-builder → model-summary to see \(n\), \(d\), \(r\), the species list, the totals, the binding-constant symbols, and the matrices \(N\) and \(L\).

4. List the vertices

   Add vertices-table off the same model. Each row is a vertex of the polyhedron: its permutation of species, type (asymptotic vs. non-asymptotic), singular / invertible status, and nullity.

5. See the regime graph

   Add regime-graph. The dropdown lets you switch between qK-neighbor (regimes joined by single parameter transitions) and SISO mode.

4.2Trace a SISO behavior path

Use this when you want to know how the circuit responds to changing one specific input.

1. Choose input, output and bounds

   In siso-params pick the \(qK\) change variable (the swept input), the target species \(x\) (the output), the path scope (feasible, robust, or all), the minimum volume fraction, and the log\(_{10}\) bounds for the scan.

2. Enumerate behavior families

   Run siso-result. The node returns a ranked list of SISO paths — each path is a reaction-order program \( b = (\rho_{1}, \ldots, \rho_{L}) \) with a feasibility volume.

3. Visualise the chosen path

   Click a path in the list. Wire to qk-poly-result to see the projected polyhedron in \(qK\)-space for that path.

4.3Run a parameter scan

When you want a numerical response curve, not just the symbolic path.

1. Pick a parameter and a range

   In scan-1d-params choose a \(qK\) variable, the log range and number of points, and type an output expression — for example 2*C_ES + E.

2. Run and read

   scan-1d-result draws the output expression versus the scanned variable. Crosshairs and value readouts feed downstream nodes.

3. Go 2D when needed

   Swap to scan-2d-params / scan-2d-result for a heatmap across two parameters simultaneously.

4.4Visualize the ROP polyhedron and the point cloud

The polyhedron itself is one node; the point cloud sampled across parameter space is another. Together they help you spot candidate robust regions.

1. Configure the polyhedron view

   In rop-poly-params choose 2D or 3D, and pair each axis with a species \(x\) and a \(qK\) parameter. The inner sample count controls how the interior is filled in.

2. Sample the cloud

   rop-cloud-params picks the sampling mode (x-space or qK-based), the number of samples, the target species and the log-bounds. The result node plots the cloud overlaid on the polyhedron.

3. Look for the dense regions

   Vertices with a dense surrounding cloud are often more robust within the chosen sampling range and sampling mode. Sparse vertices are not automatically useless, but they do suggest a narrow parameter window.

4.5Atlas search and inverse design

The atlas workflow goes the other direction: given a behavior you want, find networks that may achieve it.

1. Specify the search space

   atlas-spec has four tabs: Basic (source label, SQLite path, profile), Behavior (path scope, min volume), Enumeration (pairwise binding, reaction counts) and Explicit (JSON list of networks).

2. Preview the library

   Wire to atlas-builder and click Build Preview — this generates a slice of the atlas so you can verify the spec before committing to a full build.

3. Define the design goal

   atlas-query-config lets you state the goal: an I/O pair (e.g. tA -> AB), a motif label, an exact behavior, a witness path, or forbidden regimes. Pick a ranking mode — minimal_first or robustness_first.

4. Run forward or inverse

   atlas-query-result returns the ranked match list. atlas-inverse-result additionally runs the build + query loop with negative-example refinement and returns candidates with evidence.

6.1Regime table checklist

Start with model-summary and vertices-table. They tell you whether the network you sketched became the network you intended to analyze.

If the model summary already looks wrong, do not proceed to SISO. Fix the reaction list first. A beautiful polyhedron for the wrong conserved pools is still the wrong answer.

6.2SISO interpretation checklist

A SISO result should be read at three levels: the exact slope program, the sign-compressed behavior, and the geometry that supports it.

The sign word is a summary, not the whole story. Two paths can share a sign word but differ in strength, vertex sequence, transition control, and robustness. Use the full slope list and the projected polyhedron before treating two behaviors as equivalent.

6.3Numerical scans versus asymptotics

The ROP polyhedron is an asymptotic object: it predicts which monomial dominates in wide log-parameter regions. Parameter scans are finite numerical evaluations. They should agree in the large-scale shape, but they answer different questions.

• Use SISO paths to learn which qualitative behaviors are structurally possible.
• Use parameter scans to check the finite constants you actually plan to use.
• Use ROP cloud to estimate which regimes occupy substantial parameter volume.
• Use atlas search when the current network cannot realize the behavior and you need candidate alternatives.

9.1What the node does

The node output is checked against a fixed schema and allow-list. It is allowed to:

• Read pasted text, a PDF attachment, or a Jupyter .ipynb (only source cells; outputs are stripped locally before the file is sent).
• Emit one or more networks, each carrying a list of reversible binding reactions, a Kd in molar, and a confidence label.
• Pick recommended downstream analyses from a fixed allow-list. Anything else is dropped during post-processing.
• Add a warnings list for approximations, unit conversions, skipped files, or discarded models.

When you click Insert chain on a network card, the node drops a reaction-network with the extracted reactions, wires it into a model-builder, and adds one result node per recommended analysis. Each spawned node is a normal canvas node — edit reactions, change Kd values, rerun, save.

9.2Choosing a provider and supplying a key

The UI currently includes two provider choices, both called through the Anthropic Messages API shape:

Pick a model from the dropdown or type a custom model ID. The provider is detected from the model name (anything starting with claude goes to Anthropic, anything starting with deepseek goes to DeepSeek). Actual model availability is determined by the provider API; if a provider rejects PDF or document blocks, use the text or notebook route. The API key field is a password input; when “Remember for browser session” is unchecked, the page does not write the key to sessionStorage.

9.3Inputs: text, PDF, notebook

The three input types can be used alone or combined; combined inputs are sent as one source packet:

Text

Paste a section, supplementary methods, abstract, anything relevant. Useful when you only want a few specific reactions out of a long paper.

PDF

Upload a paper. The whole PDF is sent as one document content block. Expect higher token usage than the text path. Only available on Anthropic models.

Notebook

Upload a .ipynb. The browser parses it locally and sends only source cells (markdown + code). Output cells, base64 images and large data blobs never leave your machine.

9.4Reading the results and the auto-spawned chains

A finished run renders three things in the node body: a short paper summary, one card per extracted network, and a warnings list. Each network card carries an Insert chain button that materialises this on the canvas:

The recommended-results slot expands per network: a model-summary is retained, plus zero or more of vertices-table, regime-graph, siso-result, scan-1d-result, scan-2d-result, rop-cloud-result, rop-poly-result, fret-result. Entries outside this allow-list are dropped during post-processing and reported as warnings.

9.5Validation rules — and what gets discarded

The prompt and post-processing constrain model output, but they do not guarantee correctness. Common handling rules:

• Kd not stated. A placeholder 1e-3 M is emitted, confidence is marked low, and the warning names the reaction. Topology survives; you must edit the value.
• Only Ka given. The node emits \( K_{d} = 1 / K_{a} \) and notes the inversion in warnings.
• Only k_on / k_off. The node emits \( K_{d} = k_{\mathrm{off}} / k_{\mathrm{on}} \) and notes it.
• Hill functions, phenomenological dose-responses, catalytic turnover. Discarded with a warning. The node will not rewrite them as a binding scheme that was not stated.
• Unit conversion. nM / µM / mM are converted to M with a warning.

A run that returns zero networks plus a summary usually means the source does not contain extractable equilibrium binding chemistry, or that the provided material is insufficient for a structured reaction list. Add the relevant methods section, supplement, or reaction table rather than accepting a placeholder model.

10.1When you need to sign in

You need an account only for cloud-backed work:

• Submitting Cloud Compute jobs (atlas build, inverse design).
• Hitting per-user quotas — the daily submission counter is keyed by your Cognito user.
• Persisting result artifacts in the cloud backend's S3 prefix.

Local SISO analyses, regime graphs, point clouds, parameter scans, and model summaries work without an account. The toolbar's Sign in button only appears when the backend reports auth is enabled.

10.2The sign-in flow

Authentication uses AWS Cognito Hosted UI with the OAuth Authorization Code + PKCE flow:

1. Click Sign in in the toolbar

   The button is hidden if Cognito is not configured. When it is, the SPA fetches /api/auth/config to learn the Cognito domain and public app-client ID.

2. Go through Cognito Hosted UI

   The browser is redirected to …amazoncognito.com/oauth2/authorize. Sign up or sign in there with email + password. Email verification and optional MFA are handled by Cognito.

3. Bounce through /auth-callback.html

   Cognito redirects back to /auth-callback.html with an authorization code. The SPA exchanges the code for ID / access / refresh tokens using the PKCE verifier it stashed before redirect.

4. Return to the app

   Tokens are written to localStorage and the SPA navigates back to the page that initiated sign-in. From this point every cloud job submission attaches Authorization: Bearer <id_token>.

ID tokens auto-refresh five minutes before expiry using the refresh token. Signing out clears local tokens and visits Cognito's /logout endpoint so the next sign-in lands on the Hosted UI fresh.

10.3Same flow on macOS

The Swift macOS app runs the same auth.js inside a WKWebView. Tokens live in the WebView's own localStorage. There is no native Keychain integration today — a future Swift-side change could switch to ASWebAuthenticationSession + Keychain without touching the web codebase.

The Cognito app client must register the macOS WebView's loopback callback (default http://127.0.0.1:18088/auth-callback.html) alongside the web origin. See deploy/AWS_BATCH.md §2.2 for the full callback-URL list.

10.4Per-user quotas

When the deployment opts in with --with-quota-table, a DynamoDB counter is keyed by your Cognito sub. Every cloud job submission writes to it; the counter resets via a TTL field once per day.

The default daily limit is 50 jobs per user; the operator can raise or lower it with BIOCIRCUITS_EXPLORER_QUOTA_DAILY_LIMIT. Exceeding the limit returns HTTP 429 from the cloud backend and no Batch job is queued. Local analyses are not counted.

11.1Toggling Cloud Compute

The toolbar has a Cloud Compute button that flips a session-wide flag, persisted in localStorage:

• ON. Atlas builds and inverse-design runs are submitted as jobs to the cloud backend. The result node shows the job ID, a live status badge, and the link to the artifact when it finishes.
• OFF. The same nodes run their work locally and block the canvas while doing so. Fine for small previews.

Toggling Cloud Compute does not change the execution path for lightweight analyses in the current implementation (SISO paths, scans, polyhedron viewers). They still run on the local backend.

11.2Which jobs run remotely

11.3The deployment stack

On the operator side the cloud route uses four AWS surfaces. You do not need to know the details to use the app, but they matter when reading job logs or planning a deployment:

ECR

Stores the worker Docker image. It is the same image as the local backend, with a Batch entrypoint that reads input.json from S3 and writes status.json / result.json back.

S3

One prefix per job, holding input.json, status.json, and result.json. The frontend polls status.json and downloads result.json when the status becomes succeeded.

AWS Batch

Runs the worker image as a container in a managed compute environment. Default minvCpus=0 so the cluster scales to zero between jobs. The job definition is registered with an execution role so ECR image pulls and CloudWatch log delivery work on both EC2-launch and Fargate-launch environments.

DynamoDB (optional)

Per-user daily submission counter keyed by Cognito sub. Enabled with --with-quota-table in setup_aws_batch.sh. See §10.4 for the user-facing behaviour.

A signed Cognito ID token must accompany POST /api/jobs requests when Cognito is configured. The cloud backend rejects unsigned calls with HTTP 400 “Missing Authorization Bearer token”.

11.4Watching a remote job

The result node renders the job lifecycle inline:

• Job ID returned by Batch as soon as submission succeeds.
• Status badge stepping through pending → submitted → running → succeeded / failed / cancelled.
• Result artifact linked when the run succeeds. For atlas builds, the artifact is a SQLite file you can re-feed into an atlas-spec node on any future canvas session.
• Error message from the worker when the run fails. Deeper logs live in CloudWatch under the Batch job's log group.

A job's full lifecycle — submission, queue, container start, run, result upload — is opaque from the canvas: you only see the status badge. If you need detail, the Batch console and the per-job S3 prefix are the right places to look.