Metadata-Version: 2.5
Name: mathema-symbology
Version: 0.3.0
Summary: Standard notation for mathema's claim rendering: the symbols used in physics, chemistry, statistics, machine learning and finance, overridable per project.
Project-URL: Homepage, https://github.com/aaronbyrnephd/mathema-symbology
Project-URL: Source, https://github.com/aaronbyrnephd/mathema-symbology
Project-URL: Documentation, https://mathema.tetrionlabs.com/symbology/
Project-URL: Issues, https://github.com/aaronbyrnephd/mathema-symbology/issues
Author-email: Aaron Byrne <contact@aaronbyrnephd.com>
License-Expression: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Keywords: claim-driven-development,mathema,mathematical-notation,notation,symbology,symbols,unicode
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: pyyaml>=6.0
Provides-Extra: test
Requires-Dist: mathema>=0.6; extra == 'test'
Requires-Dist: pytest>=8; extra == 'test'
Description-Content-Type: text/markdown

# mathema-symbology

Symbol lookups for mathema claim rendering.

[![tests](https://github.com/aaronbyrnephd/mathema-symbology/actions/workflows/tests.yml/badge.svg)](https://github.com/aaronbyrnephd/mathema-symbology/actions/workflows/tests.yml)
[![PyPI](https://img.shields.io/pypi/v/mathema-symbology)](https://pypi.org/project/mathema-symbology/)

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.

```yaml
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`](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](#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](LICENSE).

## Version

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