Formulas

Github repo

Think of this as a framework to codify your poolcare workflow so that it can be used, inspected, and modified by anyone.

Most of our users don't really understand what a formula is; they just load the iOS or Android app and follow the instructions to balance their pool.

But, it's important that some of us know what's happening behind the scenes.

Why?

Flexibility

Most pool calculators reflect the opinions (or worse: financial incentives) of their creators. If you want to use different chemicals, target-ranges, or sanitization systems... you should be able to. With Pooldash, this is accomplished by selecting a new formula, or by forking an existing one to suit your needs.

Transparency

Most pool calculators don't reveal the code used to calculate chemical dosages. This makes it hard for the community to help improve the app. At Pooldash, we recognize that many of our users know more about poolcare than us, so we not only encourage them to read this code, but we welcome pull-requests from anyone who wants to write it.

Correctness

Most pool calculators provide bad abstractions. It's tempting to consider each reading individually, and ask "What treatments could we use to balance this one?" This is easy to understand, but it breaks down quickly as special cases are implemented to account for side effects and chemical substitutions. With our formulas, we attempt to approach this holistically.

Formula Structure

graph TD; A-->B; A-->C; B-->D; C-->D;

The heart of this relies on each treatment defining a pure javascript function that must answer the question "How much (if any) of this treatment should we use in this pool, and exactly what effects (and side-effects) will it have?"

To enable this, each treatment defines a pure javascript function that must answer the question "How much of this treatment should we use in this pool with these conditions?"

We previously tried a different approach based on "ChemicalEffect" objects, but it was insufficient to model the nonlinear relationships and complex side-effects. Our current model of treatments-with-functions is closer to how poolcare operators actually think, and it encapsulates the complexity in a way that is approachable to programmers from various backgrounds.

How do they work?

Formulas have an arbitrary list of readings (Free Chlorine, pH, whatever) and a separate list of possible treatments (Calcium Hypochlorite, Sodium Bicarbonate, "Backwash the filter", whatever). Each treatment has a custom function that must return a single number. They run like so:

1. The user takes all readings specified by the formula
2. The app iterates over the formula's treatments, executing the custom javascript function for each one
3. The app displays all of the treatments whose function returns a non-0 value

You can inspect formulas using the online editor here. If you want to make your own, you'll need to create a free account and remix an existing formula. They're all MIT-licensed, so you can fork whichever one(s) you want.

Below is a reference for all the properties of a formula. If you have suggestions for improvement, please post it in the forum. Similarly, if you think these docs could be improved, submit a pull-request on Github.

Add Markdown or React files to src/pages to create a standalone page:

• src/pages/index.js → localhost:3000/
• src/pages/foo.md → localhost:3000/foo
• src/pages/foo/bar.js → localhost:3000/foo/bar

Create your first React Page

Create a file at src/pages/my-react-page.js:

src/pages/my-react-page.js

import React from 'react';
import Layout from '@theme/Layout';

export default function MyReactPage() {
  return (
    <Layout>
      <h1>My React page</h1>
      <p>This is a React page</p>
    </Layout>
  );
}

A new page is now available at http://localhost:3000/my-react-page.

Create your first Markdown Page

Create a file at src/pages/my-markdown-page.md:

src/pages/my-markdown-page.md

# My Markdown page

This is a Markdown page

A new page is now available at http://localhost:3000/my-markdown-page.