DOCSEARCHbyAlgolia
Submit Docs

handcalcs

repository·main·Indexed 26 days ago

https://github.com/connorferster/handcalcs

A Python library that renders calculation code in Jupyter as LaTeX, mimicking handwritten calculations by displaying symbolic formulas, numeric substitutions, and final results. It provides the %%render and %%tex cell magics for Jupyter, as well as a @handcalc() decorator for non-Jupyter environments like Streamlit. Features include automatic Greek symbol replacement, subscript support, and customizable decimal precision and formatting via global configuration or override tags.

Tokens
6.3K
Snippets
14
Records
53
Agent score
90%

What's inside handcalcs

  1. Understand handcalcs rendering behavior and limitations

    main

    Core Behavior

    handcalcs renders arithmetical calculations written in Python code into LaTeX. It is not a general-purpose Python-to-LaTeX converter.

    Key Limitations

    • Single-line statements only: handcalcs parses individual lines of Python within a cell. It does not parse the cell as a whole. Multi-line statements like for loops, with statements, or function definitions will not render.
    • Iteration support: Rendered iterations (e.g., showing the steps of a for loop) are not supported. To handle iterations, perform the loop in a non-rendered cell and render the final result in a subsequent cell.
    • Collection types: list and dict types may not render correctly. Use tuple or one-dimensional numpy arrays (vectors) for collection-based arguments (e.g., sum((23, 123, 45))).

    Arithmetic Operator Mapping

    Python OperatorLaTeX Rendering
    ++
    --
    *\cdot (dot operator)
    /Fraction
    **Superscript
    %\mod (mod function)
    //Not supported (use math.floor instead)

  2. Export Jupyter Notebooks to PDF/HTML/LaTeX without input

    main

    When handcalcs is installed, it provides an Exporter for Jupyter. This allows you to export notebooks while suppressing all input cells, showing only the rendered outputs.

    In Jupyter, use the File -> Save and Export as menu to select:

    1. HTML_NoInput
    2. LaTeX_NoInput
    3. PDF_NoInput

  3. Use handcalcs as a Jupyter cell magic (%%render)

    main

    To render Python calculations as LaTeX in Jupyter Notebook or Jupyter Lab, import the handcalcs.render module and use the %%render magic at the top of your cell. This will automatically convert your Python code into symbolic formulas followed by numeric substitutions and results.

    You can also use the %%tex magic to convert a Python code snippet into a raw LaTeX string.

    import handcalcs.render

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

  7. Install handcalcs via pip

    main

    Install the core library using pip:

    pip install handcalcs

    Note: As of v1.9.0, the nbconvert "no input" exporters are no longer included in the main package to reduce installation size. They are now maintained separately in the nb-hideinputs repository.

    pip install handcalcs

  8. Use override tags in handcalcs

    main

    In both the cell magic (%%render) and decorator (@handcalc()) APIs, you can use "override tags" to alter the behavior and display of your calculations.

    Rules for using tags:

    • Tags params, symbolic, long, and short are mutually exclusive. You can only use one of these at a time (e.g., use params or short, but not params short).
    • The sympy tag can be used alongside any of the first four tags to combine their behaviors.
    • You can also include an integer as part of the tag configuration.

  9. Configure LaTeX for PDF printing

    main

    To print calculations to PDF, you must have a LaTeX environment installed on your system with a LaTeX compiler available in your system's PATH. This allows Jupyter to execute xelatex via the command line.

    To verify your installation, open a command line and type xelatex. A successful installation will enter a LaTeX prompt rather than returning an error.

  12. Use override tags with %%render or @handcalc()

    main

    You can customize calculation formatting using override tags. You can use exactly one override tag per cell/function, but you can combine an override tag with a precision setting.

    Available Override Tags:

    • params: Renders parameters in three columns to save vertical space and shows only the result, not the intermediate calculations.
    • long: Forces calculations to span multiple lines (the 'Long' format).
    • short: Forces calculations onto a single line (the 'Short' format).
    • symbolic: Renders calculations symbolically without numeric substitution (useful for rendering LaTeX equations).
    • sympy: Intended for use with sympy objects to handle substitution and calculation of resulting expressions.

    Usage via Jupyter Magic: %%render <tag> <precision>

    Usage via Decorator: @handcalc(override='<tag>', precision=<int>)