nomogram 0.1.0__py3-none-any.whl

nomogram/data/semantics.json

@@ -0,0 +1,464 @@
+{
+  "cf_standard_names": {
+    "air_temperature": {
+      "canonical_units": "K",
+      "pint": "K"
+    },
+    "humidity_mixing_ratio": {
+      "canonical_units": "1",
+      "pint": "dimensionless"
+    },
+    "mass_concentration_of_water_vapor_in_air": {
+      "canonical_units": "kg m-3",
+      "pint": "kg * m ** -3"
+    },
+    "relative_humidity": {
+      "canonical_units": "1",
+      "pint": "dimensionless"
+    },
+    "specific_humidity": {
+      "canonical_units": "1",
+      "pint": "dimensionless"
+    },
+    "water_vapor_partial_pressure_in_air": {
+      "canonical_units": "Pa",
+      "pint": "Pa"
+    }
+  },
+  "quantity_kinds": {
+    "AbsoluteHumidity": {
+      "added_units": [],
+      "applicable_units": [
+        "GM-PER-M3",
+        "KiloGM-PER-M3"
+      ],
+      "cf_standard_names": [],
+      "delta": false,
+      "dimension_vector": "A0E0L-3I0M1H0T0D0",
+      "iri": "http://qudt.org/vocab/quantitykind/AbsoluteHumidity",
+      "label": "Absolute Humidity",
+      "matches": [],
+      "scale_type": "ratio",
+      "specialization_of": "Density"
+    },
+    "CelsiusTemperature": {
+      "added_units": [],
+      "applicable_units": [
+        "DEG_C",
+        "DEG_F"
+      ],
+      "cf_standard_names": [],
+      "delta": false,
+      "dimension_vector": "A0E0L0I0M0H1T0D0",
+      "iri": "http://qudt.org/vocab/quantitykind/CelsiusTemperature",
+      "label": "Celsius Temperature",
+      "matches": [
+        {
+          "relation": "close",
+          "target": "http://www.wikidata.org/entity/Q74758530",
+          "verified": "2026-10-14"
+        }
+      ],
+      "scale_type": "interval",
+      "specialization_of": "Temperature"
+    },
+    "MassConcentrationOfWaterVapour": {
+      "added_units": [],
+      "applicable_units": [
+        "GM-PER-M3",
+        "KiloGM-PER-M3"
+      ],
+      "cf_standard_names": [
+        "mass_concentration_of_water_vapor_in_air"
+      ],
+      "delta": false,
+      "dimension_vector": "A0E0L-3I0M1H0T0D0",
+      "iri": "http://qudt.org/vocab/quantitykind/MassConcentrationOfWaterVapour",
+      "label": "Mass Concentration of Water Vapour",
+      "matches": [
+        {
+          "relation": "close",
+          "target": "http://www.wikidata.org/entity/Q76378808",
+          "verified": "2026-10-14"
+        }
+      ],
+      "scale_type": "ratio",
+      "specialization_of": "MassConcentration"
+    },
+    "MassRatioOfWaterVapourToDryGas": {
+      "added_units": [
+        "GM-PER-KiloGM",
+        "KiloGM-PER-KiloGM"
+      ],
+      "applicable_units": [
+        "GM-PER-KiloGM",
+        "KiloGM-PER-KiloGM",
+        "UNITLESS"
+      ],
+      "cf_standard_names": [
+        "humidity_mixing_ratio"
+      ],
+      "delta": false,
+      "dimension_vector": "A0E0L0I0M0H0T0D1",
+      "iri": "http://qudt.org/vocab/quantitykind/MassRatioOfWaterVapourToDryGas",
+      "label": "Mass Ratio of Water Vapour to Dry Gas",
+      "matches": [
+        {
+          "relation": "close",
+          "target": "http://www.wikidata.org/entity/Q17232415",
+          "verified": "2026-10-14"
+        }
+      ],
+      "scale_type": "ratio",
+      "specialization_of": null
+    },
+    "RelativeHumidity": {
+      "added_units": [
+        "UNITLESS"
+      ],
+      "applicable_units": [
+        "PERCENT",
+        "UNITLESS"
+      ],
+      "cf_standard_names": [
+        "relative_humidity"
+      ],
+      "delta": false,
+      "dimension_vector": "A0E0L0I0M0H0T0D1",
+      "iri": "http://qudt.org/vocab/quantitykind/RelativeHumidity",
+      "label": "Relative Humidity",
+      "matches": [
+        {
+          "relation": "close",
+          "target": "http://www.wikidata.org/entity/Q2499617",
+          "verified": "2026-10-14"
+        }
+      ],
+      "scale_type": "ratio",
+      "specialization_of": "RelativePartialPressure"
+    },
+    "SpecificHumidity": {
+      "added_units": [
+        "UNITLESS"
+      ],
+      "applicable_units": [
+        "GM-PER-KiloGM",
+        "KiloGM-PER-KiloGM",
+        "UNITLESS"
+      ],
+      "cf_standard_names": [
+        "specific_humidity"
+      ],
+      "delta": false,
+      "dimension_vector": "A0E0L0I0M0H0T0D1",
+      "iri": "http://qudt.org/vocab/quantitykind/SpecificHumidity",
+      "label": "Specific Humidity",
+      "matches": [],
+      "scale_type": "ratio",
+      "specialization_of": "MassRatio"
+    },
+    "TemperatureDifference": {
+      "added_units": [],
+      "applicable_units": [
+        "K"
+      ],
+      "cf_standard_names": [],
+      "delta": true,
+      "dimension_vector": "A0E0L0I0M0H1T0D0",
+      "iri": "http://qudt.org/vocab/quantitykind/TemperatureDifference",
+      "label": "Temperature Difference",
+      "matches": [],
+      "scale_type": "ratio",
+      "specialization_of": "Temperature"
+    },
+    "ThermodynamicTemperature": {
+      "added_units": [],
+      "applicable_units": [
+        "K"
+      ],
+      "cf_standard_names": [
+        "air_temperature"
+      ],
+      "delta": false,
+      "dimension_vector": "A0E0L0I0M0H1T0D0",
+      "iri": "http://qudt.org/vocab/quantitykind/ThermodynamicTemperature",
+      "label": "Thermodynamic Temperature",
+      "matches": [
+        {
+          "relation": "close",
+          "target": "http://www.wikidata.org/entity/Q264647",
+          "verified": "2026-10-14"
+        }
+      ],
+      "scale_type": "ratio",
+      "specialization_of": "Temperature"
+    },
+    "VapourPressure": {
+      "added_units": [],
+      "applicable_units": [
+        "HectoPA",
+        "KiloPA",
+        "PA"
+      ],
+      "cf_standard_names": [
+        "water_vapor_partial_pressure_in_air"
+      ],
+      "delta": false,
+      "dimension_vector": "A0E0L-1I0M1H0T-2D0",
+      "iri": "http://qudt.org/vocab/quantitykind/VapourPressure",
+      "label": "Vapour Pressure",
+      "matches": [],
+      "scale_type": "ratio",
+      "specialization_of": "Pressure"
+    }
+  },
+  "sources": {
+    "cf_standard_names": {
+      "attribution": "CF Conventions, https://cfconventions.org/",
+      "license": "CC0-1.0",
+      "version": "95"
+    },
+    "extracted": "2026-10-14",
+    "qudt": {
+      "attribution": "QUDT.org, https://qudt.org/",
+      "license": "CC-BY-4.0",
+      "version": "3.5.2"
+    }
+  },
+  "units": {
+    "DEG_C": {
+      "dimension_vector": "A0E0L0I0M0H1T0D0",
+      "iri": "http://qudt.org/vocab/unit/DEG_C",
+      "label": "Degree Celsius",
+      "matches": [
+        {
+          "relation": "close",
+          "target": "http://www.wikidata.org/entity/Q25267",
+          "verified": "2026-10-14"
+        }
+      ],
+      "multiplier": 1.0,
+      "offset": 273.15,
+      "pint": "degC",
+      "symbol": "\u00b0C",
+      "ucum": "Cel",
+      "udunits": "\u00b0C"
+    },
+    "DEG_F": {
+      "dimension_vector": "A0E0L0I0M0H1T0D0",
+      "iri": "http://qudt.org/vocab/unit/DEG_F",
+      "label": "Degree Fahrenheit",
+      "matches": [
+        {
+          "relation": "close",
+          "target": "http://www.wikidata.org/entity/Q42289",
+          "verified": "2026-10-14"
+        }
+      ],
+      "multiplier": 0.5555555555555556,
+      "offset": 459.67,
+      "pint": "degF",
+      "symbol": "\u00b0F",
+      "ucum": "[degF]",
+      "udunits": "\u00b0F"
+    },
+    "GM-PER-KiloGM": {
+      "dimension_vector": "A0E0L0I0M0H0T0D1",
+      "iri": "http://qudt.org/vocab/unit/GM-PER-KiloGM",
+      "label": "Gram per Kilogram",
+      "matches": [
+        {
+          "relation": "close",
+          "target": "http://www.wikidata.org/entity/Q21061369",
+          "verified": "2026-10-14"
+        }
+      ],
+      "multiplier": 0.001,
+      "offset": 0.0,
+      "pint": "g/kg",
+      "symbol": "g/kg",
+      "ucum": "g.kg-1",
+      "udunits": null
+    },
+    "GM-PER-M3": {
+      "dimension_vector": "A0E0L-3I0M1H0T0D0",
+      "iri": "http://qudt.org/vocab/unit/GM-PER-M3",
+      "label": "Gram per Cubic Metre",
+      "matches": [
+        {
+          "relation": "close",
+          "target": "http://www.wikidata.org/entity/Q21604951",
+          "verified": "2026-10-14"
+        }
+      ],
+      "multiplier": 0.001,
+      "offset": 0.0,
+      "pint": "g/m^3",
+      "symbol": "g/m\u00b3",
+      "ucum": "g.m-3",
+      "udunits": null
+    },
+    "HectoPA": {
+      "dimension_vector": "A0E0L-1I0M1H0T-2D0",
+      "iri": "http://qudt.org/vocab/unit/HectoPA",
+      "label": "Hectopascal",
+      "matches": [
+        {
+          "relation": "close",
+          "target": "http://www.wikidata.org/entity/Q5139563",
+          "verified": "2026-10-14"
+        }
+      ],
+      "multiplier": 100.0,
+      "offset": 0.0,
+      "pint": "hPa",
+      "symbol": "hPa",
+      "ucum": "hPa",
+      "udunits": null
+    },
+    "J-PER-KiloGM-K": {
+      "dimension_vector": "A0E0L2I0M0H-1T-2D0",
+      "iri": "http://qudt.org/vocab/unit/J-PER-KiloGM-K",
+      "label": "Joule per Kilogram Kelvin",
+      "matches": [
+        {
+          "relation": "close",
+          "target": "http://www.wikidata.org/entity/Q3085309",
+          "verified": "2026-10-14"
+        }
+      ],
+      "multiplier": 1.0,
+      "offset": 0.0,
+      "pint": "J/(kg*K)",
+      "symbol": "J/(kg\u00b7K)",
+      "ucum": "J.kg-1.K-1",
+      "udunits": null
+    },
+    "K": {
+      "dimension_vector": "A0E0L0I0M0H1T0D0",
+      "iri": "http://qudt.org/vocab/unit/K",
+      "label": "Kelvin",
+      "matches": [
+        {
+          "relation": "close",
+          "target": "http://www.wikidata.org/entity/Q11579",
+          "verified": "2026-10-14"
+        }
+      ],
+      "multiplier": 1.0,
+      "offset": 0.0,
+      "pint": "K",
+      "symbol": "K",
+      "ucum": "K",
+      "udunits": "K"
+    },
+    "KiloGM-PER-KiloGM": {
+      "dimension_vector": "A0E0L0I0M0H0T0D1",
+      "iri": "http://qudt.org/vocab/unit/KiloGM-PER-KiloGM",
+      "label": "Kilogram per Kilogram",
+      "matches": [
+        {
+          "relation": "close",
+          "target": "http://www.wikidata.org/entity/Q106645216",
+          "verified": "2026-10-14"
+        }
+      ],
+      "multiplier": 1.0,
+      "offset": 0.0,
+      "pint": "kg/kg",
+      "symbol": "kg/kg",
+      "ucum": "kg.kg-1",
+      "udunits": null
+    },
+    "KiloGM-PER-M3": {
+      "dimension_vector": "A0E0L-3I0M1H0T0D0",
+      "iri": "http://qudt.org/vocab/unit/KiloGM-PER-M3",
+      "label": "Kilogram per Cubic Metre",
+      "matches": [
+        {
+          "relation": "close",
+          "target": "http://www.wikidata.org/entity/Q844211",
+          "verified": "2026-10-14"
+        }
+      ],
+      "multiplier": 1.0,
+      "offset": 0.0,
+      "pint": "kg/m^3",
+      "symbol": "kg/m\u00b3",
+      "ucum": "kg.m-3",
+      "udunits": null
+    },
+    "KiloPA": {
+      "dimension_vector": "A0E0L-1I0M1H0T-2D0",
+      "iri": "http://qudt.org/vocab/unit/KiloPA",
+      "label": "Kilopascal",
+      "matches": [
+        {
+          "relation": "close",
+          "target": "http://www.wikidata.org/entity/Q21064807",
+          "verified": "2026-10-14"
+        }
+      ],
+      "multiplier": 1000.0,
+      "offset": 0.0,
+      "pint": "kPa",
+      "symbol": "kPa",
+      "ucum": "kPa",
+      "udunits": null
+    },
+    "PA": {
+      "dimension_vector": "A0E0L-1I0M1H0T-2D0",
+      "iri": "http://qudt.org/vocab/unit/PA",
+      "label": "Pascal",
+      "matches": [
+        {
+          "relation": "close",
+          "target": "http://www.wikidata.org/entity/Q44395",
+          "verified": "2026-10-14"
+        }
+      ],
+      "multiplier": 1.0,
+      "offset": 0.0,
+      "pint": "Pa",
+      "symbol": "Pa",
+      "ucum": "Pa",
+      "udunits": "Pa"
+    },
+    "PERCENT": {
+      "dimension_vector": "A0E0L0I0M0H0T0D1",
+      "iri": "http://qudt.org/vocab/unit/PERCENT",
+      "label": "Percent",
+      "matches": [
+        {
+          "relation": "close",
+          "target": "http://www.wikidata.org/entity/Q11229",
+          "verified": "2026-10-14"
+        }
+      ],
+      "multiplier": 0.01,
+      "offset": 0.0,
+      "pint": "percent",
+      "symbol": "%",
+      "ucum": "%",
+      "udunits": "%"
+    },
+    "UNITLESS": {
+      "dimension_vector": "A0E0L0I0M0H0T0D1",
+      "iri": "http://qudt.org/vocab/unit/UNITLESS",
+      "label": "Unitless",
+      "matches": [
+        {
+          "relation": "close",
+          "target": "http://www.wikidata.org/entity/Q199",
+          "verified": "2026-10-14"
+        }
+      ],
+      "multiplier": 1.0,
+      "offset": 0.0,
+      "pint": "dimensionless",
+      "symbol": "\u4e00",
+      "ucum": null,
+      "udunits": null
+    }
+  }
+}

nomogram/expression.py

@@ -0,0 +1,232 @@
+# SPDX-FileCopyrightText: 2026 Miki
+# SPDX-License-Identifier: BSD-3-Clause
+
+"""Formula expressions: safe parsing, LaTeX rendering and numeric evaluation.
+
+A formula's mathematical content is written once, in a restricted Python
+syntax such as ``C * exp(A * t / (B + t))``. That text is the single
+source of truth: it is parsed with :mod:`ast` against a whitelist and
+turned directly into a SymPy expression, without ever calling
+:func:`eval` (``sympy.parse_expr`` relies on ``eval`` and is not meant for
+untrusted input). Everything else derives from the SymPy expression:
+
+- LaTeX, rendered in any author's notation;
+- numeric evaluation, vectorised with numpy through ``lambdify``;
+- symbolic computation.
+
+Names in an expression are semantic *identifiers* (``t``, ``RH``,
+``e_s``...), each becoming a SymPy symbol of that name. They are never
+glyphs: the symbol a reader sees (QUDT's ``symbol``/``latexSymbol``)
+belongs to a notation. See ``docs/rosetta.md`` for the vocabulary.
+"""
+
+from __future__ import annotations
+
+import ast
+from collections.abc import Callable, Iterable, Mapping
+from functools import lru_cache
+from typing import Any
+
+import sympy
+from sympy.codegen.cfunctions import log10
+from sympy.printing.latex import LatexPrinter
+
+__all__ = [
+    "FUNCTIONS",
+    "MAX_SOURCE_LENGTH",
+    "ExpressionError",
+    "compile_numeric",
+    "parse_expression",
+    "to_latex",
+]
+
+#: Functions allowed in a formula, by the name used in the source text.
+FUNCTIONS: Mapping[str, Callable[[Any], Any]] = {
+    "exp": sympy.exp,
+    "ln": sympy.log,
+    "log10": log10,
+    "sqrt": sympy.sqrt,
+}
+
+#: Longest accepted source text, to bound parsing work.
+MAX_SOURCE_LENGTH = 2000
+
+_BINARY_OPERATORS: Mapping[type[ast.operator], Callable[[Any, Any], Any]] = {
+    ast.Add: lambda a, b: a + b,
+    ast.Sub: lambda a, b: a - b,
+    ast.Mult: lambda a, b: a * b,
+    ast.Div: lambda a, b: a / b,
+    ast.Pow: lambda a, b: a**b,
+}
+
+_UNARY_OPERATORS: Mapping[type[ast.unaryop], Callable[[Any], Any]] = {
+    ast.USub: lambda a: -a,
+    ast.UAdd: lambda a: a,
+}
+
+
+class ExpressionError(ValueError):
+    """The source text is not a valid formula expression."""
+
+
+def parse_expression(source: str, names: Iterable[str]) -> Any:
+    """Parse a formula written in restricted Python syntax into a SymPy expression.
+
+    Allowed: numbers, the declared names, ``+ - * / **``, unary ``-`` and
+    ``+``, parentheses, and calls to the functions of :data:`FUNCTIONS`
+    with exactly one positional argument. Everything else (attributes,
+    subscripts, keywords, lambdas, comparisons, strings, other calls,
+    undeclared names) is rejected. Nothing is evaluated.
+
+    Parameters
+    ----------
+    source : str
+        The expression, for example ``"C * exp(A * t / (B + t))"``.
+    names : iterable of str
+        The identifiers the expression may use (variables, coefficients
+        and constants). Each becomes a real SymPy symbol with that name.
+
+    Returns
+    -------
+    sympy.Expr
+        The parsed expression.
+
+    Raises
+    ------
+    ExpressionError
+        If the text is too long, is not valid Python syntax, or uses
+        anything outside the whitelist.
+    """
+    if len(source) > MAX_SOURCE_LENGTH:
+        msg = f"expression longer than {MAX_SOURCE_LENGTH} characters"
+        raise ExpressionError(msg)
+    allowed = frozenset(names)
+    for name in allowed:
+        if not name.isidentifier() or name in FUNCTIONS:
+            msg = f"invalid or reserved name: {name!r}"
+            raise ExpressionError(msg)
+    try:
+        tree = ast.parse(source.strip(), mode="eval")
+    except SyntaxError as exc:
+        msg = f"invalid syntax: {exc.msg}"
+        raise ExpressionError(msg) from None
+    symbols = {name: sympy.Symbol(name, real=True) for name in allowed}
+    return _build(tree.body, symbols)
+
+
+def _build(node: ast.AST, symbols: Mapping[str, Any]) -> Any:
+    if isinstance(node, ast.BinOp) and type(node.op) in _BINARY_OPERATORS:
+        left, right = _build(node.left, symbols), _build(node.right, symbols)
+        return _BINARY_OPERATORS[type(node.op)](left, right)
+    if isinstance(node, ast.UnaryOp) and type(node.op) in _UNARY_OPERATORS:
+        return _UNARY_OPERATORS[type(node.op)](_build(node.operand, symbols))
+    if isinstance(node, ast.Constant):
+        value = node.value
+        # bool is a subclass of int: refuse it explicitly.
+        if isinstance(value, bool) or not isinstance(value, int | float):
+            msg = f"unsupported constant: {value!r}"
+            raise ExpressionError(msg)
+        return (
+            sympy.Integer(value) if isinstance(value, int) else sympy.Float(repr(value))
+        )
+    if isinstance(node, ast.Name):
+        if node.id not in symbols:
+            msg = f"undeclared name: {node.id!r}"
+            raise ExpressionError(msg)
+        return symbols[node.id]
+    if isinstance(node, ast.Call):
+        if not isinstance(node.func, ast.Name) or node.func.id not in FUNCTIONS:
+            msg = "only calls to " + ", ".join(sorted(FUNCTIONS)) + " are allowed"
+            raise ExpressionError(msg)
+        if node.keywords or len(node.args) != 1:
+            msg = f"{node.func.id}() takes exactly one positional argument"
+            raise ExpressionError(msg)
+        return FUNCTIONS[node.func.id](_build(node.args[0], symbols))
+    msg = f"unsupported syntax: {type(node).__name__}"
+    raise ExpressionError(msg)
+
+
+class _NotationPrinter(LatexPrinter):  # type: ignore[misc]
+    """LaTeX printer for formulas.
+
+    The exponential is written ``\\exp\\left(...\\right)`` rather than
+    ``e^{...}``: in meteorology ``e`` denotes the vapour pressure. The
+    decimal logarithm is written ``\\log_{10}``, as in the sources.
+    """
+
+    def _print_ExpBase(self, expr: Any, exp: Any = None) -> str:
+        tex = r"\exp\left(" + self._print(expr.args[0]) + r"\right)"
+        return f"{tex}^{{{exp}}}" if exp is not None else tex
+
+    def _print_log10(self, expr: Any, exp: Any = None) -> str:
+        tex = r"\log_{10}\left(" + self._print(expr.args[0]) + r"\right)"
+        return f"{tex}^{{{exp}}}" if exp is not None else tex
+
+
+def to_latex(expr: Any, notation: Mapping[str, str] | None = None) -> str:
+    """Render an expression in LaTeX, in a given notation.
+
+    The output stays within what both matplotlib's mathtext and MathJax
+    render (``\\frac``, ``\\exp``, ``\\ln``, ``\\left``/``\\right``, braced
+    subscripts), so that one string serves documentation and plot labels.
+
+    Parameters
+    ----------
+    expr : sympy.Expr
+        An expression returned by :func:`parse_expression`.
+    notation : mapping of str to str, optional
+        LaTeX symbol for each identifier, for example
+        ``{"e_s": r"E_{\\mathrm{w}}"}``. Identifiers not listed keep
+        SymPy's default rendering.
+
+    Returns
+    -------
+    str
+        The LaTeX code, without surrounding dollar signs.
+    """
+    names = {}
+    for symbol in expr.free_symbols:
+        if notation and symbol.name in notation:
+            names[symbol] = notation[symbol.name]
+    printer = _NotationPrinter({"symbol_names": names, "ln_notation": True})
+    return str(printer.doprint(expr))
+
+
+def compile_numeric(expr: Any, arguments: tuple[str, ...]) -> Callable[..., Any]:
+    """Compile an expression into a numeric function, vectorised with numpy.
+
+    The compiled function is cached: compiling a SymPy expression is costly
+    and deterministic.
+
+    Parameters
+    ----------
+    expr : sympy.Expr
+        An expression returned by :func:`parse_expression`.
+    arguments : tuple of str
+        Identifiers of the function's positional arguments, in order.
+        Every identifier used by the expression must be listed.
+
+    Returns
+    -------
+    callable
+        A function of the given arguments, accepting numbers or numpy
+        arrays (broadcast together).
+
+    Raises
+    ------
+    ExpressionError
+        If an identifier used by the expression is not among the
+        arguments.
+    """
+    missing = sorted(s.name for s in expr.free_symbols if s.name not in arguments)
+    if missing:
+        msg = "missing arguments: " + ", ".join(missing)
+        raise ExpressionError(msg)
+    return _lambdify(expr, arguments)
+
+
+@lru_cache(maxsize=256)
+def _lambdify(expr: Any, arguments: tuple[str, ...]) -> Callable[..., Any]:
+    symbols = [sympy.Symbol(name, real=True) for name in arguments]
+    function: Callable[..., Any] = sympy.lambdify(symbols, expr, modules="numpy")
+    return function