# Calculators

A calculator turns a saved graph into a simple form for people who never open
the editor: a colleague checking a design, a client, a technician on site.
They fill in the inputs you chose, press **Calculate**, and get the results
with their uncertainty and the verdicts of the graph's requirements. Nothing
else in the graph can change.

![A calculator: two inputs, the result with its uncertainty, and the verdict of a requirement](images/calculator.png)

The tutorial's chapter *Share it as a calculator* sets one up step by step
(Help › Tutorial).

## Setting one up

1. **Track the results.** A calculator shows tracked outputs: right-click each
   output socket you want people to see and choose **Add to Tracked**.
2. **Open Share › Calculator…** (also in the command palette, Ctrl+K). It needs
   the right to edit the graph.
   - **Title** and **Description**: what the people using it read first.
   - **Inputs**: tick the settings that become the form's fields, and give
     each a plain label ("Length", not "Quantity › Value"). Every setting with
     a widget that is not linked is offered.
   - **Results**: tick the tracked outputs to show, and label them.
   - **Show the verdicts of the graph's requirements**: on by default.
   - **Save**.
3. **Save the graph** (Ctrl+S). The calculator runs the graph as it is saved:
   later changes reach it when you save them.

**Share › Calculator…** then offers **Open the calculator ↗**: the form at
`/calc?ws=<workspace>&graph=<graph>`, which anyone who may run graphs in the
workspace can open.

## Using it

The form shows each input with the value the graph was saved with, as a text
field, a number, a dropdown or a checkbox, like its widget in the editor. A
quantity is typed with its unit and, if it has one, its uncertainty:
`3.30 ± 0.01 m`.

**Calculate** runs the graph with only those inputs changed. Values the graph
cannot take, such as text where a length goes, are reported before anything
runs. The results show each value with its standard uncertainty, and the
requirements table shows each verdict: met, not met or inconclusive, against
the expanded uncertainty U = k·u (see {doc}`requirements`).

Every calculation is an ordinary run: it waits its turn in the run queue, runs
in a process of its own, writes a provenance record, and adds a line to the
graph's tracked history, so the Tracked and Requirements tabs show what was
calculated, by whom and when.

## Sharing it with a link

A **calculator link** lets someone without an account use the form, and
nothing else. To make one:

1. Open **Share › Calculator…** on the saved graph.
2. Under **Share**, say who it is for and how many days it lasts, and click
   **Create link**.
3. Copy the link: it is shown only once, because only a hash of its token is kept.

Someone with the link can open this one calculator and run it. They cannot
open the editor, the graph itself, the workspace's other graphs or files, or
the run records. The server treats them as having no role in the workspace,
only the use of this calculator.

| | |
|---|---|
| Who can make links | Managers of the workspace (admins always are) |
| The server needs | Sign-in (`noodlelab serve --auth users`, the default when it listens beyond this computer) and guest links turned on in **Admin › Settings** |
| Expiry | Like any guest link: at most 30 days by default (`guest_link_max_days` in **Admin › Settings**) |
| Revoking | **Share › Workspace members…** lists the workspace's guest links, calculator links as "Calculator: <graph>"; **Revoke** ends one at once |

## Limits

- Inputs are settings of nodes on the Processing or Reporting canvas; settings
  of nodes inside a subgraph cannot be listed.
- Results are tracked outputs: a value that cannot be tracked (an array, a
  table, a figure) shows its summary only.
- The calculator runs the saved graph, so unsaved changes on screen are not in it.

## For scripts and agents

A calculator is kept in the graph document's metadata, so a graph written as
JSON or by an agent can carry one:

```json
"metadata": {
  "calculator": {
    "title": "Floor area",
    "description": "The area of a rectangular floor against the 10 m² limit",
    "inputs": [
      {"node": "L", "input": "value", "label": "Length"},
      {"node": "W", "input": "value", "label": "Width"}
    ],
    "outputs": [{"node": "A", "output": "result", "label": "Area"}],
    "requirements": true
  }
}
```

Its outputs are written like tracked outputs (`node`, `output`, optionally a
`path` into a field). The server's routes are:

| Route | What it does |
|---|---|
| `GET /api/workspaces/{ws}/calc/{graph}` | The form: title, description, each input's key (`node.input`), label, type, widget and saved value, and the results' keys and labels |
| `POST /api/workspaces/{ws}/calc/{graph}/run` with `{"values": {"L.value": "3.3 m"}}` | Runs it; returns the status, each result (`text`, `value`, `u`, `unit`), each requirement's verdict, any problems and the run's record |

See `noodlelab.core.calculator` in {doc}`reference/concepts`.