Clearbasin user guide

Getting started

Open the tool and choose a workspace tab: Treatment train, Water chemistry, Membranes or Report. A study starts with a treatment train filled with illustrative learning values; replace every number with your own project criteria and write where they come from in the Source field of each section. The source note preserves your provenance, and the tool does not authenticate it.

First study in two minutes:

1. On Treatment train, change the design flow and watch the sizing results, charts and the disinfection verdict update.
2. Open Examples to load a small package plant, a two-segment disinfection case, a balanced water analysis or a two-stage reverse-osmosis case.
3. Use Add on the other tabs to include water chemistry or membrane staging in the same study.
4. Save writes the study to a JSON file and Open brings it back. Saving never needs a calculation to have finished.

Calculations run in a Web Worker on your device with a current domain token. If the worker refuses, you see a plain message and no numbers. Saving, opening and editing do not need a token.

Using the workbench

Every field shows a unit selector where several units are common (for example m3/s, L/s, ML/d and US MGD for flow). The study always stores SI units; the selector only changes how a value is shown and typed, and the factors are exact definitions. A value that converts to zero, to a non-finite number or outside the supported range is refused with a message, never rounded to zero.

Edits are checked against the same validator the engine uses. If you type something the engine rejects, the field is highlighted with the reason, the last valid value stays in the study, and results are hidden until every field is valid, so numbers from old inputs are never shown beside new ones.

Pass or fail statements, such as whether a contact segment reaches its entered CT target, whether the summed ratios reach 1, or whether the ideal screen has forward driving pressure, are decided with exact rational arithmetic on the numbers you entered, so a result cannot flip on the last binary digit. Displayed numbers are ordinary double-precision values.

Undo and redo step through edits (typing in one field is grouped into one step). Keyboard shortcuts are listed under Help. Your study is autosaved in this browser only and is never uploaded. Light, dark and automatic themes are available, and the layout works down to a phone width.

Each chart can be downloaded as SVG or PNG, and the Report tab prints a one-document summary. Charts are drawn from the same data as the tables.

Treatment sizing

The engine works in flow in m3/s, concentration in kg/m3, time in seconds, depth in m, viscosity in Pa s and velocity gradients in 1/s; the fields accept friendlier units and convert exactly. Coagulant mass rate is flow times dose; no dose-response prediction is made. Mix and flocculation volumes use their entered detention times. Mixing power is the entered viscosity times the square of the mixing gradient times mixing volume. Flocculation GT uses its separate flocculation gradient and detention time. No property or recommended gradient lookup is supplied.

Settling area uses the entered surface overflow rate in m3/(m2 s), equivalent to m/s. Volume uses that area and the entered water depth. Detention is the resulting volume divided by flow. These calculations do not predict solids removal or resolve short-circuiting.

Filter area is sized so that the online units can pass the entered flow at the entered filtration rate. For example, four installed units with one offline size each unit for one third of the flow. Installed area includes the offline unit; online area does not. This is a sizing allocation, not backwash hydraulics, head-loss or filter-run prediction.

For each contact segment enter volume, baffling factor, residual concentration and your applicable CT target. Nominal detention is volume/flow; T10 is nominal detention times baffling. CT uses residual in mg/L times T10 in minutes, with exact unit conversions from the SI inputs. The sum of segment target ratios is an arithmetic index only. Segments must refer to the same compatible target basis if you choose to interpret that sum; the engine cannot check pathogen, disinfectant, pH, temperature or jurisdiction. It never converts a ratio into log-removal credit. Criteria and targets are USER-ENTERED; there are no regulatory tables.

Carbonate and charge calculations

Enter prescribed pH, dissolved inorganic carbon (DIC) in mol/m3 and appropriate apparent pKa1, pKa2 and pKw. The three species are dissolved carbon dioxide/carbonic acid combined, bicarbonate and carbonate. The dilute ideal model partitions the entered DIC using two mass-action ratios. It does not solve pH from alkalinity or enforce chemical equilibrium with air or minerals. Constants are USER-ENTERED: no temperature or activity correction is inferred.

The hydrogen and hydroxide concentrations convert the prescribed-pH mol/L values into mol/m3. Carbonate alkalinity is bicarbonate plus twice carbonate plus hydroxide minus hydrogen, in eq/m3. It excludes noncarbonate buffers. No CaCO3 mass-equivalent conversion is applied.

The ion list is a separate analytical accounting list. Enter the complete list to be checked, including carbonate species, H and OH if you want them included. The engine does not insert them automatically, avoiding double counting. Positive charges contribute to cation equivalents; negative charges contribute to anion equivalents. Charge imbalance is 100 times (cations minus anions)/(cations plus anions). An empty or all-zero list has a null percentage, displayed as n/a, not zero percent. Ionic strength is one half of the sum of concentration times squared charge, in mol/m3, from that same list. This value does not feed an activity model.

Enter saturation pH from an independent, appropriate calculation. LSI is pH minus that saturation pH; RSI is twice saturation pH minus pH. No saturation-pH estimator or scaling-rate classification is supplied. These indices do not determine corrosion, scaling rate, material suitability or water safety.

Membrane stages and pressure screening

Each stage receives the preceding stage's concentrate. Enter recovery as a fraction, rejection relative to that stage inlet, and design flux in m/s. Product flow is the specified fraction of inlet flow; product concentration is the unrejected fraction of inlet concentration. Conservation gives concentrate flow and solute concentration. Area divides product flow by the entered design flux. Outputs show stage and whole-train water and salt residuals. Combined product concentration uses flow-weighted mixing. Zero total recovery gives no product concentration (n/a) and zero area.

A separate ideal osmotic-pressure screen uses your temperature, gas constant and feed/permeate osmolarities. Enter osmoles in mol/m3, already including any dissociation or osmotic-factor assumptions. Do not enter an ion count again. The pressure difference subtracts permeate hydraulic pressure, entered loss and the osmotic-pressure difference from applied pressure. Positive net driving pressure gives water flux from entered permeability and a dimensionless fouling multiplier. Nonpositive net driving pressure reports no-forward-driving-pressure and zero forward flux; it does not model reverse osmosis flow direction or shutdown controls.

Design flux and pressure-screen flux serve different purposes. The screen does not verify that the specified stage recoveries are feasible. There is no element-by-element transport, concentration polarization, precipitation, pressure profile, energy/pump model or time-dependent fouling. All membrane coefficients are USER-ENTERED. RO and NF use the same lumped balance; there is no unsupported salt-selectivity database.

Limitations and resource use

At most 32 contact segments, 64 charge-species rows and 16 membrane stages are supported. Installed filter count is an integer from 1 to 256 and at least one unit must remain online. Stage recovery is 0–0.95, rejection and baffling are 0–1, and fouling multiplier is 0–1. pH and saturation pH are 0–14; pKa values are -10–30 with pKa1 less than pKa2; pKw is 0–30. Temperature is 273.15–373.15 K and the entered gas constant must be 1–100 J/(mol K). Ion charge is a nonzero integer from -8 to 8.

Nonzero scalar inputs, including dimensionless entries, must have absolute magnitude at least 1e-12. Other nonnegative dimensional inputs are zero where explicitly allowed, or at least 1e-12 and at most 1e12 in their declared units. Flow, detention times, viscosity, design rates, settling depth and CT targets must be positive. These are computational windows, not evidence that all admitted combinations represent real water. Out-of-range, nonfinite, wrong-type, fractional-count and sparse-row inputs are refused, without coercion or silent clamping.

The conservative project/result/serialization memory estimate is 1 MiB plus 4096 bytes per contact, ion or membrane row, below 2 MiB at the row caps. It excludes the browser runtime and loaded bundle. JSON input is limited to 1,048,576 UTF-16 characters, not a byte measurement; no dense matrix is allocated. Calculations run in one Web Worker; a newer edit replaces a queued older one, and late replies are discarded.

Files and exports

The original clearbasin JSON format is version 1. It preserves all model fields and source notes and rejects unsupported fields rather than dropping them. It contains no computed result cache. No proprietary project formats are supported. Import is parse → validate; it does not run calculations or send project data to a server. Unknown versions, missing notices and nonfinite numbers are refused. Autosave uses this browser's local storage only; anything that does not pass the same strict validation is ignored, never repaired.

CSV is a three-column RFC4180 results report: quantity, unit and full-precision numeric value. Non-applicable values use n/a. Warnings and the professional-use notice follow the numeric rows. Text cells are quoted; potentially executable spreadsheet prefixes, including fullwidth characters, are neutralized. CSV is not a project interchange format. Use JSON to preserve and reopen the model. Charts export as SVG and PNG with the Clearbasin line and the professional-use notice added under the picture.

How we verify this tool

The single case register is engine/verification/cases.ts, shared by the tests and the Verify page. Synthetic scalar checks use an exact-rational hand ledger generated independently of the engine. They cover four derivation families: treatment balances, carbonate/charge accounting, membrane salt/water ledgers and an ideal pressure screen. Scalar rows from one family are grouped; they are not presented as separate measured validations. Separate seeded tests solve small linear mass-action and balance systems against the engine over 240 states.

One published CT calculation is checked against the openly available US EPA Disinfection Profiling and Benchmarking Technical Guidance Manual (2022), section 4.6, Example 4-2, printed page 33, opened and visually inspected on 2026-10-26. Its 0.8 mg/L residual and 81.3 minute contact time give 65.04 mg min/L; the publication prints 65.0. The 0.05 absolute tolerance is explicitly for that rounding. This validates that arithmetic example only, not plant treatment efficacy. Source: https://www.epa.gov/system/files/documents/2022-02/disprof_bench_3rules_final_508.pdf .

Laboratory chemistry and manufacturer membrane comparisons remain pending source, with no invented reference numbers. Pending cases have no pass verdict. The evaluator rejects nonfinite values and tolerances and has no hidden absolute floor. Tests include wrong-result controls, scale families, conservation, empty/zero cases, all numeric input guards, persistence, CSV consumers, gate refusal, worker parity and cancellation.

The Verify page runs every ready case in your browser through the same gated worker, shows the reference, computed value, difference and tolerance for each, and earns its headline only when the complete current run passed. Cases that are pending source are listed and never counted.

Compared with other tools

Specialist desktop and plant-design systems may provide full aqueous equilibrium, proprietary membrane libraries, detailed transport, cost databases, hydraulics and jurisdiction-specific disinfection credit. This preliminary browser engine covers a smaller, explicit scope. It emphasizes editable criteria, transparent balances, reproducible checks and open files. No broad parity or performance claim is made.

Troubleshooting and genuine questions

Where do CT targets come from? Obtain the applicable target from the responsible authority or a legitimately held source for your disinfectant, organism, temperature and pH. Enter it with the project source note. A source note alone does not establish its correctness.

Why enter equilibrium and membrane constants? Their validity depends on water conditions and the chosen model. Clearbasin does not ship unsourced or proprietary datasets. Provide traceable values and assess whether the ideal models apply.

Does a saturation index predict a scaling rate? No. Here the index only compares entered pH with independently supplied saturation pH.

Why is product concentration n/a? All entered stage recoveries may be zero. With no product flow, a combined product concentration is undefined.

Can this certify drinking-water safety? No. It does not establish regulatory acceptance or treatment efficacy. Confirm design criteria, chemistry, hydraulic contact behavior and real equipment performance independently.

Why is a run blocked? The worker requires a valid signed domain token. Reconnect to simulations4all.com.

Professional use

Results are for education and preliminary design; must be checked by a qualified professional. They are not a substitute for code-compliant design or licensed engineering judgement.