VON: vEnhance's Olympiad Navigator

A problem database written in Python

VON is a Python script I wrote in order to help me manage my centralized database of solutions to olympiad problems.

There is no graphical user interface; it is based on standard command line. Therefore, it will work best on Linux systems. Windows users may experience some grief, and Windows users unfamiliar with command line are going to have a bad time.

I haven't gotten around to properly documenting this, but posting it by popular request. Here are a few hints. Pull requests to improve this documentation are welcome.

Setup

This program assumes you have:

• Python 3.10+ installed (versions 3.8 or lower will not work), and
• A working LaTeX compiler with latexmk installed. (I recommend TeX Live).

1. Clone this repository (e.g. git clone https://github.com/vEnhance/von).
2. You must create a copy of rc.py based on rc.py.EXAMPLE inside the cloned repository. This is the "settings" file for the script.
3. The cloned directory should be included under PYTHONPATH, and invoked by python -m von (to get an interactive terminal). If you only want to issue one command, you can also type it directly, e.g. python -m von help will list the help and exit. (Shell users may wish to include alias von="python -m von" in their shell configuration to save keystrokes.)
4. If not pre-installed, you should pip install pyyaml (or sudo pacman -S python-pyyaml, etc.). For optional clipboard functionality, you may need to pip install pyperclip (or sudo pacman -S python-pyperclip, etc.). You can do both commands at once with pip install -r requirements.txt. On Windows, you should additionally pip install -r requirements-windows.txt.
5. Optional LaTeX integration uses von.sty and PythonTeX. The optional previewer requires evan.sty. (See below for details.)
6. If fuzzy searching is desired (optional), install fzf.

Help

Use von help to display full help. The following information is mostly a subset of it.

To exit VON, type an EOF character (usually Ctrl-D).

Storing problems and solutions

• add "Shortlist 2016 G2": add problem to database

1. Problems are stored in TeX files in VON_BASE_PATH. You can keep subdirectories in here, as well, to organize those files.
2. Problems and solutions are separated using SEPARATOR in rc.py, which by default is three dashes padded by newlines. So when entering new problems, write the statement, the separator, and then the solution.
3. Actually more generally, each problem and solution is separated into several "bodies", delimited by the separator. It's basically assumed that 0'th body is the problem statement and the 1'st body is the solution, but you can have further bodies for other purposes too.

Meta-data

• edit "Shortlist 2016 G2" or edit "16SLG2": edit entry for problem in database

1. Meta-data is stored at the top of each file after being added.

2. Problems must have a source like "Shortlist 2016 G2".

3. Problems should also have a description, and a set of tags. If a tag is specified as a sorting tag in rc.py, it will be displayed differently, but otherwise functionally equivalently.

4. Problems can also have an "author" attribute, which is displayed.

5. Problems can also have a "hardness" attribute, an integer, which is displayed differently by the user interface. You can pick any scale you want; here is mine.

6. Problems can be marked as SECRET. Problems marked as SECRET will appear in searches, but will be replaced by placeholders (unless --brave is passed).

   There are two ways to mark a problem as SECRET:

   • Include SECRET as a substring of the problem's source.
   • Include secret as one of the problem's tags.

An example of an entry:

desc:  $5^n$ has six consecutive zeros
author: Evan Chen
source:  JMO 2016/2
tags:  [wishful, favorite, mods, construct, mine, 2016-04, free, brave]
hardness: 25

---

Prove that there exists a positive integer $n < 10^6$
such that $5^n$ has six consecutive zeros in its decimal representation.

---

We will prove that $\boxed{n = 20 + 2^{19} = 524308}$ fits the bill.

... (rest of solution) ...

Searching

The search command searches everything. Use search --help for a lot of options.

• search "Shortlist 2016": search for problems with "Shortlist 2016"
• search -t anglechase: searches for problems tagged anglechase

The s command is a shorthand for search.

You can use search --everything to list all problems.

Alternatively, the f command opens an interface which allows you to fuzzily search for a problem across problems with a preview. It is an alias for show without arguments.

Displaying problems

When using various commands, every problem can be identified in two ways. One is by the source, such as "Shortlist 2016 G2". Alternatively, when one uses the search command, the results are indexed by positive integers, and those indices can be used instead of the source. For example, show 3 will display the 3rd problem in search results.

• show 3: Print the 3rd problem
• po 3: Produces a TeX/PDF of the problem and solution.

Use show --help and po --help for more details.

Recompiling the index

Sometimes the list of problems and file paths might become messed up in some way (for example, if you move a file). To fix this run von nuke to recompile the entire index. von nuke is also useful in the cases of deleting a file and thus problem from the index.

Preview

When running von add or von edit on Linux, the program creates the file /tmp/preview/von_preview.tex which is a wrapper file that inputs the currently edited problem. If you use latexmk (which I recommend!), you can run latexmk -pvc on this in order to render what you are typing. This makes it possible to work simultaneously with the input and output that you are adding in to von.

LaTeX integration

If you have von.sty and latexmk, then by using a similar mechanic to Asymptote, you can also directly query the database for problems. You should add a pythontex routine to your .latexmkrc for this to auto-work; an example might be:

sub pythontex {
    system("pythontex --runall true \"$_[0]\"");
    system("touch \$(basename \"$_[0]\").pytxmcr");
    return;
}
add_cus_dep("pytxcode", "pytxmcr", 0, "pythontex");

The basic syntax is that \voninclude{source} will include the problem statement (0th body), while \voninclude[1]{source} will include the 1st body (the solution), etc.

Of course, this would most commonly be used with theorem environments, so you can use some shortcuts to this effect. The three possible shortcuts are:

• \von{X} is shorthand for \begin{problem}[X] \voninclude{X} \end{problem}
• \von[text]{X} is shorthand for \begin{problem}[text] \voninclude{X} \end{problem}
• \von*{X} is shorthand for \begin{problem} \voninclude{X} \end{problem}

Of course, the string problem might want to be changed, if you are using a differently named theorem environment. You can change this by running \renewcommand{\vonenvname}{name}.