DogeyStamp

Contributing to Zathura as a novice

2023-10-24T10:00:00Z

Contributing to Zathura as a novice

2023-10-24

Earlier this year I made a patch for Zathura, the open-source PDF reader. In this post, I’ll document the journey of how I diagnosed the root cause of a bug in Zathura, then wrote a bugfix for it. As this is my first “real” patch that got accepted, the most important take-away for me is that it’s actually not that hard to contribute to open-source.

The bug

First of all, as seen in my last blog post, I make use of Zathura extensively in my note-taking setup. On one half of my window, I write markup in Neovim, and in the other half Zathura displays the rendered result. Every time I save the markup, it is automatically re-compiled, then Zathura reloads the document. Normally, this works really well, but if you’re reloading documents often, you’ll notice that there’s flicker every time:

Of course, this is not a deal-breaking issue. However, it is definitely annoying if you save often, and even more so if your editor automatically saves on change.

Upon finding this bug, I did what any normal person does and searched online to see if there was any fixes for it. I stumbled upon this GitLab issue: Prevent flickering when reloading document. Unfortunately for me, the thread was nearly empty, and the last comment was from another user seeking a solution.

Another thread on Stack Exchange was also a dead end, with no real answer to the problem.

At this point, there was clearly no easy solution to remove flicker from Zathura. Since this software is open source, I decided to take a look at the source code in an attempt to diagnose the issue.

Investigating source code

Zathura’s source code is available at their git repository. I cloned it to my projects folder:

git clone https://github.com/pwmt/zathura

At the time, the latest commit was c7baa2f6 (“Make icon visible on dark backgrounds”). If you want to follow along with the exact same code as I saw, run this command:

git checkout c7baa2f6

At first glance, it definitely can seem daunting to navigate an unfamiliar codebase. However, these days, we have language servers, which makes it much faster. Essentially, language servers are plugins for text editors that give language “intelligence”. With them, you can, for example, jump to the definition of a variable, or get completions when writing code. I find that language servers are useful especially in situations like these, where you might have no idea where a symbol comes from. For C, which Zathura is written in, I use clangd, which integrates easily with Neovim.

A necessary step to use clangd is to have a compile_commands.json file. Thankfully, with Zathura’s build system, Meson, this is automatically generated during the build. I followed the build instructions at the bottom of the README:

meson build
cd build
ninja

Then, I copied the resulting file back into the root directory.

cp compile_commands.json ../

Now, Neovim will automatically have language intelligence.

Still, we have no idea where the code responsible for the bug lies. Considering the bug happens upon reload, it would make sense to search for code related to reloading documents. To do this, I searched for the term “reload” using ripgrep (you could use git grep too):

rg "reload"

From here, I saw an interesting function signature in zathura/shortcuts.c:

sc_reload(girara_session_t* session, girara_argument_t* UNUSED(argument)

This looks like it could be the code responsible for reloading. Looking at it, this is the function body (heavily abridged):

bool
sc_reload()
{
  /* close current document */
  document_close(zathura, true);

  /* reopen document */
  document_open();
}

Surprisingly, reloading a document is implemented by closing and reopening the document, rather than a separate in-place refresh feature. This would explain why the screen flickers during reloads: the document disappears entirely before the new one is loaded in its place. It seems like there might be a moment between closing and reopening where there is nothing on screen, which is what causes jarring flicker.

Fixing the bug

So now, we’ve successfully diagnosed the root cause of the flickering. However, this provides no clear path towards solving it.

At this point, I decided to check out the document_close and document_open functions mentioned above. After studying these two functions, something caught my eye: during opening, we create zathura->pages, and during closing, we free it. Looking at the definition, zathura->pages is an array of pointers to GtkWidgets.

As an experiment, I commented out a bunch of code from document_close to see what happens if the pages are not freed. In my head, I thought it might leave the old pages on screen and let the new ones replace it. Obviously, that didn’t happen, and I got multiple segmentation faults, crashes and memory leaks (womp womp).

Now, I was practically at a dead end again. However, I remembered something the author of the Stack Exchange thread tried regarding this issue: they attempted to set render-loading to false to fix the flicker. On default settings, when the document is reloaded, a “Loading…” prompt flickers on screen:

Turning it off just makes the flickering a blank screen. I decided to look for code related to this prompt with rg "loading". Doing that, I found an interesting function in zathura/page-widget.c called zathura_page_widget_draw. Skimming the code, it looks like it handles drawing pages to screen. This was a promising new direction to look into.

Near the end, there is a section that takes care of drawing the loading screen. Reading above, we see that the loading screen only renders if the page has no Cairo surface. Essentially, if the page hasn’t fully loaded, put up a loading screen.

Here, I had an idea: what if we replace the loading screen with the original page from before the reload? That way, it would be a seamless transition from the original document to the new document.

To implement this, I added two extra pointers to the zathura struct: the predecessor_document, and the predecessor_pages. When Zathura closes the document for a reload, it preserves the current document and pages as “predecessors”. Zathura will not free the predecessor document and pages immediately. Then, in zathura_page_widget_draw, instead of drawing a loading screen, it will draw the predecessor pages. Since having an extra buffer also uses more memory, I added a toggle option smooth-reload that switches this feature on and off.

Of course, I’m skimming over many specific details here. To see the exact code of my patch, you can look at the commit on Zathura’s git repository.

Anyways, here is the end result of the bug-fix, where the bottom window is patched and the top one isn’t:

I was really ecstatic when Zathura first smoothly reloaded a document. It finally worked! After this initial success, I collected all these changes into a merge request on GitLab.¹ Finally, after a month of waiting, I got the maintainer to merge my patch. All in all, it took a weekend in total to get familiar with the codebase and create this patch.

Conclusion

At the time of writing, this patch is still only available in the bleeding-edge/git build of Zathura. To check that my code has made it into your version of Zathura, you can check in the man page zathurarc(5) for the option smooth-reload. (Since 0.5.5, smooth-reload is no longer an option, and it is the default behaviour.)

As of version 0.5.3, my code for flicker-free reload is enabled by default for all users of Zathura. Hopefully, this small contribution will improve the experience of future users of Zathura. Again, what I want to show in this blog post is that contributing to open-source is actually not that daunting. When you encounter odd behaviour in your favourite software, or you want improve a feature, do not be afraid to just open it up and start tinkering.

As of today the PWMT GitLab has since moved to GitHub (2025-07-19). ↩

WireGuard VPN server setup guide for Linux

2024-06-17T10:00:00Z

WireGuard VPN server setup guide for Linux

2024-06-17

Recently, I decided to set up a WireGuard VPN server for personal use. I found that existing guides about this subject are all lacking in some way. The server setup tutorials I found all go through the commands and configurations needed very throughly, but don’t explain why things work. Meanwhile, WireGuard’s Conceptual Overview focuses on the protocol itself and how it is different from others.

So, this post is a summary of my mental model of how WireGuard works, plus a tutorial for setting up the server. I assume that you have some knowledge of networking, but aren’t familiar with WireGuard. I also assume Linux knowledge. This guide should work generally, but I tested it on Arch Linux.

Note:

In this post, if you see an /24 at the end of an IP address, that’s CIDR notation. 192.168.0.0/24 could be written as “any address that fits the pattern 192.168.0.*”. Because there are 32 bits in an IPv4 address, the /24 at the end means that the first 24 bits (the first three bytes 192.168.0) are fixed, and the remaining 8 bits can be anything. Also, a /32 pattern matches only one address.

What is a VPN?

A VPN (virtual private network) is often advertised to the average user as an encrypted tunnel for their Internet connection. Mostly, this is useful for changing your IP address.

However, this is not the full picture of what a VPN is. In corporate networks, there are many important services that can’t be exposed publicly, which is why they’re only available on an internal, private network. Some off-site users, especially remote workers, need to access the internal network, but from the outside Internet. This is where a VPN can be useful: users can virtually be on the private network, as if they were on site. Using a VPN is more secure than publicly exposing services, as authentication allows fine-grained control over who can access the network.

For someone like me, VPNs are useful because I self-host private services. Normally, I would need to expose them to the public Internet to access them. Instead, I can access them solely through the local network or the VPN, preventing strangers from even seeing the login pages of my services. This reduces the attack surface and makes things more secure.

WireGuard setup

WireGuard is a relatively recent protocol for implementing VPNs. It’s shiny and new, and also has a slimmer codebase than older, more established protocols.

Let’s go through the process of setting up a VPN to access an internal network. The setup for tunneling all of a device’s Internet traffic is similar, and I will explain it too later. We will have a Client device, and a Server device. The Server is in the internal network (let’s say in the 192.168.0.0/24 subnet), and the Client is outside of it. There is also a publicly accessible domain vpn.example.com that resolves to the Server.

To recap, here is a diagram of what we’re trying to do:

 
   ╭────────────╮
   │ VPN Client │
   ╰─────┬──────╯
         │                  ╭────────────────────────────────────────────────╮
         │                  │ the private network (192.168.0.0/24)           │
         │                  │      ╭───────────────────╮                     │
 ╭───────┴─────────╮        │      │ VPN Server        │                     │
 │ public internet ├────────┼──────┤ (vpn.example.com) ├────── ⋯ other hosts │
 ╰─────────────────╯        │      ╰─┬───────────────┬─╯                     │
                            │ ╭──────┴──────╮   ╭────┴────────╮              │
                            │ │ machine 1   │   │ machine 2   │              │
                            │ │ 192.168.0.4 │   │ 192.168.0.7 │              │
                            │ ╰─────────────╯   ╰─────────────╯              │
                            │                                                │
                            ╰────────────────────────────────────────────────╯

On Linux, one of the quicker ways to set up WireGuard is through wg-quick, which is an utility that takes a config file and sets up WireGuard with it. In Arch Linux, this comes in the wireguard-tools package:

# pacman -S wireguard-tools

wg-quick stores config files under /etc/wireguard/. Each config file has the name [name].conf, where the file name is used as the interface name. These are the same network interfaces as wlan0 or eth0; WireGuard typically uses names like wg0.

Server configuration

An important thing to understand about WireGuard is that it makes no distinction of server or client: every device is a peer. To authenticate with each other, each peer has a private key, and a list of public keys of the peers it talks to. This is similar to how SSH’s authorized_keys works. To generate both the private key and the public key at once, use this command:

$ wg genkey | tee /dev/tty | wg pubkey
WDax5fhKcKwdeuiYjgi4w/34ig2aZuDjmLHYnWUtfGc=
pJApgMHuIvMMsApTNXA3MMq+82nQ30XuVbAk9jsBNRs=

The private key will be on the first line, and the public key on the second. Keep these keys around, as they will be useful later.

Let’s now see the config file for the Server:

# SERVER config
# /etc/wireguard/wg0.conf

[Interface]
Address = 10.0.0.1/32
# REPLACE THIS!
PrivateKey = [private key]
ListenPort = 51820

# make sure to replace eth0 by the appropriate interface
PostUp = iptables -A FORWARD -i %i -j ACCEPT; iptables -t nat -A POSTROUTING -o eth0 -j MASQUERADE
PostDown = iptables -D FORWARD -i %i -j ACCEPT; iptables -t nat -D POSTROUTING -o eth0 -j MASQUERADE

[Peer]
PublicKey = xZGlY8HIJt+rhGfbDK/T2xq0LQoR3kL6tGGVijaRBDI=
AllowedIPs = 10.0.0.2/32

First, let’s look at the [Interface] section, which contains information about the Server. It has the private key, and also the UDP port that WireGuard listens on (remember to open this in the firewall). The address marked here is the Server’s address. Its subnet is completely different from the LAN the Server is actually on (192.168.0.0/24). This is because we’re creating a brand new private network (10.0.0.0/24) inside the VPN connection, where our Client and Server will coexist.

Note: 10.0.0.0/8, 172.16.0.0/12 and 192.168.0.0/24 are all entirely reserved for private subnets, and you will not see them on the open Internet. To avoid collisions, the new VPN subnet should be different from the real LAN subnets for all peers. OpenVPN recommends obscure subnets like 10.66.77.0/24, which are equivalent to the middle of nowhere in IP address space.

There is also the PostUp and PostDown fields. These are commands run in bash after starting and stopping the VPN Server. I’m not going to go into the details, but I’ll explain in general what they mean:

iptables -A means to add a firewall rule when starting the VPN, and -D is to delete the rule when the VPN stops.
The %i variable is part of wg-quick, and it expands to the VPN interface name (e.g. wg0).
These rules in general allow the Server to forward packets, while masquerading. Essentially, just as a device can access the Internet through a router, the Client accesses the internal network through the Server. To do this, the Server will act like a router and perform NAT.
-o eth0 means the internal network is accessed over the eth0 interface.

Meanwhile, in the [Peer] section, we write the Client’s public key, which allows it to talk to the Server. Our Client has an address of 10.0.0.2, but instead of an Address field, we use AllowedIPs. These are the IP addresses that can be routed to and from this peer. Here are some examples to clarify what that means:

Let’s say the Server wants to send a packet to 10.0.0.2. WireGuard sees that peer xZGlY... (the Client) has this IP in its allowlist, so the Server sends the packet to the Client.
The Server wants to send a packet to archlinux.org (95.217.163.246). This IP is not in the peer’s allowlist, so it will not route the packet to the Client.
The Client sends a packet to the Server, with the source being its IP address 10.0.0.2. The Server sees that this IP is in the allowlist, so it accepts the packet from the Client.
The Client, who is now evil, decides to send a packet to the Server but impersonating another IP address: 10.0.0.69. This IP not being in the Server’s allowlist, it rejects the packet.

In general, you can see that the AllowedIPs field is what determines where packets can and can’t go. By setting AllowedIPs = 10.0.0.2, the server knows that the Client only has control over packets directed to or from that address. It is not allowed packets to or from any other IP. This concept of pairing the allowlist with public keys to manage packet routing is called cryptokey routing in WireGuard.

Also, by default, Linux disables IP forwarding. To enable it, edit /etc/sysctl.conf and add/uncomment the line

net.ipv4.ip_forward = 1

and run

# sysctl -p

to load the new configuration. If your VPN server is on the public internet, be sure to have sane firewall rules before doing this.

Note: If you use UFW as a firewall like me, note that it has its own sysctl.conf, which lives at /etc/ufw/sysctl.conf. This will override the regular sysctl if you follow the instructions above. To prevent it from erasing your changes, uncomment the relevant line:

# /etc/ufw/sysctl.conf

# Uncomment this to allow this host to route packets between interfaces
net/ipv4/ip_forward=1

Client configuration

Let’s now examine the Client’s configuration file. If the client is running Linux, it will also be in /etc/wireguard/*.conf, However, the wg-quick configuration format can be read by many other clients, like the WireGuard Android app.

Anyways, here is the configuration file:

# CLIENT config
# wg0.conf

[Interface]
Address = 10.0.0.2/32
# REPLACE THIS!
PrivateKey = [private key]

# be careful not to use CIDR notation here
DNS = 10.0.0.1

[Peer]
PublicKey = M/HD4qJYi1RlMH/K9xQ12yW6Cu62LuGasyZhfnVsbUE=

# do not forget the port here
Endpoint = vpn.example.com:51820

AllowedIPs = 192.168.0.0/24

You’ll see this configuration is very similar to the Server’s, which is natural as WireGuard devices are all peers. There are a few differences, though.

First, there is a DNS field, which can be used to prevent DNS leaks. This only works if the VPN server provides a DNS server too. Otherwise, set it to some other DNS server, or remove the line.

There is also the Endpoint field. This marks the Server’s public address on the open Internet. The Endpoint field is omitted in the Server configuration, as it is implicit: the Server will find out the endpoint IP when the Client reaches out to it for the first time.

Note: Technically, the Endpoint field not always strictly necessary. If SaveConfig is enabled in the [Interface] section, and either the Server or Client changes IP address while connected, roaming allows WireGuard to keep working and update Endpoint to the new address in the config file. I haven’t tested this, though.

Most importantly, we also have the AllowedIPs for the server. Here, it’s an entire subnet, and not just a single address. What this means is that if the Client wants to send a packet to a device on the internal network, say 192.168.0.4, WireGuard matches the IP to the subnet 192.168.0.0/24, takes the packet and routes it through to the server, which then forwards these packets to the machine at 192.168.0.4 in the internal network.

If the machine then replies with a packet, WireGuard sees it is from the 192.168.0.0/24 subnet, then routes it back to the Client. Using the VPN, the Client will be able to communicate with machines in the internal network as if it were there.

Running the VPN

wg-quick

To start/stop the VPN for both Client and Server (if they run Linux), you can use

# wg-quick up wg0
# wg-quick down wg0

where wg0 should be the name of your configuration file. Alternatively, there is a SystemD service you can use:

# systemctl start wg-quick@wg0
# systemctl stop wg-quick@wg0

or, to have WireGuard start at boot:

# systemctl enable wg-quick@wg0
# systemctl disable wg-quick@wg0

To diagnose issues with WireGuard, running wg show can be useful:

# wg show
interface: wg0
  public key: [snip]
  private key: (hidden)
  listening port: 49595

peer: [snip]
  endpoint: [snip]:51820
  allowed ips: 0.0.0.0/0
  latest handshake: 57 seconds ago
  transfer: 4.83 GiB received, 261.16 MiB sent
  persistent keepalive: every 25 seconds

This can show that there is no handshake at all between peers, and thus that there is no connection.

NetworkManager

There is also the option of using NetworkManager, which is neat if you already use it to manage your existing network connections. To do this, save your configuration file, and then import it through nmcli:

$ nmcli con import type wireguard file wg0.conf

Then, you can manage the connection as usual through nmcli:

$ nmcli con down wg0
$ nmcli con up wg0
$ nmcli con edit wg0

Mobile devices

On mobile devices, WireGuard apps can also use these configuration files:

F-Droid: WG Tunnel
Google Play: WireGuard
App Store: WireGuard

You can securely transfer the config files in a normal way, but I recommend using QR codes because it’s way simpler. Install the qrencode package, and do this:

$ cat wg0.conf | qrencode -t ansiutf8

█████████████████████████████████████
█████████████████████████████████████
████ ▄▄▄▄▄ █▄▄▄ ▀▀▀▄▀▄█▀██ ▄▄▄▄▄ ████
████ █   █ ██▄▀ █ ██▀▀▄▄▀█ █   █ ████
████ █▄▄▄█ ██▀▄ ▄▀▄█▄▄ ▄▀█ █▄▄▄█ ████
████▄▄▄▄▄▄▄█ ▀▄█ ▀▄▀ █▄█▄█▄▄▄▄▄▄▄████
████  ▀  ▀▄▀█▄▀█▄▄▄▄█ ▀ ▄▀▄▀▀█▀▀▄████
████▀█▄ ▀█▄  ▄██▄█ ▄   ▀▀▀▀▄ ▀▄█▀████
████▄█▄▄█▄▄█▀▄ █▀▄ ▀█▀▄█ █ ▀▀▀▀▀ ████
████▀ ▀█ █▄▄▄█▀█▀▀  █▄█▄▄▄▄  █ █ ████
████▀▄▀▀▄▀▄██   ▄██ ▄▀█  ███▀▄▀▀█████
████  ██▀▄▄█▀▀█▀▄ ▄▄ █▀▄█▀▄▀█ ▀█▄████
████▄▄▄▄█▄▄█▀ ▀▄▀ █ ▀ ▄█ ▄▄▄  ▄▄█████
████ ▄▄▄▄▄ ██▀▄ ▀ █ ▄ █  █▄█ ▄█▀█████
████ █   █ █ ▄ ▄▄ ▀ ▀█▀▄▄▄▄▄▄▄██ ████
████ █▄▄▄█ █▀   ▄▄█▄▀█▀▄█ █  ▀ ▄ ████
████▄▄▄▄▄▄▄█▄▄████▄▄▄▄█▄▄▄▄▄█▄███████
█████████████████████████████████████
█████████████████████████████████████

and the QR code will display in your terminal. On your phone, select the option to add a connection via QR code, and scan it. You can pipe any data to qrencode this way to generate a code, and it also creates PNG files if you select that format.

Encrypted Internet tunnel

I mentioned earlier that to the average user, a VPN is an encrypted tunnel they can run their Internet traffic through. The topology is

Client -> VPN Server -> public internet -> website

which makes it look to the website that the traffic originates from the VPN server. This is actually very similar to our internal network setup from before, which boils down to

Client -> VPN Server -> internal network -> machine

To achieve the Internet tunnel topology, we just need to modify the client configuration:

[Peer]
PublicKey = M/HD4qJYi1RlMH/K9xQ12yW6Cu62LuGasyZhfnVsbUE=
Endpoint = vpn.example.com:51820

- AllowedIPs = 192.168.0.0/24
+ AllowedIPs = 0.0.0.0/0

This [Peer] section refers to the Server. We modify AllowedIPs so that it includes all possible IPs (0.0.0.0/0), rather than just the internal subnet’s IPs.

With this, every time the Client tries to communicate on the Internet, for instance it requests archlinux.org (95.217.163.246), WireGuard will match that IP to the 0.0.0.0/0 (all IPs) mask, and route the packet to the Server. Then, the Server will forward that packet to archlinux.org.

Thus, we’ve made a VPN that works just like NordVPN or ProtonVPN, and all the others.

Note-taking with Typst and Neovim

2023-08-14T10:00:00Z

Note-taking with Typst and Neovim

2023-08-14

Warning: This post is outdated! Please see the updated 2026 version, which is a complete rewrite of this article with updated information.

A while back, I saw Gilles Castel’s series of blog posts about his note-taking setup with LaTeX and Vim. I was quite inspired by the idea, and I even tried it for a while, but gave up in the end. It was less effort to start writing in a plain text file than to write in LaTeX. So, these were my goals for a note-taking system:

Taking notes should be convenient. I should be able to to open a new notes page and start writing in a short amount of time.
The syntax for the notes should be easy to remember. If I need to look up syntax for common things, I’m wasting time.
I should be able to put basic math, figures, etc. in my notes.

Eventually, I found a typesetting system called Typst. Typst is kind of a mix between LaTeX and other formats like Markdown. On one hand, it’s designed for working with math and other technical subjects, like LaTeX. On the other hand, it has a relatively simple syntax reminiscent of Markdown. Compare these two snippets:

LaTeX:

Then, starting from 2:
\begin{enumerate}
    \item If the current number is composite, we skip to the next number.
    \item Mark all factors of the current number as composite.
    \item Move to the next number.
\end{enumerate}

Typst:

Then, starting from 2:
+ If the current number is composite, we skip to the next number.
+ Mark all factors of the current number as composite.
+ Move to the next number.

Because of the above advantages, I decided to start writing things down in Typst. In this blog post, I’ll be documenting my process and tools for Typst note-taking at the time of writing.

Neovim setup

Currently, I’m using the typst.vim plugin to integrate Typst with Neovim. It provides basic syntax highlighting, and recognizes .typ files as Typst files. The plugin also has a “watch” command that compiles your Typst file on change to a PDF. However, I haven’t figured out how to have it display compiler errors, so I have this in my Neovim config:

function TypstWatch()
    vsp
    vertical resize 20
    exec 'terminal ' .. 'typst watch ' .. expand("%:")
    exec "norm \<c-w>h"
endfunc
nnoremap <silent><leader>fc :call TypstWatch()<cr>
nnoremap <silent><leader>fr :silent exec "!zathura --fork " . expand("%:p:r") . ".pdf &"<cr>

This sets up a bind to open typst watch in a terminal pane on the right, with another bind to open the PDF in Zathura. Every time I save the content in my text editor, it updates the PDF seamlessly. It looks like this on screen:

Templates

Users of LaTeX or Typst often use templates in order to configure things like document size, layout, fonts, style, and so on. Instead of redefining these settings every time, we can just import them from a file. I won’t go into detail here; read the relvant Typst documentation for information. For reference, you can find my own templates at GitHub along with instructions for using them. The developers of Typst are working on better ways of packaging templates at the moment, so beware that they’re not the best example of how to write templates.

Anyways, you always need to import the templates for every new document you make, and you also need to pass in parameters like the title of the document. Typing all this boilerplate manually would be tedious, if done for every document. This is where UltiSnips comes in handy. UltiSnip provides snippets, which are templates of text that you can rapidly paste in the editor. For example, I’ve set it up so typing today and pressing Tab prints out the current date:

Snippets also support slots where you can type your own text. Every time Tab is pressed again, it moves to the next slot instantly. Here, you can see my snippet for new documents in action:

With this setup for Neovim, I have achieved the goal of being able to start writing new notes rapidly. It only takes around twenty seconds to open a new file in the editor, then fill out the template information, after which I can start writing.

Version control

When dealing with any textual content, a good practice is to put it under version control like Git. This is the norm for code, but it’s also viable for LaTeX/Typst content. The main advantages of this are:

You’re sure you won’t accidentally delete any data,
You can roll back to older versions, and
You can easily view what changed between versions.

For that reason, I set up a private GitHub repo for storing all my notes in a single folder. Besides that, I also set up the templates as a submodule. Like this, I can clone the notes repository and also get my templates set up at the same time.

Math & code

In the notes I’m writing, I often have to deal with mathematical expressions and code. You can see here that Castel gets a lot of use out of UltiSnips for rapidly typing math in LaTeX. However, in Typst, I find that these snippets are mostly unnecessary, since it has cleaner, simpler syntax for math in general.

For example, this is the LaTeX syntax for a fraction:

\frac{3}{2}

Typst has a much more minimal syntax:

3/2

Typst also has a simpler math “environment” syntax. Anything between dollar signs $"like this"$ is inline math. To use display math, add any spacing $ "like this" $ . With auto-pairs for Neovim, it only takes a single keystroke to start a math expression, and another to end one. See it here in action:

Another bit of syntax sugar that’s built-in to Typst is support for code blocks. Inline code is introduced by single backticks, while multi-line code is introduced by triple backticks. This is exactly the same syntax as in Markdown, which is much more familiar than \begin{verbatim}. It also provides syntax highlighting out of the box, without needing to import lstlisting:

Figures

Being able to draw diagrams in the notes is also a necessary feature. This part of my setup is mostly unaltered from Castel’s own method of drawing figures. Read his own blog post regarding drawing figures for the best explanation of how it works. To briefly summarize his post, Castel uses Inkscape to draw figures, with a shortcut script that accelerates the process. He says that he can draw almost as fast as his lecturers draw on the blackboard, although I’m not nearly skilled enough to do the same. Here’s an example from his blog post:

Again, read Castel’s blog post about drawing figures. Here, I will only explain the modifications I made to his process, assuming you already know how it works.

So, first of all, Castel’s shortcut manager (GitHub) is quite useful, and does indeed speed up drawing considerably. However, it’s built to deal with LaTeX only, which is not compatible with my notes. Therefore, I patched his scripts so that they hook into Typst rather than latexmk. The results of this are available on GitHub. Besides that, I also have a snippet for figures in Typst. It has slots for inputting the filename/ID of the figure, and also a caption for it. Once the snippet is pasted, I can hover over the filename and press <leader>ff, which opens that figure in Inkscape, or creates it if it doesn’t exist. Then, I can draw things, and have it appear in my notes. Here’s a full demo of drawing a figure (click for a non-gif version):

For now, there’s the limitation that there is no equivalent of PDF+LaTeX for Typst. This means that the font for the document is not synced to the font in the figures themselves.

Linking/references

Often, when I’m writing notes for a certain topic, I might want to reference another. Now, it is possible to use a relative path link to another PDF, but that doesn’t allow for referencing specific pages or sections. Castel himself solved this problem with Instant Reference, which creates links with the phd:// protocol, which is then handled specially by a script. However, I decided to make my own rewrite of the script in Python, in contrast to the original written in JavaScript. I prefer having my packages managed by the system’s package manager, rather than by npm. Python is better in this regard, because Arch Linux packages essential Python packages under extra/python-.*.

I have a bind set up to instantly copy a link to the currently viewed page in the PDF. For example, here I link to my algorithm notes in a document:

An extra feature I have compared to Castel’s version is referencing specific sections. This is helpful when you modify notes afterwards and a page number points to different content. A key bind in my PDF reader triggers a rofi menu where you select one of the sections visible on the current page, after which you can paste the link to that section seamlessly in your notes.

Conclusion

I’ve been using the above system for taking notes on competitive programming problems and computer science for a few months. I think that my goals of having a system for notes that was convenient, easy, and featureful has been accomplished. Indeed, I haven’t had to open up a plain text document for taking notes in quite a while; everything is in Typst now.

If you want to see the real configuration files behind all of it, check out my dotfiles on GitHub. The important files are src/.local/bin/typst-figure, and src/.config/nvim/typst.vim.

Maybe this post will sway you to check out Typst. But if it hasn’t, look at the example on their GitHub page. Hopefully, one day Typst will get wider usage, because it’s a great typesetting system.

Note-taking with Typst and Neovim in 2026

2026-01-01T10:00:00Z

Note-taking with Typst and Neovim in 2026

2026-01-01

More than two years ago, I wrote an article about the process of taking notes with Typst in Neovim; soon after, it became the most popular post on this blog.¹ Since then, however, the contents of that article have become outdated, so I’m writing this as an updated version of that post. The goal of this article is to again document how I write lecture notes in Typst, but now with the tooling of 2026.

Now that I’ve spent two years using Typst for taking notes, I can say that I’m quite happy with it. I’m at the level where I can effortlessly type notes as fast (sometimes faster) than instructors can write on the board, including mathematical notation. I also use Typst when typing up homework.

Recap

First, let’s recall the goals for my note-taking.

During lectures, I take notes in real time on my laptop, and I do not spend time after class to clean up my notes. This is a real example of how my notes look like (click for more detail):

Because of the way I write notes, it has to be fast and efficient, otherwise I can’t keep up with the lecture. More precisely, the following are my criteria for a good note-taking setup:

Taking notes should be convenient. That is, I can open my notes and start writing almost immediately. The system should be fast and responsive.
The syntax for writing notes should be easy to remember and to write. If the syntax for common things like fractions are painful to type, I’d rather use plain text or handwritten notes.
I need my notes to support math, figures, and related features for my courses.

Originally, I was quite inspired by Gilles Castel’s system which uses LaTeX for note-taking. Unfortunately, LaTeX fails some of the criteria above; it compiles slowly, which is inconvenient, and it has cryptic, weird syntax from decades ago.² So when I tried to write LaTeX, I ended up just giving up and writing plain text documents, because they are simply more convenient to write.

Then, I found Typst, which is sort of a mix between LaTeX and Markdown. On one hand, just like LaTeX, it’s designed for writing about math and other technical subjects, so it supports equations and figures. On the other hand, like Markdown, Typst has simple syntax. For instance, compare the notation for lists:

LaTeX:

\begin{enumerate}
    \item This is the first list item.
    \item Another entry.
    \item A last entry.
\end{enumerate}

Typst:

+ This is the first list item.
+ Another entry.
+ A last entry.

The Typst notation requires much less typing than the LaTeX notation. This is just one example; I would say that in general writing things in Typst is less wordy than writing it in LaTeX.

So, according to my criteria for a good note-taking system, Typst is the best, which is why I use it.

Compiling Typst in Neovim

Note:

This post focuses on local compilation, integrated with an editor (Neovim). For those who don’t live in the terminal, Typst has a closed-source web app, which is equivalent to Overleaf for LaTeX. The web app does have basic Vim binds, if that is what you need.

Let’s get started writing Typst.

Once you have Typst installed, you can already start writing in a .typ document with your favourite text editor. Run typst watch document.typ, and Typst will compile to document.pdf. There is no boilerplate required; just start writing text.

This process is fine, but navigating directories and opening a text editor, then a PDF reader can be slow. I wrote above that I want to be able to immediately write, and that is indeed possible with the workflow I use.

In this video, I demonstrate how I can start writing notes in less than 10 seconds:

Your browser does not support the video tag.

In this section, I’ll show how you can also integrate Typst to your editor like this.

Typst watch

I still use the same setup as I did in 2023: I have VimScript binds that open typst watch in a tiny side pane, and open a PDF reader (Zathura) to view the output besides the editor.

function GitRoot()
    return fnamemodify(finddir('.git', ";"), ":h")
endfunc

" compile typst doc on write
function TypstWatch()
       vsp
       vertical resize 20
       exec 'terminal ' .. 'typst watch --root ' .. GitRoot() .. " " .. expand("%:")
       exec "norm \<c-w>h"
endfunc

nnoremap <silent> <leader>fc :call TypstWatch()<cr>

nnoremap <silent><leader>fr :silent exec "!zathura --fork " . expand("%:p:r") . ".pdf &"<cr>

Every time I save the Typst source file, it compiles and shows the result in the Zathura window:

As you can see, errors are also displayed in the side pane.

Note: A difference from the original code is that we now have to set a compilation root for Typst. If your file accesses external data (e.g. images on disk), the data needs to be within the compilation root. (This feature prevents Typst files from reading your SSH private keys.) For my setup, I set the root of my notes Git repository as the compilation root.

To take notes, you first need to be able to navigate to the folder where your notes are, and open Neovim there. I’ve optimized this part of the workflow using zoxide and fish.

Zoxide is a “smarter cd command”, which lets you cd to directories without typing their full name. For instance, my notes are all in folders like ~/nt/university/25/term1/coursename, which would be tedious to type every time. But with Zoxide, I can write z nt course and it will jump to the correct directory.

Fish is a shell which is much much much better than bash by default. One of Fish’s great features is autosuggestions: when you type the start of a command, it will suggest commands from your history, which you can accept with Ctrl-F. As you can see here, I can type just z and it will complete the entire command:

Your browser does not support the video tag.

Fish autosuggestions save lots of typing, and the best part is that fish includes this feature right out of the box. There’s zero configuration³ for all good features in fish; just install it, and it’s an amazing shell right out of the box. Both Fish and Zoxide are cool because they save me immense amounts of time in any context in the terminal, not just taking notes.

Now that you understand the tools, here’s the process for opening notes at lightning speed:

Open a terminal using a shortcut in my tiling window manager.
Run z nt [course code] to get to a course’s notes folder.
Run nvim main.typ (I just have to type nv and fish completes the rest).
Press ,fc (start compiling Typst) and ,fr (open Zathura on this file).
Start writing.

Your browser does not support the video tag.

Note: (2026-01-18) Thanks to the reader who wrote to me saying navigating directories added lots of friction to writing Typst with Neovim. I realized I didn’t mention anything about zoxide and fish, which are tools I take for granted, but make the terminal experience so much more fun; I’ve now added this section to explain how fish and zoxide improve my workflow.

Tinymist

Since 2023, many things have changed in the Typst ecosystem. We now have proper Language Server Protocol (LSP) server support for Typst, which helps editors understand and manipulate Typst code. You can install the Tinymist language server, which has many features, like autocomplete, error detection, code formatting, and notably instant preview in a browser window. Every time you edit the document, Tinymist automatically compiles it and shows you a preview. You can even click in the preview, and have it sync position with the editor window:

Your browser does not support the video tag.

The one issue I have with Tinymist is that using it drains battery on my laptop (based on personal experience) which is a big disadvantage when typing notes in class. I assume this is caused by Tinymist recompiling at every keystroke rather than every time the file is saved. Because it consumes more power, I actually don’t use Tinymist that often, except for writing libraries in Typst.

To keep this post brief, I’ll avoid specifying too many details about how to set up language servers in Neovim; there is plenty of information out there already, and the configuration depends on how your specific setup works. One thing I will add here is that once you have Tinymist running, you can start the preview with the following Lua command (which you should bind to a key):

vim.lsp.get_clients({ name = "tinymist" })[1]:exec_cmd({ command = "tinymist.startDefaultPreview", title = "Preview" })

Note: If you hate having to configure everything but still like Vim-style editing, try the Helix editor, which automatically configures language servers (and many other features) for you. Once you have Tinymist running, use this command to start the preview:

:lsp-workspace-command tinymist.startDefaultPreview

I am looking to switch to Helix, but as of now the snippet support isn’t good enough.

Math & code

I often need to include math, and sometimes code in my notes. Typst is good at handling either of these.

Math

To write inline math, write $1 + 1 = 2$ (no spaces), and to write display math, write

$
1 + 1 = 2.
$

(Configure your auto-pairs plugin to recognize $ in Typst files.) You can write multiline equations with \, and align them with &, for instance

$
2 &= 1 + 1 \
  &= 1 + 1 - 1 + 1
$

gives this output:

As I mentioned above, the best part of Typst is how concise it is compared to LaTeX. Instead of \frac{3}{2}, you can write 3/2, and instead of \mathbb{R}, it’s just RR. This conciseness is especially good for people like me who are typing lecture notes in real time in class. At this point, I can sometimes type math faster than teachers can write it on the board.

See typst-undergradmath for a long list of examples of typesetting math in Typst.

Some things are still a bit tedious to write, though. For instance, to type a sigma sum, you need to type sum_(i=1)^n. While typing this expression, I mainly don’t like reaching my fingers off the home-row to reach the ^ key. A similar issue occurs with definite integrals, which are written integral_a^b. To optimize typing math, I use snippets in Neovim, specifically using the LuaSnip plugin.⁴ Snippets are like textual templates that let you fill in the blanks. When I type sum and then press Tab, it autocompletes the sum notation sum_()^():

Your browser does not support the video tag.

Unlike in LaTeX though, snippets are more a convenience rather than a necessity for typing fast, since Typst syntax is already short by itself. I would say that even without snippets, as long as you type fast, you can write Typst markup as fast as a lecturer writes on the board.

Snippets are also nice to use in other contexts, like completing today to 2026-01-01 in a journal file.

Code

Other than math, you might also want to write code blocks in Typst. Doing this is easy, and it uses the exact same notation as in Markdown, i.e. single ticks for inline code, and three backticks for code blocks:

This is `code`.

```python
print("this is code")
```

It’s just like typing code on Discord, and it even has syntax highlighting out of the box.

Figures

Another essential feature for writing lecture notes is drawing figures. The system I use is still generally the same as Gilles Castel’s method: draw figures in Inkscape, and include them in the Typst document. However, compared to 2023, my setup is a bit different. This is what the workflow looks like:

Your browser does not support the video tag.

When writing notes, whenever I want to insert a figure, I use a fig snippet, which inserts code like this:

#figure(
  image("fig/test2/label.svg"),
  caption: [Caption],
) <label>

(The label and Caption bits are blanks in the snippet that I fill in, and test2 is the filename of the document.) Then, after naming the figure, I hover over the filename and press a keybind to edit the figure. The keybind triggers a script (typst-figure) which creates the file if it doesn’t exist, and then opens Inkscape.

One important difference from my old setup is that I now use the TexText plugin to insert Typst math expressions in my figures. I edited the source code in my version of TexText so that the “save text” bind is Ctrl-s, which can be pressed by the left hand while my right hand draws with the mouse. Another difference is that I no longer use Gilles Castel’s Inkscape Shortcut Manager, and instead just use the default Inkscape binds (which aren’t too bad actually).⁵

Something I did keep from Castel’s setup is the quick style changer. He had “chorded” style keybinds:

Space + A: arrow
Space + A + G: bold⁶ arrow
Space + S: stroke
Space + S + G: bold stroke

and so on for a bunch of different styles. This lets you switch styles much faster than Inkscape’s default binds. One issue I ran into using the style switcher is that it needs a hacky X11 key event interceptor to make the binds work. Since I switched to Wayland, that doesn’t work anymore. Now, I have extracted Gilles’ style code to a Python script, and I connect it to fuzzel (which is like rofi for Wayland) in a style switcher shell script. Then, I use my window manager’s binds to trigger this style script. So the process in Inkscape to switch styles becomes:

Press Mod+A (calls style switcher).
Type the bind (e.g. ag for bold arrow) and press Enter⁷; this copies the style to clipboard.
Select an object in Inkscape and Ctrl+Shift+V to paste the style on it.

Admittedly, this method is slower, but it is more robust and will not break the moment I switch window managers. It even has the potential to work on Windows, provided you have a replacement for fuzzel and the clipboard tools.

Castel claimed to be able to draw figures with his tools as fast as the instructors could draw them on the board, but I still don’t have enough experience after two years to do that yet. Perhaps I just don’t draw that many figures in my lecture notes. Or maybe, my tooling is just not on his level.

Scripting

Typst is great not only because it’s nice to typeset with, but also because it has a sane scripting language built in. Typst is divided into a markup mode (i.e. normal, formatted text), and code mode, where you can write scripts. You enter code mode by typing #, and in code mode you can introduce markup with [].

Here are a few examples. If you need a small function that makes text bold and italic and smallcaps, Typst has got you:

This is *markup* mode text

#let very-emph = (content) => strong(emph(smallcaps(content)))

#very-emph[
  This is highly emphasized _markup._
]

(#very-emph[...] is shorthand for #very-emph([...]) which is calling the function very-emph on content.) If you want to make something render conditionally, Typst can also do that:

#if 1 + 1 == 2 [
    We have $1 + 1 = 2$.
] else [
    We have $1 + 1 != 2$??
]

Generally, I’d say that if you are used to regular programming languages like JavaScript, Typst’s scripting syntax will feel intuitive for you. See the later chapters of the Typst tutorial for more details.

I often use Typst’s scripting system for little things like making my own shorthands in math mode. For instance, I shorten the common real coordinate spaces like this:

#let Rn = $RR^n$
#let R2 = $RR^2$
#let R3 = $RR^3$
#let R4 = $RR^4$

So anywhere in math where I need to type ℝ², I can type R2, and so on for the others.

Another example is in a resume, where I make a template to format a section:

#let entry = (title, body) => {
  v(1.25em, weak: true)
  box(
    heading(title)
      + v(weak: true, 0.25em)
      + line(length: 100%, stroke: 0.7pt + black)
      + v(weak: true, 0.75em)
      + box(inset: (left: 0.75em), body),
  )
}

#entry[Education][
    *University of Ipsum* \
    _Bachelor of Something_
]
#entry[Skills][
    - Writing long-winded blog posts
    - Rust
]

These are simple examples, and Typst’s scripting language can do much more than that. For instance, I made a “smart” calendar powered by Typst’s scripting system.

Templates

Templates in Typst are like that resume entry function I wrote in the above section, but more featureful. Authors write packages which expose a template function; you call that function with the content of your document, and the template configures the paper size, font, layout, and so on. Templates separate content from style, and ensure you can focus on just writing.

In 2023, I rolled my own system for templates; I included all my template code in a .typ file and imported it in each new document I made. This was painful to use because there was no standard file path to import templates from; I had to place documents next to the template, and import by relative path, like ../../template.typ.

Soon after I wrote that article, Typst made their own official packaging system to easily distribute files like templates. Now, template authors publish packages to the Typst Universe registry.⁸ This way, documents are self-contained: rather than importing ../../template.typ, which might only exist on your computer, you import the standard package @preview/my-great-template:1.2.3. You can send a single .typ document to other people, or edit it on the Typst web app, and it will work just fine.

Now, whenever I want to start a new document, I can create a new .typ file anywhere, and import my template with this code snippet:

#import "@preview/mousse-notes:1.0.0": *
#set page(paper: "us-letter")
#show: book.with(
  title: [WUNK 101],
  subtitle: [Introduction to Wunkematics],
  subsubtitle: [Lecture notes, Fall 2023],
  subsubsubtitle: [Professor #smallcaps[Jonathan Bingus], University of Ipsum.],
  author: "John S. Student",
)

Note: book is just a function I wrote which takes content and transforms it, and show is syntax that says “call this function on the entire document.” It’s cleaner than wrapping the entire document’s content with a function call.

Or, even easier, I can paste the above boilerplate code with this single command:

typst init @preview/mousse-notes dir

which creates a notes file at dir/main.typ.

My template is available at its GitHub repo. And if you want to use my template, you can run typst init @preview/mousse-notes on your device too.

Another thing I do differently than in 2023 is the organization of my notes. In the past, I would make a new document for each chapter of a course; now, each course’s notes are contained in a “book” compiled from a single Typst document. Practically speaking, this means I only need to write the document boilerplate once at the start of each term, when I’m creating each course’s notes document.

Plugins

Typst Universe doesn’t just host templates; it also hosts plugins, which are also .typ scripts. A lot of these are useful, for example whalogen provides shortcuts to type chemical equations, and metro lets you type units. It is even possible to run Python in Typst.

For many tasks though, plugins aren’t strictly necessary. With whalogen, you can type #ce("HCl + H2O -> H3O+ + Cl-"), and without the plugin, it’s just longer: $"HCl" + "H"_2"O" -> "H"_3"O"^+ + "Cl"^-$ .

I personally dislike having extra dependencies, because it creates more maintenance burden. Oftentimes, the Typst compiler will have a breaking change (a downside of using software that is in its growth phase), and one of the plugins I use will break, or have annoying deprecation warnings.

Nowadays, I don’t use external plugins anymore: my template includes my own implementations of #theorem, #definition, #example, and so on. If it breaks, it’s my fault solely, which is good because then I can fix the issue myself.

Synchronizing notes

You may want to synchronize your Typst files so you can write on multiple devices. There are a few ways to do this.

Personally, I use Git to manage my notes. The main advantage of Git is that it is the industry standard for working with source code, and it is a highly reliable tool. The disadvantage is that you need to commit and push changes manually, which you might forget to do. (I mainly write on a single device, so this is fine.)
You could use Syncthing, which automatically syncs files across your devices. It just works. One annoying thing is that when there are sync conflicts, Syncthing will not notify you and it will instead create a “sync-conflict” file.
The most practical option (but one that goes against the idea of using local open-source tools) is to use the official closed-source web app for Typst. Unlike the two other options, you need to be online to access the web app. However, the web app synchronizes documents perfectly and lets you collaborate in real time with other people.

For the first two options, make sure that you exclude .pdf outputs in .gitignore or .stignore to save storage and bandwidth.

Conclusion

That’s all for how my current note-taking setup works. A general theme comparing the 2026 setup to the 2023 setup is that I’ve aimed for more minimalism and simplicity: a system with less moving parts is more reliable, and easier to maintain.

Notably, all my documents are now fully self-contained: they import my template from the standardized package registry rather than from a relative path, and they do not have external links. If you’ve read the 2023 version of this post, you’ll see that I created a convoluted setup to link between different PDF files. I spent much effort building the link system, only to never use it. Now, my documents are formatted as books that comprehensively cover one subject, so that I only need to link within documents (which is a feature Typst and PDF readers have good support for).⁹

Another way I’ve simplified the note-taking system is to trim out a lot of brittle external code and dependencies. I’ve trimmed down Castel’s Inkscape tools to the bare minimum, leaving only the style code itself, and as mentioned above, I’ve stopped using external Typst plugins. The projects I do rely on are generally well-maintained, like the Neovim editor, the Typst compiler itself, and TexText.

Looking forward to the future, I mainly wish I could reduce the complexity in my Neovim configuration. That is, I want to stop using as many third party plugins. The Helix editor (mentioned above) is quite promising in that a lot of the functionality in Neovim plugins (surround, Git gutter, telescope, lspconfig, tree-sitter, …) is available out of the box in Helix and maintained by their team. Once they have solid snippet support, I’ll switch fully to Helix and I’ll never again have to think about my huge Neovim configuration file, and the headache of configuring a dozen plugins.

Thanks for reading this far. If you have any questions or comments regarding this post, please do write to me, and I’ll be happy to reply to you.

Appendix: Configuration files

To keep this post brief, I did not include most of my configuration code. If you want to replicate my setup, here are the relevant configuration files on GitHub:

ftplugin/typst.vim (bind for typst watch)
ftplugin/typst.lua (tinymist)
snippets/typst.lua (snippets)
typst-figure (shell script to create figures)
stylinator.py (Inkscape quick style script)
style.sh (frontend to stylinator.py)

Edits:

(2026-01-18) Added section about zoxide and fish, made article reflect that mousse-notes is now on Typst Universe, changed examples of scripting

In fact, I moved to a new school a while ago, and some students I met there had already read my post. Hi :) ↩
This is, of course, just my personal opinion. ↩
Looking at you, zsh. ↩
In 2023, I used UltiSnips, but I got tired of it complaining about pynvim being missing on all my devices. ↩
Some of the binds I use are “toggle snap to grid” (%), “toggle grid” (#), the curve drawing tool (b), rectangle and circle (F4, F5). ↩
I think G stands for gras, “bold”? ↩
I bound Shift + V as Enter in fuzzel, so that my left hand can reach better. ↩
Or you can “publish” packages to a standard local folder on your computer. ↩
Removing inter-document links and enforcing a rule of “one subject, one document” is perhaps not ideal for those who want a personal knowledge management system, but it is good for writing course notes. ↩

Reviving a digital piano with new brains

2024-05-17T10:00:00Z

Reviving a digital piano with new brains

2024-05-17

One day, I was playing my Roland HP-1500 digital piano, which is an incredibly old model. It suddenly started making weird electrical noises, and then it died. I opened the piano up, and looked at the circuit board, but my efforts to figure out what went wrong were ultimately futile.

At this point, I had a thought: maybe I could build a brand new circuit for the piano, replacing the broken original board. After all, how hard could it be? I had just learned the basics of electronics, and this definitely seemed like a good learning experience.

That was a few months ago. Recently, I finished implementing this project, which I named geode-piano. Here is a quick demo of it (excuse the poor microphone quality):

Your browser does not support the video tag.

This project is powered by a single Raspberry Pi Pico, which runs firmware written in Rust. Source code and build instructions are available on the project repository.

It took quite a while to get to this point, and so this blog post will document the process of designing and implementing geode-piano.

How a digital piano works

First, before even designing anything, I did a bit of research on what was going on inside a digital piano. This helps understand how feasible the project is and how complicated it will be.

As it turns out, digital pianos are, electrically, pretty simple. The switches that detect key-presses aren’t that different from a regular push-button: when pressed, they let power through, which we can detect.

However, there’s 88 keys on a typical piano, and that’s a lot of switches to deal with. The microcontroller (processor chip) inside the piano usually can’t handle that many inputs.

This can be solved with a key matrix, a specific wiring design. Essentially, a key matrix helps cram all those key switches onto a microcontroller with way less input pins. For example, look at this key matrix:

     column
     1 2 3 4
row  
     │ │ │ │
  1 ─┼─┼─┼─┼
  2 ─┼─┼─┼─┼
  3 ─┼─┼─┼─┼

Columns are a power source, and rows are inputs. We hook up all of these wires to the microcontroller.

Each intersection in this grid has a switch. When a switch is on, power can flow (in only one way) from the column into the row.

The key matrix works by scanning each column sequentially. By detecting which rows are powered, we can deduce which switches were pressed.

     column                    column      
     1 2 3 4                   1 2 3 4     
row  ↓                    row    ↓         
     ┃ │ │ │                   │ ┃ │ │     
  1 ━╋━┿━┿━┿                1 ─┼─╂─┼─┼     
  2 ─╂─┼─┼─┼                2 ━┿━╋━┿━┿           and so on...
  3 ━╋━┿━┿━┿                3 ─┼─╂─┼─┼     
                                           
switches pressed:         switches pressed:
- C1R1                    - C2R2           
- C1R3

This scan is quite fast, usually taking less than a few milliseconds. Using this matrix, we need 8 pins, while an equivalent non-matrix circuit would need 12 pins. However, we sacrifice a bit of speed because we scan column by column rather than all switches at once.

In the digital piano, these switches are hooked up to the piano keys, allowing key-presses to be detected. On my piano, we have 176 key-switches (for reasons which I will explain later), which can be scanned using only 40 pins thanks to the matrix.

Note: This diagram and explanation are both simplified, so click here for a more detailled explanation. In practice, diodes are used to ensure power doesn’t flow the wrong way.

So that’s how a digital piano works, theoretically. What does that look like, under the hood? As it turns out, the matrix is accessible through ribbon cables (or flat flexible cable, or FFC).

The metallic contacts on these cables correspond to the columns and rows of the key matrix. Usually, you’ll find one or multiple ribbon cables with one end plugged into the main board of the digital piano, and the other ends leading inside the piano key mechanism.

Project architecture

geode-piano works by disconnecting the ribbon cables from the original circuit board, then reconnecting them into my own circuit. Effectively, I’m taking over the piano key circuitry.

Designing this, I tried to make things as easy as possible for me. Therefore, this project only exposes the piano as a MIDI controller. This means that we will only be transmitting data about what note was pressed when. Meanwhile, on a computer, we can make use of existing software to synthesize the actual piano sound from this data.

 ╭─────────────╮  ribbon cables  ╭──────────────────╮
 │ geode-piano ├─────────────────┤ piano key matrix │
 ╰──────┬──────╯                 ╰──────────────────╯
        │ 
        │
        │  midi over usb
        │
        │
╭───────┴──────────╮
│ software sampler │
│ (in a laptop)    │
╰───────┬──────────╯
        │
        │  3.3mm or usb or whatever
        │
╭───────┴───────────╮
│ speaker/headphone │
╰───────────────────╯

This is in contrast to actually generating the sound in my circuit and also playing it through a speaker, like the original board did.

I personally think that this architecture is the fastest way to get to a working product. After all, convincingly synthesizing a piano sound is difficult, so reinventing this wheel would be unwise.

Hardware

Now, physically, what does that [geode-piano] box in the architecture diagram above look like? The answer is that it looks like a mess.

Microcontroller

First of all, the heart of geode-piano is the Raspberry Pi Pico microcontroller, which is the green chip in the image above. I had a few laying around, so it was the obvious choice for me to use. This part actually runs the firmware, does all the processing, and also connects back to a computer via a micro-USB port.

Sockets

Then, there are the sockets above. Those are actually FFC sockets, which the ribbon cables can be plugged into. This is definitely one of the cursed parts of this project, because these sockets are designed to be soldered, and not to be used with jumper cables. In fact, I had to slice off the tips of a bunch of female-to-male jumper cables to get them to connect to the pins. I am still quite surprised that the pins snap perfectly in the female ends.

This arrangement of many jumper cables in parallel going up to the sockets was also a bad idea, as it caused crosstalk. In tests, it showed up as ghost signals being detected with no visible source. Twisting some wires together and attempting to space them out fixed this issue.

As an aside, I originally bought the wrong size of socket due to carelessness. I put up a ruler to the contacts and eyeballed the pin pitch (distance between each contacts’ centers), and decided it was 1.0mm. This was a big mistake on my part, as I found out later that it was 1.25mm.

After this, I discovered that the socket specsheets had measurements of the distance between the first and last contacts, which is easier and less error-prone to measure with a typical ruler. Actually reading these documents should help me avoid these kinds of mistakes.

Pin extenders

The astute among you might have noticed that a Pico microcontroller does not have enough input pins for this project. To remedy this issue, I used two MCP23017 chips, which are pin extenders. Each has 16 GPIO pins, and they communicate over I²C to the Pico, which requires only 2 pins on that end. For these 14 extra pins we get, we sacrifice a bit of convenience and efficiency.

One of the features of these chips is their capacity for both input and output. This is important because I don’t actually know which contact on the ribbon cable corresponds to which row and column. Instead of reverse-engineering the circuitry with a multimeter, I made a scanner that will try every row/column combination possible for each key until it finds a valid one. With this information, we can reconstruct the key matrix pinout.

Note: A few important tips I would tell past me about this chip:

You need pull-up resistors for I²C. I won’t go into detail about it because the linked blog post sums up my experience with this.
Multiple I²C peripherals can live on the same bus.
Plug the RESET pin into the positive power rail. I was stuck for an entire afternoon because no documentation said this clearly. In the datasheet, “must be externally biased” means “do not leave this pin floating under any circumstances”. Also, the overbar on the pin name in the datasheet means that pulling the pin low will cause a reset.
MCP23017 chips are known to have weird behaviour on pins GPA7 and GPB7. (Look at the most recent datasheet, not the old one!)

Firmware

If you’ve used microcontrollers before, you probably know that they’re programmed using C++, C, or MicroPython, or some similar language. The Raspberry Pi Pico is no different, as the most common ways to write firmware for it are the Pico C SDK, and MicroPython.

I had tried C before, but the tooling was painful to deal with. My language server clangd would display unfixable errors about missing imports and unknown functions. This was fine, but it was really annoying. MicroPython does seem quite user-friendly, but for scanning the key matrix, it could be problematic due to performance concerns.

In the end, I settled on using Rust. This option seems relatively obscure and less well documented, however it ended up working well for me.

The main advantage of Rust for me is that it is a modern, yet quite performant language. Even in a no_std embedded environment, you have a full package manager to easily install libraries. The MCP23017 library, for example, let me develop that part of the code faster. Also, rust-analyzer works perfectly well, and gives the most detailled and helpful messages out of all language servers I’ve used before.

Specifically for this project, I used the embassy-rs framework. This library makes embedded development in Rust really easy. It offers drivers for a bunch of useful features, like USB MIDI, USB logger output, I²C and many others. Embassy also works using async/await, which makes multitasking simple and elegant. I’m not a Rust expert, though, so consult their website for more information about this.

Even though Rust is great, it does have an infamously steep learning curve. As you might know, Rust is memory-safe by using a strict borrow checker. If you follow its rules, you can eliminate many types of memory bugs. In this project, though, I spent many hours fighting Rust’s borrow checker. What I learned from this experience is that, when possible, you should follow Rust’s idiomatic ways of solving problems. This means that you should avoid long-lived references, and keep lifetimes short. Essentially, don’t overcomplicate the program logic.

Anyways, the source code for geode-piano’s firmware is available on the project repository.

Other features

That was the general overview of the project. These are a few miscellaneous details that I could not fit well elsewhere.

Velocity detection

A digital piano is, electronically, just a bunch of buttons that trigger sound when pressed. There is, however, a slight nuance to this. A button switch has only two states, on and off. On a piano, hitting a key really hard makes a loud note, and softly pressing it makes a soft note. From the perspective of our hardware, a button press is just a button press; there is no information about intensity.

To measure the intensity of key-presses, some engineer decided that instead of every key having one switch, they should have two switches. These switches are placed so that they trip one after the other during a keypress. By measuring the time between the switches’ activations, the digital piano can estimate the intensity of a press. A fast press is a hard press, and a slow press is a soft press. This system works well, and is present in most digital pianos.

geode-piano does have velocity detection too, but it is not very precise. I think this is because it takes too long for the key matrix scan (around 7ms), which is not fine-grained enough to accurately detect velocity. Possibly, it is because of the MCP23017 being too slow, but it could also be my code. At this point though, the piano works well enough that I do not feel it is worth it to optimise this.

Sustain pedal

Pianos have pedals that control the sound. The code for handling this is not quite different from handling regular keys. However, connecting the pedal to the microcontroller is more difficult. Typically, the pedals are connected to the piano via a TRS jack (not dissimilar to a headphone jack). However, I had no socket component for this type of plug. Therefore, I made the most cursed part of the circuit:

The brown wire is stripped on the part where it wraps around the plug, and the yellow and pink parts are stripped paperclips. This may seem like a fire hazard, but the wire connected to an input pin, so unless the microcontroller uses the wrong pins (in which case we have bigger problems) there should be no short-circuit risk.

In my experience so far, this connection actually works remarkably well. Another win for terrible wiring.

Conclusion

This project was pretty fun to do. Before starting it, I thought that it was pretty ambitious for my skill level; at the time, I’d only played with wiring LEDs and buttons up to my microcontroller. Who knew that I could implement the circuitry for an entire digital piano?

I did learn a lot about electronics through this project, as well as a bit of Rust. I don’t remember where I heard it anymore, but I agree with the notion that you should try projects like this that are just barely within your capacities to accomplish. This kind of hands-on learning is one of the better ways to develop problem-solving skills.

Anyways, I now have a working piano again!

MinRSS, a lightweight feed reader

2023-05-14T10:00:00Z

MinRSS, a lightweight feed reader

2023-05-14

Purpose

If you want to read content online from many different websites, the best way is to subscribe to RSS or Atom feeds. It’s a simple, universal format for getting content onto your screen.

I personally enjoy living in the terminal. One of the more popular RSS readers for this environment is Newsboat. Newsboat has tons of useful features and a pretty TUI, and I did use it for a while.

However, I thought that it was too complex for what I needed in an RSS reader. Therefore, I decided to write a new one: MinRSS.

Concept

MinRSS is a small binary that “does one thing and does it well”: it downloads RSS articles to disk.

Essentially, every feed is represented as a folder, and individual articles are files in these folders.

Every time the binary is run, it creates a structure like this in the current working directory:

rss
|--news
|  |--article1
|  `--article2
`--blog
  |--post
  `--other_post

If an article is new (it wasn’t on disk already), its filename is printed to standard output.

The goal of doing things this way is to make writing scripts as easy as possible. If you’re familiar with shell scripting, all you need is jq and you can now parse RSS and implement any custom feature you want.

If you felt masochistic, you could even read RSS feeds using only your shell, minrss, ls, head and w3m.

This sort of structure is inspired by suckless.org’s ii and sic.

Wrapper script

I wrote my own wrapper script around MinRSS, called mrss. It has the following features:

Update feeds using MinRSS
Show all new articles using fzf as an interface (as seen in the screenshot above)
Mark articles as read
Mark articles as “watch later”
Custom handler for opening videos and podcasts in mpv

Installation

First, ensure you have the requirements:

libcurl
libxml2
json-c
xdg-open

Clone the repo:

git clone https://github.com/dogeystamp/minrss
cd minrss

Edit the config file. The comments in config.h should guide you:

cp config.def.h config.h
vim config.h

MinRSS outputs human-readable output by default. The wrapper script will only work with these options set:

static const enum outputFormats outputFormat = OUTPUT_JSON;
static const enum summaryFormats summaryFormat = SUMMARY_FILES;

Then, build and install MinRSS:

make install

Install the wrapper script:

cp contrib/mrss.sh ~/.local/bin/mrss
chmod 755 ~/.local/bin/mrss

Usage

For complete help, run mrss -h.

To get started, all you need is mrss update to update feeds, then mrss fzf to view articles. Articles are, by default, saved to ~/rss, but you can set $MRSS_DIR to change this.

fzf shortcuts

In mrss fzf’s interface, the following commands are available:

Command	Shortcut	Description
`/read`	`Enter`	Opens link in the browser or `mpv`
`/purge`	`Ctrl-D`	Mark article as read
`/purge-all`	`Ctrl-Alt-D`	Mark all articles as read
`/watch-later`	`Ctrl-W`	Send article to the watch-later folder
`/queue`	`Ctrl-E`	Queues link to be opened after leaving `fzf`

You can also use Tab and Shift-Tab to select multiple articles to be acted upon.

Viewing specific folders

The mrss fzf command can be used to view a specific folder’s contents.

To read all null-program articles (regardless of if they are marked read or not):

mrss fzf null-program

To view new null-program articles:

mrss fzf new/null-program

To see articles you’ve marked as “watch later”:

mrss fzf watch-later

Creating meta-feeds

In the latest version of mrss, you can create tags to categorize your feeds. First, create a directory for your tag under $MRSS_DIR:

mkdir ~/rss/tag

To include new articles for a given feed:

ln -sr ~/rss/new/feed ~/rss/tag/

To include all articles:

ln -sr ~/rss/feed ~/rss/tag/

To view this tag:

mrss fzf tag

Making a virtual machine from scratch (in Rust)

2024-01-20T10:00:00Z

Making a virtual machine from scratch (in Rust)

2024-01-20

Computers are wonderful machines that can do many things. However, even though they are very complex, at their core they are surprisingly simple. In fact, with only basic programming knowledge, it is possible to simulate a fully-functioning computer akin to modern ones.

In this post, I document how I built a virtual machine for Little Computer 3 (LC-3), an educational computer model. LC-3 may be simple, but it works the same way any modern computer does: through implementing it, you get a glimpse of how real architectures like x86 or ARM work. Besides that, once you’re finished, you can play 2048 in the VM you created from scratch. Is there anything more gratifying?

Writing a virtual machine is also a great test of your programming ability. I decided to do this project in Rust, in order to learn how the language works hands-on. I’ve mostly had experience with C and Python before this, and this was my first Rust project. However, this article will focus more on the virtual machine aspect, rather than the Rust.

If you’re just looking for the source code, check it out on GitHub: dogeystamp/lc3-vm.

Prerequisite reading

I assume you have a certain amount of fundamental knowledge before reading this article:

Programming knowledge (preferably in Rust or C). I assume you know programming decently well, but are not familiar with virtual machines. I’ll give code analogies in C, and I assume you can figure out what the Rust means with prior knowledge in other languages.
Binary arithmetic. Computers, at their fundamental level, deal with exclusively binary. You should know bitwise operations, like left/right shift, AND, NOT, OR, etc. to see how binary is manipulated. You should also be familiar with hexadecimal and binary number representation.

Besides that, I aim for this article to be shorter and more of an overview of topics that were interesting to me. For all the context and implementation details, see Justin Meiners’ and Ryan Pendleton’s blog post which meticulously explains LC-3, as well as the LC-3 ISA specification.

What’s inside a VM?

Starting off, here is some theory to get you in context. Skim this if you are familiar with how everything works.

LC-3 can be modeled with three simple components: the processor and registers (CPU), and memory (RAM).


    registers
    [ ][ ][ ][ ][ ]
    [ ][ ][ ][ ][ ]
    +-------------+     +------------------------+
    |             |     |                        |
    |  processor  |-----|         memory         |
    |             |     |                        |
    +-------------+     |                        |
                        +------------------------+

Memory

First, memory is where most temporary data lives in the computer. The easiest way for me to visualize it is a huge C-style array:

uint16_t mem[65536];

Instead of an index, we use an “address” for each element. Just like an array, we can read and write (get or set) the data at each address. When the computer shuts down, all data in memory is lost. (For data to persist, we use storage like hard drives, but LC-3 doesn’t have this.)

In LC-3, each element in memory is 16 bits, or 2 bytes. At this level, memory does not have any types as they do in languages like C: it’s all raw binary. Typed variables, malloc and the stack are all abstractions on top of memory.

Registers

Second, registers are where data that is immediately useful is stored. They are also 16-bit just like memory elements. Think of it as having fixed variables. LC-3 has 10 registers:

the general purpose R0 to R7,
Program Counter (PC),
and the Processor Status Register (PSR).

I’ll explain the last two later. Just like variables, you can assign values to the general purpose registers, and read from them:

uint16_t r0 = 0;
...
uint16_t r7 = 0;

r6 = r0 + r7;
r3 -= 3;

The reason registers exist when we already have memory is that it’s way more convenient to use. Physically, registers are closer to the processor than memory is, and are therefore much faster. Besides that, reading/writing from memory usually takes more instructions than just using registers. However, in exchange for convenience and speed, you have to deal with a limited amount of registers.

Processor

Finally, the processor is where the real computing happens. The processor reads instructions one by one, and executes them. Instructions are like statements in higher level code, but much simpler.

LC-3 only has 15 different types of instructions, that do things like “read memory at this address and load the value into R4”. Instructions are just 16-bit binary data. Again, read the ISA specification for detailled information about this. For example, the spec says this is how to ADD two registers and store the result in a third register:

ADD
| 0 0 0 1 | DR | SR1 | 0 0 0 | SR2 |

DR (Destination Register), SR1 (Source Register) and SR2 are all placeholders for general registers. For example, if we wanted to do r1 = r2 + r3:

ADD         r1      r2      (...)   r3
| 0 0 0 1 | 0 0 1 | 0 1 0 | 0 0 0 | 0 1 1 |

or in hex:
0x1283

As you can see, this is pure binary data, and as such can be read by the processor. When you compile a C program, machine code like this is what comes out.

There exists assembly which is a human-readable version of this binary. Unlike regular code, it is a 1-to-1 correspondence to the binary. For example, the above ADD instruction would be

ADD R1, R2, R3     ; you can put comments using semicolon

Using an assembler, a programmer can convert the assembly code into the pure binary program that LC-3 can read.

Fetch-execute loop

Now that the individual parts are explained, we move on to how it all works together. So far, I haven’t explained where the instructions actually come from. Since instructions are just binary data, we actually just place a series of them (a program) in memory:

address  value (hex)  equivalent assembly code
0x3000:  [e002]       (LEA R0, HELLO_WORLD)
0x3001:  [f022]       (PUTS)
0x3002:  [f025]       (HALT)
...

The Program Counter (PC) register we talked about earlier is a pointer to the instructions inside a program in memory. In LC-3, as seen above, PC starts at the address 0x3000. The processor will perform a fetch-execute loop:

Fetch the instruction in memory using the PC (instr = mem[PC])
Increment PC (PC += 1)
Execute the instruction
Repeat on the next instruction

Until it reaches an instruction to stop (HALT), the processor will continue this loop. Remember that PC points to the next instruction, not the current one! This often tripped me up implementing the virtual machine. The reason it doesn’t point to the current instruction is that it makes the mechanisms in the next section easier to understand.

Control flow

If statements, switches, and loops are all implemented using two instructions, JMP and BR, which alter PC.

JMP (jump) directly sets the value of PC, which means on the next fetch-execute loop, the processor will not execute the next instruction, but rather the instruction at the new PC. This is what goto in C does under the hood.

Meanwhile, BR (branch) conditionally sets the value of PC. Remember the PSR register mentioned earlier? The bottom few bits in PSR contain condition flags. Condition flags essentially represent the sign of the result of an operation like AND or ADD. Respectively, they’re P (Positive), Z, (Zero), N (Negative). BR works with these flags: for example BRnz is “jump if result is negative or zero”.

Let’s see how a for loop would be implemented this way:

AND R1, R1, #0    ; set R1 to 0 (anything bitwise and 0 is 0)
ADD R1, #5        ; set R1 = R1 + 5

LOOP_START        ; this is a label

... (for loop body)

ADD R1, #-1       ; R1 = R1 + (-1) (decrement)
BRp LOOP_START    ; loop back. once assembled, the label becomes a numerical address offset

HALT              ; we're done

The equivalent in C:

for (int i = 5; i > 0; i--) {
    // for loop body
}

It’s also common practice to AND a register with itself to check if it is positive/negative/zero. The the register AND itself is the same value, which allows testing without altering the register’s contents.

Subroutine calls

LC-3 has support for “subroutines”, which are like functions but less convenient. Practically, LC-3 can jump into a subroutine, then at the end of the subroutine, jump back to the place where the subroutine was called. This works using instructions like JSR, and RET.

JSR means “jump subroutine”, and it is essentially the same as JMP, however it also saves the current PC into the register R7. At the end of the subroutine, we put the instruction RET, which is actually a disguised JMP. RET means “JMP to the address given in R7”, which means return to the place where we originally used JSR.

An example usage:

    AND R1, R1, #0      ; random code
    JSR   SOME_ROUTINE  ; call subroutine
    HALT

SOME_ROUTINE
    ADD, R1, #1         ; random subroutine code
    RET                 ; return

This code will first set R1 to 0, jump into the subroutine, increment R1, then return to the main part and stop the program.

Memory mapped I/O

Earlier, when I described how the LC-3 virtual machine works, I omitted a pretty significant component: input and output. I/O is the sole method that the virtual machine can communicate with the outside world, whether it’s receiving user input, or sending output.

LC-3 uses a terminal for I/O, which means it can work with standard input (stdin) and standard output (stdout). Input is done via keyboard, and output via display. The way this works is memory-mapped I/O. In LC-3’s memory, there are specific addresses that connect to external I/O devices.

             +----------------+     +----------+
    ··· -----|     memory     |-----| terminal |
             +----------------+     +----------+

This is useful because LC-3 can reuse the existing instructions for loading/storing from memory to talk to the terminal. When it manipulates the special memory-mapped locations (device registers), it doesn’t actually store or load data from memory, but it communicates with the peripherals like the display or keyboard.

Here is a full list of memory-mapped addresses in LC-3:

addr      name                              short description

0xFE00    keyboard status register (KBSR)   has a key been pressed?
0xFE02    keyboard data register   (KBDR)   what key was pressed?
0xFE04    display status register  (DSR)    can the display receive a character?
0xFE06    display data register    (DDR)    character to send to the display
0xFFFE    machine control register (MCR)    power button

For example, to read keyboard input, a program would first poll bit 15 (the ready bit) of KBSR to wait for the user to press a key. If the bit is 0, then the program keeps waiting. Otherwise, the bit is 1, and that means the user pressed a key. Then, the program reads bits [7:0] from KBDR into its registers. This contains the key that was pressed, encoded as ASCII. To read more characters, it would continue this loop.

As an aside, remember that by convention, the least significant bit (the right-most units bit) is bit 0, and the other bits are numbered right-to-left as 1, 2, 3, and so on. Not realizing this has caused me issues while implementing this VM, as the program was reading from bit 15, while my VM was providing information on bit 0 (which if numbered left to right, is bit 15).

Displaying data is similar: the program first polls bit 15 of DSR (the ready bit) until the display is ready to receive a character. Then, the program stores a character in DDR encoded as ASCII. This character is finally sent to the display.

The program can also halt the computer (shut it down) by setting MCR to all zeroes.

For detailled information, again, consult the LC-3 ISA specification, specifically the Device Register Assigments.

Assorted implementation details

Now that we’ve gone through the basics of how LC-3 works, I’ll go through some interesting details that I encountered during implementation. If you came here to follow along implementing yourself, I recommend you read Meiners’ and Pendleton’s LC-3 blog post, which is actually a tutorial. For a Rust version, see Rodrigo Araujo’s implementation.

Endianness

Endianness is the order bytes are stored in memory within a word (a single piece of data). There’s big endian, and little endian. By definition, big endian starts with the most significant byte, and little endian starts with the least significant byte. By “most significant”, it means in numbers like decimal 123, the hundreds position is “more significant” than the units position.

However, I find it more comprehensible to think that big endian is the “natural” order, while little endian is the “reversed” order. For example, take the number 0x12345678. On a big endian system, it would be stored in memory like this:

address  value (hex)
0x0001:  12
0x0002:  34
0x0003:  56
0x0004:  78

However, on a little endian system, it would be like this:

address  value (hex)
0x0001:  78
0x0002:  56
0x0003:  34
0x0004:  12

Supposedly, it is easier to deal with little endian on processors, which is why it is used in many popular CPU architectures. However, LC-3 uses big endian. This is an issue to consider during implementation.

For example, if you use hexdump on a program file, you may see this:

0000000 0030 02e0 22f0 25f0 7900 6f00 7500 2000
0000010 6c00 6900 6b00 6500 2000 7600 6900 7200
0000020 7400 7500 6100 6c00 6900 7a00 6900 6e00
0000030 6700 2000 6200 6f00 7900 7300 2000 6400
0000040 6f00 6e00 7400 2000 7900 6f00 7500 0000

This is actually incorrect output! hexdump assumes groups of two bytes are a single little-endian word, so it flips it to make it the proper order. However, LC-3 data is in big endian order.

hexdump -C prints bytes as they are on disk, which produces the proper ordering:

00000000  30 00 e0 02 f0 22 f0 25  00 79 00 6f 00 75 00 20
00000010  00 6c 00 69 00 6b 00 65  00 20 00 76 00 69 00 72
00000020  00 74 00 75 00 61 00 6c  00 69 00 7a 00 69 00 6e
00000030  00 67 00 20 00 62 00 6f  00 79 00 73 00 20 00 64
00000040  00 6f 00 6e 00 74 00 20  00 79 00 6f 00 75 00 00

It is important to flip bytes or specify that the data is big-endian when reading programs into memory from a file.

Integer overflow

You may know that because integers are represented by a finite amount of bits, it is possible for them to overflow when they get too big. For LC-3, we usually implement registers and memory using unsigned 16-bit integers, which gives us a range of 0-65535. This is also the limit of our memory’s size, since we can not represent an address bigger than that. The same issue makes 32-bit computers unable to have more than around 4GB of memory ((1 << 32) - 1).

When integers overflow, they often wrap around back to 0 or the lowest number possible. This is necessary behaviour on the LC-3, as it makes it possible to use signed numbers in 2’s complement. There is no subtract operation, we just add negative numbers, and it magically wraps around to the correct value. However, we usually do not want integer overflow, so Rust complains when it happens:

error: this arithmetic operation will overflow
 --> test.rs:2:20
  |
2 |     println!("{}", 65535u16+1u16)
  |                    ^^^^^^^^^^^^^ attempt to compute `u16::MAX + 1_u16`, which would overflow
  |

Earlier, I mentioned Rodrigo Araujo’s VM, which was also written in Rust. This implementation served as a Rust reference for me. In his instruction implementations, he uses casts to perform wrapping arithmetic:

let addr = (vm.registers.get_reg(base_r) as u32 + offset as u32) as u16;

First, he adds parameters as 32-bit unsigned ints, then casts it back to 16-bit unsigned. I personally did not know what behaviour this cast would have, but upon further experimentation it turned out that it does a modulo operation in the cast. This means that if the value exceeds the u16 limit, it wraps back to 0.

Personally, I found this to be a very janky, implicit way to perform wrapping arithmetic. After all, it took me multiple Google searches and a bit of testing to be sure of what the code was doing. In my own code, I use explicit syntax for a wrapping addition:

let addr = vm.registers.get_reg(base_r).wrapping_add(offset);

This code is much clearer, and, quoting the Zen of Python, Explicit is better than implicit.

Traps

Earlier, in the memory-mapped I/O section, we saw how LC-3 can use memory-mapped I/O to talk to external peripherals. You may have noticed that all of this is a very tedious process just to get some user input. To simplify things, LC-3 implements traps. Traps are essentially utility subroutines that make life easier. These can be accessed with the TRAP instruction, along with a code to specify which subroutine the program wants (the trap vector).

However, instead of the programmer writing these subroutines, traps are part of an operating system on the LC-3. The operating system is also a program (it is also comprised of a bunch of instructions in memory), however it runs with higher privileges than the user program. The OS is stored in a special location in memory, earlier than the user program memory.

When a TRAP instruction is called, LC-3 takes the trap vector, looks up a corresponding address in the trap vector table (a section in memory before the operating system), then calls that address as if using the JSR instruction on a subroutine. These addresses all lead to subroutines within the OS. For a C analogy, it’s like the trap vector table is an array of function pointers, where the functions are part of the operating system.

Here is a list of trap subroutines in LC-3. Consult the LC-3 ISA specification for a detailled explanation.

trap vector    name    description

0x20           GETC    get a single character from keyboard (like C's getchar())
0x21           OUT     put a single character to terminal
0x22           PUTS    put a string to terminal
0x23           IN      get a single character with echo (show the character typed)
0x24           PUTSP   put a string to terminal (two characters packed per memory address)
0x25           HALT    shut down the computer

As you can see, these are high level wrappers for the memory-mapped I/O seen in the last section, and are also much friendlier to work with in general. Importantly, these routines can all be implemented in LC-3 code.

For my own virtual machine though, and Justin Meiner’s VM that inspired it, we do not actually write assembly code for trap routines. Instead, in the VM itself, we intercept these trap calls, and perform the tasks in high-level C or Rust code, instead of LC-3 assembly. This is generally simpler, although less faithful to the specification. Because of this, it is also not necessary to implement some of the memory-mapped registers, like the display registers, and the machine control register.

For example, here is my code that performs GETC:

fn trap_getc(vm: &mut VM) {
    while vm.mem.get_mem(0xFE00) & (1 << 15) == 0 {}
    vm.registers.r0 = vm.mem.get_mem(0xFE02) & 0xFF;
}

First, we poll the Keyboard Ready bit, then we load the keypress into the VM’s registers. This type of implementation is much more convenient than writing raw assembly. My own GETC is not really efficient, but using standard library getchar() or an alternative would avoid polling the ready bit constantly. Right now, with the polling loop, we use up a lot of CPU on the host machine running the VM, when we are doing nothing but waiting. However, this is the only choice if you actually implement the trap routines in assembly.

Terminal input/output

We’ve seen in the last section the interface LC-3 provides for I/O, but in this section, I’ll explain concretely how the terminal interface works in my own implementation.

In my LC-3 VM, only the keyboard device registers and the output-related trap routines are directly implemented. The input-related trap routines are based on the keyboard device registers.

Output

First, output is relatively simple : we just use the built-in print functions.

fn trap_puts(vm: &mut VM) {
    let mut idx = vm.registers.r0;
    loop {
        let c = vm.mem.get_mem(idx) as u8 as char;
        if c == '\0' {
            break;
        }

        print!("{}", c);
        idx += 1;
    }
    let _ = io::stdout().flush();
}

For example, to output a null-terminated string, we loop through it and print each character, breaking when we see a null. Importantly, remember to flush stdout. This makes sure the output actually appears when needed, and fixes some visual glitches.

Input

Input is more difficult. There are a few problems we need to fix:

Blocking input: Normal standard library input functions block, which means that your code will stop and wait until the user types their input. LC-3 requires that the CPU be able to keep running and periodically check if input comes in, instead of pausing everything to wait for input.
Buffered input: In a terminal, input is buffered, which means that input is only sent to the program when you press Enter. This behaviour is called “canonical mode”. This is not what we want: we want to get raw keypresses. It would not be fun to have to press Enter after each keypress for it to register.
Echo: In a terminal, when you type, the letters you type show up. This behaviour is called echo. We do not want this: we want the program to silently read user input to avoid visual clutter.

We’ll first get rid of canonical mode and echo. This can be done on Linux using termios:

fn setup_termios() {
    let mut term: Termios = Termios::from_fd(STDIN_FILENO).unwrap();
    term.c_lflag &= !(ICANON | ECHO);
    // TCSANOW: "the change occurs immediately"
    tcsetattr(STDIN_FILENO, TCSANOW, &term).unwrap();

    // when leaving the program we want to be polite and undo the above changes
    ctrlc::set_handler(|| {
        restore_terminal();
        // typical CTRL-C exit code
        std::process::exit(130);
    })
    .expect("Failed to set CTRL-C handler");
}

Here, we disable the ICANON and ECHO bit-flags. We also set a Ctrl-C handler: if we exit the LC-3 VM unexpectedly, we don’t want to be stuck with weird terminal settings. All restore_terminal does is flip on the flags we disabled.

Now, we have instant, silent input. However, we still block on input. This means that with code that deals with user input, the program freezes up between keypresses.

To fix this, we need non-blocking input. There are libraries to do this, however I decided to use standard Rust features to do it instead.

We first create a thread dedicated to managing stdin. This thread will block until the user presses a key, however it does not block the main thread. There is a “channel” between this thread and the main thread that allows one-way communication. This channel is like a queue data structure : the input thread can send information about key-presses, and when the main thread is ready, it can receive this information when it wants to.

In Rust, I use a TerminalIO struct to implement this:

impl TerminalIO {
    pub fn new() -> TerminalIO {
        setup_termios();
        TerminalIO {
            stdin_channel: Self::spawn_stdin_channel(),
            char: None,
        }
    }

    fn spawn_stdin_channel() -> Receiver<u8> {
        // https://stackoverflow.com/questions/30012995
        let (tx, rx) = mpsc::channel::<u8>();
        let mut buffer: [u8; 1] = [0];
        thread::spawn(move || loop {
            let _ = io::stdin().lock().read_exact(&mut buffer);
            let _ = tx.send(buffer[0]);
        });
        rx
    }
}

Here, we use a closure (the move here means that the function acquires the variables in the outside scope) that runs in a new thread. It is an infinite loop that waits for a single byte of input from the user, then transmits it over the channel back to the main thread.

Back in the main thread, I then implement the KBSR and KBDR registers:

impl KeyboardIO for TerminalIO {
    fn get_key(&mut self) -> Option<u8> {
        let c = self.char;
        self.char = None;
        c
    }

    fn check_key(&mut self) -> bool {
        match self.char {
            Some(c) => true,
            None => match self.stdin_channel.try_recv() {
                Ok(key) => {
                    self.char = Some(key);
                    true
                }
                Err(mpsc::TryRecvError::Empty) => false,
                Err(mpsc::TryRecvError::Disconnected) => panic!("terminal keyboard stream broke"),
            },
        }
    }
}

In the main thread, when the VM checks if there is a keypress ready through the Keyboard Ready bit, we attempt to receive a keystroke over the channel from the input thread. If the channel is empty, return that there is no keypress ready. Otherwise, store the character we received. Then, when the VM gets a key through the Keyboard Data register, we give it this character.

I personally find that this solution is elegant: it allows for the VM to keep working while waiting on user input, and it also doesn’t take a bunch of boilerplate and working with obscure options like file descriptors. The input thread just uses normal input functions, and passes it over to the main thread to be read later.

Debugging

Implementing a virtual machine can often introduce hard-to-find bugs. Indeed, there’s no such thing as a syntax error or a type error when you’re dealing with assembly. When something goes wrong, you’ll have absolutely no indication of where the issue stems from: you’ll just see weird behaviour. With LC-3, though, you can be reasonably sure that the programs you’re running (like 2048, Rogue), can be trusted to be bug-free, given that they’ve existed for years. Therefore, any bug most certainly stems from you, the virtual machine author.

To find the source of these bugs in your virtual machine implementation, I recommend that you read over the code implementing all the instructions, and compare it to the ISA specification. I find that this is in general great advice for programming anything that involves logic. It may not seem like reading will do much, but you will be able to catch many, many, dumb mistakes with this method.

Let’s talk about my own experience debugging LC-3. Rogue worked perfectly, but when running the 2048 program, the game started to an empty grid. (Usually, 2048 has tiles in the grid.) Pressing keys would not do anything either. To fix this, I tried applying my earlier advice about re-reading your code. I read 70% of the instructions implementation file, then decided that it was probably not worth the effort to continue. (We will see later this was a bad decision.)

I then did run-time debugging of what was happening in the VM. First, I wrote some debug print statements (these are still available with the --debug flag of the VM.) These had the following format:

PC: 0x3312, op: ADD, params: 0x261
R0: 0x0
R1: 0x29a
R2: 0x0
R3: 0x0
R4: 0x0
R5: 0x3017
R6: 0x3ffc
R7: 0x32db
COND: 0x2 (Z)

All the registers’ contents are displayed, as well as information about the current instruction. Every cycle, this information is printed to stderr, which allows the debug stream to be piped into a log file separate from regular output. The log is useful, but is too fast to be read while the VM is running, and doesn’t show any information about memory. Most importantly though, it doesn’t have one of the best creature comforts that you’d expect from a debugger: breakpoints.

At this point, I figured it was probably best to use a real debugger. For those who have used C or C++ on Linux before, you probably have experience with using GDB to debug. GDB is a venerable debugger with a command-line interface. The user experience is quite unfriendly, but it’s efficient, and fast. It turns out that GDB also works in Rust, with some slight modifications. This debugger, rust-gdb, comes packaged with the Rust compiler.

We can’t just directly use rust-gdb to debug our virtual machine software though. The debugger doesn’t understand LC-3 assembly; we can’t just tell it to, for example, break on a given line in the LC-3 code. First, I set up a breakpoint in the fetch-execute loop. This means that entering c (continue) in GDB will step through a single LC-3 instruction. With the assembly source code in a separate window, it is possible to step through the execution of the program and examine the instructions and how they affect the registers.

However, stepping through instructions individually gets tedious eventually. Monitoring the PC register, I wrote down all the addresses of a few instructions as comments in the assembly source. It’s also possible to get addresses by counting how many instructions there are in the source code. I then used GDB’s conditional breakpoints to break in the VM only when PC reaches that address. In essence, this is a breakpoint within the LC-3 code. To make this process faster, I made a GDB macro to automate it:

define vmb
    # set a breakpoint at VM addr $0
    break lc3::vm::instruction::execute_instruction if vm.registers.pc == $arg0 + 1
    set $vmb_break = $bpnum
end

This creates a new command that can be used to set breakpoints within LC-3.

Using this, I narrowed down the source of the bug in 2048 to the RAND_MOD subroutine, which is supposed to provide a random number within a given range. This is used to determine where a new tile is placed in the grid. When tested, it was giving a garbage number entirely outside the range argument. Then, I further narrowed the issue down to the division/modulo subroutine, MOD_DIV, giving the wrong answer. Stepping through this function, I finally found a single instruction that was behaving oddly: NOT.

As it turns out, I had made a very subtle typo in the implementation of this instruction:

     let res = !vm.registers.get_reg(sr);
-    vm.registers.set_reg_with_cond(sr, res);
+    vm.registers.set_reg_with_cond(dr, res);

Instead of performing the operation on the source register (sr) and storing the result in the destination register (dr), I had stored the result back in the source. In Rogue, this had not caused any issues, since that program only uses this instruction “in-place” (NOT R0, R0). However, this behaviour is obviously incorrect when the source and destination are different (NOT R2, R1), like in 2048. This spread corrupted data everywhere, and was hard to diagnose.

In the end, had I followed my earlier advice about re-reading the code, and I hadn’t given up midway, I would’ve noticed this much quicker. Indeed, this will serve as a lesson for me to properly check over code I write in the future, and make sure that it is not sloppy.

Conclusion

While LC-3 is still a relatively simple program, implementing it as a virtual machine is still quite educational. I learned about the core functionality of computers, as well as how assembly works. Through LC-3, I also learned the basics of Rust and got more experience finding subtle bugs too. If you’re looking to sharpen your skills in a language, consider the idea of writing a simple virtual machine. Or, maybe, a disassembler or assembler for LC-3.

Either way, the fact that just this small, contrived system can be so interesting is surprising. This is just a microcosm of computing, and there is so, so much more to discover.

Again, if you’re interested in further reading about LC-3, read the original blog post that inspired this one.

Also, thank you for bearing with me this far. This post is longer than any that I’ve written up to now. I hope you enjoyed my journey with LC-3 as much as I did.

Hello World (from barf.sh)

2023-05-14T10:00:00Z

Hello World (from barf.sh)

2023-05-14

Another year, another static site generator.

This time, for the 5th iteration of the website, I’m using barf to generate it.

Personally, I think the old script I was using, ssg, was really hacky in comparison to barf. One of my biggest grudges is how there was no post list on the front page by default. Most of the people using ssg (including me) had to write their own messy sed contraptions to implement it.

Thankfully, barf implements not only the post list, but also Atom feed generation, which is very convenient.

Other than that, barf excels by being tiny. Unlike ssg, the barf script fits in 3 screenfuls of text for me. In my opinion, it’s much more readable.

The great thing about these two scripts is that migrating my website from one to the other is really simple. They both work similarly, so I just needed minor changes to port over my (admittedly few) pages.

Anyways, I’ll hopefully write some blog posts soon and fix the remaining dead links on the website.

Using the shell as a file picker for Qutebrowser

2023-06-28T10:00:00Z

Using the shell as a file picker for Qutebrowser

2023-06-28

Qutebrowser is pretty great (thanks The-Compiler <3). For those who don’t know about it, it’s essentially a Vim-like browser: there’s a bunch of cryptic shortcuts, but they maximize your efficiency. The best part of Vim, which is replicated in Qutebrowser, is the ability to do everything without taking your hands off the keyboard.

Anyways, an issue I had was that when uploading a file in Qutebrowser is that it calls on a normal GUI file picker. This is probably a sane default, but the default file picker does not have Vim shortcuts (absolutely unusable!). Now, you could use ranger, or vifm in the way described here, but that’s boring. Instead, as a masochist power user, I manage all my files exclusively in the shell, and I wanted to have that experience in Qutebrowser. So, I made a 25-line script fish-fm that does just that.

Demonstration

Here’s an example usage of fish-fm.

First, when a website asks you to upload a file, qutebrowser opens a terminal window with fish-fm. Then, you have a full fish shell in which you can run sxiv, mpv, or any other command to inspect your files first. This also includes all its features like history and autosuggestions. Once you figure out what you want to upload, you then run sel [file paths]. The great thing about this is that you can use any glob or even xargs with this command. As a demo:

sxiv selection

Optionally, you can run ssel [directory or file paths], which uses sxiv to view your images. Then, you can mark the images (see sxiv’s man page), and those will be uploaded.

Installation

Install the dependencies: qutebrowser, fish
Copy fish-fm somewhere in your PATH.
Create a qutebrowser config.py. Then, add these lines:

c.fileselect.handler = "external"
c.fileselect.multiple_files.command = ["st", "-e", "fish", "-C", "set -x OUTPUT {}; source ~/.local/bin/fish-fm"]
c.fileselect.single_file.command = ["st", "-e", "fish", "-C", "set -x OUTPUT {}; source ~/.local/bin/fish-fm"]

Depending on your terminal, you might have to edit these commands. I personally use st; yours may be different. The {} here is a placeholder for a temporary file where fish-fm writes its output. This is necessary because terminals don’t forward the stdout of their commands, so fish-fm can’t just print the files selected.

Your file picker is now a fish shell.

Getting into crochet

2026-04-01T10:00:00Z

Getting into crochet

2026-04-01

As of today, we’re completely rebranding dogeystamp.com as an arts and crafts website!

A few months ago, I remembered that joke about how senior software engineers invariably retire to tend to crops and a chicken farm, or to do woodworking. I wanted be ahead of the curve, so I too decided to get a hobby that involved tangible things: I learned crochet, which a way of making things (like that ribbon in the picture above) using yarn.

I’m not skilled or anything, so as the title suggests, this article mostly describes the beginner experience, and what I wish I’d known earlier. If you had to retain one thing from reading this, I would say that crochet is quite fun and accessible, as long as you have patience. Notably, I won’t actually explain how to crochet; many people have made much better online resources for that.

Materials

You only really need two things to crochet, the yarn and a crochet hook,¹ and at the end you’ll need scissors to cut away the yarn you haven’t used. Usually, people have scissors already, so yarn and the hook are the only thing you need to get. Hooks and yarn both come in different sizes, and you do want the sizes to match. There is some margin of error on the sizes, though, so a small mismatch is fine.

I have actually never personally bought a hook or yarn as of writing, because some very generous people I know gifted me hooks and yarn.² It’s probably not hard to buy yarn and a hook of matching sizes, but if you really want to be safe, they sell kits for beginners that should work fine out of the box.

Getting started

Crochet in particular is nice (compared to something like knitting) at the beginner stage, because every single stitch you make can be effortlessly undone by unravelling the yarn.

So to figure out how to crochet, I repeatedly made then unmade yarn squares, following tutorials online. (Pretty much any tutorial for complete beginners seems to be about making these swatches.) Here’s a work-in-progress picture of one of my first squares: It turns out that the techniques for making squares are actually sufficient for creating many interesting items. In fact, all of the creations pictured in this article are entirely composed of rectangles stitched together in different ways.

The process for making a square swatch starts with making a chain of yarn, then repeatedly building rows of single crochet stitches on top of that foundation, as if laying bricks to build a wall.³

Most of the difficulty in learning crochet comes from figuring out which hole to insert the hook into. On every row, there will be V-shapes, which you are supposed to pass the hook through to create stitches. I’d follow tutorials step by step, and end up confused because I couldn’t recognize the shapes from the tutorial when looking at the yarn in my hands. For me, it helped to fiddle and twist the row until the V-shapes were clearly visible, after which everything looked exactly like the tutorials.

Other than figuring out how to put the hook in the right hole, an important aspect of crochet is making your stitches nice and regular. There are two things that helped me with this. First, I learned that the thickest part of the hook is a measurement tool; by always wrapping your yarn around the thickest part when making stitches, your stitches will have a regular size. If you wrap yarn around a thinner part, the holes you make will be too tight to pass the hook through. Second, I watched this video about the “golden loop,” which contributed to making my stitches more consistent. The video itself is much better at explaining than I am, so please watch that for further information.

Making things

After becoming half-decent at making square swatches, I was able to make more interesting things.

Ribbons

I followed this tutorial for making a bow tie / ribbon just like the one pictured at the top of this page.

The ribbon is actually composed of two rectangles; one is for the main body part, and one for the two dangly bits below. The tutorial tells you the sizes (number of chains and number of rows) to make both rectangles, and once you make them, you attach them together by threading yarn through the stitches.

Ribbons were fun, since they don’t take a lot of time or material to make, are prettier than square swatches, and use the single crochet technique used for the beginner squares. The method I used for “sewing” together the rectangles was also pretty much just single crochet stitches,⁴ so once you figure out how to make a square, a ribbon isn’t much of a big step up.

Beanie

Once I made a few ribbons, I got bored and started looking for a new project. Taking some inspiration from the friend that helped me get into crochet, I made a beanie with cutesy ears,⁵ following this tutorial. Here’s me wearing the beanie:

(It’s hard to demonstrate a beanie without showing my face.) Despite the seemingly curved ears, the beanie is formed from a single rectangle; when worn, it naturally folds in a way that gives ears.⁶ Thus, making a beanie is really not that different from the square swatches I started off with. However, with this project, I did encounter some challenges.

First, the beanie does not just use single crochet stiches; it uses half-double crochet stitches, and slip stitches. This sounds quite daunting, but these stitches are actually quite similar to single crochet. For me, learning the new stitches took much less time than figuring out single crochet for the first time, because most of the muscle memory was the same.

Second, getting the dimensions of the beanie right was challenging. Making the beanie, I had to pick its width and length so that it could fit on my head. After two weeks of crocheting, I realized that I was running out of yarn, and, even worse than that, my beanie was comically tall. Unfortunately, I had picked completely incorrect dimensions, so I had to unravel everything and start over again. Thankfully, the second time crocheting the beanie, I was much faster because I got better at crochet.

Another thing to watch out for in terms of dimensions is that putting your crochet work in the washing machine might shrink it. Apparently blocking helps with shrinkage; I don’t know much about blocking though.

Conclusion

Learning crochet was fun; it’s easy to get into, and very forgiving of mistakes. Best of all, I get to keep the tangible fruits of my labor, and put cool photographs of them in this article.

There’s much much more to crochet than what I’ve outlined here; notably, amigurumi techniques let you make things that aren’t just rectangles. Hopefully though, this is enough to convey how getting into crochet is really accessible.

That concludes my thoughts on crochet. Happy April Fool’s Day!⁷

“Crochet hook” means “hook hook” but it is what it is. ↩
On the off-chance you are reading this, thanks a lot for the materials and your guidance :) ↩
For a niche 3D modeling metaphor for crochet, see this CodeParade video. ↩
Often, tutorials recommend that you use a proper sewing needle to sew together different pieces. So far, I have gotten away with just stitching pieces together. ↩
Everyone says these are cat ears, but I assure you these are shiba ears because I’m dogeystamp. ↩
The normal not-eared beanie is not a rectangle, and is arguably harder to make. ↩
To the astute readers who noticed that I posted this a few days late and backdated it to April 1st: shush you didn’t notice anything. ↩

Lower bound, upper bound in C++, visually explained

2024-04-02T10:00:00Z

Lower bound, upper bound in C++, visually explained

2024-04-02

One of the most common problems programmers have to solve is retrieving specific data — finding the needle in the haystack. To make this simpler, languages provide standard tools to perform this task: in particular, this post focuses on C++’s lower_bound and upper_bound.

Personally, I find that the documentation for these functions is quite unclear and verbose. For example, cppreference.com describes lower_bound like this:

Searches for the first element in the partitioned range [first, last) which is
**not** ordered before value.

That sounds like gibberish, and is too technical to quickly understand. For that reason, I’m making this blog post to explain my own mental model of these functions.

Refresher on binary search

First, it’s important to understand how lower_bound and upper_bound work under the hood.

As you know, finding words in a dictionary is relatively fast. This is possible because the words are in alphabetical order. If the words weren’t ordered, you’d have to look through every single word in the dictionary, one by one. That would be an excruciating, and much slower process. Because of the ordering, you can rapidly narrow down the word you want.

Computers can do the same with ordered data: this is called binary search, and is what powers lower_bound and upper_bound. For example, say our dictionary is 1000 pages, and the computer wants to look for the word “rabbit”. These are the steps it takes:

Start at exactly page 500.
See the word “murmur”, so go forwards to page 750.
See the word “sunny”, so go backwards to page 625.
And so on.

This is called “binary search” because we halve the region we are looking in every time (we pick either the left half, or the right half.) For step 1, the computer is halving the range 1-1000. In step 2, 500-1000. Then for step 3, 500-750. This is like the way humans look at dictionaries, but more structured.

Anyways, this is not intended to be a full explanation of binary search: refer to Tom Scott’s video about it for more information.

Lower bound and upper bound

Back to the real subject of this post: lower_bound and upper_bound in C++. What I used to understand of these functions is that they use binary search to find elements in a sorted container. However, I didn’t get what differentiated them. Again, if you read solely the documentation about these functions, it’s not easily comprehensible.

First of all, say we wish to search for the integer k (k for key) in a sorted vector (array) of integers v. We can find the lower and upper bounds with these function calls:

// (you could use auto here instead of the verbose type)
std::vector<int>::iterator lb = std::lower_bound(v.begin(), v.end(), k);
std::vector<int>::iterator ub = std::upper_bound(v.begin(), v.end(), k);

Based on the documentation, we know the first two arguments specify the region of v we’re looking in. Here, it’s the entire vector (from the beginning to the end). Also, put simply, the functions return by default:

lower_bound: the first element e where k <= e;
upper_bound: the first element e where k < e.

Note: Both functions return v.end() if no valid element is found. This iterator points just after the last element of v.

This is the technical definition; it doesn’t mean much by itself. However, with a concrete example with real numbers, it clicked in my mind. For example, let k = 3. Here is an example sorted array v, with upper and lower bounds marked:

    lower   upper
      ↓       ↓
1 2 2 3 3 3 3 4 5 6
      ───────
         ↑
 matching interval

The first 3 is the lower bound: it’s the first element bigger or equal to our key. The 4 is the upper bound, the first element strictly bigger than our key.

Here, when it’s laid out visually, it’s now clear what the lower and upper bounds mean: it’s the bounds of the interval that matches our search key. This is mostly useful if the array has duplicate elements.

Notice how the upper bound is one past the end of the interval, just like how v.end() is one past the last element of the vector. This is usually how C++ iterators work, and makes some tasks more convenient. Take this regular for loop:

for (int i = 0; i < 10; i++) { ... }

This loop will iterate over the numbers 0 to 9, excluding the upper bound 10. The same logic applies to C++ iterators. If we want to iterate over all elements of a vector, we’d use:

for (auto it = v.begin(); it != v.end(); it++) { ... }

Here, we use != instead of < for iterators, but it does practically the same thing. When the iterator goes past the end of the vector, it’ll hit v.end() (which is one past the last element), and as such the loop stops.

Note: Usually, you’d do for (auto number : v) to iterate over the entire array.

So, having the upper bound be right past the end of the interval makes this possible:

for (auto it = lb; it != ub; it++) {
    // *it is like pointer dereference:
    // it gets the number pointed to by the iterator
    std::cout << *it << std::endl;
}

Anyways, I’ll repeat it again: lower_bound and upper_bound represent the interval that matches what you’re looking for.

Conclusion

So, that is my “visual” explanation how lower and upper bound works in C++. In hindsight, this seems obvious, but back when I was first told about these functions, I could not understand it because of the confusing descriptions. Having this intuition for concepts is pretty helpful for truly understanding them: you don’t want to be stuck memorizing things that don’t make sense.

Chess engine, pt. 6: Neural-net evaluation

2025-05-28T10:00:00Z

Chess engine, pt. 6: Neural-net evaluation

2025-05-28

This post is part of a series about building a chess-playing engine.

Introduction (0) | ← Last part (5)

The engine we built in this blog post series is now capable of playing chess, and it understands the game decently on a tactical basis. However, a common comment from human players was that the engine plays “weird”. This unnatural-ness is a symptom of the engine having no knowledge of chess other than tactics.

In this post, I’ll cover some of the main methods, both traditional and modern, used to give the engine some positional knowledge. To do this, I will continue building on our engine’s evaluation function. Right now, it’s based on material counting, but by the end of this post, it will be replaced by a neural network.

First, though, a disclaimer. The purpose of this post is slightly different from the rest of the series, because I am not an expert on chess neural networks, or machine learning in general. The point of this post is not to describe best practice, but to show how to build a neural network, from the perspective of a beginner in ML. If I can do it, you can too!

Material counting

Let’s revisit our engine’s current evaluation function. Primarily, it is based on material counting; that is, each piece is assigned a point value, like a pawn is 1 point (or 100 centipawns), and the queen is 9 points. Then, whichever player (White or Black) has more points has more advantage.

The main reason material counting is useful is that it’s really effective at all levels of chess, and is low effort to implement. As I mentioned before, even the best chess players in the world would struggle if they had a huge material disadvantage.

However, there is of course more to chess than counting material. Take for example this opening, the Bongcloud Attack:

If we just counted material, for all we know, this position is perfectly equal for both sides. In reality, the Bongcloud is so bad for White that it has become a meme. Why is it bad? Wikibooks says that this opening “prevents castling to protect the King, endangers the King, ignores development and the center, and blocks the Queen and Bishop”.

Our engine can’t understand any of that, because it only sees that a side has a given piece, and it doesn’t know where that piece is.

Piece-square tables

To make the engine understand basic positional aspects of chess, we can use piece-square tables. These encode a score not just for having a piece, like “pawn is 100 centipawns”, but also their position, like “pawn on a6 is 180 centipawns”. This score includes the inherent material value of the piece (1 point), and a bonus for its advanced position on the board (0.8 points).

Piece-square tables can encode a lot of conventional wisdom about chess. For example, “knights on the rim are dim”, that is, knights on the edge of the board, and especially the corners, are less valuable because their mobility is limited. In practice, the piece square table is an array of numbers that represent the score for each square a knight could be on. For “knights on the rim are dim”, this could be the PST you use:

pst_knight_white = [
    -70, -20, -20, -20, -20, -20, -20, -70,
    -20,   0,   0,   0,   0,   0,   0, -20,
    -20,   0,   0,   0,   0,   0,   0, -20,
    -20,   0,   0,   0,   0,   0,   0, -20,
    -20,   0,   0,   0,   0,   0,   0, -20,
    -20,   0,   0,   0,   0,   0,   0, -20,
    -20,   0,   0,   0,   0,   0,   0, -20,
    -70, -20, -20, -20, -20, -20, -20, -70,
]

Each number represents a square, so the PST assigns scores for the entire chessboard. This PST specifically would penalize the knights for being on the edge, and doubly so for being in the corners.

The array is one-dimensional, because engines typically don’t use row/column notation (a1 is row 0, column 0); engines typically use a single number for every square, so a1 is 0, and h8 is 63. (Here is a neat visualization of which numbers correspond to which squares.)

Developers will often bake the material values of the pieces into the table. In pseudo-Python, it could look like this:

pst_knight_white = [score + 300 for score in pst_knight_white]

In other words, we can directly add the knight’s 3 point material value into the piece-square table, instead of it being a separate score we have to add.

Also, piece-square tables are usually given from White’s view of the board. To get Black’s scores for each square, engines commonly do a vertical flip of White’s scores. Using the standard square numbering convention, if a certain square is x, the vertically mirrored equivalent square is x ^ 56 (the square’s index bitwise XOR 56). Then to generate Black’s piece-square table, we can use this code:

pst_knight_black = [pst_knight_white[i ^ 56] for i in range(64)]

Note: In this post specifically, scores will be from White’s perspective, so positive is good for White, and negative is good for Black. For negamax, if we want Black’s perspective, we can negate the score. Typically, NNUE engines do not operate this way; they use perspective networks.

To keep with the sign convention, whenever we evaluate a position with the PST, we add scores for White, and subtract scores for Black.

So far, this is just the knight PST; you should also make a table for all the other pieces. For instance, pawns that are close to the end of the board are very valuable because they can promote.

Then, here is some pseudo-code for how your evaluation function could look like:

def eval(position):
    score = 0
    for square in range(64):
        piece = position.get_piece_on(square)
        if piece.color == white:
            score += get_piece_square_value(piece, square)
        else:
            score -= get_piece_square_value(piece, square)
    return score

Once you have piece-square tables in your engine, your evaluation function can become quite smart, depending on what heuristics you can encode in it.

Tapered evaluation

The game of chess is often divided into the opening, midgame and endgame phases. In the midgame and endgame phases, the PST is useful for guiding the engine’s moves. However, the best strategy for the midgame is probably not the best strategy for the endgame. Therefore, engines often have two piece-square tables, one for the midgame and one for the endgame.

As I mentioned in the last post, chess engines commonly determine whether it is the midgame or endgame based on how many pieces are still left on the board. Often, there will be a “phase” number that you calculate that will determine if you are in midgame or endgame. Based on this number, the engine will interpolate between using the midgame and endgame piece-square tables.

Interpolating between the tables is important (so I’ve read). If you use a fixed threshold and switch abruptly between the tables, the engine might avoid a good capture because it has a better score with the midgame table than the endgame table. To smooth out the difference, you “taper” the evaluation between midgame and endgame.

Summary

To briefly conclude this section, piece-square tables help your engine understand the value of where the pieces are on the board. To do this, each piece-square combination is assigned a bonus or penalty.

PSTs can be quite effective as an evaluation function. As of writing, the PeSTO engine, an engine that operates with piece-square tables only, is rated 3125 Elo on CCRL Blitz (for comparison, Stockfish is 3818). PeSTO’s evaluation function is the product of lots of effort and fine-tuning, but it goes to show that PSTs are pretty powerful, despite their relative simplicity.

Neural network evaluation

One of the main reasons I did this chess engine project was to get experience with training and running neural networks.

I saw DeepMind’s work with AlphaZero, a neural-network based chess engine with zero knowledge of chess that learned to play at a superhuman level within a few hours. The idea behind AlphaZero is quite elegant; by having the network play games against itself, then training from these games, it managed to learn chess with no external help or initial knowledge of chess except for its basic rules.

Before machine learning became commonplace, hand-crafted evaluation (HCE) techniques like piece-square tables were the norm in chess engines. At the time, engine developers had to be good enough at chess to codify the winning strategies of the game.

My idea was, if I can’t play half-decent chess, maybe my computer could learn about chess by itself like AlphaZero did. (I can say in hindsight that my engine was definitely far from AlphaZero’s success, but it did succeed at learning chess at a higher level than my own understanding of it.)

Now, since this was my first significant neural network project, I made a lot of mistakes doing it. Generally, the advice I give here is hopefully decent, but in the real project my methods were flawed. The purpose of this part is to document what I did and what I did wrong, but also to show you that getting into chess neural nets isn’t super difficult. Chess-inator is really bad relative to the best engines out there, but it’s much better than anything I thought I could ever make on my own.

Also, before I continue, you should probably have some knowledge of neural networks, like what is a neuron and activation function, or how the typical neural network’s forward pass works.

NNUE

Neural networks and machine learning can be a bit scary, because they commonly need lots of costly hardware to run. AlphaZero was trained using thousands of TPUs specialized for neural nets, and many other ML projects require GPUs at inference time.

With many modern chess engines, though, you don’t need a GPU to run the neural network anymore.

NNUE, or Efficiently Updatable Neural Network, is a neural network design that is specifically CPU-friendly. Unlike deep learning, where there are many layers of neurons, I like to call NNUE “shallow learning”, because it often uses a very small amount of layers. Because of this small layer count, and the nature of games like chess, this type of network allows for extreme speed optimizations. Other neural networks may be more intelligent, but NNUE makes up for it in speed.

The goal of NNUE is to replace the evaluation function in our engine (which might be material counting, or piece-square table, or any other HCE logic). It takes in a chess position, and gives us a score for it.

Before I get into the details, I want to say that at a beginner level, you can definitely wrap your head around NNUE. The folks making Stockfish and other advanced engines have really complicated neural networks, which makes it seem like NNUE is hard to implement. However, basic NNUE designs are actually quite simple, but also very effective.

PST, again

To ease you into the idea of NNUE, let’s take the piece-square tables we had earlier, and turn them into a neural network.

Recall that in the piece-square table, each combination of piece and square is assigned a score. The color of the piece is also important for the score’s sign. For instance, a White Pawn on a1 could be worth 100 centipawns, while a Black Rook on h8 would be worth -500 centipawns.

There are 6 pieces (rook, knight, bishop, queen, pawn, king), 2 colors (White, Black), and 64 squares on the chessboard. These features make up 768 inputs to the piece-square table. Based on these inputs, the table returns a single value, the score of the position.

We can therefore represent a piece-square table as a neural network with no activation functions, and no biases:

Each input is either a 1 or a 0. For instance, if the first input is 1, that means “there is a White pawn on a1”. Otherwise, “there is not a White pawn on a1”.¹

These inputs almost fully represent a chess position. Notably, castling rights and en-passant aren’t accounted for. However, for our purposes, the evaluation function doesn’t have to be perfect, and our engine’s search will take care of those elements. (I like to think that the evaluation function is the intuition of the chess engine, while search is the logical brain, so that evaluation doesn’t have to be 100% accurate in its calculations.)

We then multiply each input by a weight. (In the example diagram above, I picked some arbitrary numbers like 100 and -500, which roughly correspond to the material values of the White pawn and Black rook, in centipawns.) Then, we take the sum of the products, and the resulting output is the score of the position in centipawns. The score is from White’s perspective; a positive score is good for White, and a negative score is good for Black.

In other words, we add the values of all White pieces, and subtract the values of all Black pieces. But now, instead of explicitly doing that calculation, we use a neural network to do it.

Here is some pseudo-code for evaluating the neural network’s output:

WEIGHTS = [100, 100, 100, ..., -500, -550, -500]

def forward_pass(inputs):
    output = 0

    for i in range(768):
        output += WEIGHTS[i] * inputs[i]

    return output

But since the inputs are binary zeroes and ones, this code is equivalent:

def forward_pass(inputs):
    output = 0

    for i in range(768):
        if inputs[i] == 1:
            output += WEIGHTS[i]

    return output

Now, we have a “neural network” that implements a piece-square table.

Incremental update

In this section, I’m going to continue using the simple PST neural network in the diagram above to explain the core idea behind NNUE. Remember that NNUE stands for efficiently updatable neural network. What does that mean?

In the evaluation function code I showed above, there is a for loop that iterates over all 768 inputs. In the PST, this isn’t that bad; for computers, a few hundred operations is nothing in terms of time. However, for more complicated neural networks, we start getting nested for loops, and in that case doing the same thing 768 times becomes computationally expensive.

To avoid this all looping and repetition, engines use incremental updates. The engine always keeps track of the score output of the current position. Whenever we make a move on the position, we only need to calculate the difference in score between the old and the new position. Since individual moves don’t change the position that much, this calculation is really simple.

As an example, suppose our engine is using material counting, and we are trying to calculate the score after exd5.

If I tell you that the material score of the first position is 0, what is the material score of the second position? It’s a 1 point advantage for White, because the only difference between the two positions is that Black’s pawn was removed. With material counting, when a piece is removed, its score is removed from the evaluation. When a piece is added, its score is added.

If we apply this same idea to the PST neural network above, whenever an input bit is changed to a 1, we add its weight, and whenever a bit is changed to 0, we subtract its weight from the output.

For instance, if we move the Black rook from h8 to h7 (assuming there is no piece on h7), we turn on Rook, Black, h7 (bit 766), and we turn off Rook, Black, h8 (bit 767):

# this is the score before we move the rook.
original_score = forward_pass(inputs)

# this is the score after moving the rook.
new_score = original_score + WEIGHTS[766] - WEIGHTS[767]

Similar incremental updates can be done for captures too; a capture turns two bits off, and one bit on.

We also need to implement a way to “undo” the score, since we can unmake moves. Whenever we unmake moves, we do the inverse operations to restore the original state. For example:

original_score = ...

# make move (Rh7)
score += WEIGHTS[766]
score -= WEIGHTS[767]

# unmake move (Rh7)
score -= WEIGHTS[766]
score += WEIGHTS[767]

# score is now back to the original state.

Now that we have incremental updates, we can re-evaluate our PST neural network in only a few operations, rather than re-doing 768 operations every time.

In the engine’s function for applying a move to a position, and undoing a move, you can add calls to the incremental update functions. Then, whenever you make moves on the board, the evaluation updates accordingly; whenever you unmake/undo moves, the evaluation returns to its original state.

NNUE, one hidden layer

Now that we’ve covered a contrived piece-square table neural network, I introduce a basic NNUE design:

This neural network takes the same chessboard input as before, and outputs a score for it. However, the network is now more complex.

Notably, we introduce a hidden layer of neurons. There are also biases on the hidden layer nodes and the output node. I chose to have 3 hidden layer nodes in this example, but there’s usually more than that (i.e. dozens to a few thousand).

In the hidden layer, I’m using the clipped ReLU (sometimes called CReLU) activation function. The original ReLU (rectified linear unit) is a common activation function defined as ReLU(x) = max(0, x). Clipped ReLU is similar, but it completely clamps the output between 0 and 1. We can define the function as CReLU(x) = max(0, min(x, 1)), or equivalently, CReLU(x) = clamp(x, 0, 1).

Here is the graph for CReLU (Desmos):

CReLU is (from what I’ve read) not an ideal choice, but it’s simple and easy for beginners to deal with. The hidden layer’s activation function will be very often used compared to the output node’s activation function, so we ideally pick a function can be optimized for speed. CReLU’s limited range is good for optimization (we’ll see later), which is why it is preferred over ReLU.

One major difference between this neural network and our PST is that the output is no longer a score in centipawns (known as CP-space). Now, we express the position’s score as a win probability in WDL-space: a 0.0 is a loss, a 0.5 is a draw, and a 1.0 is a win. When I talk about training the network in the next section, you’ll see that using WDL is more natural than centipawn scores. Centipawns are the traditional unit for scores, though, so we need to find a way to convert between CP-space and WDL-space. Engine developers have figured out that a sigmoid function is pretty good for that task. Sigmoid functions look like this:

where k is a scaling constant. For our purposes of converting between centipawns and WDL, a value of k = 400 is commonly used to scale the sigmoid properly. Here’s a graph (Desmos):

On the X-axis, we have centipawns, and on the Y-axis, we have win probability. The output of a sigmoid function is between zero and one, and its domain is all real numbers. This makes it ideal for our purposes of creating a WDL score. You can see that for negative centipawn scores, the game is probably a loss (near 0), and for high centipawn scores, the game is probably a win (near 1).

Since we want the neural network to provide us with a WDL-space score, the output neuron’s activation function is also a sigmoid function. However, we use a k = 1 curve, not the k = 400 centipawn-WDL curve. I’ll explain why we do this later.

Training process

For now, let’s focus on the way the network is trained. The NNUE is supposed to take a board position, and return an accurate WDL score. To accomplish this task, we need to figure out good values for all the weights and biases. Gradient descent is the tool used to do this.

By providing examples pairs composed of a chess position (input) and a correct evaluation of the position (output), gradient descent works backwards to tune the weights so that the network is as accurate as possible.

The problem is, how do we get these examples? One supervised learning approach would be to have Stockfish evaluate a bunch of positions, and use those position-score pairs as examples. That’s cheating, though; in a way, we’re stealing Stockfish’s existing knowledge of chess.

Instead, the more fun solution is to generate training data ourselves. We have the engine play against itself for lots of games, and then extract all the positions from these games. We also track the engine’s evaluation of the positions, and the result of the game.

Then, for every position, the “correct” evaluation is a linear interpolation between the engine’s evaluation, and the real final result (win, draw, loss) of the game.

First, the engine’s centipawn evaluation for the position is converted to WDL space using the sigmoid curve (k = 400) we saw earlier.
Then, we convert the game’s result into WDL, either 1.0, 0.5 or 0.0.

Now, we have two scores for the position, both in WDL space (i.e. between 0 and 1), that we mix together. This way, the engine learns from the outcomes of its games. Eventually, with enough positions, the neural network will learn what wins and what loses in positions.

The positions in the training dataset must be quiescent positions. That is, there must not be any pending captures or imminent checkmates. Remember how material counting breaks in non-quiescent positions? If we train the neural net on non-quiescent positions, it will also get confused.²

Typically, NNUEs are trained on the order of hundreds of millions of positions. According to an Engine Programming Discord member kind enough to answer me, the training games can be run with a “5000 node soft limit” on the search, for example. I assume this means that after an iterative deepening iteration, if the count of game tree nodes visited in negamax exceeds 5000, break the loop. Also, I assume this node limit helps generate more positions in a small amount of time.

Since training operates on a huge amount of chess position data, it is essential that you encode it in an efficient way. FEN, or worse, just storing the input features as a boolean array, are horrible formats; instead, you should use binary packed formats. In the worst case scenario, this is the difference between your training requiring 128GB of RAM, or 3GB of RAM to run. See this blog post from a Lichess developer about Stockfish’s NNUE position format. On average, their format requires 18.7 bytes per position.

At the time I wrote the engine, I had no idea of how any of this worked, so I actually trained chess-inator on only a few million positions, which is “drastically little” for the network I was using. I believe, as a consequence of this lack of training data, my NNUE was severely restricted in its performance. Also, I was limited by my terrible position encoding which consumed a large amount of RAM. At the end of this article, I’ll talk about these issues more and mention some of the things I did to cope with these problems.

An unoptimized implementation

Now, here’s the forward pass of the neural net in pseudo-code, and I hope it answers any of your questions about how it works:

def crelu(x):
    return clamp(x, 0, 1)

def sigmoid(x):
    # k = 1
    return 1 / (1 + exp(-x))

# hidden layer size
L1_SIZE = 3
# number of input bits
INPUT_SIZE = 768

WEIGHTS_L1 = [
    [...3 weights],
    [...3 weights],
    [...3 weights],
    ... 768 times total
]
BIASES_L1 = [...3 biases]

WEIGHTS_OUTPUT = [...3 weights]
BIAS_OUTPUT = 1 bias

def forward_pass(inputs):
    # pre-activation state of the hidden layer
    hidden = [0, 0, 0]

    for j in range(L1_SIZE):
        for i in range(INPUT_SIZE):
            if inputs[i] == 1:
                hidden[j] += WEIGHTS_L1[i][j]
        hidden[j] += BIASES_L1[j]

    # weighted sum of hidden layer's activations, plus bias
    output_preactivation = 0
    for j in range(L1_SIZE):
        output_preactivation += WEIGHTS_OUTPUT[j] * crelu(hidden[j])
    output_preactivation += BIAS_OUTPUT

    output = sigmoid(output_preactivation)
    return output

I wrote this forward pass function here so you can understand exactly how the neural network operates without any optimizations. Practically, this is exactly how it operates in my Python neural network training code. In the following sections though, I’ll be improving this code until it runs fast. This is necessary in the engine side of things (the Rust side in my engine).

Sigmoid at runtime

The neat thing about the sigmoid activation function we used for the output neuron is that we don’t need it at runtime (i.e. when the engine is playing chess.) Because the curve that converts between CP-space and WDL-space is also a sigmoid, we’re actually training the neural network to think in terms of centipawns. Here’s the k = 400 curve that converts CP-space to WDL-space, but with clearer variable names.

And here is the sigmoid activation function that we actually use in our neural net:

where x is the pre-activation of the output neuron, and σ(x) is the neuron’s output. Since we’re training so that σ(x) is equal to WDL, that implies that

and therefore,

If your eyes glazed over the moment you saw math equations, here’s the key point of this section: we can multiply the neural net output’s pre-activation by 400, and interpret that value as being in centipawns, rather than using a WDL output.

Thus, we can change our evaluation function to be like this:

SCALE_K = 400

def forward_pass(inputs):
    for _ in range(L1_SIZE):
        for _ in range(INPUT_SIZE):
            ... # see last section; I removed this code for brevity

    output_preactivation = 0
    for j in range(L1_SIZE):
        output_preactivation += WEIGHTS_OUTPUT[j] * crelu(hidden[j])
    output_preactivation += BIAS_OUTPUT

    # HERE: notice how the sigmoid is missing
    return output_preactivation * SCALE_K

and instead of returning a weird 0.0 to 1.0 win probability value from the neural network, the evaluation function will return a centipawn score, just the way we’re used to. Also, we avoid computing sigmoid, which saves time.

Incremental update for NNUE

Notice that the forward pass has an expensive nested for loop, which does 768 * L1_SIZE iterations. That’s bad; with a sufficiently big hidden layer, this could become a million iterations.

The key observation that defines NNUE is that we can also apply incremental updates to this neural network, just like I demonstrated earlier with the PST. Each time we need an evaluation, we don’t have to re-compute the entire forward pass; we only need to calculate the difference caused by a few input bits changing.

Here is code that turns on or turns off bits in the input layer, then incrementally updates the NNUE evaluation:

# hidden layer size
L1_SIZE = 3
# number of input bits
INPUT_SIZE = 768

# sigmoid parameter
SCALE_K = 400

WEIGHTS_L1 = [
    [...3 weights],
    [...3 weights],
    [...3 weights],
    ... 768 times total
]
BIASES_L1 = [...3 biases]

WEIGHTS_OUTPUT = [...3 weights]
BIAS_OUTPUT = 1 bias


# current hidden layer state (pre-activations)
hidden = [...3 elements]

def bit_set(i, on):
    """Set bit `i` on or off."""
    if on:
        inputs[i] = 1
        for j in range(L1_SIZE):
            hidden[j] += WEIGHTS_L1[i][j]
    else:
        inputs[i] = 0
        for j in range(L1_SIZE):
            hidden[j] -= WEIGHTS_L1[i][j]

def evaluation():
    """Get NNUE output (centipawns)."""
    output = 0
    for j in range(L1_SIZE):
        output += WEIGHTS_OUTPUT[j] * crelu(hidden[j])
    output += BIAS_OUTPUT

    output *= SCALE_K
    return output

# example: move rook from h8 to h7
bit_set(767, False)
bit_set(766, True)
score = evaluation()

# then unmake (undo) the above move
bit_set(767, True)
bit_set(766, False)

Each bit-set operation now only requires L1_SIZE operations to update the hidden layer pre-activations. Then, once we want the NNUE’s output, we use another L1_SIZE operations to run the hidden layer’s activation functions and sum them to get a final score. This is much better than the earlier 768 * L1_SIZE number of operations.

Commonly, the term accumulator is used to describe the hidden layer pre-activations (hidden in the above code). The accumulator is the only state that you maintain for the NNUE; the output (and any further layers there might be) are computed from the accumulator state. Using incremental updates, it’s highly efficient to update the accumulator, so adding more hidden layer nodes is cheap. The accumulator is the efficiently updatable part of NNUE. If we had more layers after the accumulator (some engines do), these would not be efficiently updatable, and would have to be entirely recomputed every time.

SIMD, assembly-level optimization

I want to stress the importance of a few implementation details in bit_set above. First of all, WEIGHTS_L1 is indexed first by the input node, then the hidden layer node. This makes it so that in the loop, array elements that are next to each other in memory are accessed one after the other. Secondly, in bit_set, I use if outside, and the for inside, even if this causes a bit of code duplication. This is the commonly advised way to write the loop, since this way we avoid repeatedly testing a condition that won’t change between iterations.

In my original code, I implemented both of these things the wrong way. After a long time fiddling in Godbolt’s Compiler Explorer and looking at the generated assembly, I figured out what was wrong, fixed the code and the compiler suddenly started generating SIMD instructions. SIMD (single instruction, multiple data), or vectorized code means that instead of adding the weights one at a time to the accumulator, it would add multiple elements at a time, speeding up the process.

The new vectorized code was amazingly snappy; I was actually overjoyed seeing the engine evaluate positions multiple times faster. This was the first project where I actually had to go read the compiled assembly to deeply optimize my program. Usually, in competitive programming (and a lot of other domains), we only think about asymptotic time complexity. For my chess engine, I had to optimize the constant factor, which I had ignored all these years.

Note: In my engine, since its logic is simple, the compiler (rustc, powered by LLVM) managed to auto-vectorize the code. I often see that other engine developers manually vectorize their code, which is too complex to auto-vectorize.

Quantization

Other than heavy use of SIMD, the other major optimization in NNUE is quantization. Floating point numbers are evil (*personal opinion), so engine developers prefer to use integers rather than floating point numbers to represent the NNUE’s accumulator state. One reason is that integers are faster than floating point.

The other reason to use integers is to avoid floating point error. Infamously, 0.1 + 0.2 = 0.30000000000000004. In a typical neural network, this infinitesimal error could be acceptable. However, remember how our chess engine works. It tries a move, evaluates, undoes the move. Tries another move, evaluates, undoes. Each time the engine makes or unmakes a move, it is also incrementally updating the evaluation. The engine relies on the undo operation to get back to the original, clean, NNUE accumulator state. With floating point, the undo will return to a slightly different “original” state than before. Eventually, because of errors accumulating, repeated undos will return to an accumulator state that is completely different from the original.

Here’s an analogy: imagine you’re using a text editor, and you type:

Hello World!

Then you undo, and get this:

Helln

Then you type some other word, like “Everyone!”:

Helln Everyone!

Then you undo, and repeat this over and over again a thousand times, and you end up with this:

Hexza

This is of course not the behaviour you want; you would expect the text to still be Hello. In this analogy, Hello represents the accumulator’s original state, which, while making and unmaking moves repeatedly, gets corrupted by floating point errors and becomes Hexza.

Note: In my experience, this sort of catastrophic floating point error only happened with 16-bit (half precision) floats, and is not nearly as bad on f32 (single) and f64 (double) types. I’m sure there’s still some drift of the accumulator state, though.

This issue can’t happen if we used integers to represent the accumulator state, because in integers, 1 + 2 = 3 exactly, with no error whatsoever.

Now, the problem is that neural networks don’t use integers, they use floating point numbers. We need to quantize the network’s parameters, i.e. convert the floating point numbers to integers. Naively, we could round all the numbers to the nearest integer. However, this causes inacceptable error. For example, let’s say one of the weights in our NNUE is 0.51. If you round 0.51 to 1, that’s a nearly 96% relative error on the original value.

To lessen this rounding error, we can scale all the values by some constant. For example, let’s multiply the values by 10. Then we round 5.1 to 5, which is much better (~2% error) than before. Once we’re done with the calculations, we can divide out the scaling constant to get a real answer.

Here’s a simple example with a linear function. This is our original function:

def f(x):
    WEIGHT = 0.33
    BIAS = 0.51
    return WEIGHT * x + BIAS

If we rounded the weight and bias naively, we get this function:

def f_round_naive(x):
    WEIGHT = 0
    BIAS = 1
    return WEIGHT * x + BIAS

and if we apply a scaling constant of 100:

def f_quantized(x):
    WEIGHT = 33
    BIAS = 51

    # `//` is integer division
    return (WEIGHT * x + BIAS) // 100

Now, let’s compare their outputs for x = 20:

>>> f(20)
7.11

>>> f_round_naive(20)
1

>>> f_quantized(20)
7

You can see that the properly quantized function has almost the right answer, and that the naively rounded function is completely wrong.

Let’s apply quantization to our basic NNUE network now. We can keep our training process completely the same (i.e., with floating points), and only quantize the weights after. That is, once we have a fully trained neural network, we take its floating-point parameters, then convert them to integers before using the network in the engine.

Before quantizing, we scale the neural net parameters:

Multiply the accumulator’s weights and biases by SCALE_L1, which is defined to be 255.
Multiply the output’s weight by SCALE_OUT, which is defined to be 64.
Multiply the output’s bias by SCALE_OUT * SCALE_L1.

(I just took the values straight from the Wiki article, which says that these are commonly used.) Then, we round the model parameters to the nearest integer. Once the model parameters have been quantized, we need to modify the inference code in the actual engine. This happens in two places:

We re-define CReLU to be clamp(x, 0, SCALE_L1).
At the end of the neural net forward pass, we divide by SCALE_L1 * SCALE_OUT, i.e. 255 * 64.

After the division, the result is exactly the same as before scaling (if we exclude rounding error). For an explanation of why, please see this appendix to this post.

The model now being quantized, everything in the engine code operates with integers, so the neural network inference is faster, and most importantly, does not have drift caused by floating point error. The trade-off for this is that the result is less accurate, because rounding the parameters creates a different kind of error (but this error does not build up over time).

It is important to carefully consider the data-types you use in your engine code, because it could make SIMD more effective. Recall that SIMD means you are executing a single instruction, on multiple data. The amount of data a single instruction can process is limited to a certain amount of bits; typically this is something like 256 bits. That means if your accumulator uses i32 (32-bit signed integer), you can operate on 8 numbers at once. However, if you use i16 (16-bit signed integer), you can operate on 16 numbers at once, which could be faster.

A caveat: if you pick a data-type that is too small, there is a risk that you get integer overflows or underflows. This is why the clipping in CReLU is important; it has a very specific and known output range, which lets you ensure that the integer limits are respected. Recall also how the centipawn-WDL sigmoid curve has a parameter K = 400, but our output node’s activation function is a sigmoid with K = 1. Our neural network K parameter is smaller so that the neural network is trained to output relatively small values. This way, the network’s weights will be small and won’t cause overflows.

For an example of how a good engine works with different data-types in NNUE code, see Stockfish’s docs about quantization. They use a mix of i8 and i32 depending on the layer of the network, in order to push the CPU to the maximum.

For my engine, optimizing every single instruction is not my priority, so I just picked i16 for the parameters, and i32 for the accumulator. (Having i32 gives a large margin for avoiding integer overflows.)

Here’s an example of pseudo-code for quantized NNUE evaluation. Note that it only contains the inference code for running CReLU and then computing the result at the output node; the accumulator nodes are updated with practically the same code as before (but with quantized weights now).

# quantization scales
L1_SCALE = 255
OUTPUT_SCALE = 64

DE_SCALE = L1_SCALE * OUTPUT_SCALE

# sigmoid K parameter
SCALE_K = 400

def crelu(x):
    return clamp(x, 0, L1_SCALE)

def output(hidden):
    """Compute the neural network evaluation in centipawns."""

    # hidden is the hidden layer's pre-activation states (i.e. the accumulator).

    out = 0
    for j in range(L1_SIZE):
        out += WEIGHTS_OUTPUT[j] * crelu(hidden[j])
    out += BIAS_OUTPUT

    out *= SCALE_K

    out /= DE_SCALE

    return out

Recall that the weights themselves aren’t quantized in the engine code (for my engine, the Rust code), they’re already quantized in the neural network training code (Python for me). In the engine, the main thing we need to do is de-scale the output at the very end (i.e. divide by DE_SCALE). The de-scaling is the last step, because integer division loses precision; in other words, we round only at the end.

Conclusion

I’m done explaining how my engine’s NNUE works. Now, here’s the fun part: pitting the smarter engine against the old engine, which has material counting evaluation. When I did this, the NNUE engine crushed the material counting engine, with 667 wins, 7 losses, and 32 draws, which represents a few hundred Elo gain. Not bad!

Here is an example game from this tournament. Note that this tournament ran at a time control of 8 seconds + 0.08 second increment, and an opening book was used for the first few moves.

I’m not good at chess, so I can’t analyze the game for you. However, notice how White (the material-counting engine) shuffles its rook over and over, while Black (NNUE) develops its pieces. You can definitely tell that the NNUE has some positional intelligence.

If you want to see more, I also uploaded two other games from this tournament to the Lichess study, which you can access through the “View on Lichess” option.

There are of course still many issues with my engine’s NNUE in its current state. First of all, its chess strategy is still far from being good. One of my smarter human friends who played against it said “that’s not how you play chess”. (I personally don’t understand chess enough to discern this.) I think the NNUE’s inability to play great chess is probably a limitation of its training, which I talk about more in this appendix to this post.

However, in general, I’m quite proud of my chess engine; it plays chess at a level way above my own comprehension of the game, and I’m happy with that.

Appendix: CReLU quantization

Above, I outlined the procedure for applying quantization on the basic NNUE. Recall that during the quantization process, we scale up all the neural network’s parameters. Then, at the end of inference, we scale the result down so that it has the same value as a network without quantization. We use scaling because rounding big parameters causes less relative rounding error than with small parameters.

To scale the parameters correctly, we first follow these steps:

Multiply the accumulator’s weights and biases by SCALE_L1, which is defined to be 255.
Multiply the output’s weight by SCALE_OUT, which is defined to be 64.
Multiply the output’s bias by SCALE_OUT * SCALE_L1.

Then in the inference code, we make the following adjustments:

Redefine the CReLU activation function as clamp(x, 0, SCALE_L1);
Divide the neural net’s output node pre-activation by SCALE_L1 * SCALE_OUT.

I will now show why this procedure works while preserving the neural network’s output.

Let’s define the original neural network’s output as a mathematical expression, using i to index inputs, and j to index hidden layer nodes:

where:

z_out is the pre-activation of the output node (output_preactivation);
b_out is the bias of the output node (BIAS_OUTPUT);
w_(out, j) is the weight of the connection between the j-th hidden layer node and the output node (WEIGHTS_OUT[j]);
w_ij is the weight of the connection between the i-th input and j-th hidden layer node (WEIGHTS_L1[i][j]);
x_i is the value of the i-th input;
b_j is the j-th hidden layer node’s bias.

During the quantization process, we multiply all weights and biases by some constants, SCALE_L1 (which I will denote S_L1) and SCALE_OUT (denoted S_out). We also change the definition of CReLU to clamp(x, 0, SCALE_L1) (instead of clamping from 0 to 1). I’ll denote this new CReLU as CReLU_L1. This gives us a scaled neural network output,

Let’s first focus on the CReLU, which is this part of the expression:

If we factor out S_L1, we get

As you can see in the graph below, we can pull out the scaling constant from the scaled CReLU_L1 to get a normal CReLU:

Now, the scaled output of our neural network is which we can factor (S_L1 * S_out) from to get Note that inside the bracket is the original, unscaled output of the neural network: from which we get To conclude, at inference time, after scaling the weights, biases, and the CReLU function, we can recover the unscaled output by dividing the scaled output by SCALE_L1 * SCALE_OUT. ↩

Appendix: Having no training data

In the post, I mentioned a few issues with the chess engine that I actually built, chess-inator. Most importantly, the NNUE is trained on a few orders of magnitude less data than it should have been trained on. Below, I document how that affected my project. Note that nothing in this section reflects best practice: I’m writing this purely to document what happened during the project.

There are two reasons I could not train the NNUE on a sufficiently large dataset; first, I was using data from SPRT tests (instead of generating them specifically for NNUE training), and also, my training code was not able to handle large datasets. As I mentioned in the post, someone in the Engine Programming Discord recommended using a 5000 node limit to generate training data. In my engine’s training, there is no such limit, so searches take longer to finish. This already reduces the number of positions that can be generated as training data. My training pipeline also heavily limited the datasets I could train on, as I I encoded positions in compressed text files as zeroes and ones corresponding to the input features. In hindsight, this is one of the most inefficient options there is, considering that in chess, most of the inputs are 0 at all times. The compression also didn’t help much because once you load the data in memory, it must be decompressed to allow for random access. Aggravating the memory usage problems, the Python library I used to deal with the training data, pandas, isn’t great at dealing with huge datasets.

When I first implemented NNUE in chess-inator, I trained it on roughly a thousand games from my own testing. This was, in hindsight, woefully too little training data. During games, this network would would make egregious tactical blunders, demonstrating a total lack of material knowledge. Later models were trained on barely more data, around tens of thousands of games; this was not enough of an improvement.

At the time, I could not fix the neural network’s tactical blunders, so I decided to use a hacky solution. I hardcoded the material knowledge in the neural network by directly writing piece values into the neurons before training. After this modification, the neural network would at least match the performance of material counting evaluation.

Generally, I would say this strategy worked in my situation; all of my NNUE models are trained with hardcoded material knowledge, and they’re definitely superior at chess than the non-NNUE evaluation functions.

Still, training with really low amounts of training data has its issues. Notably, the engine isn’t realizing the potential of its current neural network architecture; lots of performance could still be achieved just by increasing the amount of data. Also, there are weird artifacts in the evaluation function: sometimes, the score for a specific position will be thousands of centipawns off.

Unfortunately, this is the point where I left off on chess-inator; I never fixed the neural network’s lack of training data. This was my first real project in machine learning, and ultimately I learned that throwing more data at an ML problem is usually a good idea. It would be really fun to come back⁴ to chess-inator and properly train the neural network with lots of data, but the reason I stopped working on the project was that chess engine development is highly addicting, and I’m scared of getting sucked back in. ↩

Because of how chess works, there will never be a White pawn on a1, so this bit is useless. However, such redundancy helps simplify our code, so it’s fine to leave it there. ↩
See this paper that mentions this issue. ↩
As I understand it, Stockfish no longer uses HalfKP as of today; they use HalfKA. ↩
As of writing, it has been a few months since the last commit of chess-inator. ↩

Chess engine, pt. 5: Quiescence search, endgames, repetition avoidance

2025-04-26T10:00:00Z

Chess engine, pt. 5: Quiescence search, endgames, repetition avoidance

2025-04-26

This post is part of a series about building a chess-playing engine.

Introduction (0) | ← Last part (4) | Next part (6) →

At this point in the series, our DIY chess engine has an okay skill level, but it actually has a few major flaws.

If you observe the games it plays, it occasionally makes really obvious (to a human) mistakes, it can’t checkmate with just a king and a queen, and it will draw by threefold repetition instead of easily winning the game.

These are really annoying issues if you don’t know what causes them, or how to fix them. The obvious blunders are especially annoying, because it seems like a logic error in your code, but it is actually a fundamental problem in our heuristic negamax algorithm.

In this post, I’ll therefore be examining each of these problems, what causes them, and how they can be fixed. In other words, this part of the series is a “fixing annoying issues” post.

Horizon effect

The horizon effect (Wikipedia) is a problem that affects most programs that deal with a game tree, like our chess engine. It stems from the fact that our negamax thinks ahead by some exact depth, like 4 half-moves deep, and it immediately stops without considering what happens at the 5th half-move.

An example position

An example is the best way to demonstrate the horizon effect. Consider this chess position:

In earlier versions of my chess engine, it would play Bb5+:

This is a bad move: White is leaving their queen under attack, eventually losing the bishop. At first, it seems really weird that a program that is based entirely on counting material would make a move that loses material.

To debug this kind of mistake, we can construct the Principal Variation (PV) line of the negamax search. The PV is the series of best moves from a position, according to the chess engine. The first PV move is White’s best move, then the second PV move is Black’s best reply, then White’s best reply, and so on.

In other words, the PV is the “thought process” of the chess engine that shows what it expects to happen in the future.

To construct the PV, an easy (but inefficient) method is to return a list of moves instead of just the best move from the negamax function. A more efficient way is to use the transposition table (from last post) repeatedly to get the best moves, but this is not guaranteed to get the full PV.

Now, here’s the PV line of the above position, annotated by me:

The engine’s PV is Bb5+ c6 Bxc6+ Nxc6 Qxf6. White takes a pawn with a bishop, then takes a knight with the queen. With a depth of 5 half-moves, White thus gains a pawn (+100 centipawns) in material value.

However, at a depth of 6 half-moves, Black can take the queen (gxf6), and White thus has a -800 centipawn score from this exchange, i.e. it is a huge mistake.

Presumably, the chess engine searched at a depth of 5 half-moves and found that this exchange was advantageous, not seeing the big loss that happens at 6 half-moves.

Quiescence search

Let’s now try to mitigate this horizon effect.

Our chess engine evaluates this position as a +100cp advantage for White:

However, a human player, seeing this, would understand that White’s queen will immediately be captured on the next move, so this is actually a -800cp position. Therefore, if there are any pending captures in a position, our evaluation function can be misleading.

Let’s call any position without such pending captures a quiescent position, or quiet position.¹ (The above position where the queen is about to be taken is a non-quiescent position.) Then, notice how our engine’s evaluation function breaks on most non-quiet positions.

To avoid the horizon effect, all we need to do is to only run our evaluation function on quiescent positions.

Quiescence search (Wikipedia) accomplishes this by always searching more moves into the future until a quiescent position is found, and only then running the evaluation function.

In other words, we only evaluate positions after all the captures are done; we never use the evaluation function on positions where pieces are hanging (i.e. non-quiet positions).

Our negamax search will thus be divided into two parts: regular search, and quiescence search (“q-search”). For example, for a depth 5 search, negamax would search 5 half-moves ahead, then, if the leaf node is not a quiet position, quiescence search might look an extra 2 half-moves further until the position is quiet. Theoretically, there should be no depth limit on quiescence search; it runs until it finds a quiet position.²

Quiescence search is different from regular search in that it does not search all possible moves. While regular search will search every move, quiescence search will only examine obvious captures, like pawn takes queen in the above example.

What makes a capture “obvious”, though? Chess players know when a capture is good because they run a quick mental calculation of the exchange. They look at which pieces are attacking, and which pieces are defending, and then they see if they gain material by capturing.

Static exchange evaluation

Static exchange evaluation (SEE) is a heuristic that performs this quick calculation, that is it predicts how much material a player will gain or lose from performing a certain exchange.

The key idea of SEE is that in any exchange, there are two choices for the player to move. They can:

capture and keep the exchange going; or
stop the exchange if it’s not worth it to continue.

SEE is based on this dichotomy; both players always pick the choice that ends up giving the maximal score for them.

Take this position as an example:

White first captures with Rxd5, giving them a 900cp score.
Black captures with Bxd5, giving a 400cp (for White) score.
White then stops and plays a non-capture move Qh6, ending with a final score of 400cp.

In each step, the moves either side plays are advantageous for them (that is, any other move would be worse). It is worthwhile for White to trade their rook for Black’s queen, and it is worthwhile for Black to take back with a bishop. However, White does not want to trade their queen for the bishop.

Here is an example implementation of SEE in pseudo-code:

def eval_see(board, dest_square, our_color) -> int:
    """Simulate an exchange on a given square, and return its material gain for a given side."""

    # attacker piece of our color with the minimal material value
    least_attacker = board.get_least_attacker(dest_square, our_color)
    defender = board.get_piece_on(dest_square)

    eval = 0

    if defender is not None:
        least_attacker.capture(dest_square)

        opponent_gain: int = eval_see(board, dest_square, our_color.flip())

        # this represents the two choices of _stop_ and _capture_.
        # if capture has a negative eval, stop the exchange and get 0 material gain.
        eval = max(0, defender.value - opponent_gain)

        least_attacker.undo_capture(dest_square)

    return eval

Note: In the above code, I used a get_least_attacker(dest_square, our_color) method without explaining how to implement it. Recall the “I see you, you see me” check detection method from the first chapter. Suppose the king can move like a rook, and that the king-rook can capture an enemy rook. Then, we know that this enemy rook is attacking the king (and a similar process is used for other piece types). We can generalize this method to any square to detect attackers for SEE.

Now that we have an SEE routine, whenever we want to score a capture move, we can call SEE and check if it seems like a good capture or a bad capture.³ This is of course only a heuristic, because our static evaluation doesn’t take into account pins, promotions and other edge cases. SEE works most of the time, though. Remember that we mostly use SEE in quiescence search; regular search does take into account pins and promotions.

Quiescence search, continued

Having discussed SEE, let’s return to quiescence search. Our goal is, before calling the evaluation function, to get to a quiet position. That is, as long as there are good capture moves, or in other words pending captures, we should not evaluate the position.

Quiescence search is just like normal negamax search, except we only examine the good capture moves. When we run out of good capture moves, we can finally evaluate the position.

To find good capture moves, we first generate all captures, then narrow down the list by discarding captures with negative SEE score. If there are no captures, that means the position is quiet.

However, if the player is in check, we can’t just generate captures; we should generate all possible moves that could evade the check. A position with check can not be quiet, since there is a risk of checkmate.⁴

An important detail is that in quiescence search, no player is forced to make a move as in normal chess. That is, if all the captures with positive SEE worsen the current score of the position (given by the evaluation function), you are allowed to use this current score, known as the stand pat evaluation. When the stand pat evaluation is better than any capture move’s score, it’s a sign that the best move in that position is a non-capture move, which we don’t care about in quiescence search. If the player is in check though, we are not allowed to use stand-pat, since we might be ignoring checkmate.

Another note about implementing quiescence search is that many people write it as a separate function that is called in leaf nodes of negamax, while I integrated it into negamax to reuse some logic.

Now, here is my pseudo-code for quiescence search within negamax. I have removed the alpha-beta portions to make the function simpler; for a further explanation of the code this is based on, see the end of part 2.

QSEARCH_DEPTH_LIMIT = 8

def negamax(position, depth: int, is_qsearch: bool) -> (Move, int):
    """
    Return the best move and evaluation of a chess position.

    Will only think `depth` half-moves ahead.
    """

    if depth == 0:
        if is_qsearch:
            # hit depth limit (in quiescence search).
            # note that eval is score from our perspective
            return None, eval(position)
        else:
            # enter quiescence search
            return negamax(position, QSEARCH_DEPTH_LIMIT, True)

    best_score = -infinity

    if is_qsearch and not position.is_check():
        # stand pat score
        best_score = eval(position)

        # keep only captures with positive (good) SEE
        possible_moves = [move for move in generate_captures(position) if eval_see(position, move.destination, position.turn) >= 0]
    else:
        possible_moves = generate_moves(position)
        if possible_moves.empty():
            # checkmate or stalemate
            return None, eval(position)

    best_move = None

    for each move in possible_moves:
        updated_position = apply_move_to_position(position, move)
        opponent_move, opponent_score = negamax(updated_position, depth - 1, is_qsearch)
        our_score = negate_score(opponent_score)

        if our_score > best_score:
            best_score = our_score
            best_move = move

    return best_move, best_score

Note: Make sure that you have a move generator that specifically generates captures, instead of taking a regular move generator and filtering its output. Move generation is an expensive operation because it checks the legality of moves, and you don’t want to check the legality of moves that you immediately discard. My engine’s quiescence search took a long while to work because I made this mistake.

Checkmate heuristics

An essential skill in chess is delivering checkmate with few pieces. In this section, I’ll focus on the KQ vs. K (king + queen vs. king) and KR vs. K (king + rook vs. king) endgames.

Here’s an example of how an early version of my engine performs in a K-Q vs. K endgame:

The engine draws by repetition, even though KQ vs. K is supposed to be an easy win for the player with the queen.

The typical strategy in the KQ vs K endgame and the KR vs K endgame is as follows:

Bring the enemy king to the edge of the board.
Have your own king near the enemy king.
Checkmate with your king supporting the queen or rook.

The first two steps are essentially the preparation required to give checkmate; they set up all the pieces so they’re in the right place. Once we get to step 3, the engine should be able to see checkmate. Therefore, our goal is to help the engine do steps 1 and 2.

Cornering the enemy

Let’s first do step 1, bringing the enemy king to the edge of the board. In the code, we can do this by using piece-square tables.

To keep this article short, I’m only going to fully explain piece square tables in the next post. Essentially, in the evaluation function, a bonus or penalty is given to the score of a position depending on which square the king is on. In the endgame, we want the king to be at the center, so that can be a slight bonus. Meanwhile, a king at the edge of the board is vulnerable, so when the king is on the edge squares it gives a significant penalty.

Once we have this penalty, the engine will seek to gain advantage by cornering the enemy king, because it now knows that a king on the edge of the board is vulnerable.

We only want this piece-square table bonus/penalty to apply during the endgame, since in the opening of the game, we actually do want the king to stay at the edge. To concretely determine when it’s the endgame, we can count the pieces still remaining on the board, and if it’s under a certain threshold we say it’s the endgame.

Again, this is just a brief summary; see the next post for details about piece-square tables and determining when is the endgame.

Here is an example implementation in pseudo-code:

def eval_with_endgame_pst():
    score = count_material()  # this returns a score from our side's perspective.
                              # see prior posts for more information.

    if is_endgame:
        # 64 elements, one score per square the king could be on.
        # positive is a bonus, negative is a penalty.
        square_scores = {a1: -100, b1: -100, ..., e4: 10, ..., h8: -100}

        score += square_scores[board.get_square_of(our_king)]
        score -= square_scores[board.get_square_of(their_king)]

    return score

Note that in a real engine you would not implement a piece-square table just for the king: this code is specifically for demonstrating this section’s key ideas. Also, don’t use a dictionary for a piece square table.

King distance

Now, after we bring the enemy king to the edge of the board (first step), we continue with the second step: bringing our own king over to help with the checkmate.

In the above example KQ-K endgame, White’s king was on the wrong side of the board. It would take multiple steps to move the king across the board, but the engine’s search depth limit prevents it from seeing that. Thus, the engine could not deliver checkmate, and kept shuffling the queen until it got a threefold repetition draw.

To fix this issue, we tweak the evaluation function so that, in king + piece vs. king endgames, there is a bonus to a position’s score if the kings are closer. Or, equivalently, there is a penalty if the kings are far away.

Here is pseudo-code implementing this penalty:

def king_dist_eval():
    score = eval_with_endgame_pst()

    if (number of non-king pieces == 1) and (the piece is not a pawn):
        distance = (manhattan distance between kings)

        # this factor specifies which side is winning (i.e. doing the checkmate)
        advantage = 1 if (our side has the extra piece) else -1

        # this might have to be tweaked
        KING_PENALTY_FACTOR = 70

        king_penalty = -distance * advantage * KING_PENALTY_FACTOR

        score += king_penalty

    return score

The king distance penalty kicks in when the engine detects that it’s in a KR-K or KQ-K endgame. Notably, the code excludes a pawn endgame, which has a different strategy.

Then, we calculate the Manhattan distance between the kings. I used this instead of the usual Euclidean distance because it gives an integer result and is easier to calculate. Essentially, Manhattan distance is the distance to get from one point to another, if you can only move up, down, left, right (four directions, no diagonals). (In retrospect, it might have been a good decision to use Chebyshev distance instead, since it corresponds exactly to the number of moves it takes for a king to move between two points.)

Next, a negative sign is added to the distance; recall that a larger distance between kings is worse (negative) for the player trying to do checkmate.

An “advantage” factor is also used to make the sign of the penalty correct (since negative evaluation is good for the opponent, and positive is good for our side).

Before we get a final number, we multiply the penalty by KING_PENALTY_FACTOR. Once there are other bonuses or penalties in the evaluation function, this factor sets the weight of the “king distance” penalty compared to others.

Once we have these two heuristics, bringing the enemy king to the edge, and bringing our own king over, the chess engine is fully able to win in a KQ-K endgame:

The engine can also win a KR-K endgame:

With the heuristics, the engine took 30 half-moves to mate, while under optimal conditions (according to Lichess’s tablebase) this position is mate in 27 half-moves.

We’ve thus successfully taught the engine how to mate with just a rook, or just a queen.

Note: Iterative deepening is really helpful in endgame situations like this; since there are less pieces on the board, the engine can usually search deeper in the same amount of time. Using a fixed search depth, the engine might complete a depth 6 search in 0.2 seconds and stop right there; with iterative deepening, the engine might attempt a depth 7 or higher search with the extra time it has.

Threefold repetition draws

In chess, when a position is repeated three times (not necessarily three times consecutively), this is called a threefold repetition, and the players may claim a draw.

In computer chess, threefold repetition is usually automatically declared a draw by the UCI server, so you technically don’t have to handle it. However, threefold repetition leads to really annoying outcomes, like in this real game:

Though Black (my engine) has the advantage, it fails to win because it enters a loop and draws by repetition.

I’m not exactly sure what the engine’s thought process is in this situation; I assume it’s thinking “I can always capture the queen one move later” before playing Ne4+.

Regardless, we don’t want the engine to draw by threefold repetition when it’s obviously winning. We need to implement a system that detects threefold repetition ahead of time, and assigns that position a draw (zero) score. Then, the engine will prioritize winning over drawing, and avoid repetitions.

First, we need to precisely define what a position being “repeated” means. Wikipedia says (emphasis mine):

Two positions are by definition ‘the same’ if pieces of the same type and color occupy the same squares, the same player has the move, the remaining castling rights are the same and the possibility to capture en passant is the same.

Recall from last post that we already implemented a system that detects repeated positions: the Zobrist hash is a unique number assigned to each position such that two identical positions will have matching hashes. Our Zobrist hash incorporates all the elements of this definition: pieces with a given type, color, and square; the castling rights; the en-passant rights; and the current turn.

Therefore, the strategy for detecting threefold repetition is to keep a stack (a list) of the hashes of recent positions, and compare the hash of the each new position to the ones in the list. If there is a match, that means there is probably a repetition, so we can assign a draw score to the position. Every time we make a move in negamax, add the new position to the top of the stack, and every time we undo a move, remove the position from the stack.

You may think that comparing the hash of new positions to every single hash in the list is computationally expensive. One thing that makes it less inefficient is that we don’t actually have to look at the entire list. Moves like captures and pawn moves are irreversible, so once they happen, it’s impossible to see the previous position again. The engine already keeps a counter of “how many half-moves has it been since the last irreversible move,” since that’s part of the Forsyth-Edwards Notation (FEN) string. Therefore, we only need to search that amount of positions backwards in the list. Usually, this is some small number.

Note that some chess engines don’t actually implement threefold repetition specifically. Instead, twofold repetitions are already considered a draw, since it’s a waste of time to re-run negamax on a position the engine has already seen. There are some exceptions, though. Specifically, this is the strategy my own engine uses:

Three-fold repetition (i.e. the position is repeated twice) is an automatic draw. This follows the rule in chess.
Two-fold repetition (position repeated once) is a draw if the position being repeated is part of the negamax search tree, and hasn’t actually happened on the real board yet. This means that we’re already running negamax on this position, so we avoid re-doing the computation.
Two-fold repetition is not a draw if the position being repeated is in the history of the game, and actually already happened on the board. Two-fold repetition is not legally a draw in chess, and we still need to run negamax on the position for the first time.

If this strategy is too complicated, just ignore it and always score two-fold repetitions as draws. (The Chess Programming Wiki page has a differently-worded explanation of this concept, if it helps.)

Once repetition detection is correctly implemented, the chess engine will only go for repetition draws when the alternative is losing.

Conclusion

Once all the above features have been implemented, here is an example game between the upgraded engine and itself:

As you can see, the game does not end in a repetition draw, and quiescence search makes it so there are no horrible tactical blunders being played. This is definitely an improvement over prior versions of the engine.

At this point, a major issue still remains: human chess players often say my engine plays “weird”. I think this is because the engine has basic tactical (short-term) knowledge, but zero positional (long-term strategy) knowledge in chess. You may notice that in the game above, pawn promotion was the decisive factor in White’s win. Since pawns need many moves to get to the top of the board, the engine can’t see pawn promotion in negamax; pawn promotion is more positional than tactical. Clearly, positional chess skills can make or break a game.

In the next post, I’ll be explaining how the evaluation function of a chess engine can be improved (this component of the engine is where positional knowledge is encoded.) By the end of it, I’ll introduce neural networks to the chess engine, so that it plays better (and hopefully less “weird”).

Next part →

More precisely, we can define a quiescent position is a position where there are no good moves that significantly change the evaluation function’s result; the position is thus stable, or “quiet”. ↩
Empirically, I found that limiting quiescence to an amount like 8 half-moves produces performs well (but I do not know why). ↩
See this section of the relevant Chess Programming Wiki article. ↩
Recall that a quiet position can be defined as a position where the static evaluation is stable. A checkmate instantly destabilizes the static evaluation, so positions where that might happen are not quiet. ↩

Chess engine, pt. 4: α-β pruning and better search

2025-04-18T10:00:00Z

Chess engine, pt. 4: α-β pruning and better search

2025-04-18

This post is part of a series about building a chess-playing engine.

Introduction (0) | ← Last part (3) | Next part (5) →

In the part 2 of this series, I discussed how the negamax algorithm can be used to construct a chess-playing program. We saw that as negamax thinks more and more moves ahead, it increases exponentially in runtime. Because of that, we used a heuristic approach that limits how deep the algorithm calculates. The advantage of this approach is that negamax can run in a reasonable timeframe, but the disadvantage is that it now no longer plays perfect chess.

In the current state of the engine, it can think around 4 half-moves ahead; anything deeper and the runtime grows exponentially to the point where it freezes. However, many human chess players can calculate much further into the future than that, so they can easily defeat the chess engine. Meanwhile, modern, good chess engines can calculate lines dozens of moves deep. Many of them actually use the exact same negamax algorithm shown earlier; the difference between our bad engine and a good engine is how the negamax is optimized.

Search is the process of traversing the gametree, and negamax is one way to do it. Optimizing this part of the engine is how we can go from thinking 4 half-moves ahead, to thinking 30 half-moves ahead. Search is one main component of chess engines; evaluation is the other, and I’ll discuss that in a future post.

In this post, I’ll explore some of the main optimizations that can make our engine’s search more efficient, and therefore make it play better chess. Specifically, I’ll be examining alpha-beta pruning, transposition tables, move ordering, and iterative deepening. These are the optimizations that I think are the easiest to implement, but that give the biggest gains in performance.

Note: If you’re following along by writing your own chess engine, remember to SPRT your changes, as I discuss in the last post. This will ensure that your optimizations actually improve the engine.

Alpha-beta pruning

The main issue with our current negamax search is that it examines every possible move in every position, which takes a long time. What if we could reduce the number of nodes that it examines? This is known as pruning the game tree; we are cutting branches, i.e. not examining some moves in some positions.

Alpha-beta pruning is one strategy for pruning. Its core idea is that once you realize a move is a mistake, you stop analyzing this line, and you think about other moves instead.

An example situation

Here’s a concrete example position, White to move:

(If you can’t see the interactive Lichess study widget, a picture of the position is provided below.)

Suppose our chess engine generates moves in this order:

Rf1
Rd2
Rd8#

I know that a human player would immediately see the checkmate, but bear with me, because the computer has a different thought process.

We can draw a game tree as follows:

This game tree is limited to two half-moves. I’ve marked the evaluations for each end position, which are either material evaluations (0 because equal material) or checkmate evaluations (M0).

Here is how the engine evaluates the three moves:

The first move evaluated, Rf1, leads to a drawish position where both sides are equal in material. Therefore, this move has an evaluation of 0. So far, this is the best move.
Then, the engine will look at Rd2. This is a severe mistake, as it lets Black checkmate in one (Re1#). Without alpha-beta pruning, the engine, once it sees the checkmate, will keep examining Black’s other responses that don’t checkmate, like Re2 and a6. In other words, the engine thinks, “well, what if Black doesn’t do mate in one?” This is a waste of time; a human in the same situation, knowing that Rd2 is a mistake, would simply reject this candidate move, and think about other possibilities.
Finally, the engine sees that it can checkmate with Rd8#; this is the best move, and the final move it picks.

So, in this example, what we’d want to prune are the moves Re2, a6, and so on that we know aren’t worth considering. In a non-contrived example where the depth is higher, these moves would all have their own subtrees, which the engine would fully examine. Thus, pruning these moves creates big time savings; alpha-beta is the mechanism used to perform this pruning. (From my own experience, alpha-beta pruning noticeably improves the performance of the engine, shortening the search time from a few seconds to less than a second.)

Alpha and beta

To implement alpha-beta pruning, we introduce two arguments to negamax’s function signature:

negamax(position, depth: int, alpha: int, beta: int)

This function takes a node in the game tree, and returns the score of the node, along with the best move. Alpha and beta represent scores, in centipawns.

Alpha represents the best score obtained by the current player (us) in the current search. Meanwhile, beta is the best score obtained by the other player (them) in the current search. The current player is the one whose turn it is in the current node.

Every time negamax computes a score for a node, alpha is updated to the score (if it is better). Then, when negamax recurses, alpha and beta are switched and negated, because it’s now the other player’s turn.

Pruning happens when the current player finds a move from this node that’s “too good”, therefore the opponent will avoid letting this situation happen in the first place. Because of that, after finding that good move, we no longer examine other moves from this position.

Specifically, a move that is “too good” is a move that gives a score better than beta. This means that in some ancestor node above in the tree, the opponent found a candidate move that had a score of beta. Then, they examined another candidate move (which is a mistake) that leads to the current node. We got a score that’s better than beta (i.e. worse for the opponent). Since the current node is only reached by a bad move, we do not need to analyze it any further.

Note: When alpha-beta causes pruning, this is known as the node failing high. This means that the position will never happen, because it has a too high score for us. Since the score is better than beta, the pruning is also known as a beta cutoff.

Let’s now quickly examine how negamax with alpha-beta pruning works on the example position (see annotated game tree below).

Rf1 gives a score of 0 for White: no matter what both players do after Rf1, nobody has a material advantage. Then, alpha (White’s best score) is set to this score, α = 0.
Next, negamax tries Rd2, and now it is Black’s turn. Alpha now becomes beta, β = 0.
Black now responds with Re1#, giving a mate score (positive infinity for Black). This score is above beta (+∞ ≥ 0), which means we have a cutoff. Therefore, the rest of the moves, Re2, a6, and so on, are pruned and not considered at all.

In other words, from White’s perspective, Rf1 results in a score of 0, and Rd2 results in a score of -∞.¹ The move Rd2 is clearly a mistake for White, so they will never play that move. Therefore, we don’t need to consider Re2, a6 and all the other replies Black can play to Rd2.

Below, I’ve annotated the game tree diagram. The pruned moves have been grayed out and crossed with a red line. Dotted arrows also show where the 0 value comes from for alpha then beta.

I intentionally did not go through every step of negamax here, like some other sites do; I only wrote down the important values that caused the pruning. Personally, I think stepping through the algorithm for each node is useful, but it clutters a post like this. Do remember that each node has its own alpha and beta, which is transmitted down the tree.

Now, an implementation of alpha-beta in pseudo-code:

def negamax(position, depth: int, alpha: int, beta: int) -> (Move, int):
    """
    Return the best move and evaluation of a chess position.

    Will only think `depth` half-moves ahead.
    """

    if depth == 0:
        return eval(position)

    possible_moves = generate_moves(position)

    if possible_moves.empty():
        # checkmate or stalemate
        return eval(position), None

    best_score = -infinity
    best_move = None

    for each move in possible_moves:
        updated_position = apply_move_to_position(position, move)
        opponent_move, opponent_score = negamax(updated_position, depth - 1, -beta, -alpha)
        our_score = negate_score(opponent_score)

        if our_score > best_score:
            best_score = our_score
            best_move = move

        if our_score >= beta:
            # Beta cut-off
            break

        alpha = max(alpha, our_score)

    return best_move, best_score

Initially, alpha and beta should be set to negative infinity and positive infinity (the worst scores for us and them respectively, from our perspective.).

Transposition table

A transposition in chess is when you get to the same position in a different way. For example, look at this game tree from the starting position (Lichess study):

Both branches have different moves, but in the end, both reach the same outcome. Currently, each time our engine gets to a node that is a transposition, it does the entire negamax computation again. This is wasteful, so we want to avoid re-computing the same values.

Hashing

Generally, the solution to avoid costly recomputation is caching, or memoization. Essentially, once we compute the score for a position, we store it in a hash table. (In our case, the hash table is usually a big array.) Every time we encounter the same position in our search, we can reuse this cached score.

Importantly though, how do we hash a chess position? We want to be able to take a chess position and turn it into an integer array index, so that every time we encounter the same position, we can reuse the score in the array.

The common method to hash chess positions is Zobrist hashing. I’m not good enough at math to explain why this is a good hashing method with low collision probability, but I can explain how it works.

First, randomly generate a bunch of 64-bit integers, known as keys. Generate:

one key for every combination of square (64 squares), piece type (6 types) and colors (2 colors), for a total of 768 keys;
2**4, so 16 keys for every combination of castling rights. There are two colors, and each can have either kingside castling, queenside castling, both, or neither;
8 keys for the current en-passant file;
one key for every color, to mark the current turn.

Essentially, these keys all represent individual attributes of a chess position. These are most of the fields in a FEN, except for the move counters. Using these attributes (what pieces are on which squares, what castling rights does everyone have, if and where we can en-passant, whose turn it is), we can uniquely identify a chess position.

Then, to hash a chess position, take all the keys that represent it, then bitwise XOR the keys. This will produce a numeric, 64-bit integer hash.

If two positions have a matching Zobrist hash, then chances are they’re the same position.

Incremental hashing

The main advantage of Zobrist hashing is that it can be incrementally updated.

Let’s say we move a White pawn from e2 to e4. Then, to get the Zobrist hash for the new position, we take the old hash, XOR the (pawn, e2, White) key, and XOR the (pawn, e4, White) key. This works because if you XOR twice by the same thing, it cancels out and undoes the first operation. Then, do the same XOR operations for the current turn / color keys.

So, computing the new hash is only four operations, which is good for performance. Every single negamax call will have to compute a hash, which is why we want to optimize this step as much as possible.

Indexing

Our hash table / cache can be implemented as a big array. In C-style pseudo-code, it looks like this:

TTableEntry hashTable[N];

where N is the number of entries in our cache. Ideally, we would have 2**64 entries, that is, for every possible Zobrist hash, we store an entry. However, if we had 2**64 entries, each a byte, that would be in total 18.4 exabytes in memory usage, which is infeasible.

Typically, hash tables are around the scale of 100 megabytes, so N = 10**8 entries.

Therefore, we need to find a way to convert a hash into an index that is smaller than 10**8, or some reasonable number like that.

To do this, we take the hash modulo N. For example, if the hash was 223, but the array only has N = 100 entries, then I would use the index 223 % 100, i.e. the index 23.

Better engines that strongly optimize performance don’t explicitly use the modulo, because this operation is relatively slow. Instead, they set their hash table’s size to some power of two. Then, truncating the high bits off the hash is equivalent to the modulo operation. For example, say N = 8, and the hash is 0b110110. Then, the top two bits would be truncated to give an index 0b0110. This is equivalent to 0b110110 % 8.

Note: Even better engines, like Stockfish, use arcane math magic to use fast CPU instructions, while also allowing any N, not just powers of two. See Daniel Lemire’s post about this technique.

Using the transposition table

Once we have the indexing scheme, we can use it to cache our negamax results.

Earlier, I used the type TTableEntry for the individual array elements of the transposition table. This could be a struct, and the important fields stored in the transposition table are usually:

the Zobrist hash of the position;
the depth parameter of negamax;
the score returned;
the best move returned.

Then, at the start of the negamax function, we attempt to use a cached result. If there is a matching table entry, we check the depth of the result. If the cached result’s depth is greater or equal to the depth we want (i.e. the cached result is accurate enough), we may use the cached result directly.

entry = hashTable[indexFrom(position.hash)]
if entry is not None and entry.hash == position.hash:
    if entry.depth >= depth:
        return entry.score, entry.best_move

Notice how we compare the transposition table entry’s hash to the position’s hash. Since we use modulo to get the index in the transposition table, two hashes will often map to the same index. Therefore, we need to compare the full 64-bit hash to be certain the cache entry matches our current position.

At the end of the negamax function, we save the result to the transposition table:

hashTable[indexFrom(position.hash)] = (position.hash, depth, best_score, best_move)

Here, we’re overwriting the hash entry at that index. Possibly, there might already be an entry with this index, which we would erase by doing this. This is known as an always replace replacement strategy. There are other replacement strategies, but empirically, always replace is a simple and decent one.

Note: When testing the transposition table, it may be useful to implement the info hashfull statistic in UCI. This represents, in permille (0 permille is 0%, and 1000 permille is 100%), how many entries in the hash table are used. When hashfull is high, that means entries are often being replaced. Ideally, this number would be low, so that you aren’t throwing away entries.

Move ordering

Move ordering is the order in which moves are evaluated by the engine in each position. Optimizing move ordering is an easy, yet very effective approach for improving the performance of alpha-beta pruning. We saw earlier how alpha beta pruning can easily cut out dozens of moves from the game tree, like with Re1# in this diagram:

However, this relies on Re1# being the first move examined. If Re1# was the last move, then the beta cutoff would only be triggered at the end, and that would save no computation at all.

Because of how alpha-beta pruning works, finding a good move first can either immediately cause a beta cutoff, or, otherwise, raise alpha so that later there is a beta cutoff. Therefore, we want to examine good, or at least promising moves first, and then examine bad moves. This way, we maximize the chances of pruning the game tree and saving time.

The problem with getting good move ordering is that computers have zero intuition about chess. A hypothetical chess engine could evaluate a3 first from the starting position, simply because of alphabetical order, even though it’s not a great move.

Generally, the strategy to teach the computer about move ordering is to assign a score to each move based on some heuristics, then sort the list of possible moves based on that.

MVV-LVA

A good heuristic to order moves is MVV-LVA, most valuable victim, least valuable attacker. Essentially, this heuristic assigns a score to each capture move, which is:

(material value of captured piece) - (value of capturer piece)

For example, capturing a queen with a pawn has a score of 9 - 1 = 8, so pretty good. But capturing a pawn with a queen is 1 - 9 = -8, so not a good idea. Thus, MVV-LVA provides some decent intuition to the chess engine about what makes a good capture.

Recapture heuristic

In chess, trading pieces is an important part of the game. For instance, in this position, White can trade its pieces on the d5 square to gain 700 centipawns of material:

When exchanging pieces, most of the time the best move is very obvious: it’s to recapture the piece on the square you are trading on. The computer does not understand this, and it might generate completely irrelevant moves that lose material, like Nd7?? in the above study.

Therefore, the recapture heuristic says the engine should recapture with the least valuable attacker. This is practically always the best move in an exchange of pieces. Since we have MVV-LVA, we already have a bonus for the least valuable attacker, so we just keep track of the square where a capture last happened, then add a bonus to the move’s score if it’s a recapture on that square.

Iterative deepening

Iterative deepening is another strategy that helps with move ordering. The key idea is that the best move you get running negamax at depth N is probably the same move you’ll get running negamax at depth N + 1.

Because of that, we can run negamax at a lower depth, then use the results from that search to help with move ordering at a higher depth. Practically speaking, that means we run negamax at depth 1 to get a rough idea of what the best move is, then run it again at depth 2 to get a better idea, then depth 3, 4, 5, and so on. Each iteration improves on the accuracy of the best move returned.

In pseudo-code:

i = 1
while True:
    negamax(depth = i)
    i += 1

    if good enough:
        break

Iterative deepening might seem like a waste of time because it re-runs negamax over and over again, but in combination with the transposition table and alpha-beta pruning, it is actually a big improvement.

We can use the transposition table as a move ordering heuristic: always consider the transposition table’s best move (the “hash move”) first in negamax, even when the entry’s depth is lower than the search’s depth. When using iterative deepening, we’ll re-run negamax on the same nodes multiple times, and it will be able to use the hash move from prior iterations to guide the move ordering.

Better move ordering creates more beta cutoffs, and this completely offsets the time spent repeating negamax at lower depths.

Time management

Iterative deepening is good for move ordering, but as a side note, it is also necessary for clock management. When playing bullet (~1 minute) chess, the chess engine doesn’t have as much time to think as in classical (~1 hour) chess. Therefore, depending on how much time the engine has left, it must manage how deep it thinks.

Typically, engines will use iterative deepening to first perform low depth searches, and if it has more time, start higher depth searches.

The way this is usually implemented is with two deadlines: one soft, one hard. If iterative deepening finishes a negamax search and the time is past the soft deadline, it breaks out of the loop. Meanwhile, if the hard deadline is passed, negamax immediately aborts, even in the middle of the search.²

Conclusion

In this post, I covered some of my favourite optimizations for chess engine search. Unfortunately, because I didn’t implement all these features in this order in my own chess engine, I can’t show an example game between the improved and original version. Trust me though, they do make the engine play much better chess.

Again, these are just some of the most simple to implement techniques; if you wish to read more, there are a bunch of links in this post, and you can also consult Search on the Chess Programming Wiki for more inspiration. Note that the wiki documents a wide variety of search strategies and optimizations, many of which are rare and not necessarily worth implementing.

At this point in the series, there are still some major issues with our chess engine. Some of the most annoying ones are that it constantly does repetition draws, makes obvious blunders, and, worst of all, according to my friend, it “plays weird”. In the coming posts, I’ll discuss strategies to fix all of these issues.

Next part →

(Thanks to Lichess for the interactive studies and chessboard diagrams.)

When there is a beta cutoff, the score that causes the cutoff (+∞ for Black in the example) is a lower bound on the true score. We never actually examine the pruned moves, which may have a higher score. From the opponent’s perspective, the score (-∞ for White in the example) is an upper bound. ↩
The hard deadline can be implemented with a check in negamax that runs occasionally, e.g. every 65536 nodes searched, to avoid a performance hit. If the hard deadline is passed, the search is aborted. ↩

Chess engine, pt. 3: Elo, and rigorous SPRT testing

2025-03-15T10:00:00Z

Chess engine, pt. 3: Elo, and rigorous SPRT testing

2025-03-15

This post is part of a series about building a chess-playing engine.

Introduction (0) | ← Last part (2) | Next part (4) →

In the last part, we went over the negamax algorithm, which is the core of how a chess engine can play good chess.

Honestly though, I think the content in this post is the most important part of the series, in terms of how essential it is to writing a good chess engine. Minmax and negamax are really well-covered, even trite topics at this point. But proper testing methodology is something many other websites won’t teach you. Despite the relative obscurity of this topic, you need to test, and you should start as soon as possible.

This post will talk about the Sequential Probability Ratio Test¹, or SPRT. What is this test? Essentially, it is a statistical technique that can help you determine if an improved version of your engine is actually better than the old version.

By always running an SPRT when you create an improved version, you are certain that your engine is better, and it’s not a fluke. Otherwise, you might be introducing changes that weaken your engine, but because of bad testing methods, you’ll think it’s actually better. And then, in the worst case scenario, you’ll have to tear apart then re-test every single piece of your code.

So, learn good habits; do SPRT.

In this post, I’m not going to thoroughly explain all the details of the mathematics of SPRT (since I don’t have a solid background in statistics). For our purposes, we just need to understand what it’s doing, and its main results.

Elo ratings

First, some prerequisite context. How do we determine that a chess engine (or a version of the engine) is better than another? We measure the performance of the engines by having them play matches against each other. Usually, wins are assigned a score of 1 point, draws are 0.5 points, and a loss is 0 points.

For example, if Engine A wins 3, draws 1, and loses 1 game against Engine B, then Engine A has 3.5 points, and Engine B has 1.5 points. In total in this match, 5 games were played, and these 5 points were distributed between the players.

However, comparing performance based on win/draw/loss counts or points is a bit unwieldy. For example, if Engine A and Engine B play each other and their score is 12.5 to 10.5, while Engine B and Engine C get a score of 8.5 to 9.5, which engine is the best? Are you confused by all these numbers?

If so, you should be happy to know that a certain chess player, Arpad Elo, invented the Elo rating system to make our life easier. Using the point scores, Elo’s system lets you calculate a single rating number that quantifies a chess player’s performance, whether the player is human or machine. (If you want to see these calculations, please consult the relevant section on Wikipedia.)

Elo rating lets you easily compare the performance of players. If a player A has a higher rating than player B, player A is expected, on average, to perform better, i.e. score more points against player B. A bigger rating difference also predicts that there is a bigger skill difference, i.e. one player will score a lot more points than the other.

For instance, as of writing, Magnus Carlsen has a FIDE rating of 2837.1, and Hikaru Nakamura has a rating of 2799.4. Generally, Magnus Carlsen is considered to be a better chess player.

Note that Elo’s performance predictions say what should “probably” happen; it’s always possible, but improbable, that a bad player wins against a better player. Elo provides a framework that assigns probabilities for these outcomes.

FIDE and many other chess organizations use an Elo rating system.² Generally, even between different player pools that both use the same Elo system, ratings are not comparable. Machines also have their own Elo ratings. At the CCRL website, you can see a leaderboard of some of the best chess engines, as well as their rating. As I said, this is not really comparable to FIDE rating, or any other rating.

The SPRT

Now that we know what Elo is, let’s return to the main topic of the sequential probabilility ratio test.

What is an SPRT?

Note: This section is more mathematical in nature, and is not absolutely essential to using SPRT in engine development. However, I wrote this because having a base level understanding of what you’re doing is helpful. Skip this if you’re allergic to maths. Practically, this process is handled entirely by existing tools, so you don’t need to understand it.

The goal of an SPRT in chess is to accurately estimate the performance of an engine versus another engine. When testing, we run a series of games between the engines we want to test. Let’s say we want to test that engine A is better than engine B by some amount. We have two possible hypotheses:

Engine A is 0 Elo points better than engine B (no improvement).
Engine A is 10 Elo points better than engine B (improvement).³

These can be considered as “models” for the data. The models give the probability of certain outcomes. For example, let’s say we ran 1000 games, and the outcomes of these games for Engine A are WDLWWDWLLWLLWWWDD.... That is, Engine A won, then drew, then lost, then won, won, and so on, for a total of 1000 games.⁴ Here are some invented probabilities:

The “non improvement” hypothesis could say “there is a 1% chance of these outcomes happening.”
The “improvement” hypothesis could say “there is a 3% chance of these outcomes happening.”

These percentages are called the likelihood of this outcome, under a given hypothesis. If the likelihood for a given hypothesis is higher, that means the hypothesis is better at explaining the results we got, thus it seems like a better model.

Let’s define the likelihood ratio LR of our hypotheses as follows:

LR = (likelihood with "improvement" model) / (likelihood with "no improvement" model)

So, LR is a value between 0 and infinity. When it is lower than 1, that means our hypothesis of “no improvement” is a better explanation of our data. When it is higher than 1, our hypothesis of “improvement” is a better explanation.

Often, chess SPRT tools will convert this into a neat number using a logarithm. We can define the log-likelihood ratio as

log-likelihood-ratio = log(LR)

so that if the improvement hypothesis is more likely, it will be positive, and otherwise it will be negative. This is the number you’ll be seeing when you run an SPRT in practice.

We set some bounds, A and B. We set A to be a negative number, and B to a positive number. If log(LR) <= A, then we are mostly certain that the “no improvement” hypothesis is true. If log(LR) >= B, then we think “improvement” is the correct hypothesis.

But what happens if A < log(LR) < B? That means we don’t have enough data to convincingly pick either hypothesis over the other. Remember: at this point we are running chess games between engine A and engine B, and collecting the outcomes of the game. So, in SPRT, if we don’t have enough data, we keep running more games, until we get enough data to prove either hypothesis.

Once SPRT is confident of the hypothesis, we stop playing the chess games. Thus, we collect exactly enough samples to prove that one of our hypotheses is more likely than the other.

Now, where do the parameters A and B come from? There’s a formula that takes two parameters, α and β, and gives us values for A and B. α represents the probability of a false positive (i.e. a type I error), and β represents the probability of a false negative (i.e. a type II error).

So if you configure it so that α = 0.05, there is a 5% chance that the SPRT will wrongly determine that the “improvement” hypothesis is true, when it is actually false.

Note: For more information about the mathematics of SPRT, please see these links:

A lot of the information in this section comes from these pages.

Practical use: fastchess

Alright, enough math. How do we use the SPRT to test chess engines?

As it turns out, other people have already developed tools that perform SPRT tests for us. The one I use is fastchess. Once you have an engine that supports UCI (i.e. it implements the essential UCI commands from part 1 of this series), you can plug it into fastchess, and it will take care of everything.

First, you need to install fastchess and compile it using make from source. It is written in C++.

Next, you need to download an opening book. This is because if you play the same engine against the same other engine 1000 times, the outcome will probably be the exact same every time. Adding an opening book introduces some variation by playing a few unique moves in the opening before the engine starts playing. For my project, I used 8moves_v3.pgn from stockfish.

Then, you can start an engine chess tournament using fastchess:

fastchess \
    -engine cmd=engine_new name="The new engine" \
    -engine cmd=engine_old name="The old engine" \
    -pgnout file="games.pgn" \
    -openings file=8moves_v3.pgn format=pgn order=random \
    -each tc=8+0.08 \
    -rounds 5000 -repeat \
    -concurrency 8 \
    -recover \
    -sprt elo0=0 elo1=10 alpha=0.05 beta=0.1

Flag by flag, this is what this command means:

-engine: This is the path to the executables of the engines you want to test. You can assign a human-readable name to each of them.
-pgnout: This is a Portable Game Notation (PGN) output file, where fastchess will export all the games played in the tournament.
- Notably, the Lichess analysis board lets you import these games for you to review them.
- You may also create a Lichess study and import multiple games at once.
-openings: This specifies the opening file mentioned above.
-each tc: The “each” sets an option for both engines. The “tc” is the time control. This specifically means “8 seconds, plus an increment of 0.08 seconds per move played.”⁵
-rounds: Play 5000 rounds at most. Each round uses one single opening.
-repeat: Each round, play two games (swap the players’ colors for the second game).
-concurrency: Play 8 games at once. The more cores you have on your computer, the faster you can perform an SPRT.
-recover: If an engine crashes, restart it.
-sprt: These set the parameters for SPRT. Alpha and beta are the false positive and false negative rates, and elo0 and elo1 are the two hypotheses we want to test.

Fastchess has a decent man page and --help page, so consult those for more information.

One of the main pain points of using fastchess is that you have to compile your engines repeatedly and deal with all the executable files. Seemingly, many people (including me) accelerate this process by writing a shell script to automate it. Here is my shell script. Essentially, in my code repository, I can use git tag to mark the old and new version with descriptive names. Then, the script can take the tags, compile the respective versions, then run fastchess on them.

Another important point is the time control. Humans typically don’t play 8+0.08, because they can’t really think that fast. But in SPRT, you typically need thousands of games to achieve a statistically significant result. Therefore, developers often use a short time control (called STC), so that we can run these games in a practical time frame. The opposite is a long time control (LTC), which is closer to human blitz chess.

At this point in the series, I still haven’t covered time management yet, so if you’re writing an engine and you don’t have that feature, set its depth searched to some low number such that it’s fast enough to play a game in 8+0.08 time.

The other parameter you might want to tune are the SPRT hypotheses. [0, 10] works for testing a relatively big improvement. But if you are doing a non-regression test, i.e. testing that engine A is just as good as than engine B, you should use [-10, 0] instead. For example, this could be useful if you do a refactor and you want to make sure you did not accidentally weaken the engine’s code.

Also, if you’re testing really minuscule changes that only slightly affect engine performance, you might want to consider using a smaller value, like [0, 5]. See the Chess Programming Wiki article about SPRT for more examples.

Interpreting the output

Once you’re running fastchess, you should start seeing the outcomes of the chess games. Periodically, fastchess will also give a status report that looks like this:

--------------------------------------------------
Results of c_i nnue08a-512 (920bea1) vs c_i eval-saturating (9b3074e) (8+0.08, NULL, 500MB, 8moves_v3.pgn):
Elo: 107.54 +/- 127.62, nElo: 144.54 +/- 152.27
LOS: 96.86 %, DrawRatio: 50.00 %, PairsRatio: 4.00
Games: 20, Wins: 12, Losses: 6, Draws: 2, Points: 13.0 (65.00 %)
Ptnml(0-2): [0, 1, 5, 1, 3], WL/DD Ratio: inf
LLR: 0.17 (-2.25, 2.89) [0.00, 10.00]
--------------------------------------------------

The main statistic you want to look at in this status report is the LLR (here, 0.17), which is the log-likelihood ratio of SPRT, as discussed above. The (-2.25, 2.89) represent the A and B bounds, and [0.00, 10.00] are the Elo hypotheses.

Never ever stop the SPRT prematurely. In this example, you want to wait for the LLR to either be above 2.89, or below -2.25. If you see something like 30 wins and 50 losses, and you think “wow, this version must be worse, so I will stop the test”, that is wrong! For all we know, the engine might just be having a bad day and isn’t performing well. The whole point of SPRT is that the log-likelihood ratio will tell you if the engine is better or not, statistically speaking.

Once the SPRT is confident about a hypothesis, fastchess will automatically stop itself. Here, for example, is the final outcome of a passed SPRT:

--------------------------------------------------
Results of c_i nnue08a-512 (920bea1) vs c_i eval-saturating (9b3074e) (8+0.08, NULL, 500MB, 8moves_v3.pgn):
Elo: 19.57 +/- 13.22, nElo: 22.46 +/- 15.13
LOS: 99.82 %, DrawRatio: 37.81 %, PairsRatio: 1.27
Games: 2026, Wins: 867, Losses: 753, Draws: 406, Points: 1070.0 (52.81 %)
Ptnml(0-2): [134, 143, 383, 181, 172], WL/DD Ratio: 8.34
LLR: 2.91 (-2.25, 2.89) [0.00, 10.00]
--------------------------------------------------

As you can see, 2.91 > 2.89, so we are confident that the version nnue08a-512 is more likely to be 10 Elo better than eval-saturating, rather than 0 Elo. A negative LLR would be the opposite.

However, if your LLR is between the bounds (-2.25, 2.89), then that is not a valid result! You need to run the test for longer to get enough data to prove your hypothesis.

If you do accidentally stop fastchess, it automatically saves its state to a file called config.json. You can resume the SPRT by running

$ fastchess -config file=config.json

and it will restore your existing data.

Game pairs & pentanomial results

Remember when I said that fastchess will run two games per round? These are called game pairs, and the two games use the same opening. We use game pairs because every opening will give an advantage to a certain player. Even the starting position in chess is unfair, because White moves first. Therefore, for fairness reasons, we need players to play both White and Black in the round.

If we have engine A, and engine B, then on the first game, A is White, B is Black. Then on the second game, we swap it so B is White, A is Black. Because of this symmetric nature, we can say that the outcomes of individual games may be biased by the opening, but the outcomes of game pairs are unbiased in that regard.

These are the outcomes possible for the two games in a game pair:

Points	Outcome	Description
0	`LL`	loss, loss
0.5	`LD`	loss, draw
1	`WL`	win, loss
1	`DD`	draw, draw
1.5	`WD`	win, draw
2	`WW`	win, win

Since both DD and WL are 1 point, they are considered the same outcome. Thus, we have 5 possible outcomes, giving a pentanomial model. In fastchess, the Ptnml(0-2) statistic counts the game pairs that had each outcome. For example, if you see Ptnml(0-2): [134, 143, 383, 181, 172] that means there were 134 LL, 143 LD, 383 WL or DD, and so on.

Fastchess is faster than some other SPRT tools, because the pentanomial model will pick a hypothesis faster than using the trinomial (win, draw, loss only) model, using the same data.

Making your own Elo leaderboard

SPRT is the right tool for saying, “I am confident this version is better than that version.” However, if you want to rank a bunch of engines on a leaderboard, the better tool is Ordo.

Ordo takes the outcomes of chess games between any amount of players (human or engine), and computes Elo ratings based on it.

Once you build it from source, here is an example usage:

$ ordo -o ratings.txt -- file1.pgn file2.pgn

-o ratings.txt means output to ratings.txt, and file1.pgn, file2.pgn are the games it should read from. You can use a glob like games/*.pgn to match all PGN files in a directory games/.

Here are some ratings of different versions of my engine:

   # PLAYER                                :  RATING   POINTS  PLAYED   (%)
   1 c_i ttable-smaller4 (3060140)         :  1719.0   5897.0   11770    50
   2 c_i nnue08a-512 (920bea1)             :  1718.3   9428.0   18760    50
   3 c_i duplicate (920bea1)               :  1717.8   2478.0    4963    50
   4 c_i eval-saturating (9b3074e)         :  1698.8   3358.0    6804    49
   5 c_i ttable-smaller3 (a40e3b7)         :  1696.9   4636.5    9159    51
   6 c_i ttable-smaller2 (7123e9e)         :  1688.5   1510.0    2997    50
   7 c_i ttable-beta-cutoff (3baeda6)      :  1685.8   7544.0   15104    50
   8 c_i ttable-alpha-cutoff (a3649e4)     :  1685.5   2609.5    5223    50
   9 c_i ttable-smaller (bd477ba)          :  1674.2    689.0    1425    48
  10 c_i recap-heuristic2 (de55bab)        :  1654.8   1448.5    2839    51

  25 c_i lmr-new-new3 (cf52e13)            :  1501.8   4811.0    9626    50
  26 c_i lmr-new-new2 (3b748a1)            :  1499.3   4814.5    9614    50
  27 c_i no-frac (c0e36f5)                 :  1495.5  10259.5   19983    51
  28 c_i null-window-more2 (f5a17d8)       :  1484.4    749.5    1548    48
  29 c_i history-heuristic (dcff015)       :  1481.5    638.5    1330    48

 150 c_i nnue3-512 (4503401)               :  1012.4     11.5      28    41
 151 c_i contempt-disabled (caa3bc4)       :  1008.7     28.5      58    49
 152 c_i promote-extension2 (9b711bd)      :  1006.4     28.5      60    48
 153 c_i hash-opt-fix (79cfbef v)          :  1002.3     83.5     183    46
 154 c_i short-time2 (290a69a)             :  1000.5     28.0      60    47
 155 c_i promote-extension (359dd5a)       :  1000.0     41.0      88    47
 156 c_i contempt (3fe4b8c)                :   995.0     11.5      26    44
 157 c_i engine2 (97db55b)                 :   990.7    139.5     950    15
 158 c_i avoid-rep7 (e27e18e)              :   990.6    110.5     258    43
 159 c_i contempt3 (68d3d7e)               :   976.4     10.5      26    40
 160 c_i avoid-rep (db365c1)               :   972.4     13.5      32    42

(Since there are many versions, I’ve cut out many rows.)

Ordo provides nice leaderboard-style ratings for your engines. So, once you test a lot, you’ll be able to see the progression.

Conclusion

If you are writing a chess engine, run an SPRT on every change you make, with no exceptions. If you don’t, it’s quite possible that you’ll regret it.

Before I move on to the next topic, here is some further reading about engine testing:

Danny Hammer – Proper Chess Engine Testing: This guide is more thorough, and outlines how to use OpenBench, which allows you to runs tests on multiple computers. It also goes over a way you can estimate your engine’s CCRL rating.
Stockfish Docs – Fishtest Mathematics & Fishtest FAQ: Stockfish is the #1 engine in the world; these pages go over some details of how their advanced testing framework functions.

In the coming parts of this series, I’ll be going over the main improvements that you can make to a chess engine. If you’re following along by writing your own engine, you should be able to implement these changes and, using SPRT, be confident that your engine is improving.

Next part →

My apologies for writing “SPR Test testing” in the title. ↩
A notable exception is Lichess, which uses the Glicko 2 rating system. ↩
Internally, tools first convert Elo values to scores before performing the SPRT. See fastchess’s source code for an example. ↩
In practice, SPRT isn’t performed on the win/draw/loss outcomes of individual games in computer chess; we use the outcomes of game pairs to reduce bias. See this section of this post. ↩
I personally had to talk to the Engine Programming Discord members to discover the 8+0.08 time control, since it’s not really documented in many places online. Less than this, and your engine could forfeit games on time, and more time takes too long for the SPRT to finish. ↩

Chess engine, pt. 2: Negamax search

2025-03-07T10:00:00Z

Chess engine, pt. 2: Negamax search

2025-03-07

This post is part of a series about building a chess-playing engine.

Introduction (0) | ← Last part (1) | Next part (3) →

In the last post, I covered the UCI protocol, and move generation. Implementing these, it’s possible to create a chess “playing” engine that plays random legal moves. Though it does play chess, this engine is very bad, and it loses rapidly against players with any skill.

So, how do we make our program actually play chess? The classic answer is to use the minmax algorithm, but in my engine specifically, I use negamax, a common variation of minmax.

Negamax is the core of many modern chess engines, so in this post, I’ll attempt to explain the algorithm in a way that builds strong intuition and understanding for how it works.

The negamax algorithm

Negamax is an algorithm that finds the best move to play in any chess position. In other words, it is the brain of the chess engine, and it is what lets it play good chess.

What is the “best move” in chess, though? Our engine’s ultimate goal while playing chess is to win, or failing that, get a draw.

Scoring outcomes

Let’s now specifically define what the outcomes “win, lose, draw” mean.

We lose when it is our turn and we are are in checkmate.
We win when our opponent loses.
A draw is when the fifty-move rule or threefold repetition rule are invoked, or there is a stalemate.

For our purposes, there are no other outcomes to the chess game.

Notice how I don’t mention White or Black at all above. Usually, chess engine think in terms of Us versus Them. “We” are the player to move, which can be either Black or White.

Also, the outcome of a game depends on your perspective. If we win, they lose, and vice versa. The specific terminology is that chess is a zero-sum game. First, we assign numerical scores to win (1), draw (0) and loss (-1). These scores are positive when the outcome is good, and negative if the outcome is bad. Then, the scores for both players literally sum to zero:

our score + their score = 0

W + L =  1  + -1  = 0
L + W = -1  +  1  = 0
D + D =  0  +  0  = 0

By doing some algebra on this formula, we find out that

our score = -(their score).

In other words, we can negate a player’s score to get the other player’s score. This will be important later, and is the “nega” of negamax.

The game tree

We may imagine the game of chess as a tree structure, like this:

This picture represents all possible games of chess that can be played. The nodes (the circles) represent positions, and the edges (the arrows between circles) represent moves, which bring the game from one position to another.

The starting position is the node at the very top of the tree, and all possible games branch out from it.

The leaves (the nodes at the bottom) of the tree, each represent the end of a game of chess. There are practically infinite leaf nodes, but I only drew three of them.

In the leaf nodes, I also wrote the score of the game, from the perspective of the side whose turn it is. Notice how there are no 1 scores, since games can only end in either draw, or checkmate (which is a loss for the current player).

Trivial cases

Recall that the goal of the engine is to find the best move in each position. Let’s now examine some simple situations to see what engine should do in each case. From these examples, we’ll be able to build an algorithm that works generally in all situations.

First, say we’re White, and we have to choose between two moves in the diagram below:

the move on the left, which delivers checkmate (i.e. we win);
the move on the right, which lets Black checkmate us (i.e. we lose).

Let’s call this position A.

What’s the best move? Of course, the move on the left that makes us win, and not the one that makes us lose. Then, practically speaking, if we get to position A, that is a guaranteed win for White.

Next, say we’re White, and we have two moves to choose from. Both moves let Black checkmate us. Let’s call this position B.

In this situation, both moves are the best, since they both have the same outcome (i.e. we lose). Therefore, if we get to position B, White is guaranteed to lose.

More complex cases

So far, the positions we’ve looked at have been pretty simple. Let’s invent a more complicated position.

Say we’re Black, and we have the choice between two moves:

one leads to position A (a guaranteed win for White);
one leads to position B (a guaranteed loss for White).

Let’s call this position C.

Now, what is our best move? Earlier, we saw that for White, A is a win, and B is a loss. But for Black, it’s the opposite: A is a loss, and B is a win. Because of that, Black’s best move is the one that goes to B.

Therefore, if we get to position C, Black is guaranteed to win.

Eventually, we have the general case. Say we have the position X, where we have to choose between multiple moves, and they lead to positions Y1, Y2, and so on.

What is the best move? The best move is the one that leads to the position with the best outcome for us (i.e., the best outcome for the player to move). For example, if the position Y1 is a guaranteed win for us, we pick the move that leads to Y1. If there is no next position that is a guaranteed win, we pick the guaranteed draw.

Now, how do we know the outcome of the Y positions? Using a similar process for determining that position C above was a win for Black, we can build the game tree up to determine the outcome of any position in chess, including the Y positions.

The actual algorithm

Let’s now build concrete code (in pseudo-Python) for negamax, based on the above method for finding the best move.

The negamax function can be called on a node, and it will return both the best move for us (the player to move), and the numerical evaluation (i.e. the guaranteed outcome) for the position.

The notable difference between this code and the examples above is that this algorithm starts from a position, and thinks a few moves ahead, while in the examples we started from the end of the game, and worked backwards. (I think working backwards is easier to understand, as it’s more obvious why the best moves are the best.)

def negamax(position) -> (Move, int):
    """Return the best move and evaluation of a chess position."""

    if position.is_checkmate():
        return None, -1
    else if position.is_drawn():
        return None, 0

    possible_moves = generate_moves(position)

    best_score = -infinity
    best_move = None

    for each move in possible_moves:
        # note: in real code, consider using make/unmake instead
        updated_position = apply_move_to_position(position, move)

        opponent_move, opponent_score = negamax(updated_position)
        our_score = -opponent_score

        if our_score > best_score:
            best_score = our_score
            best_move = move

    return best_move, best_score

Here are the rough steps of the code:

Look at all the moves we can make.
Find the outcome of each resulting position by recursively calling the negamax function.
This outcome is from their perspective, so negate it to get the score from our perspective.
Pick the move that resulted in the best score.
The best score is the guaranteed outcome of this position.

Optimal play

With just these lines of code, we’ve (technically) solved the game of chess. Why? All games of chess are finite because of the fifty-move rule, so the function must terminate in finite time. We can therefore call our negamax function on the starting position, and it must tell us that either:

White has a guaranteed win;
Black has a guaranteed win; or
White has a guaranteed draw.

Not only that, it will also tell us the best opening move for White.

The consequence of this is that if two geniuses played chess optimally, the outcome would be the same every time. Therefore, as Claude Shannon wrote in 1949, if such “mental giants” were to start a game, one of them would immediately resign, or they would agree to a draw.

In this (unfortunately fake) video, grandmaster Maxime Vachier-Lagrave shows that in this scenario, the starting position in chess simply becomes a chess puzzle.

Your browser does not support the video tag.

Now, we know that in real life, no human chess player can play optimally. In fact, not even chess engines play at the level of our negamax algorithm. Theoretically, this code would play perfect chess. But practically, it would take forever to run.

If we use really generous numbers, let’s pretend that in any chess position there are two legal moves, and that there are invariably 80 half-moves in a chess game. Also pretend that the above algorithm requires one picosecond to analyze one unique game.

Then in that case, it would take 1e-12 * 2**80 seconds, which is around 38000 years to run. Of course, this is infeasible, so we must take some shortcuts with our algorithm.

A heuristic approach

The main issue with using the theoretical negamax algorithm is that as it looks more and more moves deeper down the game tree, it takes exponentially more time to run. An obvious way to make the algorithm practically useful is to limit the depth of recursion. That is, instead of examining the entire game tree down to the leaves, only examine a few layers of it.

Once we recurse up to a limit of n times, we’ll stop recursing. Then, negamax will guess the outcome (1, 0, -1) of a position, instead of properly calculating it. The disadvantage is that we’re no longer guaranteed the outcome, but now our negamax will run in a practical timeframe.

The evaluation function is the part that does this guessing. A chess engine’s evaluation function takes a chess position, and returns a numerical score for it. Traditionally, this score will be a single number. A bigger (positive) number means the position is probably a 1, while a lower (negative) number means the position is probably -1.

In this heuristic approach, we are replacing the theoretical scores 1, 0, -1 by the score given by the evaluation function. If our evaluation function is accurate at guessing the outcome of a game, negamax will find moves leading to positions with higher score, thus positions where the engine will probably win the game.

Material counting

Now, how do we make an evaluation function? How do we guess the outcome of a chess game?

It turns out that most chess players already have a decent sense of how to evaluate a position. Take a look at this position. Who do you think will win?

The answer is that White is winning. Why? One obvious hint is that White has an extra queen, and an extra knight. Having more pieces, or material, in chess is a big advantage, and will help you win. Let’s quantify this advantage now. When learning chess, many players are taught these relative numerical values for each piece:

Piece	Value
Pawn	1
Bishop	3
Knight	3
Rook	5
Queen	9

This rule of thumb helps players determine whether or not to sacrifice their pieces. For instance, you should sacrifice your rook, if it allows you to take the opponent’s queen. This is because the rook is less valuable (5) than the opponent’s queen (9), so in the exchange, you would gain 9 - 5 = 4 points of material.

Most of the time, counting the material value in a chess position is a really decent indicator of who will win, regardless of what level of chess you are at. Even the best players are less likely to win if they are at a material disadvantage. Thus, let’s define our evaluation function based on material value:

eval(position) = (sum of our piece values) - (sum of opponent's piece values)

On the board in the picture above, this would be

White material value:
5 + 9 + 3 + 3 + 1 + 1 + 1 + 1 = 24

Black material value:
5 + 3 + 1 + 1 + 1 + 1 = 12

Difference:
12 - 24 = -12 (score for Black)

Since it’s Black’s turn, we calculate that Black has a 12 point disadvantage.

Instead of using “material points” as our unit though, the traditional unit is the centipawn. As seen above, pieces are defined in terms of the value of a pawn (set to 1). Our scores can be more precise if we set the pawn’s value to 100 centipawns instead. A knight is 300 centipawns, a rook 500 centipawns, and so on. In the above example, Black thus has a -1200 centipawn score.

Note that usually, chess websites and programs will always display scores from White’s perspective, i.e. positive for White, negative for Black. So, on a Lichess analysis board, you would have a positive score here. But in negamax, and engine development generally, we usually deal with scores that are positive for “us” (the side to move), and negative for “them” (the opponent).

Regardless, this is the centipawn scale that engine evaluations and eval bars operate with. Typically, scores will be displayed as pawns. For instance, a -1200 centipawn score for Black will be displayed as +12.0.

Checkmate scores

Our evaluation function now works using the material advantage on the board.

At a basic level of chess, players want to earn material. However, the true end goal is always to deliver checkmate to the opponent. Therefore, our evaluation function scores also needs to take that into account.

To do this, we introduce mate scores. If the player to move can deliver checkmate in one half-move, then that is mate in one, or mate 1. For the opposite player that is about to get mated, this score is negative, so mate -1.

Note: other engines, chess websites, and the UCI protocol sometimes use full moves for mate scores. I think it’s slightly easier to code with half-moves instead, so that is what I used in my project. Divide by two to get a full move count.

For example, in this position, the score is mate 1, since White can win with Qh7#:

Let’s also define, as a base case, that the score for a position in checkmate is Mate(0). That is, if the player to move is in check and has no legal moves, that position’s score is Mate(0). If a player is about to be checkmated in one move (two half moves), that is instead Mate(-2).

Quantitatively, we can imagine mate scores as big numbers. This is because checkmate is literally a game-winning advantage, so it is much more important than any material advantage.

For example, we can assign

Mate(1) = 1000000
Mate(-1) = -1000000.

Let’s also make it so that mate in more half-moves is a worse score. If all mate scores are the same, the engine might start procrastinating the checkmate. It’ll always think “well this move lets me checkmate in 2 moves anyways, why should I do checkmate in 1?”, and then before you know it the engine starts shuffling pieces back and forth and draws by repetition. To avoid that, we could assign the values like this:

Mate(2) = 999999
Mate(-2) = -999999
Mate(3) = 999998
Mate(-3) = -999998

and so on...

Using these values, our engine will:

always prioritize avoiding checkmate or delivering checkmate over material advantage;
make moves that get closer and closer to winning.

Now, let’s redefine our evaluation function, this time in pseudocode:

def eval(position):
    if position.is_checkmate():
        return Mate(0)
    else if position.is_stalemate():
        return 0
    else:
        return position.our_material_value() - position.their_material_value()

We also need to write logic to increment the “mate in n” counter in the negamax algorithm. At every level of recursion, the Mate(0) will become a Mate(1), then Mate(-2), Mate(3) and so on. I’ll do this in the next section, with the final pseudocode for negamax in this post.

Heuristic negamax pseudocode

Let’s now rewrite our negamax algorithm to work with heuristic evaluation scores, instead of game-theoretical scores.

def eval(position) -> Score:
    """Evaluate a position."""
    if position.is_checkmate():
        return Mate(0)
    else if position.is_stalemate():
        return 0
    else:
        return position.our_material_value() - position.their_material_value()


def negate_score(score) -> Score:
    """Negate score, and for checkmate scores, increment mate in `n` counter."""
    if score is Mate(n):
        if n > 0:
            return Mate(-(n + 1))
        else:
            return Mate(-n + 1)
    else:
        return -score


def negamax(position, depth: int) -> (Move, int):
    """
    Return the best move and evaluation of a chess position.

    Will only think `depth` half-moves ahead.
    """

    if depth == 0:
        return None, eval(position)

    possible_moves = generate_moves(position)

    if possible_moves.is_empty():
        return None, eval(position)

    best_score = -infinity
    best_move = None

    for each move in possible_moves:
        updated_position = apply_move_to_position(position, move)
        opponent_move, opponent_score = negamax(updated_position, depth - 1)
        our_score = negate_score(opponent_score)

        if our_score > best_score:
            best_score = our_score
            best_move = move

    return best_move, best_score

When calling negamax initially, you should set some depth limit like 4. This is not a lot, but remember that negamax takes exponentially more time for every extra depth level searched.

Conclusion

Now, here’s a game between last part’s version (the one that plays the first move generated, without thinking) and a version using the negamax algorithm from this post. White is the negamax, and Black is the random move.

As you can see, negamax successfully captures a pawn, then delivers checkmate. Embarassingly, even though this version only looks 5 half moves ahead, and it has literally zero knowledge of chess other than the rules and the value of material, it can reliably beat me.

In this post, we’ve thus constructed a chess engine that can convincingly play chess. In the grand scheme of things, it’s not that good; any competent chess player would easily defeat this engine.

There’s lots of room for improvement right now. However, in the next part, before I explain some of the main optimizations for negamax, I’ll go over the testing methodology used to ensure that improvements actually improve the engine. This may seem boring, but if you are actually writing a chess engine, testing rigorously is a really essential good habit.

Next part →

(Credit to Lichess for the chessboard diagrams.)

Chess engine, pt. 1: Getting started

2025-03-06T10:00:00Z

Chess engine, pt. 1: Getting started

2025-03-06

This post is part of a series about building a chess-playing engine.

Introduction (0) | Next part (2) →

In this part of the series, I go over all the information you need to write a basic chess engine, one that plays random moves. Such an engine is the “hello world” of chess; once you get it to run, adding more features is simple. If you follow along through this entire post, you will be able to play games of chess against your engine. You could even connect your bot to Lichess, where it can play chess online.

The UCI protocol

I’ll start off by explaining the Universal Chess Interface, or UCI.

In computer science, protocols are quite powerful. Once your program implements an interface, or a simple subset of it, it suddenly has a common language to talk to other devices that also implement the protocol. For example, take HTTP; you can implement a server using any language, any hardware. Once you build something that talks HTTP, you can effortlessly expose it to billions of devices on the Web.

The equivalent standard protocol for chess engine programming is UCI. In UCI, there are two parties involved: the GUI, and the engine.

The GUI keeps track of the chessboard, takes move input from human players, and determines who wins the game.
The engine plays chess, i.e. given a chess position, it finds the best move.

Because the GUI handles a lot of tasks in UCI, your engine only needs to implement logic to play good moves. You can use GUIs built by other people, like CuteChess or Arena, which saves time and lets you focus on actually playing chess. The most exciting part is that once you have UCI, you can hook your engine up to lichess-bot, which lets it play rated chess online against other bots, and even human players on Lichess.

So now, let’s go over the actual protocol. Of course, I won’t go over every single detail in UCI; please see the UCI specification for more details. We’ll only look at a subset of UCI, but once an engine implements this, it can play chess through any compatible GUI.

First off, UCI communication happens over a command-line through stdin / stdout. For example, in Python, you could use input(), and print() in the engine to receive and send messages to the GUI.

Here is an example UCI communication. I’ll prefix the engine’s messages with >>>, and the GUI’s messages with <<< for demonstration purposes, but remember that these aren’t actually part of UCI.

<<< uci

>>> id name chess_inator
>>> id author dogeystamp
>>> option name Hash type spin default 16 min 1 max 6200
>>> uciok

<<< isready
>>> readyok

<<< ucinewgame

<<< position startpos moves e2e4
<<< go wtime 59780 winc 0 btime 60000 binc 0

>>> info score cp 43
>>> bestmove g8f6

<<< position startpos moves e2e4 g8f6 b1c3
<<< go wtime 59323 winc 0 btime 59123 binc 0

>>> info score cp 28
>>> bestmove b8c6

<<< quit

Let’s break this down.

`uci`

First, right after the engine is started, the GUI sends a uci. This command means “let’s talk using UCI”. The engine must reply with an uciok, which means “yup, I support UCI.” These messages exist because UCI isn’t the only protocol out there; others exist, like the Chess Engine Communication Protocol (CECP). Between uci and uciok, the engine may also send the id and option messages, which specify metadata about the engine, like its name, or the settings you can tweak. Typically, in the GUI, options will be displayed as buttons, or sliders, or checkboxes, depending on the type.

`isready`

Then, there’s an isready from the GUI, following by a readyok from the engine. This command is sort of an “are you still alive?” check from the GUI. If the chess engine is busy with initialization, it should send readyok after finishing up, i.e. when it is ready to play.

`ucinewgame`

Next, the ucinewgame from the GUI tells the engine to reset its state. This makes it possible to play multiple games without completely rebooting the engine every time.

`position`

Now for the actual game. In this example, we could assume White is a human player making moves on a chessboard GUI, while the engine plays Black. Here, the human plays the move e4 (this is Standard Algebraic Notation, or SAN for moves). The GUI therefore sends this command to the engine:

<<< position startpos moves e2e4

Here, the GUI is giving the state of the chessboard, i.e. “from the starting position, White made the move e4”. In UCI though, we don’t use standard algebraic notation like e4 to denote moves.

Instead, we use UCI long algebraic notation, like e2e4 to denote moves. This means “the piece on e2 moved to e4”.

For promotions, the piece being promoted to is added to the end, for example e7e8q is “promote a pawn on e7 to queen”, or e7e8r is “promote to rook”.
Castling is denoted as the king moving two squares in either direction, for instance e1g1 is kingside castling, while e1c1 is queenside castling for White.

Long algebraic notation is easier for programs to deal with, since it’s more explicit about what piece is moving.

`go`

The go command is the most important one in UCI. It tells the engine to start searching the for the best move in the current position (e.g. after White played e4, the engine thinks of Black’s best response).

<<< go wtime 59780 winc 0 btime 60000 binc 0

The wtime, winc, btime, binc parameters give information about how much time the engine has left to think.

wtime and btime are the clocks for White and Black, given in milliseconds. In the example, White has 59.78 seconds on the clock, while Black has 60 seconds.
winc, binc are the increments for the timer. In a 10+10 time format game, each side would have a 10000 increment, meaning after every move they gain 10 seconds on the clock.

Once the go command is received, the engine must reply with a bestmove:

>>> info score cp 43
>>> bestmove g8f6

This is essentially the engine saying “I play Nf6.”

Your engine may also print info lines. Here, score cp 43 means the engine thinks this position is a 0.43 pawn advantage for itself, i.e. a slight advantage for Black. The cp stands for “centipawns”. There are fields other than score (see the UCI spec), and these would be printed on the same info line. Ideally, you would print multiple info lines while the engine thinks in order to get a sense of the engine’s thought process, but this is not necessary.

`quit`

The quit command is self-explanatory; it tells your engine to terminate the program. (In C/C++ for example, this would be returning from main.) This is not to be confused with stop, that only stops an individual search.

`position fen`

This command is not in the example, because I don’t think it’s strictly necessary for a functioning chess engine. However, it’s very useful, so I’m including it in this list.

position fen takes a Forsyth-Edwards Notation, or FEN code, which is a string that represents a chess position. FEN is used commonly; for example, in Lichess, the analysis board always shows the current position’s FEN. You can then copy-paste the position into your engine, which is quite convenient.

For example, after 1. e4 from the starting position, you would have:

position fen rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1 moves e2e4

For brevity’s sake, I will not fully explain how FEN works; please read the Wikipedia article about it. However, I will give some extra tips.

First, remember that half-moves and moves are different.

A half-move, or ply is a single movement of a piece, e.g. e4 is a half-move.
A full move, or just move is when White makes a half-move, then Black makes a half-move, e.g. 1. e4 e5 is a full move.

This distinction is important, because FEN tracks full move and half move numbers.

Another thing is that the en-passant square in the FEN is the target square that can be captured. For example, if White plays pawn to e4, then the target square is e3, the square the pawn crossed over. Black could then play cxe3, capturing the pawn en passant.

FEN implementations differ on how they treat the en passant target square. Some, like Lichess, only include the en passant square in the FEN if it would be legal to take en passant. In the Wikipedia example, after pawn e4, the en passant square is e3; Lichess would say there is no en passant square, because Black’s pawns are not in the right place to take en passant.

When writing an engine, you may also notice that UCI GUIs usually send position startpos moves ... instead of a position fen .... This is because FEN is not actually able to fully represent a chess position. Due to the threefold repetition rule, you also need the board history to accurately evaluate a position. This is why a series of moves from the start position, which does encode the full history, is used instead.

`stop`

Another command you should technically handle is stop.

While the engine is thinking, if it receives a stop command, it should stop thinking and be ready to process other commands from the GUI.

This is relatively difficult to implement, since programs usually can’t process user input while doing computations simultaneously. Typically, chess engines will have two threads, one input thread, and one engine thread. The input thread processes the UCI commands, and the engine thread thinks. At regular intervals (but not too often to avoid performance issues), the engine thread will check in with the input thread to see if it has received a stop. If so, the engine will abort its thinking.

Move generation

Now that we know how to get the engine to talk to the GUI, we need to figure out the best moves to play. To do this, our engine needs to figure out what moves can be played legally. This is known as move generation. As mentioned in the introduction section, I assume that you know the rules of chess, so I will not go over how each piece can move.

Board representation

To generate moves, we must first have a board representation, i.e. a data structure in code that represents a chessboard. Two important ways of doing this are the mailbox and bitboard approaches.

In a mailbox board representation, the board is represented as a 2D grid, or array of 64 squares. Each square has a value that indicates either no piece, or the color and type of the piece on it. As I understand it, “mailbox” refers to the squares, and the pieces are the “mail” in the boxes. Mailbox board representation is usually the first implementation that programmers think of, and it is the simplest.

In a bitboard representation, each piece type and color (e.g. black rook, white pawn, white queen), has a 64-bit binary value that represents which squares it occupies, i.e. its “occupancy”. For example, in the starting position, the white rook bitboard could be 0b10000001, which means there is a white rook on a1, and a white rook on h1. Each bit in the binary value represents one of the 64 squares of the chessboard; typically the least significant (rightmost) bit is a1, and the most significant (leftmost) is h8. (See this page for a neat visualization and explanation of bitboards.)

A way to distinguish bitboards and mailbox is to think of them as piece-centric and square-centric. The bitboard answers the question “where is this piece?” while the mailbox answers the question “what is on this square?”. Because of their complementary nature, it can be useful to use both representations despite their redundancy.

The advantage of bitboards is that modern computers love dealing with 64-bit binary values, and as such they can be optimized really really well. However, algorithms using bitboards can be relatively complicated. The mailbox representation’s biggest advantage is that it’s simple to understand, because it maps well to our idea of what a chessboard is like.

In my chess engine, I decided to mostly use mailbox board representation, because it does a good enough job and it is simple to implement.

I’m skipping over many details about board representation above; if you’re curious, see the relevant CPW article on the topic.

Move encoding

After representing the chessboard, we also need to figure out how to represent moves.

A typical representation in strong engines packs moves into 16 bits. The source square takes 6 bits, and the destination square takes 6 bits, leaving 4 bits to encode things like the piece being promoted to, or any other information. In chess-inator, efficiency is not the primary concern, so moves are represented as a 24-bit Rust struct containing the same information.

Another important point is how moves are applied.

At first, in chess-inator, I thought it would be conceptually neat to implement chessboards as immutable states, such that moves could take in a chessboard to produce a distinct, updated chessboard state. The issue with this method is that copying entire chessboards around is painfully slow.

A faster method is make-unmake, where the engine has a single chessboard in memory. When the engine calculates, it makes moves on this board, then “unmakes” (undoes) the moves when it’s done with that line of thought.

Move legality

Coding the basic piece movement rules can be relatively simple. For instance, the rook can move in any square along 4 directions, but it is blocked by other pieces. Similar logic applies for the queen and bishop.

What complicates move generation is that in chess, players must not make moves that put their king in check. Such moves are illegal, and can not be played.

Engines therefore have to filter out illegal moves. A simple way to do this, and the way chess-inator does it, is to try every move, and determine if the king is in check. If it is, then the move is illegal.

A common method to determine if the king is in check is the “I see you, you see me” method. Let’s say we want to detect checks from rooks. Pretend the king can move like a rook. If the king, with rook movement, could capture an enemy rook, then that means the enemy rook can capture the king.

This method works for all other pieces (be careful with pawns, since their moves aren’t symmetric). It’s also decently efficient, since this method only needs to trace rays for 8 directions, and check for knight attacks, which will always be less than 64 squares checked. Still, my benchmarks show that check detection is one of the most expensive operations in my engine, since it’s called so often.

Testing with perft

Once you’ve written a move generation algorithm, you need to make sure it actually works.

The canonical test for move generation is the perft (performance test) function. perft(n) is the count of all unique chess “games” you can play, where each game lasts at most n half-moves. In other words, perft counts the leaf nodes of a legal game tree limited to some depth n.

For instance, from the starting position, perft(1) = 20. This is because there are 20 “games” of 1 half-move: White has 16 pawn moves (8 pawns can be pushed one or two squares), and 4 knight moves, giving 16 + 4 = 20. Then perft(2) = 400, because for each of those 20 opening moves from White, Black has 20 responses, giving 20 * 20 = 400 unique games of two half-moves.

Using your own move generation code, you can write a perft function, and generate your own numbers. If your results are different from known numbers, you can quickly deduce that there is a bug in the code. However, if your results are the same, that does not prove that there are no bugs.

A test suite I’ve often seen recommended is Andy Grant’s standard.epd, which contains different positions, as well as their expected perft results for different depths.

The bare minimum engine

Now that we have both UCI, and move generation, we have the tools to make the most basic engine, the equivalent of a “Hello World”: an engine that plays random moves.

My engine chess-inator achieved this milestone with commit 5751215, implementing an engine that plays the first move it generates. This took a while to implement properly, so finally putting the executable in the GUI and seeing my code play moves was pretty exciting.

For reference, here’s a game of me playing against this engine (credit to Lichess for the animation). As you can see, it’s not that great at chess, though nor am I:

We’re only getting started though; take a look at the next part of this series, which talks about ways the engine can more intelligently select the next move.

Next part →

Chess engine, pt. 0: Index

2025-03-05T10:00:00Z

Chess engine, pt. 0: Index

2025-03-05

Building chess engines, that is, making computers play chess, is seemingly a common pastime of programmers. Of course, I had to try it too, so I created my own engine, chess-inator, from scratch. As it turns out, chess engine development is incredibly addicting (I say this from experience), because there is always more room for improvement in your engine. Now though, chess-inator can beat most chess players I know personally, so I’m stopping before I spend way too many hours on this project.

This blog post series is essentially a log of chess-inator’s development, including important tips and information that I had difficulty finding from other online sources. Even though the series is mostly about my own engine, I wrote these posts as if they were a tutorial, because I like that tone. These posts are intended to focus on practical rather than theoretical aspects; you should technically be able to write an engine by following along.

The target audience of this blog series is me from 2024, that is a version of myself that doesn’t know anything about chess engine development. Ideally, this series contains all the essentials to get started with writing an engine without any prior experience. I assume you, the reader, are proficient with some programming language,¹ you’ve played chess before, and you know the rules of the game (google en passant). In this series, I use pseudo-Python for code examples, but my real chess engine project uses Rust for engine code.

Before I begin, here are the mandatory acknowledgements. Thanks to

the Chess Programming Wiki
the members of the Engine Programming Discord
and all the other people who publish resources about chess engine development online

for providing valuable information about chess programming and making this domain accessible to everyone. This project would really not be possible without them.

Index

Here is an overview of all the posts in this series:

Part 1: Getting started: In this post, I cover enough for you to write a chess engine that plays random moves. This is the base that the next parts will build upon. If you follow along with this post, you will quickly be able to play games against the engine you create.
Part 2: Negamax search: I cover the negamax search algorithm, which is a variation of minmax. Once negamax is implemented, the chess engine will play moves more intelligently (i.e. not random moves).
Part 3: Elo, and rigorous SPRT testing: I introduce the Sequential Probability Ratio Test, which is a statistical tool that can be used to rigorously test a chess engine’s performance. SPRT is very important in modern chess engine development.
Part 4: α-β pruning and better search: I go over some of the main optimizations to negamax: alpha-beta pruning, the transposition table, move ordering, and iterative deepening.
Part 5: Quiescence search, endgames, repetition avoidance: In this part, I explain how to fix some really annoying bugs in the chess engine. These bugs are inherent to how we implement negamax. After this part, the engine plays chess at a beginner level, albeit with a quite unnatural (i.e. bad) playstyle.
Part 6: Neural-net evaluation: I explain how neural networks, specifically the NNUE, can be used to improve a chess engine’s performance. This post goes over chess-inator’s NNUE architecture in great detail.

Some of my favourite posts in this series are part 3 (SPRT) and part 6 (NNUE). SPRT is something you should use as soon as possible when developing a chess engine, yet I’ve never heard of it before starting this project. If I had to recommend one part of this blog series, it would be the part about SPRT. It’s not an exciting subject, but it is essential to making a good chess engine.

I also had fun writing the NNUE post, because I think there is a shortage of resources for beginners. In my research, I found lots of general summaries that explain NNUE’s general concept, and also deep dives about Stockfish’s complex NNUE architecture. However, resources for my skill level are rarer. The aim in my NNUE post is to explain how a simple (and easy to understand) NNUE architecture works, with enough detail for you to follow along with its implementation.

In total, this blog series was written over a period of a few months, which is unsurprising given that it is really long² compared to my other writings. I hope that some of you find will it useful. If you find any mistakes in the posts (such as mixing up an i and a j, or a typo), please tell me. Feel free to write to me if you have any other comments.

Now, let’s begin: Part 1 →

Note: The dates given for all the blog posts are not the publication date; they’re the date that I created each document. Part 0 (this page) was written on 2025-07-07, but it has been backdated so that the order of the posts on the home page makes sense.

Ideally, the programming language you use for a chess engine is a performant language like C++, Rust, Java, C#. If your language is generally faster, then your engine will be better because it can do more calculations in the same amount of time. ↩
This series is roughly 25k words, which is five times more than the LC-3 article, the previous record holder. ↩

Box-drawing test

2024-02-03T10:00:00Z

Box-drawing test

2024-02-03

In my last blog post about the LC-3 virtual machine, I made a few diagrams with ASCII art. I found out recently that I didn’t have to use + and - and | symbols to make boxes; Unicode has symbols specifically for that. So I’m going to use this blog post as a playground for box-drawing.

The symbols used here are all copied directly from this Wikipedia article.

boxdraw kit

smooth box
╭─╮││╰─╯

jagged box
┌─┐││└─┘

heavy box
┏━┓┃┃┗━┛

wires
┌─┐│└┘┬┴┤├┼

arrows
←→↓↑↔↕

dotted
⋯⋮┄┈┊

To make boxes using the kit, copy-paste one of the “box” symbol sets, put newlines, and then expand the box to fit the text:

╭─╮││╰─╯

╭─╮
││
╰─╯
╭────────────╮
│ hello guys │
╰────────────╯

Put spacing around the text, too.

the diagram from last time but smoother ooOOOooo

    registers
    ┌─┐┌─┐┌─┐┌─┐┌─┐
    └─┘└─┘└─┘└─┘└─┘
    ┌─┐┌─┐┌─┐┌─┐┌─┐
    └─┘└─┘└─┘└─┘└─┘
    ╭─────────────╮     ╭────────────────────────╮
    │             │     │                        │
    │  processor  ├─────┤         memory         │
    │             │     │                        │
    ╰─────────────╯     │                        │
                        ╰────────────────────────╯

Note how the place the wire connects to each box is a different character (┤) that makes it attached.

╭───────────────────────────────────────────────────╮
│                                                   │
│                                                   │
│                                                   │
│             a big funny box (smooth)              │
│                                                   │
│                                                   │
│                                                   │
╰───────────────────────┬───────────────────────────╯
                        │
              ╭─────────┴─────────╮
              │ boxes interlinked │
              ╰───────────────────╯
                 ┌────────────┐
                 │ not smooth │
                 └────────────┘

               ┏━━━━━━━━━━━━━━━┓
               ┃ a weighty box ┃
               ┗━━━━━━━━━━━━━━━┛

╭─────────────────────╮
│ wires (plus arrows) │
╰──┬──────────────────╯
   ├────────┬────┐
 ←─┼──────┐ │    └─→         
   │      │ │                
   └──────┴─┤              
            │ ↑               
            │ │              
            ├─┘
            ↓

(The vertical arrows are slightly janky.)

          ╭────────────────────────────╮
⋯ ┄┄┄┄┄┄┄┄│ this goes off somewhere... │
          ╰────────────────────────────╯
                       ┊
                       ┊
                       ⋮

Making custom Arch Linux live ISOs without Arch Linux

2023-06-07T10:00:00Z

Making custom Arch Linux live ISOs without Arch Linux

2023-06-07

If you’ve ever installed any Linux distro, you probably had to do it using a live install environment. Once you flashed the USB drive, you could boot off it and you’d be greeted with a Linux system.

I’ve always found it fascinating that you could pack the entire OS onto a stick and bring it around with you. However, something even more enticing is being able to customize that system.

This is where archiso comes in handy: it’s a tool that can be used to generate ISOs with Arch Linux on them. You can flash these ISOs to USB drives to make portable Arch Linux systems. archiso is also incredibly flexible, and you can customize it very well. In fact, it’s the tool that Arch’s maintainers use to generate the official live installation images.

The one issue I have, though is that you need to be running Arch Linux to run archiso:

“Currently creating the images is only supported on Arch Linux but may work on other operating systems as well.”

As I run another distro on my laptop, I could not use archiso. So, in the last few days, I set out to make archiso run on my system. The final results of this endeavour can be found on GitHub.

Pacstrap

One of the essential dependencies of archiso is pacstrap. Essentially, what pacstrap does is that it creates a small Arch Linux system in a folder. This is the bootstrapped root filesystem (root FS). Later, archiso takes that folder, compresses it, and puts it in the final ISO file.

The problem is that pacstrap needs your host system to be Arch Linux so that it can bootstrap a new Arch system. In fact, if you look at the source code, you’ll find that the host system uses its own pacman to install everything to the bootstrapped system:

pacman -r "$newroot" "${pacman_args[@]}"

pacstrap only has to create a few directories, but the rest is done by installing the base metapackage through pacman. base includes both filesystem and pacman. As far as I understand, this means that all the important files in an Arch Linux system come from installing the filesystem package. Once the host pacman installs base in the bootstrapped system, we have a full Arch Linux root FS, including its own pacman.

However, since I do not have pacman to bootstrap this way, I needed another way to obtain an Arch root FS. I came across archstrap, which does exactly that. archstrap downloads a pre-built Arch Linux root FS as a tarball, then installs packages to it just like regular pacstrap. Cleverly, this script removes the need for arch-chroot on the host system: it runs the arch-chroot inside the downloaded Arch filesystem.

Somewhat annoyingly though, archstrap does not operate exactly the same way pacstrap does: I had to patch it to get it working with archiso. Also, I patched archiso itself to remove some flags archstrap doesn’t parse.

Other changes

The other main dependency missing in archiso is pacman, Arch’s package manager. Since we aren’t running Arch, we of course do not have it on our host system. However, the bootstrapped Arch root FS we downloaded earlier does have pacman inside of it. Therefore, I replaced all invocations of pacman inside archiso with invocations of the bootstrapped pacman.

archiso also includes a small script to test your generated ISOs in a QEMU virtual machine. I added a check to it that switches some hard-coded paths. In Arch, the path is /usr/share/edk2-ovmf/x64, but on my system it was at /usr/share/edk2-ovmf.

Conclusion

It turns out that modifying open source software isn’t that difficult. Given that archiso’s maintainers wrote very structured and organized code, it’s surprisingly easy to navigate around the script to patch things.

Of course, I definitely ruined the quality of archiso by doing this: there’s missing features and everything is untested and unlinted. Then again, this isn’t going to be production-grade software; I just wanted to make a custom portable Arch USB while using Gentoo on my PC.

Anyways, if you want to make your own custom Arch USBs but don’t have Arch, check out archiso-portable on GitHub.

As a bonus, here’s a screenshot of the Arch Linux live environment I made earlier on a Gentoo system:

DogeyStamp

Contributing to Zathura as a novice

Contributing to Zathura as a novice

The bug

Investigating source code

Fixing the bug

Conclusion

WireGuard VPN server setup guide for Linux

WireGuard VPN server setup guide for Linux

What is a VPN?

WireGuard setup

Server configuration

Client configuration

Running the VPN

wg-quick

NetworkManager

Mobile devices

Encrypted Internet tunnel

Further reading

Note-taking with Typst and Neovim

Note-taking with Typst and Neovim

Neovim setup

Templates

Version control

Math & code

Figures

Linking/references

Conclusion

Note-taking with Typst and Neovim in 2026

Note-taking with Typst and Neovim in 2026

Recap

Compiling Typst in Neovim

Typst watch

Terminal Navigation

Tinymist

Math & code

Math

Code

Figures

Scripting

Templates

Plugins

Synchronizing notes

Conclusion

Appendix: Configuration files

Reviving a digital piano with new brains

Reviving a digital piano with new brains

How a digital piano works

Project architecture

Hardware

Microcontroller

Sockets

Pin extenders

Firmware

Other features

Velocity detection

Sustain pedal

Conclusion

MinRSS, a lightweight feed reader

MinRSS, a lightweight feed reader

Purpose

Concept

Wrapper script

Installation

Usage

fzf shortcuts

Viewing specific folders

Creating meta-feeds

Making a virtual machine from scratch (in Rust)

Making a virtual machine from scratch (in Rust)

Prerequisite reading

What’s inside a VM?

Memory

Registers

Processor

Fetch-execute loop

Control flow

Subroutine calls

Memory mapped I/O

Assorted implementation details