Methodology: formulas, sources and test cases
Every calculator on this site and in the Pooldex app uses one chemistry engine. This page lists its units, constants, and formulas, the sources behind them, where those sources disagree and what we chose, and how we test each release.
On this page (10 sections)
Units and constants
Inside the engine, everything is kept in base units and nothing is rounded: US gallons or liters for volume, ppm (mg/L) for concentrations, grams for dry products, and milliliters for liquids. Total alkalinity (TA) and calcium hardness (CH) are expressed "as CaCO3", and borates as boron (B). Rounding happens only when a number is shown to you.
| Constant | Value |
|---|---|
| 1 US gallon | 3.785411784 L |
| 1 cubic foot | 7.48052 US gallons |
| 1 fl oz | 29.5735 mL |
| 1 oz (weight) / 1 lb | 28.3495 g / 453.592 g |
| Equivalent weight of CaCO3 | 50.04 g per equivalent |
| Molar masses used | Cl2 70.906; NaHCO3 84.007; Na2CO3 105.988; NaHSO4 120.06; HCl 36.461; CaCl2 110.98; CaCO3 100.087; cyanuric acid 129.07; B 10.81 |
The general rule for any product: grams of active ingredient = ppm change × liters ÷ 1,000. Products differ only in how much active ingredient they contain.
Chlorine dosing by product and label basis
The same "10%" means different things on different labels, and this is the most common reason chlorine answers disagree online.
- Pool liquid chlorine (10%, 12.5%) is labeled in trade percent: grams of available chlorine per liter divided by 10. So 12.5% trade = 125 g/L, and the dose in mL = ppm × liters ÷ (percent × 10). This is also how the Taylor K-1005 treatment table is built.
- Household bleach (6%, 7.5%, 8.25%) is labeled in percent sodium hypochlorite by weight. We convert it to g/L of available chlorine with the solution's density (linear interpolation in the OxyChem sodium hypochlorite table) and the ratio of chlorine to sodium hypochlorite: g/L = percent × density × 10 ÷ 1.05.
- Cal-hypo, dichlor, and trichlor are labeled in percent available chlorine: grams = ppm × liters ÷ 1,000 ÷ (percent ÷ 100). Side effects are shown with the dose. Cal-hypo adds about 0.7 ppm calcium hardness per 1 ppm chlorine (from its formula). Dichlor adds 0.9 ppm cyanuric acid (CYA) and trichlor 0.6 ppm CYA per 1 ppm chlorine (PHTA).
Liquid chlorine also loses strength over time. PHTA data: 12.5% sodium hypochlorite loses half its strength in about 180 days at 77 °F, but in about 48 days at 95 °F. The app can learn your jug's real strength from a retest 30–120 minutes after a dose. The site lets you enter a "strength left" percent by hand on the liquid chlorine calculator.
How much free chlorine to aim for
Stabilizer (cyanuric acid, CYA) protects chlorine from sunlight but also binds part of it. The CDC's Model Aquatic Health Code (MAHC 2024 Annex, 5.7.3.1.1.2) explains that the active form (hypochlorous acid) stays about the same when the CYA-to-chlorine ratio stays the same, so the minimum chlorine should rise with CYA. Our rules:
- minimum free chlorine (FC) = the larger of 1 ppm (no CYA) or 2 ppm (with CYA), and 7.5% of CYA (5% for salt water generators), rounded up to 0.5 ppm;
- target range = from the minimum (at least 2 ppm) to 2 ppm above it (at least 4, at most 10 ppm);
- shock: no level from CYA. The engine still keeps a reference value (40% of CYA, at least 10 ppm), but the site and the app never show it or turn it into a dose, because it is above the swim limit on pool chlorine labels. Shock follows your product's label;
- hot tubs: minimum 3 ppm (CDC), target 3–5 ppm capped at the label's swim limit (default 4 ppm, so 3–4 ppm), and no CYA.
The 7.5% and 5% ratios follow a principle popularized by the Trouble Free Pool community. We could read it only in secondary sources, so we treat it as secondary and use our own parameterization rather than copying any published table. See it for your pool on the chlorine levels page.
pH correction model
How much acid lowers pH by 0.3 depends on alkalinity, stabilizer, and borates in your water, so a fixed "ounces per 0.1 pH" rule is often wrong. We use a closed carbonate-system model: while you dose, no CO2 escapes, so total inorganic carbon stays constant.
- From your pH and TA, we compute total carbonate, after subtracting the part of TA that comes from cyanurate, borate, hydroxide, and hydrogen ions at your pH.
- For acid, the dose in equivalents is the drop in alkalinity needed to reach the target pH at that carbonate level. Muriatic acid strength comes from its density table (31.45% ≈ 9.97 mol/L); dry acid is sodium bisulfate at 93.2%.
- For soda ash or borax, the amount is found numerically (200 steps of bisection), because both raise pH and alkalinity at the same time.
Constants at 25 °C: carbonic acid pK1 6.35 and pK2 10.33 (standard textbook values), cyanuric acid pKa 6.88, boric acid 9.24, with a Davies activity correction based on total dissolved solids (TDS), with ionic strength ≈ 2.5 × 10⁻⁵ × TDS. Compared with the legacy TFP pool calculator, the model agrees within 1–5% (for example, both give 9.6 fl oz of 31.45% acid for pH 7.8 → 7.5 at TA 100 and CYA 40 in 10,000 gallons). With 50 ppm borates the difference grows to about 14%, because sources use different pKa values for boric acid.
Limits: the model does not include CO2 loss after dosing, which slowly pushes pH back up, and it uses 25 °C constants. That is why every acid step says "retest", and why acid is never more than 0.4 pH or 20 ppm TA per step. See it in action on the muriatic acid calculator.
LSI formula
The Langelier Saturation Index tells whether water tends to dissolve plaster (negative) or deposit scale (positive). We use the continuous formula instead of lookup tables, so small changes move the result smoothly:
- pHs = (9.3 + A + B) − (C + D), and LSI = pH − pHs
- A = (log10 TDS − 1) ÷ 10
- B = −13.12 × log10(°C + 273) + 34.55
- C = log10(CH as CaCO3) − 0.4
- D = log10(carbonate alkalinity), where carbonate alkalinity = TA minus the cyanurate and borate parts at your pH
Check: for pH 7.6, 84 °F, CH 300, TA 90, CYA 60, and TDS 1,000, the table method in an Orenda example gives 0.00 and our formula gives +0.01. We show −0.3 to +0.3 as balanced and up to +0.5 as slightly scaling (APSP range as published by PHTA). Try it in the LSI calculator.
Volume formulas and the above-ground correction
| Shape | Gallons (feet in, US gallons out) |
|---|---|
| Rectangle | length × width × average depth × 7.48 |
| Round | π ÷ 4 × diameter² × average depth × 7.48 |
| Oval, true ellipse | π ÷ 4 × length × width × average depth × 7.48 |
| Oval, above-ground style | ((length − width) × width + π × width² ÷ 4) × average depth × 7.48 |
| Kidney | 0.45 × (width A + width B) × length × average depth × 7.48 (common approximation) |
| Sloped floor | average depth = (shallow + deep) ÷ 2, or a length-weighted average for pools with a hopper |
| Hot tubs | seats and jets make shape math unreliable: we time the fill with a bucket and hose, or use the maker's capacity |
Above-ground pools hold less than their nominal size suggests: walls lean, corners round off, and the fill line sits below the top rail. We collected 35 above-ground pools and inflatable spas with capacities published by Intex, Bestway, and Coleman. We read 33 of them on the manufacturer's own page on 2026-09-29. For the 26 pools with a stated fill level, the manufacturer capacity divided by geometry at the same fill has a median of 0.933 (range 0.823–1.000). Inflatable-ring pools cluster at 0.82–0.90, and frame pools at 0.90–1.00. So when you don't pick a model, our calculators multiply geometry by 0.93 for frame pools and 0.87 for inflatable-ring pools and say "about ±7%". These factors are our own statistics, not a standard. The full list is in the above-ground pool gallons chart.
Where sources disagree, and what we chose
| Question | Source A | Source B | Our choice |
|---|---|---|---|
| Free chlorine with stabilizer | EPA labels and PHTA: 1–4 ppm, swim at 4 ppm or less | MAHC Annex: the minimum should rise with CYA | show both; keep CYA at 30–50 so the target fits; always "follow the label" |
| Liquid chlorine 12.5% | Taylor: trade percent | PHTA's figures: about 3.5% more liquid per ppm (10.6 vs 10.24 fl oz in 10,000 gal) | trade percent; the difference is smaller than test error |
| What to correct first | Taylor: alkalinity before pH | CDC priority on sanitizer | chlorine first if below minimum, then TA, pH, and calcium |
| Borax for +10 ppm borates (10,000 gal) | PHTA: 7.05 lb (uses 128 oz per gallon of water) | stoichiometry: 7.36 lb (a gallon of water weighs about 133.5 oz) | 7.36 lb |
| "Oval" factor | Hayward: L × W × depth × 6.7 | true ellipse: × 5.875 | two shapes; 6.7 matches the above-ground style when length is twice the width |
| Balanced LSI | APSP: −0.3 to +0.5 | Hayward: 0 ± 0.2 | balanced −0.3 to +0.3, caution to +0.5 |
| Maximum CYA | APSP: 100 ppm | salt cell makers: up to 80 ppm | warning above 90 ppm; salt pools target 60–80 |
Safety limits built into every dose
These limits are our choice, not a standard, and they apply on the site and in the app:
- acid: at most −0.4 pH and −20 ppm TA per step, then retest; target pH never below 7.2;
- soda ash: at most +0.3 pH per step; baking soda: at most +30 ppm TA per step; calcium chloride: at most +50 ppm per step;
- stabilizer is never raised above its target, because only draining lowers it;
- chlorine is never raised above the swim limit on your product label (4 ppm unless you enter your own). The plan shows "wait" when chlorine is above that limit, and "Don't swim yet" when it is below the minimum (or the label limit, if that is lower), above 10 ppm (the MAHC upper limit), or less than 30 minutes after acid;
- the plan does not calculate a shock level: it scales the shock directions from your product's label, or tells you to follow them;
- test-strip readings give a dose range, because a strip reads in steps; calcium, stabilizer, and salt from strips are confirmed with a drop test before adding or draining;
- acids and pH increasers are rounded down, everything else to the nearest step.
Read the pool chemical safety guide before handling acid or chlorine.
67 test cases and how we verify every release
The engine ships with 67 reference cases: input, expected output, and tolerance (0.1% for doses, 0.5% for the pH model, ±0.01 for LSI). Where an independent published value exists, the case lists it. Examples:
| Case | Our engine | Independent value |
|---|---|---|
| 10% liquid chlorine, +1 ppm, 10,000 gal | 12.80 fl oz | 12.8 fl oz (Taylor K-1005) |
| Cal-hypo 65%, +1 ppm, 10,000 gal | 2.054 oz | 2.05 oz (Taylor) |
| Trichlor 90%, +1 ppm, 10,000 gal | 1.484 oz | 1.48 oz (Taylor) |
| Baking soda, +10 ppm TA, 10,000 gal | 1.401 lb | 1.40 lb (Taylor) |
| Muriatic acid 31.45%, −10 ppm TA, 10,000 gal | 1.603 pt | 1.60 pt (Taylor) |
| Calcium chloride 77%, +10 ppm, 10,000 gal | 1.202 lb | 1.20 lb (Taylor) |
| Salt 0 → 3,200 ppm, 10,000 gal | 267.1 lb | 267 lb (Hayward) |
| 1 quart of 5.25% bleach in 6,000 gal | +2.24 ppm | about 2 ppm (EPA-registered Clorox label, 2011) |
Every site build runs all 67 cases in JavaScript (the code your browser runs) plus a separate Python reimplementation, and compares the two on more than a hundred extra inputs. If any case fails, the site is not built. The iPhone app will run the same cases in Swift. Calculator results on the page are prerendered by the same JavaScript, so the number you see without JavaScript is the number the calculator computes.
Not yet covered by reference cases: the pump, heater, and cost calculators (simple physics: 1 gallon of water ≈ 8.34 lb, 1 BTU raises 1 lb by 1 °F), the tablet CYA projection, and the hot tub water-change rule of thumb (gallons ÷ 3 ÷ daily soakers, original source not confirmed). These pages say so.
Change log
| Engine version | Date | Change |
|---|---|---|
| 0.1 | 2026-09-29 | First version: volume, chlorine targets, dosing for all common product types, pH model, LSI, validation, and display rounding; 67 reference cases. |
Sources
- CDC, Home pool and hot tub water treatment and testing: cdc.gov
- CDC, Model Aquatic Health Code 2024, Annex: cdc.gov (PDF)
- CDC, pool chemical injuries 2008–2017: archive.cdc.gov
- Taylor Technologies, K-1005 instruction manual and treatment tables: PDF
- Taylor Technologies, Watergram on water balance: PDF
- PHTA fact sheet, Sodium hypochlorite: phta.org
- PHTA fact sheet, Dichlor: phta.org
- PHTA technical bulletin, Boric acid and sodium borates: phta.org
- PHTA, Water balance indexes: phta.org
- OxyChem, Sodium Hypochlorite Handbook (density table): PDF
- EPA label, Clorox Regular Bleach, Reg. No. 5813-1 (2011): epa.gov (PDF)
- Hayward, AquaRite manual: PDF; How much salt to add: hayward.com
- Orenda, pKa and alkalinity buffering: blog.orendatech.com; Understanding labeled chlorine percentages: blog.orendatech.com
- Wikipedia, Hydrochloric acid (density table): wikipedia.org
- Leslie's, How to calculate pool volume (kidney approximation): lesliespool.com
- Manufacturer capacities: intexcorp.com and bestwayusa.com product pages, read 2026-09-29 (links in the gallons chart).
- Secondary: legacy TFP pool calculator (used only to cross-check the pH model): legacy.poolcalculator.com