Handcalcs：从Python数学代码自动呈现Latex方程式

Handcalcs是一个用Latex自动呈现Python计算代码的库，但是使用的方式与用铅笔编写计算的方式相似：先写符号公式，然后是数字替换，然后是结果。

因为手算显示了数字替换，所以计算变得非常容易手工检查和验证。

手算是为了与木星笔记本或木星实验室一起使用，作为一种细胞魔法。

然后，在要使用手算渲染的任何单元格中，只需使用单元格顶部的渲染单元格魔术即可：

渲染后，如果您的系统上安装了Latex环境，则可以将笔记本导出为PDF。如果您刚开始使用Latex，并且想要将其安装到您的系统上以便使用此功能，请参阅维基中的“安装TeX”一节。

您还可以使用%%tex命令将任何Python代码片段转换为有效的LaTeX。例如：

第一个进口手柄。我们还为下面的示例从数学包中导入了一些属性/函数。

\[\BEGIN{ALIGNED}a&；=\frac{2}{3}\cot\sqrt{\pi}=\frac{2}{3}\cot\sqrt{3.142}&；=1.182\end{aligned}\]

除了不是在Jupyter单元中运行代码，而是在Python函数中运行代码，该函数被视为Jupyter单元之外，情况与此相同。

@handcalc()def my_calc(x，y，z)：a=2*x/y b=3*a c=(a+b)/z返回本地变量()。

返回由(latex_code：str，locals：dict)组成的元组，其中locals是函数命名空间范围内所有变量的字典。

LEFT和RIGHT是可以在编码的Latex字符串之前和之后的字符串，例如\\[AND\\]或$和$。

Jupyter_display为True时，将仅返回本地变量字典，并使用IPython.display中的display(latex(Latex_Code))显示编码的Latex字符串。如果不在内部使用，将返回错误。

在修饰函数中，def my_calc(...)。而return locals()现在类似于Jupyter单元格中的代码，不同之处在于它是一个标准的Python函数。

以这种方式使用，您可以使用@handcalc()动态生成Latex代码，以便在Jupyter和非Jupypter Python环境(例如Streamlight)中显示。

Handcalcs会对您希望如何格式化计算进行某些假设，并且不允许在这方面进行大量定制。但是，目前有三种自定义可以使用#COMMENT标记作为%%呈现单元格魔术之后单元格的第一行。每个单元格只能使用一个注释标签。

注释标签既可以与Jupyter cell Magic一起使用，也可以与函数装饰器一起使用。要将注释标记与修饰符一起使用，注释标记必须是签名后的第一行(即def func_name()：)。

Handcalcs一个接一个地垂直呈现代码行。但是，当您为变量赋值或显示结果变量时，您可能不想浪费所有的垂直空间。

使用#Parameters注释标记，您的参数列表将改为以三列呈现，从而节省垂直空间。

为了节省垂直空间，Handcalcs会尝试计算出您的计算有多长，如果计算足够短，则会在一行中完整地显示出来。

如果handcalcs的内部测试认为计算太长，不能放在一行上，它会将计算分成多行。

使用#Long或#Short注释标记覆盖长度检查，并以"；Long"；格式或"；Short&34；格式显示单元格中所有计算的计算。例如：

#"；短"；计算的格式(可以放在一行上)：c=2*a+b/3=2*(2)+(3)/3=5#"；长"；计算的格式(需要多行格式)c=2*a+b/3=2*(2)+(3)/3=5。

手算的主要目的是用数字替换来呈现完整的计算。这使得计算的可追溯性和验证性变得容易。

但是，在某些情况下，可能更倾向于简单地以符号方式显示计算。例如，您可以使用#Symbol标记来使用Handcalcs作为以符号方式呈现Latex方程式的快速方法。

或者，您可能更喜欢在一个单元格中呈现所有输入参数，将公式象征性地呈现在下一个单元格中，然后在最后一个单元格中呈现所有最终值，从而完全跳过数字替换过程。

请记住，即使您在计算中使用了#Symbol标记，您仍然需要提前声明这些变量(通过为它们赋值)，才能使您的计算成为有效的Python。

Handcalcs设计为与Units软件包一起使用，for all People(for all People设计为与Handcalcs兼容)。然而，最近有报道称，品脱也能起到很好的效果。

在Python中，显示许多变量的值通常需要将它们全部输入到一系列print()语句中。手持计算器使这一点变得容易得多：

如果您只想直接生成渲染的Latex代码以在您自己的Latex文件中使用，则可以改用%%tex单元魔术：

当变量名中使用_时，将自动创建变量名中的下标。每个单独使用的序列都嵌套子下标。

任何包含希腊字母的变量名(例如"；pi"；，"；upsilon"；，"；eta"；等)。因为字符串或子字符串将被适当的Latex代码替换以表示该希腊字母。

使用小写字母作为变量名将使希腊字母变得小写。

为变量使用大写名称将使其显示为大写希腊字母。

如果在计算中使用Python函数，例如。Min()或tan()，它们将被替换为Latex代码以在Latex中表示该函数。

如果您正在创建自己的函数，则它们将作为自定义操作符在Latex中呈现。

如果您正在使用名为sqrt的函数(无论是您自己的自定义实现还是来自math.sqrt)，那么它将被呈现为部首符号。

在一行计算之后放置的任何注释都将在Latex中呈现为内联注释。

这便于在计算的同时做笔记，以简要说明您可能从何处获得或派生出一个特定值。

任何完全括在圆括号()中的计算都将呈现为param=result，没有替换。

导出为PDF(通过Latex)：使用之前安装的Latex发行版，Jupyter将首先将您的笔记本导出为.tex文件，然后将该文件渲染为PDF。这要求您的系统上已经安装了Latex发行版(说明：windows、mac os、ubuntu)。优点：分页符往往工作得更好，并且您可以使用生成的.tex文件进一步自定义输出。

缺点：无法轻松地重新调整PDF打印的比例(例如，为了确保非常长的公式适合页面大小)，并且您不能将复制/粘贴到笔记本中的图像包括在内。可以使用图像，但必须使用Markdown链接，并且文件必须与笔记本位于同一目录中。

如果代码输入单元格被抑制，用手工计算器制作的PDF笔记本往往看起来更好。为了方便起见，handcalcs附带了两个修改后的nbConvert模板文件，可以在导出之前通过在Jupyter中运行函数来安装这两个文件。

Swapin：您希望安装的handcalcs模板文件的名称。如果未提供，该函数将打印可用模板列表，这些模板的名称是此参数的可接受输入。SWAP_OUT：要替换的nbConvert模板文件的名称(默认文件分别为nbConvert'；的默认html或LaTeX模板)Restore：当设置为True时，该函数将删除以前安装的模板文件并恢复默认的nbConvert模板。

虽然有一些方法可以手动更改nbConvert使用的模板，但这必须作为单独的转换步骤在命令行上执行。此默认模板覆盖方法在Jupyter GUI界面中不可用。

我发现快速更改默认导出行为的最简单、最可靠的方法是换出和替换默认模板文件。通过使用这种方法，您可以直接从Jupyter GUI菜单选项导出您的笔记本，并让您的笔记本看起来像您希望的那样，而不必纠结于可能需要或可能不需要的多个配置设置。

当Handcalcs安装这些模板时，它们会对您的模板进行半永久性更改，这些更改将在您使用Jupyter打印的所有其他笔记本中保留下来，无论您是否使用Handcalcs。它之所以这样做，是因为它在物理上为您的本地安装换出并替换了您的nbConvert默认模板文件，这意味着它将在您的Jupyter会话结束后仍然存在。

使用Restore=True参数可以随时恢复此更改。此外，该功能不会让您重复安装相同的模板。如果您希望安装另一个模板，该函数将在尝试另一个安装之前提示您运行RESTORE=True函数。

通过这种方式，Handcalc可以为您完全管理这些模板安装。但是，如果手动更改nbConvert Templates目录中已安装的handcalcs模板的文件名，则不能保证可以成功恢复原始模板。

>；>；>；来自手提电脑。Install_template从handcalcs导入install_html>；>；。Install_template import install_latex>；>；install_html()#不带参数使用可用模板可用模板：['；full_html_noinputs.tpl'；]>；>；install_html('；full_html_noinputs.tpl'；)#选择要安装的模板/usr/name/path/to/your/nbConvert/。Tpl-现在是-/usr/name/path/to/your/nbConvert/plates/dir/html/full_swaps。Tpl/usr/name/path/to/your/handcalcs/plates/dir/html/full_html_noinput。Tpl-is现在-/usr/name/path/to/your/nbConvert/plates/dir/html/full。Tpl>；>；>；install_html(restore=True)#要将此更改恢复到模板文件/user/name/path/to/your/nbConvert/plates/dir/html/full。TPL-已删除，并替换为-/USER/NAME/PATH/TO/YOUR/nbConvert/Templates/dir/html/full_swaps。第三方物流。

Handcalcs旨在呈现用Python代码编写的算术计算。它不打算将任意Python渲染到Latex中。

鉴于此，handcalcs只呈现Python的一个很小的子集，而且有很多东西不会工作，特别是发生在多行上的任何事情(例如，函数定义、for循环、with语句等)。

Handcalcs通过解析单元格中的Python各行来工作。它不会将单元格作为一个整体进行解析。因此，所有要呈现的语句必须包含在一行中。

Handcalcs将尝试呈现所有数据类型。但是，它不适用于基于集合的类型(例如列表、元组、字典等)。

A)如果对象具有用于将其自身呈现为Latex代码的某种替代方法，例如.latex()或.to_latex()，则也将尝试该方法。

为了正确呈现表示，对象的Latex表示必须使用MathJax和/或Katex实现的命令。

如果您使用对象类型具有呈现为MyObject：Value=34；字符串方法，则Latex解释器将看到并尝试呈现该对象类型。

当前//没有呈现，但是您可以轻松地使用math.loor作为函数。

但是，即使它是正确有效的Python，下面的代码也会产生意想不到的结果：

在本质上，Handcalc中解析的Python代码被表示为嵌套的双端队列：每组括号(无论上下文如何)都开始一个新的嵌套双端代码，并递归地转换为Latex代码。

上面的行将如下所示(为简洁起见，表示为列表)：[[3，'；*'；，'；a'；]，'；/'；，'；sqrt'；，[2，'；*'；，'；，'；+'；，'；b'；，'；**'；，'；**'；，'；**'；，'；**'；，'；**'；，'；**'；，'；**'；，'；2'；]]。注意到/操作符之后的sqrt是如何单独的吗？

要正确呈现分数，需要执行预视，并将/之后的下一项呈现为分母。在本例中，下一项是函数名sqrt，而不是完整的表达式。

将整个分母括起来会使handcalc在前视中看到整个表达式(作为嵌套双队列)。

如果您的Latex输出看起来不太正确，请检查您是否以这种明确的方式使用了方括号和分数。

当单元运行时，所有实际计算都由Jupyter处理。结果值存储在用户的名称空间字典中，handcalcs使用名称空间字典中变量的相应值作为结果进行显示。因此，即使计算的表示形式看起来很奇怪，但如果您使用的是唯一的变量名，结果将是正确的。(参见Gotchas)。

不支持显示渲染迭代。使用的目的是在未呈现的单元格中执行迭代，然后，一旦迭代产生了所需的结果值，就在单独的单元格中呈现结果。

由于handcalcs是为在Jupyter环境中使用而设计的，而且Jupyter单元格可能会出现乱七八糟的情况，如果您在整个笔记本中重复使用变量名，则可能会出现大量渲染精美但计算完全错误的情况。

Handcalcs使用笔记本的用户名称空间字典查找名称空间中所有变量的值。如果您的计算在整个笔记本中重复使用变量名称，则当您按照原来的顺序运行单元格时，该名称的字典条目可能不是您所认为的那样。

如果单元格按正确的顺序运行，您可以在整个笔记本中重复使用变量名以达到良好的效果(如果这只是从上到下运行，则更容易)。

请注意：如果您使用手写计算器进行任何可能成为法律文档的报告(例如设计工程计算)，则应由您来确保结果符合您的预期。Handcalcs是免费的开源软件，作者对因使用它而导致的错误计算不承担任何责任。

这就是说，手工计算器呈现其数学的方式的真正目的是使手工确认和验证计算变得非常容易。

**请参阅wiki了解Handcalc在教育和工程中的应用，以及与Streamlight和Paper Mill等其他Python库一起使用Handcalc的示例。