API reference

The public surface is small: two functions and one result object. Both functions are also available as methods on any SymPy expression or equation, so you can build a formula symbolically and evaluate it in place.

sym_evalf

sym_evalf(
    expr,
    subs=None,
    output_unit=None,
    *,
    n_display=4,
    mode="multi_line",
    output_symbol=None,
    **evalf_kwargs,
) -> SymbolicEvaluation

Numerically evaluates a formula with unit-aware Pint quantities and renders it as LaTeX: the symbolic form, the substituted form, and the result.

Call it as a function, or as a method on a SymPy expression or equation:

from symeval import sym_evalf

sym_evalf(equation, values, output_unit="MPa")
equation.sym_evalf(values, output_unit="MPa")   # equivalent
Parameter Type Description
expr sympy.Expr \| sympy.Eq The formula to evaluate. A sympy.Eq is solved for its single unknown (the free symbol not present in subs), and its output symbol is inferred.
subs dict[Symbol, pint.Quantity] Maps each symbol to a Pint quantity (a plain number is accepted and treated as dimensionless). Same shape as SymPy’s evalf subs, and positional like it too.
output_unit str \| pint.Unit \| None Target unit for the result. When None, the result is rendered in SI base units.
n_display int Significant figures for the result; substituted inputs show one more figure, with trailing zeros trimmed. Defaults to 4. Display only: it never changes the computed quantity. When n < n_display, a warning is raised because the extra displayed digits would be meaningless.
mode "multi_line" \| "verbose" \| "one_line" Rendering style, see below.
output_symbol str \| sympy.Symbol \| None LaTeX label for the result, for example r"\sigma". Required for a bare expression; for an equation it defaults to the inferred unknown and an explicit value overrides only the label.
**evalf_kwargs Forwarded to expr.evalf(...), for example n (significant digits of numeric precision, 15 by default), chop, strict.

Returns a SymbolicEvaluation.

Rendering modes

mode="multi_line" (the default) renders three lines: the symbolic form, the substituted form, then the result.

\begin{aligned} \sigma &= \frac{F}{A} \\ &= \frac{\,-680\ \mathrm{kN}}{\,10580\ \mathrm{mm}^{2}} \\ \sigma &= -64.27\times 10^{6}\ \mathrm{Pa} = -64.27\ \mathrm{MPa} \end{aligned}

mode="verbose" adds a fourth line showing every value converted to coherent SI units (kN to N, mm to m, km/h to m/s) in engineering notation (exponents a multiple of 3), useful when you want to audit the unit conversions. The result line carries the same conversion as its left half.

\begin{aligned} \sigma &= \frac{F}{A} \\ &= \frac{\,-680\ \mathrm{kN}}{\,10580\ \mathrm{mm}^{2}} \\ &= \frac{\,-680.00\times 10^{3}\ \mathrm{N}}{\,0.010580\ \mathrm{m}^{2}} \\ \sigma &= -64.27\times 10^{6}\ \mathrm{Pa} = -64.27\ \mathrm{MPa} \end{aligned}

mode="one_line" collapses it onto a single line.

\sigma = \frac{F}{A} = \frac{\,-680\ \mathrm{kN}}{\,10580\ \mathrm{mm}^{2}} = -64.27\ \mathrm{MPa}

quantity_evalf

quantity_evalf(
    expr,
    subs=None,
    output_unit=None,
    **evalf_kwargs,
) -> pint.Quantity

The numeric-only sibling of sym_evalf: the same unit-aware evaluation without the LaTeX rendering. Returns a bare pint.Quantity, which makes it well suited to computing a new column across every row of a DataFrame.

quantity_evalf takes an expression, not an equation: it has no output symbol to infer. Pass a sympy.Eq to sym_evalf, or evaluate the equation’s right-hand side (equation.rhs).

Parameter Type Description
expr sympy.Expr The expression to evaluate.
subs dict[Symbol, pint.Quantity] Maps each symbol to a Pint quantity (a plain number is accepted and treated as dimensionless).
output_unit str \| pint.Unit \| None Target unit for the result. When None, the result is in SI base units.
**evalf_kwargs Forwarded to expr.evalf(...).

Returns a pint.Quantity in output_unit if given, otherwise in SI base units.

SymbolicEvaluation

The symbolic evaluation returned by sym_evalf. It renders as LaTeX in marimo and Jupyter through _repr_latex_, and exposes three attributes for chaining one symbolic evaluation into the next:

Attribute Type Description
.quantity pint.Quantity The result quantity with its unit.
.latex str The LaTeX rendering.
.symbol sympy.Symbol The output symbol, ready to reference in a later formula.

Because .symbol and .quantity are plain SymPy and Pint objects, chaining reads as a straight sequence: each result becomes a symbol and a value in the subs of the next symbolic evaluation. See the tutorial for a worked chain.

The registry

SymEval bundles no UnitRegistry. It reads the registry off the Pint quantities you pass in (quantity._REGISTRY), so results land in your registry. When subs is empty, it falls back to pint.get_application_registry(). Create your quantities with pint.Quantity (or your own UnitRegistry) and SymEval follows along.

Back to top