Learn

New to this? Start here

The words on this site, the questions people ask, and where every number comes from.

Glossary

The same explanations the buttons show, in reading order.

Diabetes and dosing

Type 1 diabetes: A condition where the body makes no insulin, so people must give themselves insulin every day for life. About 9.5 million people live with it worldwide; many rely on pumps and software to dose. Source
CGM: A continuous glucose monitor: a small sensor under the skin that reports glucose every few minutes. It is the algorithm's only view of the body. Gaps and false readings are realistic faults.
Bolus: A one-off dose of insulin, usually at a meal. Forgetting one, or the algorithm not knowing about one, are common real-world problems the trial tests.
Temporary basal rate: A short-term change to the steady background insulin a pump gives, in units per hour, usually for 30 minutes. This is oref0's main lever. Small changes every 5 minutes are how the algorithm keeps glucose in range.
Insulin on board: Insulin already given that is still acting in the body, in units. If the algorithm underestimates it, it gives more insulin than needed, which can cause a low.
Carbs on board: Carbohydrates eaten that have not yet raised glucose, in grams. The algorithm uses them to predict a rise and dose for it.
Max safe basal: oref0's hard cap on a temporary basal rate: the lowest of the configured maximum, 3 times the highest daily basal, and 4 times the current basal. Every deployed engine release is checked to never exceed it.

The idea

OpenAPS oref0: The open-source algorithm that decides, every 5 minutes, how much insulin a pump should give, based on glucose readings and insulin already given. MIT licensed. It is the project Virtual Trial protects. Its logic was carried into other open-source dosing apps (AndroidAPS, Trio). Source
Virtual patient: A computer model of a person whose blood sugar rises with food and falls with insulin, the way a real body does. We use the UVA/Padova model via simglucose: 30 patients, children to adults. It lets us see what a code change would do to a body over a day, without risking anyone. Source
UVA/Padova simulator: A mathematical model of how glucose and insulin move through the body, developed at the University of Virginia and the University of Padova. The FDA accepted the commercial version in 2008 as a substitute for animal trials in testing insulin controllers. We use an open-source implementation and do not claim FDA validation. Source
Closed loop: The algorithm doses, the virtual body responds, the next reading feeds the next decision, every 5 minutes. Mistakes compound over hours. Checking one decision at a time misses that.
Open-loop testing: Feeding fixed inputs to the algorithm and comparing its output with an expected answer, with no body in between. It catches typos but cannot show harm: a dose that looks reasonable once can stack up into a dangerous low over hours.
Fault injection: Deliberately adding real-life problems to the trial: sensor dropouts, false readings, missing pump records, forgotten boluses. Many real dosing bugs only appear when data is messy, not on a perfect day.
Scenarios: Eight simulated days, each with meals and at most one fault: a normal day, a forgotten bolus, a large dinner, a sensor dropout, a false low, a sensor jump, a pump history that starts with a resume, and a bolus missing from history. Each fault is modeled on a failure reported in real dosing software or a recall, so the trial tests what has actually gone wrong before.
Base and head: Base is the dosing code before the change; head is the code with the change. The trial runs both on the same patients, meals, faults, and random seed. Because everything else is identical, any difference in outcomes comes from the code change.
Random seed: A number that fixes the sensor noise and other randomness, so a run can be repeated exactly. The same inputs always give the same result, so a verdict can be reproduced and checked by anyone.

Reading the results

Time in range: The share of the day glucose stays between 70 and 180 mg/dL, the target range in the international consensus. It is the headline measure of how well a person's glucose is controlled. Source
Low blood sugar risk: How often and how far glucose falls below safe levels: below 70 mg/dL (level 1) and below 54 mg/dL (level 2, clinically serious). Severe lows can cause confusion, seizures, or worse. A change must never make them more likely.
High blood sugar risk: How long glucose stays far above range (above 250 mg/dL), a warning sign for diabetic ketoacidosis. A gate that only checks lows would reward giving too little insulin. We check both directions.
LBGI and HBGI: Low and High Blood Glucose Indexes (Kovatchev): single numbers that weigh how far and how often glucose goes low or high, with larger excursions counting more. They capture risk that a simple percentage of time misses, such as one deep low.
Severe low event: Glucose below 54 mg/dL for at least 15 minutes in a row. This is the consensus definition of a clinically significant low. Any new event blocks a change.
Paired consistency check: For each patient and scenario, compare base and head. If a risk index rises by 15% or more on average and rises in so many pairs that chance is ruled out (exact sign test, p at most 0.01), the change is blocked. A bug that makes things a little worse almost every time is real harm, even if the average change is small.
Gate limits: The thresholds a change must stay within, in gate/thresholds.yaml. For example, time below 70 may rise by at most 0.5 percentage points. People own these numbers through code review (CODEOWNERS). Agents can never change them.

The engineering

Merge request: A proposed change to the code, reviewed before it is merged. GitLab's name for a pull request. Every dosing change arrives as one, so that is where the trial runs and where the verdict appears.
Pipeline: The automatic sequence of jobs GitLab runs for each change: tests, security scans, the trial, the gate, and deployment. It makes the safety check impossible to skip: a blocked gate stops the change.
Safety gate: The pipeline step that reads the trial's verdict and passes or blocks the change. It turns the trial into a decision: risky changes cannot merge or ship.
GitLab Duo flow: An AI agent workflow on GitLab's Duo Agent Platform. Ours start on their own: when a merge request opens, when its pipeline fails, or when an incident opens. Our three flows plan the trial, explain the verdict, and respond to incidents. They can read and comment, the planner can make the trial bigger, and the incident agent can undo a change with git revert. None can write dosing code.
Agent boundary: A pipeline job that fails if any AI agent account committed a change to dosing code, the trial, or the gate limits. The only exception is an exact undo (git revert) of a commit already on the branch, verified by comparing the two patches. The rule does not depend on what an agent's instructions say. It is enforced by the pipeline, and tested against four ways to abuse the exception.
Canary release: A new engine version is deployed but receives no traffic until it passes a safety check on 151 dosing decisions. Then it gets all traffic and is checked again. A broken release never serves anyone. This caught a real crash on Oct 13: the bad version never received traffic.
Rollback: Sending traffic back to the previous engine version. Automatic if a promoted version fails the check; one click otherwise.
Google Cloud Run: Google's service for running containers on demand. Our dosing engine, website, and virtual clinic run on it. It scales to zero when idle, so the live demo costs almost nothing.
Keyless deploys: GitLab's pipeline proves its identity to Google Cloud with a short-lived token (Workload Identity Federation), so no password or key is stored anywhere. No secret to leak. Google only trusts this project, on protected branches.
Virtual clinic: Ten virtual patients living on the deployed engine. Every 10 minutes they move 2 simulated hours forward, and every insulin decision comes from the live engine. If a release made dosing worse, it would show up here, as worse outcomes for these patients.

Questions

Is this a medical device?

No. It is a research and education project. It tests code; it never treats anyone. All patients are simulated.

Why not just use the project's existing tests?

They check that one input gives one expected output. They do not show what a change does to a body over many hours, which is where dosing mistakes become dangerous.

Can a simulator be trusted?

Not as a prediction for a real person. We use it to compare old and new code on identical patients and days. If the new code does worse in the same conditions, that is worth a person's attention before release.

Does the AI change the dosing code?

No. Two agents plan trials and explain verdicts; neither has a tool that can change files. A pipeline job (the agent boundary) also fails any merge request where an agent account changed dosing code, the trial, or the gate limits.

Why both low and high blood sugar?

A check that only punishes lows would quietly reward giving too little insulin, which leads to dangerous highs. We check both.

What is OpenAPS oref0?

An open-source dosing algorithm, MIT licensed. Virtual Trial imports it into GitLab and wraps the trial around it.