formula-cpp 0.1.0

formula-cpp 0.1.0

The first release of formula-cpp, a header-only C++23 library for traceable formulas. You write
a formula once, in C++. The library checks its dimensions at compile time, converts units exactly,
and evaluates it in exact rational arithmetic, so a number is never silently rounded. It renders
the same formula as documentation. It also records every step of an evaluation, so the result
comes with an audit trail that states each number with its unit and where it came from.

The library is licensed under Apache-2.0.

Documentation, with the guides, a gallery and the API reference:
https://lastrada-software.github.io/formula-cpp/

Requirements

• C++23 and CMake 3.23 or newer.
• CI builds and tests every change on MSVC cl and clang-cl (Windows), Clang and GCC 14
  (Linux, with an UndefinedBehaviorSanitizer build) and Clang on macOS.
• Minimum compiler versions are not settled yet.

What is in it

• Exact numbers and rounding: a checked rational type that reports overflow instead of
  wrapping, with rounding to decimal places, significant digits or multiples under named modes.
• Dimensions and units: dimensions with rational exponents, checked at compile time, and units
  with exact conversion, including affine ones such as degrees Celsius.
• Quantities: declared once with a symbol, a description and a unit, either as an alias or as a
  struct. Measurements may be absent without that being an error.
• Expressions and evaluation: arithmetic, powers and roots over environments of measured or
  hand-entered values. Evaluation yields an outcome that is a value, a verdict, an invalid result
  or nothing, never a bare number that hides which.
• Citations and documentation: documented() citations on any part of a formula. Formulas
  render as plain text, Markdown or LaTeX, and the library generates documentation with a symbol
  table.
• Tracing and audit reports: composable sinks, a trace of every step, and a bounded rendering
  of it that a person can check line by line.
• Rounding and conditionals: rounding as a node of a formula, when() conditionals, and a
  justified escape hatch from units.
• Constraints: constraints as peers of formulas. Their verdicts are recorded in the trace, and
  a set of constraints is checked without short-circuiting.
• Lookup tables: exact, banded and interpolating lookups over tables validated at compile time.
  A value outside the table gives no number at all.
• Methods and jurisdiction overlays: a method holds variants chosen by tag, together with
  rounding rules and constraints. A jurisdiction's overlay can fix constants, derive quantities,
  replace formulas, pin or prune variants, and use its own vocabulary of symbols. Every change is
  cited in the trace.
• Series and grading curves: a quantity at every point of a method's domain, elementwise
  arithmetic, running totals, sums, conformity against a limit envelope, snapping, curves,
  interpolation, splicing, and binning of raw observations.
• Statistics and outlier rejection: mean, variance and range of a sample, precision limits,
  critical-value tables read at the sample size, and iterative outlier rejection with its own
  abort rules.
• Cross-record context and lineage: a formula can read from other samples and tests, with each
  value's origin stated in the trace, and can check that records share a lineage.
• Opaque operations and least squares: named computations traced by their inputs and outputs,
  with the inside marked as not shown. The first of them is a least-squares line.
• Bounded retry: a step repeated until it is accepted, at most a fixed number of times. It ends
  in exactly one of six stated ways, and ends in the method's verdict when the attempts run out.

Using it

Install it with CMake, then consume it with find_package:

cmake -S . -B build -DFORMULA_INSTALL=ON -DCMAKE_INSTALL_PREFIX=/your/prefix
cmake --install build

find_package(formula-cpp 0.1 CONFIG REQUIRED)
target_link_libraries(your_target PRIVATE formula-cpp::formula-cpp)

The installed package exports the header-only INTERFACE target formula-cpp::formula-cpp and a
version file. Its compatibility is SameMinorVersion, so a request for 0.1 is not satisfied by
0.2. Because the library is header-only, copying include/ into your tree also works.

Known limits

• No stable API before 1.0. A minor release may change the public API. Every change is
  recorded in the CHANGELOG.
• 64-bit rational headroom (#1):
  some realistic laboratory statistics exceed the 64-bit numerator and denominator. Such a
  computation reports an overflow; it never gives a wrong number. The guide "Numeric headroom"
  describes the limits in detail.
• Units of single-value arithmetic in a trace
  (#2): a computed single value,
  such as a product or a quotient, is shown in its coherent SI value with no unit symbol. The
  number is right, but the reader has to know which unit it is in.

The full list of changes is in CHANGELOG.md.