mathema-symbology

Symbol lookups for mathema claim rendering.

mathema renders a verified claim back as one readable line of text, and on its own it can only spell a parameter the way the code spells it. This package supplies the notation: a curated mapping from common parameter and function names to the symbols their field's literature actually uses, so a claim about price, sigma1 or delta_revenue renders as P, σ₁ and ΔR rather than as Python identifiers. mathema asks it for a symbol on every render, and any name it has no entry for falls straight back to mathema's own naming.

Install

pip install mathema-symbology

mathema discovers it automatically once installed, through the mathema.capabilities entry point; there is no configuration to write.

Before and after

claim: for price in [0, 100], f(price) >= 0

without:  ∀ price ∈ [0.0, 100.0] ⊂ ℝ ∪ {∅}, f(price) ≥ 0
with:     let P = price, ∀ P ∈ [0.0, 100.0] ⊂ ℝ ∪ {∅}, f(P) ≥ 0

claim: for delta_revenue in [0, 10], f(delta_revenue) >= 0

without:  let x = delta_revenue, ∀ x ∈ [0.0, 10.0] ⊂ ℝ ∪ {∅}, f(x) ≥ 0
with:     let ΔR = delta_revenue, ∀ ΔR ∈ [0.0, 10.0] ⊂ ℝ ∪ {∅}, f(ΔR) ≥ 0

claim: for sigma1 in (0, 5], f(sigma1) >= 0

without:  ∀ sigma1 ∈ (0.0, 5.0] ⊂ ℝ ∪ {∅}, f(sigma1) ≥ 0
with:     let `σ₁` = sigma1, ∀ `σ₁` ∈ (0.0, 5.0] ⊂ ℝ ∪ {∅}, f(`σ₁`) ≥ 0

claim: for variance in [0, 10], f(variance) >= 0

without:  ∀ variance ∈ [0.0, 10.0] ⊂ ℝ ∪ {∅}, f(variance) ≥ 0
with:     let `σ²` = variance, ∀ `σ²` ∈ [0.0, 10.0] ⊂ ℝ ∪ {∅}, f(`σ²`) ≥ 0

claim: for pct_change_ebit in [-50, 50], f(pct_change_ebit) <= 1

without:  let x = pct_change_ebit, ∀ x ∈ [-50.0, 50.0] ⊂ ℝ ∪ {∅}, f(x) ≤ 1
with:     let `%ΔEBIT` = pct_change_ebit, ∀ `%ΔEBIT` ∈ [-50.0, 50.0] ⊂ ℝ ∪ {∅}, f(`%ΔEBIT`) ≤ 1

claim: for half_life in (0, 100], f(half_life) >= 0

without:  let x = half_life, ∀ x ∈ (0.0, 100.0] ⊂ ℝ ∪ {∅}, f(x) ≥ 0
with:     let `t½` = half_life, ∀ `t½` ∈ (0.0, 100.0] ⊂ ℝ ∪ {∅}, f(`t½`) ≥ 0

A symbol that isn't a valid identifier arrives backtick-wrapped, and the rendered text still parses back to an equivalent claim.

Resolution order

1. The project's own .mathema/symbology.yaml, if one exists.
2. Compositional shapes: delta_<rest> and delta<Rest> resolve <rest> on its own and prefix Δ, and pct_change_<rest> does the same with %Δ.
3. The built-in table of standard notation.
4. A <base>_<digits> name falls back to the spelling without the underscore, so alpha_1 and alpha1 resolve identically.

A name none of these recognise renders unchanged.

Configuration

.mathema/symbology.yaml takes four keys, all optional: params and funcs map names to symbols, show_missing controls whether an unbounded domain prints whether missing values are included or excluded, and enabled: false switches the package off for the project. A symbol that isn't a valid Python identifier goes inside of backticks (handled in mathema). The file is found from the working directory, under the nearest .mathema/ within the enclosing repository, so a command run from a subdirectory reads the project's own file.

params:
  headcount: N
  runway: "`T_run`"
funcs:
  payback: PB

Setting MATHEMA_SYMBOLOGY_DISABLE=1 in the environment switches it off for one run, whatever the file says.

Adding a symbol

Open a pull request against the table in src/mathema_symbology/_default_mapping.py. An entry has to be real, standard notation in some field, worth making the default for parameter names that match. The missing-symbol issue template asks for the details that justify including it.

For symbols that don't generalise beyond your codebase, use Configuration instead.

Requirements

Python 3.10 or later. The only runtime dependency is pyyaml; mathema itself is not strictly required, only discovered when present.

Licence

Apache-2.0, see LICENSE.

Version

The interface may change before 1.0; the installed version is mathema_symbology.__version__.