Keecas: Python package for symbolic math with units in Jupyter/Quarto notebooks

[kompre]

Description

I'd like to share Keecas, a Python package I built for symbolic and units-aware calculations in Jupyter notebooks, specifically designed to work in a Quarto environment.

Background

As a structural engineer writing calculation reports, I wanted executable notebooks that generate publication-quality PDFs with proper equation numbering and cross-references. Quarto solved the document rendering problem beautifully, but I still had too much boilerplate in the Python code itself. Keecas eliminates that.

What It Does

Keecas provides a thin layer over SymPy + Pint that uses dicts as equation containers. Keys represent left-hand side symbols, values represent right-hand side expressions. This maps naturally to how equations are written and reduces repetitive code.

Key features for Quarto users:

• Automatic amsmath LaTeX generation with \label{} for equation numbering
• Cross-references work out of the box with \eqref{} and \ref{}
• Unit-aware calculations with automatic conversion
• Dict comprehensions for clean, readable calculation patterns
• Multi-language support (localized units and terms)

Example

A typical Python cell would look like this:

from keecas import symbols, u, pc, show_eqn, generate_unique_label

# Define symbols with LaTeX notation
F_d, A_load, sigma = symbols(r"F_{d}, A_{load}, \sigma")

# Parameters with units
_p = {
    F_d: 10 * u.kN,
    A_load: 50 * u.cm**2,
}

# Expressions
_e = {
    sigma: "F_d / A_load" | pc.parse_expr
}

# Evaluate
_v = {
    k: v | pc.subs(_e | _p) | pc.convert_to([u.MPa]) | pc.N
    for k, v in _e.items()
}

# Description
_d = {
    F_d: "design force",
    A_load: "loaded area",
    sigma: "normal stress",
}

# Generate labels for Quarto cross-referencing
_l = generate_unique_label(_d)

# Display
show_eqn(
    [_p | _e, _v, _d],
    label=_l
)

show_eqn returns an IPython.display.Latex object, that will be rendered by the Jupyter engine.

Generated LaTeX:

\begin{align}
    F_{d} & = 10{\,}\text{kN} &   & \quad\text{design force}  \label{eq-1kv2lsa6}  \\[8pt]
    A_{load} & = 50{\,}\text{cm}^{2} &   & \quad\text{loaded area}  \label{eq-1qnugots}  \\[8pt]
    \sigma & = \dfrac{F_{d}}{A_{load}} & = 2.0{\,}\text{MPa} & \quad\text{normal stress}  \label{eq-27myzkyp}
\end{align}

Since show_eqn returns a Latex object, the command \label{} must be used, and therefore to reference equations \eqref{} or \ref{} must be used as well. I couldn't find a workaround to use @eq- syntax, but at least a user can copy-paste the interpolated labels, or use an inline helper function:

The normal stress in equation `{python} Markdown(fr'\eqref{{{_l[sigma]}}}')`
is calculated from the design force in `{python} Markdown(fr'\eqref{{{_l[F_d]}}}')`...

Quarto Workflow

As a personal preference I develop calculation reports as ipynb for the vertical input-cell/output layout. Since VS Code's KaTeX doesn't support \label{}, I use Quarto's #| eval: false to set config options that will run only during the development phase, but not during rendering with quarto render.

• During development: set config options fro printing labels, debugging LaTeX, KaTeX compatibility, etc. in #| eval: false cells
• During rendering: the cell will not be evaluated, thus those options will not be set, and the document can be rendered for publishing

This approach require either to pass --execute flag to quarto render, or to convert ipynb to qmd before final render. (I prefer the latter approach, and convert the ipynb with a pre-render step in _quarto.yml.)

Try It

If you have uv installed, try a quick session:

uvx keecas edit --temp --template quickstart

A jupyterlab session will open a temporary file using the quickstart template.

Use Cases

• Engineering calculation reports (structural, mechanical, etc.)
• Scientific papers with unit-aware calculations
• Academic documentation requiring reproducible math
• Technical reports mixing narrative and calculations

Examples

• hello_world.ipynb
• Full Quarto example with ipynb source and rendered documents

Links

• Documentation: https://kompre.github.io/keecas/
• Source: https://github.com/kompre/keecas
• PyPI: https://pypi.org/project/keecas/

Feedback Welcome

I've been using this professionally for over a year in structural engineering, but would love feedback from the broader Quarto community. Questions, suggestions, and contributions are all welcome!

[jimjam-slam]

This is really cool! I feel like this kind of expressive DSL stuff is very common in R because of its Non-Standard Evaluation, but much less common in Python. Love to see it!