How formulas work

This guide explains the PoolCloud formula engine — how it takes a pool's water readings and calculates exactly which chemicals to add and how much. For the request/response contract, see the calculate endpoint reference.

What is a formula?

A formula is a complete recipe for balancing a pool's water chemistry. Each formula is designed for a specific sanitization type (chlorine, salt water, bromine, or minerals) and contains:

• Readings — what to measure (free chlorine, pH, alkalinity, etc.)
• Target ranges — the ideal range for each reading
• Balance order — the sequence in which to adjust chemicals (order matters)
• Treatments — the chemicals and actions used to correct each reading
• Adjusters — logic that accounts for chemical interactions (e.g. pH and alkalinity affect each other)

Formulas in detail

Chlorine (chlorine_cal_hypo)

The most common formula, for standard chlorine pools using calcium hypochlorite.

Readings: Free Chlorine, Total Chlorine, pH, Total Alkalinity, Cyanuric Acid (CYA), Calcium Hardness

Balance order and treatments:

Default target ranges:

Adjusters: shock adjuster (infers combined chlorine from TC − FC), pH/TA adjuster (accounts for cross-effects between pH and alkalinity).

Salt water (salt)

For pools with a salt chlorine generator (SWG). Like the chlorine formula, but adds salt monitoring and raises the CYA target, since salt systems need more stabilizer.

Readings: Salt, Free Chlorine, Total Chlorine, pH, Total Alkalinity, Cyanuric Acid (CYA), Calcium Hardness

Balance order and treatments:

Target range overrides (vs. chlorine):

All other target ranges match the chlorine formula.

Key differences from chlorine:

• The default chlorine treatment is "Salt Generator Up" — a task, not a chemical — telling the user to turn up the cell's output
• Dichlor is offered as a chlorine substitute instead of liquid chlorine
• A salt reading with its own treatment

Bromine (bromine)

For pools and hot tubs sanitized with bromine instead of chlorine.

Readings: Bromine, pH, Total Alkalinity, Cyanuric Acid (CYA), Calcium Hardness

Balance order and treatments:

Default target ranges:

Key differences:

• No Free Chlorine or Total Chlorine readings — Bromine instead
• One treatment for raising bromine (no substitutions)
• Adjusters: pH/TA only (no shock adjuster without FC/TC)

Minerals (minerals)

For pools on a mineral sanitization system (Nature2, Frog, and similar). Minerals do most of the sanitizing; only trace chlorine is needed as a backup.

Readings: Free Chlorine, Total Chlorine, pH, Total Alkalinity, Cyanuric Acid (CYA), Calcium Hardness

Balance order and treatments: identical to the chlorine formula.

Target range overrides (vs. chlorine):

All other target ranges match the chlorine formula.

All readings

Every reading the engine understands, with its default configuration:

How warning buffers work

Some readings have a warning buffer — a zone just outside the target range where the engine generates a warning instead of a treatment action. This prevents over-treating readings that are only slightly off.

For example, Free Chlorine has a target range of 1–3 ppm and a warning buffer of +2 above. If FC reads 4.5 ppm, it's above the 3 ppm max but within the 5 ppm warning ceiling (3 + 2), so the engine returns a warning rather than telling you to drain the pool.

Wall type effects on targets

For plaster, concrete, and pebble pools, the Calcium Hardness target is raised to 200–275 ppm (from the default 175–225 ppm). These surfaces are more susceptible to etching from low-calcium water.

How combined chlorine (CC) is calculated

Combined chlorine is not measured directly. The engine infers it:

CC = Total Chlorine (TC) − Free Chlorine (FC)

If CC is above the 0.1 ppm threshold, chloramines are present. The shock adjuster creates a delta that triggers a shock treatment to break them down through breakpoint chlorination.

All treatments

Chemical treatments

Task treatments

Not chemicals — actions for the pool owner to take.

Special treatments

Substitutions by formula

Each formula has a default treatment (first in the list) for each reading direction. You can substitute any of the alternatives via the substitutions request field.

Chlorine and minerals

Salt

Bromine

How the calculation engine works

When you submit readings to POST /api/calculate/, the engine runs through these steps:

1. Determine target ranges

For each reading, the engine picks the ideal range by checking, in priority order:

1. Custom target levels passed in the request
2. Formula-level overrides (salt sets CYA to 60–80 ppm; minerals sets FC to 0.5–4 ppm)
3. Wall type adjustments (plaster/concrete/pebble → CH 200–275 ppm)
4. Default reading targets

2. Calculate deltas

For each reading, compare the current value against the target range:

• Within target range — no action
• Outside target, within warning buffer — a warning, no chemical treatment
• Outside the warning buffer — a delta (distance from the midpoint of the target range)

3. Run adjusters

Adjusters handle chemical interactions between readings.

Shock adjuster (chlorine, salt, minerals): infers CC = TC − FC; if CC exceeds 0.1 ppm, creates a delta that triggers shock. This is why both FC and TC matter — the difference reveals chloramines.

pH / TA adjuster (all formulas): pH and total alkalinity are chemically linked — raising one raises the other. The adjuster accounts for the cross-effect so the engine doesn't over-correct.

4. Execute treatments in balance order

For each reading, in the formula's order:

1. Check for a delta (positive = too low, raise; negative = too high, lower)
2. Select the default treatment, or the substitution if one was provided
3. Run the treatment's dosing function to get the amount in ounces from pool volume and delta
4. Update all deltas to account for side effects

Why order matters: pH first, because it affects how effective everything else is. Alkalinity second, because it buffers pH. Chlorine or bromine next for sanitization. CYA and CH last — they change slowly and interact least.

5. Insert wait periods

The engine inserts "Wait" actions between treatments that need circulation time:

Wait actions appear in the response with type: "special", and the ounces field holds the number of minutes.

6. Combine drain actions

If several readings are dangerously high (say CYA and calcium hardness), the engine combines their individual drain treatments (drain_cya, drain_ch) into a single Dilute Pool action and sorts it to the top. One partial drain fixes several problems. When only one reading needs a drain, its specific drain_* treatment is returned as-is.

7. Append warnings

Readings within the warning buffer are appended as warning actions at the end. Their ounces field holds the delta from the target range (negative = below target, positive = above).

Target level overrides

Every reading has a default target range, overridable per request:

{
  "target_levels": [
    { "id": "fc", "min": 3, "max": 5 },
    { "id": "ph", "min": 7.4, "max": 7.6 }
  ]
}

Useful when a pool has special requirements (commercial pools often run higher chlorine), a customer has custom ideal ranges, or a surface or sanitizer calls for different targets.

The pool object

Understanding the response

The response is an ordered list of actions — the steps to perform, in sequence.

Action types

Treatment options

Each action includes a treatment_options array listing every available treatment for that reading; treatment is the selected one. Use IDs from treatment_options as substitutions in future requests to switch.

Example walkthrough

For a 10,000 gallon plaster chlorine pool with FC=0, pH=7.2, TA=80, CYA=0, CH=0 — the reference page's example request — the engine returns:

1. Raise FC — add chlorine tablets (1 oz). Alternatives: chlorine granules, liquid chlorine
2. Wait — 60 minutes for chlorine to circulate
3. Raise CYA — add 52 oz stabilizer to protect chlorine from UV
4. Wait — 20 minutes
5. Raise CH — add 288 oz hardness increaser to protect the plaster

Each step is a separate entry in the actions array, in the order to perform them.