How handcalcs reads your code#

handcalcs renders arithmetic calculations written in Python. It is not a general Python-to-math converter. This page explains what happens to your code and what each kind of line turns into.

What happens when you render#

Your code runs as ordinary Python (in the notebook, or with exec for a script). While it runs, handcalcs records the values of its variables just before and just after each statement.
handcalcs parses the source, statement by statement, into a tree of nodes. Each variable in the tree is paired with the value it had on that line: a calculation substitutes the values its operands had when it ran, and its result is the value it produced.
A renderer turns the tree into output: the symbolic form uses the variable names, the numeric form uses their values.

So a name can be reassigned: each line shows the value it had there, and an if shows the branch that ran with the values its test was evaluated with:

a = 2
b = a * 3
a = a + 8
if a > 5:
    a = 1
    c = b + a

Output (ASCIIRenderer)

a = 2
b = a * 3 = 2 * 3 = 6
a = a + 8 = 2 + 8 = 10
Since (a>5) -> (10>5) is True:
    a = 1
    c = b + a = 6 + 1 = 7

Kinds of line#

Calculations#

An assignment whose right-hand side uses variables, operators or function calls is a calculation. It is shown as target = symbolic = substituted = result:

a = 2
b = 3
c = 2*a + b/3

Output (ASCIIRenderer)

a = 2
b = 3
c = 2 * a + b / 3 = 2 * 2 + 3 / 3 = 5

When two steps would read the same (for example q = b), the duplicate is dropped.

Parameters#

An assignment of a plain number, a negative number or a collection of literals ([1, 2, 3]) is a parameter. It is shown as target = value:

L = 6.0
loads = [1.2, 3.4, 5.6]

Output (ASCIIRenderer)

    L = 6
loads = [1.2, 3.4, 5.6]

Several parameters on one line, separated by ;, are laid out as a parameter grid.

Skipping the substitution#

Wrap the right-hand side in parentheses to show only target = result. This is useful for intermediate values that are not the focus of the calculation:

a = 2
b = 3
d = (a**2 + b**2)
e = a**2 + b**2

Output (ASCIIRenderer)

a = 2
b = 3
d = 13
e = a² + b² = 2² + 3² = 13

Expressions#

A bare expression (no assignment) is shown like a calculation without a target: its symbolic and substituted forms, then its result. A call to your own function is not run again, so it has no result; see Show the result of an expression.

a = 2
b = 3
a + b

Output (ASCIIRenderer)

    a = 2
    b = 3
a + b = 2 + 3 = 5

Conditional expressions#

A conditional expression is shown with its keywords, and the substitution shows which branch the values pick:

a = 2
b = 10 if a > 0 else -10

Output (MarkdownRenderer)

Rendered

\[\begin{aligned} a &= 2 \\ b &= 10\;\mathrm{if}\;a \gt 0\;\mathrm{else}\;-10 = 10\;\mathrm{if}\;2 \gt 0\;\mathrm{else}\;-10 = 10 \end{aligned}\]

Markdown output

$$\begin{aligned} a &= 2 \\ b &= 10\;\mathrm{if}\;a \gt 0\;\mathrm{else}\;-10 = 10\;\mathrm{if}\;2 \gt 0\;\mathrm{else}\;-10 = 10 \end{aligned}$$

Comments, headings and imports#

Source	Becomes
`## Title`, `### Subtitle`, …	A heading. `##` is the top level; each extra `#` goes one level down.
`# Some text` on its own line	A paragraph of prose. Consecutive comment lines join into one paragraph.
`x = 1 # note`	The note, shown next to the line.
`# hc: ...`	A comment command. It is not shown.
`import math`	The import, shown as code (renderer dependent).

Blocks#

Source	Becomes
`if` / `elif` / `else`	The condition that was true, symbolically and with values, followed by that branch’s lines. Branches that did not run are not shown.
`for`	A line describing the loop, followed by its body. The body shows the values of the last pass through the loop.

See Writing calculations for examples.

What is not rendered#

Function and class definitions, while loops, with blocks and augmented assignments (a += 1) are not shown. Run them in a cell or script section that you don’t render, then render the calculation that uses the result.
print(...) calls are skipped, so a script can print progress without it showing up. A comment line above one is kept.

Function names and symbols#

Renderers translate names as they render them. In the ASCII, HTML, LaTeX and Markdown renderers:

Greek letter names (alpha, beta, Gamma, …) become Greek letters; a lowercase name gives a lowercase letter, a capitalized name an uppercase letter.
_ starts a subscript: I_y becomes I_y; each further _ adds a subscript after a comma (N_pl_Rd → N_pl,Rd). (The ASCII renderer keeps the underscore.) See naming variables for Greek letters joined to other letters, accents and display symbols.
sqrt(...) becomes a radical; ** becomes a superscript; / becomes a fraction in LaTeX and Markdown.
Other function calls are shown by name, with their arguments.

alpha = 30
L_span = 6.0
F_y = 350
d = L_span * sin(radians(alpha)) / sqrt(F_y)

Output (MarkdownRenderer)

Rendered

\[\begin{aligned} \alpha &= 30 \\ L_{\mathrm{span}} &= 6 \\ F_{y} &= 350 \\ d &= \frac{L_{\mathrm{span}} \cdot \sin\left(\operatorname{radians}\left(\alpha\right)\right)}{\sqrt{F_{y}}} = \frac{6 \cdot \sin\left(\operatorname{radians}\left(30\right)\right)}{\sqrt{350}} = 0.16036 \end{aligned}\]

Markdown output

$$\begin{aligned} \alpha &= 30 \\ L_{\mathrm{span}} &= 6 \\ F_{y} &= 350 \\ d &= \frac{L_{\mathrm{span}} \cdot \sin\left(\operatorname{radians}\left(\alpha\right)\right)}{\sqrt{F_{y}}} = \frac{6 \cdot \sin\left(\operatorname{radians}\left(30\right)\right)}{\sqrt{350}} = 0.16036 \end{aligned}$$

Each renderer page lists its exact translations; Customizing shows how to add your own.

Next: Writing calculations.