Skimmer Formula Guide

Skimmer formulas calculate exactly which chemicals to add and how much, based on your pool's water readings, sanitization type, and surface material.

What Makes Skimmer Formulas Different

Skimmer formulas are built on the PoolCloud engine but with more accurate chemistry:

• Tighter pH target: 7.2–7.6 (industry standard for comfort and sanitizer effectiveness)
• Tighter TA target: 80–120 ppm (prevents scaling and pH drift)
• Independent pH/TA treatment: Both are treated in the same pass — no suppression
• Soda ash dual effects: When soda ash raises pH, the TA side-effect is calculated and deducted from the remaining TA delta
• Baking soda is TA-only: No pH dosing hack — baking soda only treats alkalinity
• TA-dependent dosing: Treatment multipliers adjust based on current TA level (higher TA = less chemical effect per ounce)
• Extended readings: Phosphate, iron, copper, TDS, borate, temperature, and biguanide

Available Formulas

Chlorine (skimmer-chlorine_cal_hypo)

The most common formula. For standard chlorine pools using calcium hypochlorite.

Readings: FC, TC, pH, TA, CYA, CH, Phosphate, Iron, Copper, TDS, Borate, Temperature

Balance order:

Salt Water (skimmer-salt)

For salt chlorine generator pools. Same as chlorine but with salt monitoring and higher CYA target.

Key differences from chlorine:

• CYA target: 60–80 ppm (salt systems need more UV protection)
• Default FC treatment: Increase SWG Output (not a chemical — tells user to turn up the salt cell)
• Salt reading with salt treatment
• Dichlor available as chlorine substitute

Bromine (skimmer-bromine)

For pools and hot tubs using bromine sanitizer.

Key differences:

• Uses Bromine reading (3–5 ppm target) instead of FC/TC
• No shock adjuster (no combined chlorine inference)

Minerals (skimmer-minerals)

For mineral sanitization systems (Nature2, Frog, etc.) that need only trace chlorine.

Key differences:

• FC target: 0.5–4 ppm (minerals do most of the sanitizing)

Biguanide (skimmer-biguanide)

For pools using biguanide sanitizer (Baquacil, etc.). No chlorine or bromine.

Readings: Biguanide, Biguanide Shock, pH, TA, CH, Phosphate, Iron, Copper, TDS, Temperature

Balance order:

Default Target Ranges

How the Engine Works

1. Resolve Formula

If no formula_id is provided, the engine picks one based on pool.water_type:

• chlorine → skimmer-chlorine_cal_hypo
• salt_water → skimmer-salt
• bromine → skimmer-bromine
• minerals → skimmer-minerals
• biguanide → skimmer-biguanide

2. Determine Target Ranges

For each reading, targets are resolved in priority order:

1. Reading defaults (e.g. pH reading defaults to 7.2–7.6)
2. Formula overrides (e.g. salt formula sets CYA to 60–80)
3. Wall-type overrides (plaster/concrete/pebble → CH 200–275)
4. User overrides (target_levels in the request — highest priority)

3. Calculate Deltas

For each reading with a value provided:

• Within target → no action
• Outside target, within warning buffer → warning (no treatment)
• Outside warning buffer → delta calculated (midpoint of target minus current value)

4. Run Adjusters

Shock adjuster (chlorine, salt, minerals formulas): Infers CC = TC − FC. If CC > 0, creates a delta to trigger shock treatment.

5. Execute Treatments in Balance Order

For each reading in the formula's balance order:

1. Check if there's a delta
2. Select treatment (substitution if provided, otherwise first in the list)
3. Run the dosing function → calculate ounces based on pool volume, delta, and chemistry brackets
4. Update all deltas with side effects (e.g. soda ash raises pH AND TA)

6. pH/TA Chemistry Details

Soda ash (pH up):

• pH multiplier varies by current pH: max(0.000805, 0.00035 × (pH + 1))
• TA side-effect multiplier varies by current TA:
  • TA ≤ 80: 0.00016 (more responsive)
  • TA 80–120: 0.00014
  • TA 120–150: 0.00012
  • TA > 150: 0.00010 (less responsive)

Muriatic acid (pH/TA down):

• pH lowering uses pH-dependent brackets (more acid needed at lower pH)
• TA lowering uses TA-dependent brackets
• pH delta takes priority over TA delta

Baking soda (TA up only):

• TA multiplier varies by current TA:
  • TA ≤ 80: 0.000250
  • TA 80–120: 0.000224
  • TA 120–150: 0.000200
  • TA > 150: 0.000180

Sodium bisulfate (pH/TA down):

• TA lowering prioritized over pH lowering
• TA multiplier varies by current TA

7. Insert Wait Periods

Automatic wait actions between treatments that need circulation time. The ounces field on wait actions contains the minutes to wait.

8. Combine Drain Actions

If multiple readings need draining (e.g. high CYA + high CH), they're combined into a single "Drain & Refill" action at the top.

9. Append Warnings

Readings within the warning buffer are appended as warning actions at the end.

Understanding the Response

Action Types

Treatment Options

Each action includes treatment_options — the full list of alternatives. The treatment field is the selected one. Use IDs from treatment_options as substitutions values to switch.

Example Flow

For a 10,000 gallon chlorine pool with FC=0, pH=7.0, TA=60:

1. Raise pH — 11.2 oz pH Increaser (also raises TA as side-effect)
2. Wait — 20 minutes
3. Raise TA — Alkalinity Increaser (reduced amount because soda ash already raised TA)
4. Wait — 20 minutes
5. Raise FC — Add chlorine tablets