Maths engine and verified calculations¶

Spum 0.2.4 adds a native deterministic maths engine. Numerical results come from the maths engine rather than from generated model text. It runs locally and needs no Python installation or remote service.

The Mac app's Verified calculations workflow uses a local model to extract inputs, presents those values and units for review, and runs the selected calculation only after Calculate locally. The answer has a Verified maths label, and the calculation request, outputs and assumptions are retained with the local conversation. The Ubuntu app's Maths button evaluates an expression entered in its composer; structured instrument tools are also available through the CLI.

Verification here means the maths operation and its inputs are explicit and checked. It does not prove that a model has interpreted a physical experiment correctly. Review the extracted inputs and the tool's assumptions before applying its result.

Expressions¶

spum calculate --expression '1600 / sqrt(1600 + 400 + 10^2)' --json
spum calculate --expression '16 * 2048 * 1536 * 12 / 8 * 30 / 1e9'
spum calculate --expression 'sin(pi/2) + ln(e)'

Supported operations: +, -, *, /, ^, parentheses and scientific notation. Exponentiation is right-associative: 2^3^2 = 512. Unary minus has the usual mathematical precedence: -2^2 = -4.

Supported functions: sqrt, ln/log (natural logarithm), log10, exp, sin, cos, tan, abs, min, max, pow. Constants: pi, e. Trigonometric arguments are in radians.

The engine uses finite real floating-point arithmetic. It is not a symbolic algebra system or an arbitrary-precision calculator. Variables, programming statements, file access and network access are not part of the expression language. Expressions are limited to 4,096 characters, with nesting and complexity limits. Division by zero and non-finite results are rejected.

Command options¶

Option	Meaning
`--expression TEXT`	Evaluate an arithmetic expression
`--request-json JSON`	Supply a structured calculation directly
`--input FILE`	Read a structured JSON request, maximum 64 KiB
`--json`	Return machine-readable results, inputs and assumptions
`--output FILE`	Save the result instead of printing it
`--quiet`	Suppress optional summaries

Choose exactly one of --expression, --request-json or --input. Calculation does not require a language model. Keep the complete native runtime with the CLI.

Fluorescence exposure and SNR¶

Save as exposure.json:

{
  "tool": "fluorescence_snr",
  "signal_electrons": 1600,
  "background_electrons": 400,
  "read_noise_electrons_rms": 10,
  "reference_exposure_ms": 20,
  "exposures_ms": [20, 80],
  "minimum_snr": 60,
  "minimum_fps": 10
}

spum calculate --input exposure.json --json --output exposure-result.json

The formula is S / sqrt(S + B + read_noise^2). Signal and background scale linearly from the reference exposure. Read noise is per frame. Maximum frame rate is 1000 / (exposure_ms + readout_ms); optional readout_ms defaults to zero.

For these inputs:

Exposure	Signal	Background	SNR	Maximum fps	Meets both limits
20 ms	1600 electrons	400 electrons	34.9149	50	No
80 ms	6400 electrons	1600 electrons	71.1111	12.5	Yes

The tool assumes independent Poisson signal/background shot noise, additive read-noise variance, and no motion or bleaching. It does not model EM gain, correlated noise or a device-specific exposure controller. Specify both minimum constraints or neither. Between 1 and 32 exposure times are accepted.

Microcamera-array data rate¶

Save as array.json:

{
  "tool": "camera_array_throughput",
  "cameras": 16,
  "width_pixels": 2048,
  "height_pixels": 1536,
  "bits_per_pixel": 12,
  "frames_per_second": 30,
  "link_gigabits_per_second": 10,
  "overhead_percent": 20,
  "packing": "packed"
}

spum calculate --input array.json --json

The engine computes bytes per camera frame as ceil(width * height * bits / 8), then multiplies by camera count and frame rate. Link capacity converts Gbit/s to bytes/s and deducts the supplied overhead percentage.

For these inputs, raw data is 2.26492416 GB/s, usable capacity is 1 GB/s, and raw streaming does not fit. The minimum required compression ratio is 2.26492416:1. Whether lossless compression reaches that ratio depends on the images.

Units are decimal: one GB is 10^9 bytes, one Gbit is 10^9 bits. Packed pixels, byte-aligned camera frames and no extra per-frame metadata/padding are assumed. Unpacked pixel storage is rejected rather than silently treated as packed data.

App workflow¶

Select a local model and start a new conversation.
Enable Verified calculations.
Ask an expression question or supply the inputs for one of the supported instrument tools.
Check the extracted values and units in the review sheet. Missing values remain missing. Select the pixel layout explicitly if the model did not extract it.
Select Calculate locally. Invalid schemas or values produce an error rather than an invented numerical answer.

The local model is an input planner in this mode. Its generated arithmetic is never substituted for the deterministic tool result. Unsupported questions do not fall through to an unverified numerical answer. General chat remains available with the toggle off.

Functional checks¶

62 independent checks cover the two worked examples, Decimal-reference SNR, integer packed-frame sizing across varied camera configurations, expression precedence, units, invalid domains, unknown fields, missing inputs and rejected programming syntax. The same checks run on macOS and Ubuntu. These tests do not establish universal model reasoning accuracy or clinical validity.

A Neuroscape Imaging product.