Quickstart

Content

• ❓ Is this for me?
• 💻 Installation & prerequisites
  • Python package
  • LaTeX toolchain
  • Checklist
• 🌟 Basic usage
  • 1. Declare & export variables in Python
  • 2. Include results in LaTeX

❓ Is this for me?

Before you start and to avoid frustration, let’s make sure that ResultWizard is the right tool for you:

• It’s not primarily for you, if you’re writing your LaTeX code in a web-based editor like Overleaf. ResultWizard is a Python package that will export a .tex file in the end. You have to include this file in your LaTeX project and the closer your Python code is to your LaTeX document, the easier it is to reference it without having to do anything manually in-between. You could still use ResultWizard in your Python code and manually copy the contents of the generated results.tex file into Overleaf, but this is not the originally intended workflow.
• The same philosophy applies to Jupyter Notebooks that run in a browser. Instead, you should use a local Jupyter Notebook setup and have your LaTeX project reside next to your Python code. Using VSCode as editor is one way to do this. It has built-in support for Jupyter Notebooks and with the LaTeX Workshop extension you can easily compile your LaTeX document and see the changes immediately. For a possible setup within WSL, see this guide.

Ideally, you’d have a folder structure where code (or python or src or whatever) and thesis (or latex or document or whatever) are folders on the same level. See also the wiz.export() API.

Ideally, you also have used the siunitx LaTeX package beforehand to know how to format units, e.g. \m\per\s^2. But don’t worry if you haven’t, you can still use ResultWizard and learn about siunitx along the way. You might also want to check out the siunitx configuration page.

💻 Installation & prerequisites

Have a LaTeX toolchain including siunitx set up and Python >=3.8 installed.
Then install the ResultWizard package via pip:

pip install resultwizard    # use `pip install resultwizard==1.0.0a2` in the current alpha stage

Move on to Basic usage.

Python package

You can install ResultWizard via pip:

pip install resultwizard

ResultWizard is currently fully functional but still in its alpha stage, i.e. the API might change. We’re happy to receive your feedback until the first stable release.
Please report any issues on GitHub. To get the latest alpha version, you have to install it via
pip install resultwizard==1.0.0a2 (otherwise you end up using the older version 0.1).

Verify you’re using the version you intended to install:

pip show resultwizard | grep Version

LaTeX toolchain

To compile the LaTeX document, you need a working LaTeX toolchain. If you don’t have one yet, there are many guides available online for different OS, e.g. on the LaTeX project website.

• For MacOS, you might want to use MacTex.
• For Windows, we recommend MikTex.
• For Linux (Ubuntu, e.g. also in WSL), we recommend Tex Live¹:

  sudo apt install texlive texlive-latex-extra texlive-science
  

No matter what LaTeX distribution you’re using, you will have to install the siunitx LaTeX package. This package is used to format numbers and units in LaTeX, e.g. for units you can use strings like \kg\per\cm. In the Tex Live distribution, this package is already included if you have installed sudo apt texlive-science.

Checklist

• Python >=3.8 installed & ResultWizard installed via pip
• LaTeX toolchain set up, e.g. TeX Live
• siunitx LaTeX package installed

🌟 Basic usage

1. Import the library in your Python code, declare your results and export them:

   # In your Python code
   import resultwizard as wiz
   wiz.res("Tour Eiffel Height", 330.362019, 0.5, "\m")  # units must be `siunitx` compatible
   wiz.export("./results.tex")
   

2. Include the results in your LaTeX document:

   % In your LaTeX document
   \input{./results.tex}
   \begin{document}
    The height of the Eiffel Tower is given by $h = \resultTourEiffelHeight$.
    % also try out: $h = \resultTourEiffelHeight[value]$
   \end{document}
   

1. Declare & export variables in Python

In your Python code, import ResultWizard and use the wiz.res function to declare your results. Then, export them to a LaTeX file by calling wiz.export. For the unit, you must use a siunitx compatible string, e.g. \m for meters or \kg\per\s^2. See the siunitx docs for more information.

import resultwizard as wiz

# your complex calculations
# ...
value = 330.362019  # decimal places are made up
uncertainty = 0.5
wiz.res("Tour Eiffel Height", value, uncertainty, "\m").print()
# will print: TourEiffelHeight = (330.4 ± 0.5) m

wiz.export("./results.tex")

There are many more ways to call wiz.res(), try to use IntelliSense (Ctrl + Space) in your IDE to see all possibilities. If you want to omit any rounding, pass in values as string, e.g.:

wiz.res("pi", "3.1415").print() # congrats, you found an exact value for pi!
# will print: pi = 3.1415
wiz.res("Tour Eiffel Height", str(value), str(uncertainty), "\m").print()
# will print: TourEiffelHeight = (330.362019 ± 0.5) m

You can also use the wiz.config_init function to set some defaults for the whole program. See many more configuration options here.

wiz.config_init(sigfigs_fallback=3, identifier="customResult")
# default to 2 and "result" respectively

If you’re working in a Jupyter Notebook, please see this page for a suitable configuration of ResultWizard that doesn’t annoy you with warnings and prints/exports the results automatically.

2. Include results in LaTeX

You have either called wiz.export(.results.tex) or set up automatic exporting with wiz.config_init(export_auto_to="./results.tex"). In any case, you end up with a LaTeX file ./results.tex. Import it in your LaTeX preamble (you only have to do this once for every new document you create):

% Your LaTeX preamble
\input{./results.tex}
\begin{document}
...

Then, you can reference the variables in your LaTeX document:

% Your LaTeX document
This allowed us to calculate the acceleration due to gravity $g$ as
\begin{align}
    g &= \resultG
\end{align}
Therefore, the height of the Eiffel Tower is given by $h = \resultTourEiffelHeight$.

It will render as follows (given respective values for g and Tour Eiffel Height are exported):

If you set up your IDE or your LaTeX editor properly, you can use IntelliSense (Ctrl + Space) here as well to see all available results, e.g. type \resultTo. Changing the value in Python and re-exporting will automatically update the value in your LaTeX document².

Also try out the following syntax:

% Your LaTeX document
The unit of $h$ is $\resultTourEiffelHeight[unit]$ and its value is $\resultTourEiffelHeight[value]$.

Use \resultTourEiffelHeight[x] to get a message printed in your LaTeX document informing you about the possible strings you can use instead of x (e.g. withoutUnit, value etc.).

---

1. For differences between texlive packages, see this post. For Ubuntu users, there’s also an installation guide available here. If you’re interested to see how Tex Live can be configured in VSCode inside WSL, see this post. ↩

2. You have to recompile your LaTeX document, of course. But note that you can set up your LaTeX editor / IDE to recompile the PDF automatically for you as soon as any files, like results.tex change. For VSCode, you can use the LaTeX Workshop extension for this purpose, see a guide here. In the best case, you only have to update a variable in your Python code (and run that code) and see the change in your PDF document immediately. ↩