Handcalcs v2.0

[connorferster]

Many of the issues raised are caused by limitations from the string parsing procedures utilized by handcalcs. I am planning a complete rewrite of handcalcs so that, instead of "reading" Python code as strings, handcalcs will access the abstract syntax tree directly. This will allow handcalcs to recognize all Python tokens (for loops, proper conditionals, and exceptions, for example) and the behaviours to convert each of these tokens into Latex can, ultimately, be customizable.

Other issues regarding rendering of the Latex code to PDF will be unaffected by this change but I am frequently thinking about these problems and am slowly strategizing a solution.

While I do not have a timeline for the v2.0 yet, it is certainly a major goal that I plan on achieving. The amount of community that has developed around handcalcs is truly inspiring for me and I want this tool to be far more adaptable and flexible than it already is.

Please keep raising issues. While I have not been around to answer them lately, I read them and I appreciate them.

I am planning some intermediate releases to fix quick bugs or to add easy-to-implement features throughout 2024. Stay tuned for those.

[DonCammne]

Ehi Connor, thank you for the incredible work, I really look forward to the version 2.0!

With the current version, I encountered some issue (or I would call them limitation) that I list below:

• Render simple text in more ways (aligned to the right, aligned to the left, centered, non-static text, etc.) in functions with "@handcalc", i.e. at the moment comments are incredible for notes on a specific equation/result, but they have a lot of limitation (they are truncated in the pdf if the line is too long, they need to be placed after a code line, they don't support LaTex commands, etc.); for now, the shortcut that I use is to create multiple small functions with "@handcalc" and group them in another function without "@handcalc" that I fill with display(Math(r'\hspace{1.5cm}' + comment + r' \\')) or display(Latex(r'\begin{align*}' + comment + r'\end{align*}')) (functions from IPython.display) to render text in a more controlled way (see image at the bottom for an example of the output)
• Turn off rendered output in specific situations from "@handcalc" functions, i.e. if a function with "@handcalc" is called in another function (for example in a for loop to create a plot), the latter will display the rendered output of the former even if it's not desired.
• Local rendering options, i.e. imposing the type of rendering (params, sci_not, long, short, etc.) for specific parts of a function with "@handcalc" (using keyword in comments for example)
• Long lines from cell output are truncated instead of being wrapped in PDF (you already addressed this problem recently in this issue, but I list it here for completeness).
• More control on which part of a function with "@handcalc" is rendered (with keyword in comments for example) to exclude specific parts of the code (issue reported for error handling)

If a point is unclear, please do not hesitate to ask for more information and/or a proper replicable example. I hope that this feedback could help you improve this library and if I missed something that already solves some of these limitations, let me know and sorry for the miss!

Figure with an example of the shortcut for rendering simple text in a function in combination with the handcalc output (no left aligned text at the moment but needed for the norm reference):

[reneholmgaard]

Hi Conner, fully agree with DonCammne: thank you for the incredible work, I really look forward to the version 2.0!

A couple of V2 comments/feature requests:

• For the function decorator I am missing a way of displaying the function without actually calling the function with input variables. Possibly the function decorator could be inspired by the latexify package
  
• I miss a way of using multiple subsequent greek letters, like e.g. Δσfor stress range and Σρ for sum of curvatures. One addition here is that the Handcalc is not capable of handling greek ascii letters in the code properly. With no whitespace there is no error, but also only the result. If white spaces are added in the function definition an error is returned with: ParseException: Expected == | = | + | - | * | // | / | % | , | <= | < | >= | > | != term, found 'Δσ' (at char 4), (line:1, col:5)
  
• For number precision, I find the general format more intuitive as default beharviour, compared to the current (assumption) float format used. And on the point of number representation, digit grouping by e.g. non-breakable white space could be an interesting option.
  

[av1dm]

Hello,

General format

I find @reneholmgaard's idea with general format very good.
I am using fixed units (with pint). E.g. 123.00 mm does not make sence, while 12.55 MPa or friction coeff. of 0.25 does. Therefore a fixed precision is not very intuitive for me also.

I changed the rendered_string line of latex_repr in handcalcs.py to g:

rendered_string = f"{item:.{precision}g{preferred_formatter}}"

with a display_precision = 3, the output looks much better for my taste:

Alignment

I would only align the first equal sign in equations. The blanc gap between the equation and the result is not looking very nice.
For long cells there should be also a "semi-long" option, where the symbolic line and the numeric line + result is broken, but not the numeric line from the result:

[PascalGitz]

Hey Connor

I'm using this issue to describe another usecase of handcalcs.

Recently I came across Quarto which is pretty neat for creating PDFs out of Notebooks. I see alot of potential in the combination of handcalcs and Quarto. It already works fine with handcalcs.

But I still desire a proper Markdown output of the handcalcs - generated calculations and an equation label (since quarto translates Markdown) as the example provided below (I wasn't able to do it by tinkering with the config.json file):

$$
\frac{\partial \mathrm C}{ \partial \mathrm t } + \frac{1}{2}\sigma^{2} \mathrm S^{2}
\frac{\partial^{2} \mathrm C}{\partial \mathrm C^2}
  + \mathrm r \mathrm S \frac{\partial \mathrm C}{\partial \mathrm S}\ =
  \mathrm r \mathrm C 
$$ {#eq-black-scholes}

This would eventually enable one to cross reference equations inside the notebook. On top of that the whole report creation and formating could be done in a notebook.

I would highly appreciate that handcalcs v2.0 gets rebuilt with Quarto in mind.

Thank you!

[connorferster]

@PascalGitz I have been wanting to check out Quarto! I will definitely be thinking of Quarto :)

[connorferster]

@DonCammne Thanks for these suggestions. I have just gotten a brainwave of how loops can be accommodated and dealt with...

[connorferster]

Apparently if I submit a comment by doing Ctrl-Enter, it closes the issue. Oops!

[av1dm]

Round instead of fixed float or general format

General format

I find @reneholmgaard's idea with general format very good. I am using fixed units (with pint). E.g. 123.00 mm does not make sence, while 12.55 MPa or friction coeff. of 0.25 does. Therefore a fixed precision is not very intuitive for me also.

I changed the rendered_string line of latex_repr in handcalcs.py to g:

rendered_string = f"{item:.{precision}g{preferred_formatter}}"

round instead of general format looks even better.

rendered_string = f"{round(item, precision):{preferred_formatter}}"

[SpazzNon]

Ehi Connor, thank you for the incredible work, I really look forward to the version 2.0!

With the current version, I encountered some issue (or I would call them limitation) that I list below:

• Render simple text in more ways (aligned to the right, aligned to the left, centered, non-static text, etc.) in functions with "@handcalc", i.e. at the moment comments are incredible for notes on a specific equation/result, but they have a lot of limitation (they are truncated in the pdf if the line is too long, they need to be placed after a code line, they don't support LaTex commands, etc.); for now, the shortcut that I use is to create multiple small functions with "@handcalc" and group them in another function without "@handcalc" that I fill with display(Math(r'\hspace{1.5cm}' + comment + r' \\')) or display(Latex(r'\begin{align*}' + comment + r'\end{align*}')) (functions from IPython.display) to render text in a more controlled way (see image at the bottom for an example of the output)
• Turn off rendered output in specific situations from "@handcalc" functions, i.e. if a function with "@handcalc" is called in another function (for example in a for loop to create a plot), the latter will display the rendered output of the former even if it's not desired.
• Local rendering options, i.e. imposing the type of rendering (params, sci_not, long, short, etc.) for specific parts of a function with "@handcalc" (using keyword in comments for example)
• Long lines from cell output are truncated instead of being wrapped in PDF (you already addressed this problem recently in this issue, but I list it here for completeness).
• More control on which part of a function with "@handcalc" is rendered (with keyword in comments for example) to exclude specific parts of the code (issue reported for error handling)

If a point is unclear, please do not hesitate to ask for more information and/or a proper replicable example. I hope that this feedback could help you improve this library and if I missed something that already solves some of these limitations, let me know and sorry for the miss!

Figure with an example of the shortcut for rendering simple text in a function in combination with the handcalc output (no left aligned text at the moment but needed for the norm reference):

Hi, my apologize for my bad english but how do you do the "Check" and "Warning don't pass" i been triying but i can't.