Coming from handcalcs v1#

handcalcs v2 is a rewrite. The parser now builds a tree of nodes, and separate renderers turn that tree into Markdown, LaTeX, HTML, plain text or Excel. Most notebooks need only a few changes.

Quick reference#

v1

v2

import handcalcs.render

import handcalcs

%%render

%%render (now shows Markdown with LaTeX math by default)

%%tex

%hc_default_renderer latex, then %%render; or HandCalcs(LatexRenderer())

%%render 2 (precision)

# hc: -f .2f (any format code)

%%render params

; parameter grids, or # hc: -h; # hc: -p for one line

%%render long

# hc: -m

%%render short

the default (or # hc: multiline = False)

%%render symbolic

# hc: mode = "ass sym" (see mode)

%%render sympy

not available in 2.0

from handcalcs.decorator import handcalc

from handcalcs import handcalc

@handcalc(override=..., precision=..., ...)

@handcalc(renderer, render_context={...}) (see the decorator)

handcalcs.set_option("display_precision", 3)

handcalcs.set_option("format_code", ".3f")

latex_block_start, line_break, math_environment_start, … options

renderer class attributes (see LaTeX and Markdown tokens)

custom_symbols option

the symbols option with renderer-neutral specs (see display symbols), or a renderer rule for raw markup

greek_exclusions, underscore_subscripts options

the greek_prefixes/subscripts settings, or a renderer subclass (see Customizing)

What’s new#

  • Renderers. Choose the output format, restyle it, or write your own.

  • A Python interface. HandCalcs(renderer)(source) renders a string or a .py file outside Jupyter (see the object-oriented interface).

  • Comment commands. # hc: commands work per line or per section, instead of one override per cell.

  • Headings and prose. ## comments become headings and comment lines become paragraphs, so a single cell can hold a whole documented calculation.

  • Jinja in comments. {{ name }} inserts a value into a comment.

  • Nested conditionals and for loops.

  • Excel output with live formulas (see the Excel renderer).

  • Better names. Comma subscripts (N_pl_Rd → Npl,Rd), Greek letters joined to other letters (DeltaH → ΔH), accents (V_dot → V̇) and display specs (the symbols option). See naming variables.

  • Long equations break where the source line continues with \, and a bare expression line shows its result (see writing calculations).

  • %render, a line magic that runs and renders one line (see Jupyter).

  • Checks and page breaks. # hc: --check marks a comparison ✓ or ✗, and # hc: --pagebreak starts a new page in exported output (see the cookbook).

  • More Python. Conditional expressions (a if test else b), methods on expressions ((a * b).to("mm")), cbrt, factorial and infinity.

  • Text output for terminals and logs from ASCIIRenderer (ascii), with underlined headings and = signs lined up (see the ASCII renderer). If you tried a 2.0 pre-release, this is the renderer that was called PlainTextRenderer (plain_text).

  • Word output with native equations (see the Word renderer).

  • Many input sets. Render one script for a table of inputs with HandCalcs(...)(path, inputs=...) or %%render inputs=case.

Converting a cell#

A v1 cell with cell-wide overrides:

%%render params 2
b = 300
h = 600

%%render long 2
I_x = b * h**3 / 12
S_x = I_x / (h / 2)

becomes one v2 cell, with each setting where it applies:

## Section properties
# hc: -f .2f
b = 300; h = 600
I_x = b * h**3 / 12   # hc: -m
S_x = I_x / (h / 2)
Output (MarkdownRenderer)

Section properties

\[\begin{aligned} b &= 300.00 \; &h &= 600.00 \; \end{aligned}\]
\[\begin{aligned} I_{x} &= \frac{b \cdot h^{3}}{12} = \frac{300.00 \cdot 600.00^{3}}{12} = 5400000000.00 \\ S_{x} &= \frac{I_{x}}{\frac{h}{2}} = \frac{5400000000.00}{\frac{600.00}{2}} = 18000000.00 \end{aligned}\]
# Section properties

$$\begin{aligned} b &= 300.00 \; &h &= 600.00 \; \end{aligned}$$

$$\begin{aligned} I_{x} &= \frac{b \cdot h^{3}}{12} = \frac{300.00 \cdot 600.00^{3}}{12} = 5400000000.00 \\ S_{x} &= \frac{I_{x}}{\frac{h}{2}} = \frac{5400000000.00}{\frac{600.00}{2}} = 18000000.00 \end{aligned}$$

The heading and the ; grid replace a separate params cell, and -m applies to the one long line rather than the whole cell.

Names that render differently#

v1

v2

To get the v1 output

x_a_b → xab (nested)

xa,b (comma)

handcalcs.set_option("subscripts", "nested")

PiD, phiM, eta2, chi2 shown as words

ΠD, φM, η2, χ2: a Greek name before an uppercase letter or digit is a letter

set_option("greek_prefixes", False), or # hc: greek_prefixes = False

x_hat, p_bar, V_dot, M_star as subscripts

accents and *

a symbols entry, e.g. {"p_bar": "p_{bar}"}

ΔH (Unicode) failed under pdflatex

\Delta H

—

Global options that were removed#

The v1 options decimal_separator, latex_block_start, latex_block_end, math_environment_start, math_environment_end, line_break, use_scientific_notation, display_precision, underscore_subscripts, greek_exclusions, param_columns, preferred_string_formatter and custom_symbols no longer exist. v2 has four options (format_code, default_renderer, jupyter_renderer, line_values) plus any custom options; the rest is controlled by the renderer.

An old config.json from v1 is not read; v2 stores its configuration in a new location (see Configuration).