httk.core.precision

How precisely a number was written down.

A data file states its numbers to a definite number of digits, and that is a claim about precision: 0.3333 says the value is known to about 1e-4, while 0.33 says only 1e-2. Recovering that claim is what lets a matching tolerance — or an spglib symprec — be derived from the data rather than guessed at, which is otherwise a recurring source of arbitrary constants.

The value returned is an absolute bound, in whatever units the number was written in. It is not a relative precision and not a significant-figure count: 0.0001 and 9999.9999 both report 1e-4.

This is deliberately a separate concept from the arithmetic precision in exactmath, which governs how far an inexact computation is carried. This module is about what the source said; that one is about what we compute.

Functions

decimal_precision(→ fractions.Fraction | None)	The absolute precision implied by how a number was written, or None.
combined_precision(→ fractions.Fraction | None)	The precision of a set of values taken together: the coarsest of them.

Module Contents

httk.core.precision.decimal_precision(text: object) → fractions.Fraction | None

The absolute precision implied by how a number was written, or None.

None means the literal makes no precision claim, which is a different thing from claiming perfect precision. It is returned for an empty or missing value, for CIF’s ? and . placeholders, for anything that is not a decimal literal, and — this one matters — for an exact rational such as "1/3", which states a value rather than a measurement and so should not drag a structure’s precision down to the width of its last digit.

Examples, all exact:

• "0.123" -> 1/1000 — three digits after the point

• "-0.5" -> 1/10 — the sign is not part of the claim

• ".25" -> 1/100 — a leading point is still two digits

• "5." -> 1 — a trailing point states no fraction

• "10" -> 1 — an integer literal is precise to the unit

• "1.2e-3" -> 1/10000 — one digit, then scaled by the exponent

• "1/3" -> None — exact, not measured

• "?" -> None — no value at all

httk.core.precision.combined_precision(values: collections.abc.Iterable[object]) → fractions.Fraction | None

The precision of a set of values taken together: the coarsest of them.

A structure is only as precisely stated as its least precisely stated number, so one sloppy 0.5 among a table of six-decimal coordinates really does mean the table is good to 1e-1. Taking the coarsest is the conservative reading and the one that keeps a derived tolerance from being too tight to match anything.

Each value may be a literal to be interpreted by decimal_precision(), or an already-computed precision as a Fraction, int, or float — a standard uncertainty read from a file, say. Floats convert through their decimal spelling, so 0.005 lands on 1/200 rather than a binary approximation of it. Values that state no precision are skipped, and None is returned when none of them state one.