Get started#

This page gets you from nothing to a rendered calculation in a couple of minutes. The other pages in this section explain each feature in depth.

1. Install#

$ pip install handcalcs

For Excel output, install the extra: pip install "handcalcs[excel]". See Installation for uv, Jupyter setup and the other extras.

2. Render a calculation#

Import handcalcs once, at the top of the notebook:

import handcalcs

Then start any cell with %%render. The cell runs as normal Python, and handcalcs displays it as a calculation:

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

Create a HandCalcs object with a renderer and call it with your source code:

from handcalcs import HandCalcs
from handcalcs.renderers import ASCIIRenderer

calc = HandCalcs(renderer=ASCIIRenderer())
print(calc("""
a = 2
b = 3
c = 2*a + b/3
"""))

Either way, each line is shown as the symbolic formula, the formula with the values substituted, and the result:

Output (MarkdownRenderer)
\[\begin{aligned} a &= 2 \\ b &= 3 \\ c &= 2 \cdot a + \frac{b}{3} = 2 \cdot 2 + \frac{3}{3} = 5 \end{aligned}\]
$$\begin{aligned} a &= 2 \\ b &= 3 \\ c &= 2 \cdot a + \frac{b}{3} = 2 \cdot 2 + \frac{3}{3} = 5 \end{aligned}$$

Lines that only assign a number (a = 2) are shown as just the value. Calculations show every step.

3. Add explanation#

Comments become part of the output. A ## comment is a heading, a plain comment line is a paragraph, and a comment at the end of a line is shown next to that line:

## Hypotenuse of a right triangle
# Both sides are measured from the site drawings.
a = 2.5  # Side a, in m
b = 4.0  # Side b, in m
c = sqrt(a**2 + b**2)
Output (MarkdownRenderer)

Hypotenuse of a right triangle

Both sides are measured from the site drawings.

\[\begin{aligned} a &= 2.5 \quad\text{(Side a, in m)} \\ b &= 4 \quad\text{(Side b, in m)} \\ c &= \sqrt{a^{2} + b^{2}} = \sqrt{2.5^{2} + 4^{2}} = 4.717 \end{aligned}\]
# Hypotenuse of a right triangle

Both sides are measured from the site drawings.

$$\begin{aligned} a &= 2.5 \quad\text{(Side a, in m)} \\ b &= 4 \quad\text{(Side b, in m)} \\ c &= \sqrt{a^{2} + b^{2}} = \sqrt{2.5^{2} + 4^{2}} = 4.717 \end{aligned}$$

4. Control the formatting#

A comment that starts with hc: is a command. It changes how the line (or the following lines) are rendered. For example, -f sets the number format:

a = 2.123456
b = 3.987654
c = a * b  # hc: -f .2f
Output (MarkdownRenderer)
\[\begin{aligned} a &= 2.1235 \\ b &= 3.9877 \\ c &= a \cdot b = 2.12 \cdot 3.99 = 8.47 \end{aligned}\]
$$\begin{aligned} a &= 2.1235 \\ b &= 3.9877 \\ c &= a \cdot b = 2.12 \cdot 3.99 = 8.47 \end{aligned}$$

Comment commands lists them all.

Go deeper#

How handcalcs reads your code

What each kind of line becomes, and what is not rendered.

How handcalcs reads your code
Writing calculations

Headings, prose, inline comments, parameter grids, conditionals and loops.

Writing calculations
Comment commands

# hc: commands for number formats, long equations, grids and spacing.

Comment commands
Formatting numbers

Format codes, and setting them per line, per section or for the whole session.

Formatting numbers
Configuration

Save your preferred defaults: format code, default renderers, custom settings.

Configuration
Units

Calculations with forallpeople or pint quantities.

Units
Gotchas

Out-of-order cells, unsupported code, and responsibility for results.

Gotchas
Coming from handcalcs v1

What changed in v2 and how to update your notebooks.

Coming from handcalcs v1

Next: choose where your output goes with a renderer, or choose how you call handcalcs with an interface.