wency suo - blog

How To Play Cut The Rope on Your TV

wency suo — Thu, 09 Apr 2026 00:00:00 +0000

intro</h3>
It might come as a surprise to most that CutTheRope(CTR), a childhood banger of a game, has a TV distribution on LGTV platforms. The game features the same rope cutting, bubble popping, and whoopee cushion squeezing mechanics modified for a remote controller.
We played significantly more than a few levels on the TV and long story short now the remote is lagging because we’ve drained the battery playing so much CTR.
Having decided that replacing a TV remote battery was simply too difficult, we decided that the remote was unecessary and built a way to play CTR on the TV without it :)

brainstorming</h2>

What does it actually look like to play CTR on the TV without a remote? While brainstorming control interface designs, we can generalize this problem statement to simply:

how can we remotely control TVs without a little plastic box that natively speaks to our tvOS via a mix of bluetooth and infrared signals? </blockquote>

With this pretty vague problem statement, let’s define some more concrete project goals that will help tighten the design:

Accuracy! It can be frustrating to play with the remote since it’s not very sensitive, are there ways to improve this?</li>
Reduce lag and intuitive game controls</li>
Identify a consistent playing surface that's easy for the user to interact with</li>
Actually cut the ropes and interact with other in game elements</li>

Beat some levels with our setup</li> </ol>

Design 0: gesture recognition on laptop with webcam</h2>
As a proof of concept, we wanted to start by seeing if we could play a web-based port of CTR on a laptop with the webcam for gesture recognition.
To build this we relied primarily on computer vision tools like OpenCV and MediaPipe. If you see videos or photos of other people’s projects that use vision recognition, there’s a good chance that at least a portion of their code or a dependency uses OpenCV. OpenCV contains the webcam control and frame processing code we need, wrapped nicely in the `VideoCapture</code> class. The class allows you to read a stream of frames from a video file, camera, or image sequence making the setup for frame by frame manipulation a 5 lines-of-code problem. Since we’re using the webcam input channel, OpenCV also spins up a live video player on my laptop when running the program to make visualization super easy.`
``
`MediaPipe provides access to the hand gesture recognition models that are applied to the video data captured by the webcam. Google has several image recognition models in MediaPipe to choose from. We initially experimented with a simple hand recognition model for point tracking but decided to use specifically a gesture recognition model to easily map in-game controls.`
`For this version of our code, we used 👆 for dragging, 🖐 as a neutral do nothing but move the cursor. 👊 as our click.`
`Recognizing gestures is only half the problem. Now we need to use a tool like PyAutoGUI, a programmatic gui controller, to actually send native mouse controls like drag, click, cursor movements to my laptop. Each movement is broken down into two steps, pyautogui.moveTo(x,y)</code> and pyautogui.mouseUp()</code> or mouseDown()</code>.`
`At this stage, we noticed that the gesture recognition model really struggled with recognizing hand gestures that were incomplete or on the edges of the image so we added a small non-playable margin within the full image as an easy fix. All of this gives us a functional, albeit basic, way to control the game via webcam!`
`You’ll notice that this PoC ignores a big part of our CTR-for-TV dream: LG’s proprietary tvOS…`

Design 1: gesture control on TV with laptop webcam</h2>
Moving from local laptop control to the TV meant we had to figure out how the TV expects to receive mouse events. This means figuring out how command packets were being sent from the remote to the TV in order to mimic the dragging motion of LG’s Magic Remote. I’m not sure how accessible other tvOS’s are but the target audience for LG TV’s WebOS seems largely to be app developers for the ecosystem. Not many of them are trying to optimize for the smoothest remote-less CTR experience, much to our dismay.</p>
connecting to the tv</h3>
LG’s webOS exposes a websocket that apps and remote-control clients can use to communicate with the TV. Our client connects to a secure local websocket endpoint on port 3001, registers itself with the TV, and receives a client key after the user approves the connection.</p>
The key can then be saved locally and reused so the TV does not ask for permission every time the app launches. The commands are then sent through a secondary websocket dedicated to mouse and keyboard inputs.</p>
communing with the tv</h3>
After some initial testing we quickly realized that WebOS was going to be a pain for us to work with. LG has proprietary message encodings that are not well documented. Meaning there are any number of private functions that Magic Remote has access to that we don’t even know exist. Values that aren’t used by the TV are ignored, true/false string values do nothing, and missing values actively cause errors in the response payloads.</p>
Through repeatedly sending commands until the tv did something and some snooping through source code, we figured out that the move command sent to WebOS has a hidden parameter called drag that is commonly set to down in order to simulate clicking behavior. This was the key to simulating the click-and-hold necessary to actually “cut” the in-game rope, otherwise we would just be moving from one side of the rope to the other without interacting with it.</p>
fighting with the tv</h3>
Tedious experimentation of the controls again revealed some more limiting features of the WebOS movement command. Move commands are all relative to the cursor position which is set to the center position on the TV or (0,0). So move(x,y) is really move(dx, dy). This was fine to work around once discovered, we just have to translate pixels to a coordinate system with (0,0) in the middle of the screen. We thought this would introduce little processing overhead, however getting this to work correctly was probably the hardest part of this project.</p>
Having to recalculate constantly the relative move commands given the detected hand position from the camera feed forced us to keep an internal cursor state that recorded its absolute position and if it was dragging or not. The TV sometimes resets or recenters the cursor after a period of inactivity. So our code needed to also track the time of the previous movement. If less than about 5.5 seconds have passed, it assumes the cursor is still where we left it and sends a delta from the stored position. Otherwise we would need to treat the next movement as originating from (0,0).</p>
This wasn't a particularly elegant calibration system but it was enough to keep the prototype moving in roughly the right direction.</p>
moving pixel by pixel</h3>
I like to make extragerated gestures across the camera, full of drama, in an effort to cut the rope when I'm playing. However, the movements turn out to be pretty chopy if you don't break down the moveTo()</code> commands to small, incremental movements.</p>
To abstract away the relative movement commands we used a custom moveArbDistance</code> function which takes any x, y</code> and converts it into a sequence of one-pixel WebOS commands that will get your cursor to the correct final position.</p>
Why 1 pixel at a time, you might ask?</p>
Initially we assumed that dx</code> and dy</code> represented straightforward posiiton changes. Under that model, sending dx: 3</code> should move the cursor three times as far as sending dx: 1</code>. In reality the vaues behaved more like a velocity or movement-intensity vector than a discrete pixel offset. So increasing the step size did not produce a clean propotional movement. This was particuarly noticeable during dragging. Larger values made the cursor accelerate or jump across the screen instead of tracing the smooth path of the user's hand.</p>
Using stepsize of 1 ended up being the smoothest way to produce dragging without the cursor jumping all over the screen. So after this, pure horizontal becomes repeated dx steps and pure vertical becomes repeated dy steps. Any diagonal movement uses a basic slope ratio that alternates between horizontal and vertical steps for stable movement. We also had to account for jitter at this point, for example if the user sits at the center of the screen for some amount of time, we need to send tiny (1, 1) and (-1, -1) steps to keep it in place.</p>
At this point if you're still reading i think you might guess what became our biggest headache. decompressing single movements into tiny steps works well if you don't move too far but this can easily send hundreds or thousands of move requests to the tvOS server, all of which take some time to process. Additionaly, if any requests failed the internal cursor state will drift from the real cursor position and the calcualted relative movements would be incorrect.</p>
A serial dispatch queue helped us confirm that the messages would at least be sent in order. Without serialization, overlapping drag and movement commands could arrive in an exciting but incorrect sequence. If we had more time to improve the project, I would definetly spend more time designing the cursor state management or testing the WebOS commands to see if we can stablize long continuous movement without sending too many requests to get match to the movement smoothness of the Magic Remote.</p>
At this point though, we do have a playable CTR tv version that's controlled from my mac webcam.</p>
But holding your hand in front of the laptop while looking sideways at a television is not a particularly natural way to play. We wanted the controls to feel more like touching a physical game board.</p>
Design 2: table top gesture control and tv via lidar</h2>
Design 2 is anchored by the idea of playing CTR on our coffee table top. This would be similar enough to a giant trackpad for the TV or a futureistic terminal ipad console thing that seem to always appear in scifi spaceships.</p>
A phone is mounted approximately 2 feet above the table, looking downward. The camera tracks the player's fingertips while the depth sensor determines when those fingertips were close enough to the tabletop to count as a touch.</p>
Moving your finger above the table would do nothing (hovering!). Touching the table would produce a click. Sliding your finger while touching the table woudl drag across the tv screen and cut a rope. We built a quick SwiftUI iOS app called WirelessCandy. Apple nicely packages lidar data access and some cool AR features into RealityKit and ARKit.</p>
teaching my phone how to identify my table</h3>
The app’s root ContentView</code> is intentionally minimal. Most of the screen is occupied by a full-screen RealityKit ARView</code>.
Apple has a nice plane detection feature that we can enable in the configuration:</p>
config.planeDetection</span> =</span> [.horizontal]</span></span>
config.frameSemantics</span> =</span> .sceneDepth</span></span></code></pre>
Scene depth is the useful part. On supported devices in our case we used an iPhone 14 Pro, ARKit produces a depth map estimating the distance between the phone and each part of the camera image. We use that map to check if a detected fingertip is hovering over the table or physically touching it.</p>
An ARSessionDelegate</code> receives each new camera frame:</p>
func</span> session</span>(</span>_</span> session</span>: ARSession, </span>didUpdate</span> frame</span>: ARFrame</span>) {</span></span>
    // Hand tracking and collision detection happen here</span></span>
}</span></span></code></pre>finding fingertips with Vision</h3>
For every AR frame, we run a VNDetectHumanHandPoseRequest</code>.</p>
Vision returns recognized hand landmarks, including the tips of all five fingers:</p>
.thumbTip</span></span>
.indexTip</span></span>
.middleTip</span></span>
.ringTip</span></span>
.littleTip</span></span></code></pre>
We collect the recognized points for each visible hand and pass them into the depth-processing pipeline.</p>
Why all five fingertips instead of just the index finger?</p>
Partially because it makes the interaction more flexible but mostly because detecting five potential collision points made us more certain of the user's hand position. Depending on the angle of the phone and how far the user is from the camera the depth data may not be accurate. Initially, the collision detection was too sensitive and anchoring to a index-middle-ring finger bundle for collision detection worked much better for us.</p>
detecting a fingertip-table collision</h3>
To detect a fingertip-table collision we need to convert position data between several different coordinate spaces:</p>

Convert the fingertip location into the depth map's coordinate space.</li>
Sample the depth value at that location.</li>
Use the camera intrinsics to reconstruct the corresponding 3D camera-space point.</li>
Transform the point from camera coordinates into AR world coordinates.</li>
Transform it again into the table plane’s local coordinate system.</li>
Measure its distance from the plane.</li>
</ol>
Camera intrinsics describe how 3D points are projected onto the camera image. To match the resolution of the depth map to the camera image, we scale the intrinsic matrix before reconstructing the point.</p>
This way a depth pixel becomes a camera-space position:</p>
x = (pixelX - centerX) * depth / focalX</span></span>
y = (pixelY - centerY) * depth / focalY</span></span>
z = depth</span></span></code></pre>
Luckily, ARKit gives us the camera transform needed to move that point into world space. We then apply the inverse table transform to express it relative to the detected table.</p>
If the point is within approximately five centimeters of the table plane, we treat it as a potential collision:</p>
distance </span><</span> 0.05</span></span></code></pre>
The final version should use the absolute distance after confirming the plane’s sign convention. Otherwise, a point far below the table could theoretically be considered “close” simply because its signed distance is negative.</p>
Once a fingertip is close enough, we project it onto the table and check whether the point falls within the table plane’s detected bounds.</p>
This converts a real finger touching a real table into a two-dimensional point we can draw on the TV :)</p>
deciding between clicks and drags</h3>
A single table collision should behave like a click but a collision that continues across multiple frames should behave like a drag.</p>
The coordinator stores whether the previous frame contained a collision:</p>
hadCollisionLastFrame</span></span></code></pre>
The current frame becomes a drag when both conditions are true:</p>
isDragging </span>=</span></span>
    hadCollisionLastFrame </span>&&</span></span>
    !</span>collidedPointsInPlane.isEmpty</span></span></code></pre>
This gives us a simple interaction state machine:</p>
no contact → no contact: move nothing</span></span>
no contact → contact: click</span></span>
contact → contact: drag</span></span>
contact → no contact: release</span></span></code></pre>
So tada! here's the demo of design 1 because I somehow don't have a video of the table version:</p>
</video>
things that almost worked</h2>
I'll list here a few things that we couldn't debug or discovered too late to design around.</p>
depth data resolution</h3>
Apple's ARKit scene-depth map has a resolution of only 256x192 pixels. That gives us 49,152 depth samples spread across the phone's entire field of view. This means that the object tracking of a small fingertip is only occupying a pretty small portion of the depth map. Apple explicitly describes the lidar feature as sa lower-resolution dpeth map chosen so ARKit can run algorithms in real time. So we end up in the awkward state where the camera can properly track the outline of a finger but the depth map doesn't have enough spatial detail to accurately report back the depth position of that finger. As we would try to touch the table with our finger, the depth values around it would often snap to the table's depth value. Instead of reporting one region for the finger and anohter slightly further region for the tabletop the depth mapwould flatten both into the same surface. This was pretty hard to design around since we didn't have other depth data sources available.</p>
Using multiple fingers made the interaction somewhat more stable because we had more samples to work with. But none of this changed the fact that the data was just too low resolution for design 2 :/</p>
processing every frame is expensive</h3>
Because AR frame launches hand-pose detection and depth processing, if the vision pipeline takes longer than the camera's frame interval, work can overlap and create a backlog. This accumulates over time and leads to unpredictable behavior of the cursor. Some finetuning of the fps was necessary but didn't solve the issue at the root.</p>
table classification can be temperamental</h3>
We only accept planes classified by ARKit as .table</code>.
If ARKit detects the surface but classifies it as unknown, the app sees a perfectly good table and chooses not to believe in it. I would have loved a more comprehensive user setup flow where one could select a plane as a playing service and calibrate it before playing.</p>
conclusion</h2>
The 3 prototypes of cut-the-rope-tv we built had varying levels of success. From our original rubric we were able to beat levels consistently, with a little user frustration when it came to design 2. But more importantly:</p>

We finally touched some fancy AR features and used the lidar sensors in our expensive iphones for something fun.</li>
Swipe madly across the table to cut the rope.</li>
Feed Om Nom.</li>
</ol>
The project was therefore a success.</p>



disguising my online traffic :)
wency suo — Wed, 01 Apr 2026 00:00:00 +0000
intro</h3>
One of my biggest headaches while traveling in China has always been deciding which VPN to use. To watch YouTube or access anything outside the Great Firewall (GFW) I would have to route my traffic through a server outside the country.</p>
In the past I’ve tried a few paid services like Surfshark, NordVPN (their ads are everywhere) but none have worked consistently for me. Granted, there’s a legitimate reason why VPN reliability may degrade over time. VPN traffic can tend to have distinctive patterns that then get detected and blocked, providers have to push fixes to restore access for those on the service periodically.</p>
As with any VPN service you also have to trust a 3rd party vendor with all of your network traffic so they can forward your encrypted requests to your final destination. I’m sure there’s a lot of discourse online about whether or not to trust VPNs/ISPs</a> and the like but for me climbing subscription fees and data privacy is really just a pretense for learning how to set up my own private network!</p>
It can’t be that hard right?</p>
how does the internet work again</h2>
Let’s start by reviewing some foundational networking concepts. Hypertext Transfer Protocol or HTTP is how data gets passed between machines to render websites. Assuming some familiarity with client/server architectures (cloudflare has some decent materials</a>), you can think of the GFW as a monitor at the ISP level.</p>
The GFW is smarter than just checking blacklisted URLs, it uses an advanced network security probing method called Deep Packet Inspection (DPI) to analyze the packet sizes, timing patterns, handshake signatures of your traffic. Even when content is encrypted, traffic can look like VPN traffic, which is exactly how VPN connections get detected and throttled. Your destination IP and requested domain name is also usually public and unencrypted since TLS encryption only protects the content of the client server communication, so everything after a handshake is established not before.</p>
So our goal here isn’t necessarily encryption but actually making our traffic indistinguishable from regular HTTPS browsing.</p>
my options</h2>
A few projects have emerged to fill this specific niche over the years. The most popular and well established tool that I came across is Shadowsocks, which introduced its own encrypted SOCKS5 proxy protocol. The protocol unfortunately has a detectable fingerprint, so the GFW has gotten pretty good at identifying it over time. For this reason I chose to keep looking for other tools. Granted, I haven’t tested it out myself so perhaps for my use case this would’ve been fine.</p>
V2Ray adds a layer of obfuscation on top to disguise proxy traffic as WebSocket, gRPC, or HTTP. This gets pretty close to a convincing disguise! However, from what I can tell, V2Ray doesn’t fully hold up against active probing, where the GFW sends it’s own requests to servers it suspects might actually be proxies. To handle this properly, V2Ray requires custom fallback configs to respond properly to requests from unauthorized sources.</p>
Trojan builds on this idea of mimicking regular web servers by actually running a proper web server with a valid TLS certificate, making proxy requests indistinguishable from valid HTTP requests. In the case of active probing, when a request is sent to a trojan server that isn’t a valid trojan request then the server, which also runs Nginx, gets served a real webpage. This does mean that in order to use Trojan I need to actually register a domain which is another upfront cost that might influence which tool you would pick to set up your own proxy server. This wasn’t an issue for me so I chose this option for my server.</p>
It’s worth mentioning that ShadowSocks and V2Ray has some pretty great documentation in comparison to Trojan</a>. V2Ray is part of a broader ecosystem of tools that help you build your own privacy network called Project V</a> and the community investment in maintain documentation shows. Working with Trojan was a little more difficult since there are several unmaintained repos that you have to sift through to find the most recent fork, though the setup instructions have remained consistent.</p>
deep dive into trojan</h2>
To understand what Trojan is doing, it helps to have a quick mental model of how a request travels from your browser to a server.</p>
</p>
When you type a URL, your machine resolves the domain to an IP address via DNS, opens a TCP connection to that IP, and if it’s HTTPS, negotiates a TLS handshake before any application data gets exchanged. TCP is the transport layer and handles reliable ordered delivery of packets. HTTP sits on top and defines the structure of the actual request and response. TLS sits between them and handles encryption.</p>
What legitimizes this request is the TLS and to complete the TLS handshake we need a properly signed certificate for our web server. When your browser connects to a server, the server presents a certificate signed by a trusted Certificate Authority (CA). Your browser checks that the signature is valid and that the certificate matches the domain you’re visiting to establish a chian of trust from the browser’s built-in root CA down to the certificate on the server.</p>
Trojan requires that you obtain a real certificate for a real domain. That means your server looks exactly like any other HTTPS server. Same handshake, same certificate structure, same everything. There’s nothing synthetic for DPI or active probing to uncover.</p>
server setup</h2>
I really spent some time thinking about where and how I was going to go about setting up my own server since it seemed like an easy excuse to get my hands on a Raspberry PI. I genuinely did want to explore this option since it would also give me full hardware control but I was on a time crunch before the trip, so this will probably have to wait until I get back.</p>
I also briefly considered repurposing my home router. Routers are essentially small Linux computers that also have network switches so flashing it with tools like OpenWrt would’ve let me protect every device on my home network automatically at the router level with no per-device config needed. The problem is with my ISP which locks down the hardware :( so OpenWrt isn’t really an option, again future project once I get back.</p>
So the easiest and cheapest solution to all of my problems is to secure a free VPS from Oracle. Using the free tier does mean that my server might not have the best uptime since I’m at the mercy of whatever OCI is doing with their servers but honestly I’m not confident that I would have better reliability running a Raspberry Pi out of my apartment anyway.</p>
managing proxy traffic</h2>
Setting up the proxy is just the first step, to actually use my VPS I also have to connect my devices to my server and manage my proxy requests. The brute force approach is to route everything through the proxy. For this to work you would need to route all of your traffic, all the way down at the system level through my server. This is admittedly wasteful but it does work. The better approach here is to define a set of rules, maybe based on domain, device etc. so that you selectively use your proxy.</p>
This is what proxy managers like Clash handle. You define rules in a config file and Clash decides how to route each request. It’s also possible to define multiple proxies and set fallback behavior if one goes down, which means you’re not betting everything on a single server. Hurrah Redundancy!</p>
keeping the server running with systemctl</h2>
Right now I’m starting the Trojan-Go process manually over SSH, which is fine for testing and deeply not fine for anything else. If the server reboots, the process dies and stays dead until I notice and SSH back in.</p>
The fix is turning it into a systemd</code> service, which is Linux’s standard way of managing long-running processes. All I have to do is write a unit file that describes how to start the process, what user to run it as, and what to do on failure, then register it with systemctl</code>. After that, systemctl enable trojan-go</code> means it starts automatically on boot and systemctl restart trojan-go</code> gives you a clean way to reload config changes. Logs go through journald</code>, so journalctl -u trojan-go</code> gives you a clean view of what the service is doing if anything goes wrong.</p>
what to do from here</h2>
I set things up in kind of a rush so that I can get a minimum viable product for my upcoming trip so there’s still a lot of work to be done. I can surf the open web but I still need to actually measure my performance and request latency. In another post I’ll explore profiling tools and optimizations i can make to my current system to achieve a smoother web browsing experience.</p>
Until next time!</p>


FastJet but faster? Part II
wency suo — Thu, 05 Mar 2026 00:00:00 +0000
tldr</strong></h3>
We never set out to make fastjet-rs</a> faster than FastJet.</p>
But after some elbow grease, SIMD, and some not-so-micro optimizations we’ve managed to make our Rust simple jet finding algorithms a few microseconds faster than the original C++ implementations.</p>
If you haven’t already gone over the basics of this project in part 1, all you need to know is that fastjet is a particle physics package that performs nearest neighbor calculations to merge subatomic particles into jets. We are trying to rewrite the original C++ as Rust for the language’s memory safety advantages.</p>
The benchmarking results from a comparison of the simple O(n²) clustering algorithm found that our Rust implementation is roughly equivalent in performance to a Julia implementation, JetReconstruction.jl</a>, but ultimately slower than the original C++ version by ~130 microseconds… but that’s not the case anymore!</p>

Jump to the end if you’re just interested in the results of our benchmarking.</em></p>
</blockquote>
We’ll go over three major categories of code changes since our commit as of Part 1</a>.</p>
tiling</strong></h2>
</p>
Thanks JetReconstruction.jl team for this wonderful graphic!</em></p>
Fastjet and JetReconstruction.jl both implement a tiled clustering algorithm in addition to the simple n² clustering algorithm so we thought we should too. The key to this algorithm lies in the fact that clustering particles on an eta, phi coordinate system doesn’t change too much if we localize the clustering. In other words, instead of scanning and calculating distances between one jet and all other jets, we can define a tiled representation of our particles so that we only use the closest particles during distance calculations. Depending on how small we make our tiles, we essentially do the minimum amount of distance calculations for each jet at the expense of extra bookkeeping as we now need to store which jets are in which tiles and actively update it.</p>
In practice, this means implementing a doubly linked list.</p>
Let’s introduce some new structs Tile</code> and TiledJet</code> to represent all of our jet information relationally.</p>
    /// The neighbourhood of a tile is set up as follows:</span></span>
    ///       LRR</span></span>
    ///       LXR</span></span>
    ///       LLR</span></span>
    ///</span></span>
    /// tiles contains XLLLLRRRR with pointers</span></span>
    ///                     |   \ RH_tiles</span></span>
    ///                     \ surrounding_tiles</span></span>
</span>
Credit</span>:</span> fastjet authors</span></span></code></pre>
Choosing a doubly linked list gives us instant access to adjacent jets in both directions, making it easy to rescan neighbors around a merge. Flattening each tile makes traversal linear, all we have to do is a little bit of math to map the grid index of each neighboring jet in a tile to its flattened index. Looks pretty easy to implement right?</p>
why can doubly linked lists be unsafe in Rust?</strong></h3>
Linked lists are a bit of a pain to implement in Rust.</p>
struct</span> Node</span> {</span></span>
 val</span>:</span> u32</span>,</span></span>
 prev</span>:</span> Option</span><</span>Box</span><</span>Node</span>>></span>,</span></span>
 next</span>:</span> Option</span><</span>Box</span><</span>Node</span>>></span></span>
}</span></span></code></pre>
Since each node needs to hold references to both the prev node and the next node, any interior node will always have multiple simultaneous owners. The moment you try to mutate a node in the middle of the list the Rust borrowchecker will throw a fit since you’ll need to have write permissions to both the node itself, the previous node, and the next node.</p>
Since each node needs to hold references to both the prev node and the next node, any interior node will always have multiple simultaneous owners. The moment you try to mutate a node in the middle of the list the Rust borrowchecker will throw a fit since you’ll need to have write permissions to both the node itself, the previous node, and the next node.</p>
why RefCell is ‘essential’</strong></h3>
Recall RefCell<T></code> from part 1, paired with Rc<T></code> they are the Rust sanctioned safe method of allowing shared mutability. If you wrap nodes with Rc<RefCell<Node>></code> ownership checks will now be performed at runtime instead of compile time. This is significant since the borrow checker, which runs at compile time is quite conservative so it ends up rejecting any borrowing patterns that can’t be proven safe statically. At runtime all of this changes since we can actually check if any simultaneous borrows conflict. Thus our doubly linked list node implementation looks more like this:</p>
struct</span> Node</span> {</span></span>
 val</span>:</span> u32</span>,</span></span>
 prev</span>:</span> Option</span><</span>Rc</span><</span>RefCell</span><</span>Node</span>>>></span>,</span></span>
 next</span>:</span> Option</span><</span>Rc</span><</span>RefCell</span><</span>Node</span>>>></span></span>
}</span></span></code></pre>
This will compile successfully, but the problem comes when actually accessing any of our jets inside the linked list. Each time you want to read a field within an object of type Node you will need to call .borrow()</code> or .borrow_mut()</code>. Each call to either of these functions is a runtime borrow check, adding a significant overhead anytime we work with jets in our algorithm.</p>
ok but what if we don’t want to always have runtime borrow checking?</strong></h3>
A better solution is actually pretty elegant here if you are willing to trade in storage overhead for better runtime performance. The astute reader might have already noticed that we don’t actually need to store references to each jet object, we can just keep a well updated table of jets and use usize</code> indices instead.</p>
Our main clustering logic is implemented inside ClusterSequence so we can give it sole ownership over this table. This is actually a common design pattern more commonly known as arena-style bookkeeping</strong>. Instead of using pointers or references, we can store all of our objects in contiguous blocks of memory that we access via indices. However, since our clustering algorithm requires we merge quite a few jets the upkeep of marking jet indices stale was nontrivial in our implementation. Many bugs emerged due to an erroneous index to an already removed or merged jet. All of this still ended up being worth it in our case since our runtime performance did improve after removing several repeated runtime borrow checks.</p>
So linked lists really aren’t all that easy to pull off in Rust without giving some thought to ownership models in your data structures. The reason why implementing linked lists might feel easier in other languages is simply because the memory management is abstracted away behind complex garbage collection cleanup that has its own hidden costs. From a pedagogical perspective, tiling our clustering algorithm turned out to be a great way to learn Rust.</p>

For a more thorough explanation of all things linked lists in Rust we highly recommend checking out Learning Rust With Entirely Too Many Linked Lists</a> :)</em></p>
</blockquote>
the fallacy of SIMD</strong></h2>
Implementing a SIMD version of the simple n² clustering algorithm was the second design change we made to increase our performance.</p>
SIMD stands for (Single Instruction Multiple Data) where the CPU groups together multiple data elements as vectors (defined as LANES) and performs the same instruction to all this data simultaneously. In Fastjet, there are multiple scenarios where our data is highly parallel, finding the distance metric for all jets at once, initializing them, and updating the nearest neighbors each time we remove/add a new jet. Some other parts of the code are inherently sequential, such as finding which jet to remove and performing our updating logic on it since it relies on finding the minimum distance jet and then acting upon it. In these cases the latter is more ripe for SIMD than the former. In these cases SIMD can optimistically produce performance gains of 3–4x</strong>, however, the compiler is a fickle thing and it is possible that SIMD can cause performance penalties because nothing beats the compiler.</p>
Normally, SIMD requires fine tuning to specific CPU architectures and calling archaically named functions after scouring through CPU documentation. Thankfully for our purposes we can test drive std::simd</code>, a feature of Rust nightly which has long awaited a stable release, that aims to provide a “universal” SIMD implementation. The initial setup was pretty straightforward other than actually needing to learn SIMD!</p>
When it came to retrofitting our code for SIMD we faced a number of difficulties.</p>
SIMD memory requirements</strong></h3>
</p>
Ref: https://www.researchgate.net/figure/A-comparison-of-the-Array-of-Structs-AoS-and-Struct-of-Arrays-SoA-memory-layouts_fig2_259132352</em></p>
First off, SIMD requires all the data to be contiguously located in memory, meaning that we had to vectorize our current paradigm where each Jet struct contains elements containing its pt</code>, eta</code>, phi</code>, NN_index</code>, etc. This means that every time we call a SIMD function we need to loop over all vectors and initialize arrays holding just phi</code>, eta</code>, and so on. Initializing this data each SIMD call would increase the overhead so much that the performance gain is unjustified, thus we must shift to running our entire algorithm using structures of arrays instead of arrays of structs.</p>
For this reason, we were drawn to Rusts’ arena (recall the importance of arena-style bookkeeping from earlier!</em>) since it allows for fast memory allocation given that we know the amount of Jets that we account for at a time will never be larger than the initial length of input particles. This required a large overhaul of our code, but it was all going to be worth it right?</p>
SIMD and primitives</strong></h3>
Another issue we ran into was the fact that SIMD arrays only take primitives but our NN_index</code> was encoded as an Option</code> (to highlight jets not having NN) could not be imputed. Then thanks to (JetReconstruction.jl</a>) we realized that we can actually modify NN_index</code> to be set to a sentinel value of itself!</p>
When creating new jets (whether merged or initialized) we already know its own index to access it, and most functions where we unwrap can instead just check its index. This mainly improves performance (removing unwrapping and wrapping) but also has the secondary effect of reducing data size, f64</code> is 8 byte while an Option is double that (just to store the None value).</p>
An interesting example to highlight was the following function since the min(a, a) = a</code>:</p>
fn</span> _bj_dij</span><</span>J</span>:</span> ProxyJet</span>></span>(</span>jet</span>: &</span>J</span>,</span> jets</span>: &</span>[</span>J</span>])</span> -></span> f64</span> {</span></span>
        jet</span>.</span>nn_dist</span>()</span></span>
        *</span> jet</span>.</span>kt2</span>()</span>.</span>min</span>(</span></span>
                jet</span>.</span>nn_jet_index</span>()</span></span>
                .</span>map</span>(</span>|</span>index</span>|</span> jets</span>[</span>index</span>]</span>.</span>kt2</span>())</span></span>
                 .</span>unwrap_or</span>(</span>f64</span>::</span>MAX</span>),</span></span>
        )</span></span>
   }</span></span>
</span>
fn</span> _bj_dij</span><</span>J</span>:</span> ProxyJet</span>></span>(</span>jet</span>: &</span>J</span>,</span> jets</span>: &</span>[</span>J</span>])</span> -></span> f64</span> {</span></span>
        let</span> kt2_a</span> =</span> jet</span>.</span>kt2</span>();</span></span>
        let</span> kt2_b</span> =</span> jets</span>[</span>jet</span>.</span>nn_jet_index</span>()]</span>.</span>kt2</span>();</span></span>
</span>
        // Bypasses the f64::min NaN checks, yielding pure hardware speed</span></span>
        let</span> min_kt2</span> =</span> if</span> kt2_a</span> <</span> kt2_b</span> {</span> kt2_a</span> }</span> else</span> {</span> kt2_b</span> };</span></span>
</span>
        jet</span>.</span>nn_dist</span>()</span> *</span> min_kt2</span></span>
   }</span></span></code></pre>
Now with all the setup out of the way we can examine a smaller SIMD function to highlight its technicalities. Since we showed the _bj_dij</code> function earlier it seems right to highlight it parallelized.</p>
#</span>[</span>cfg</span>(</span>feature </span>=</span> “simd”</span>)]</span></span>
    fn</span> _dij_simd</span><</span>const</span> LANES</span>:</span> usize</span>></span>(</span></span>
        kt2_arr</span>: &</span>[</span>f64</span>],</span></span>
        nn_idx</span>: &</span>[</span>u64</span>],</span></span>
        nn_dist</span>: &</span>[</span>f64</span>],</span></span>
        di_j</span>: &</span>mut</span> [</span>f64</span>],</span></span>
    ) {</span></span>
        let</span> n</span> =</span> kt2_arr</span>.</span>len</span>();</span></span>
        let mut</span> j</span> =</span> 0</span>;</span></span>
</span>
        //  SIMD loop</span></span>
        while</span> j</span> +</span> LANES</span> <=</span> n</span> {</span></span>
 // note: [j..j + LANES] does not include j + LANES</span></span>
            let</span> kt2_i</span> =</span> Simd</span>::</span><</span>f64</span>,</span> LANES</span>></span>::</span>from_slice</span>(</span>&</span>kt2_arr</span>[</span>j</span>..</span>j</span> +</span> LANES</span>]);</span></span>
            let</span> dist_i</span> =</span> Simd</span>::</span><</span>f64</span>,</span> LANES</span>></span>::</span>from_slice</span>(</span>&</span>nn_dist</span>[</span>j</span>..</span>j</span> +</span> LANES</span>]);</span></span>
            let</span> indices</span> =</span> Simd</span>::</span><</span>u64</span>,</span> LANES</span>></span>::</span>from_slice</span>(</span>&</span>nn_idx</span>[</span>j</span>..</span>j</span> +</span> LANES</span>]);</span></span>
</span>
 // must store indices as u64 because compiler errors with other funcs</span></span>
            let</span> indices_usize</span> =</span> indices</span>.</span>cast</span>::</span><</span>usize</span>></span>();</span></span>
</span>
            let</span> kt2_b</span> =</span> Simd</span>::</span><</span>f64</span>,</span> LANES</span>></span>::</span>gather_or</span>(</span>kt2_arr</span>,</span> indices_usize</span>,</span> kt2_i</span>);</span></span>
</span>
            let</span> kt2_min</span> =</span> kt2_i</span>.</span>simd_min</span>(</span>kt2_b</span>);</span></span>
            let</span> res</span> =</span> kt2_min</span> *</span> dist_i</span>;</span></span>
</span>
            res</span>.</span>copy_to_slice</span>(</span>&</span>mut</span> di_j</span>[</span>j</span>..</span>j</span> +</span> LANES</span>]);</span></span>
</span>
            j</span> +=</span> LANES</span>;</span></span>
        }</span></span>
</span>
        // scalar handling for remainder of elems aka tail</span></span>
        for</span> i</span> in</span> j</span>..</span>n</span> {</span></span>
            let</span> idx</span> =</span> nn_idx</span>[</span>i</span>]</span> as usize</span>;</span></span>
            di_j</span>[</span>i</span>]</span> =</span> nn_dist</span>[</span>i</span>]</span> *</span> kt2_arr</span>[</span>i</span>]</span>.</span>min</span>(</span>kt2_arr</span>[</span>idx</span>]);</span></span>
        }</span></span>
    }</span></span></code></pre>
Starting from the top, we gate SIMD use only when building with feature “simd” which prevents compiler errors from not being on nightly Rust as the code is basically “ignored” by the preprocessor.</p>
Then when calling these SIMD functions we must pass a size parameter labeled LANES which as mentioned previously is how many elements we wish to pass to a SIMD instruction at a time. It is up to the user to check whether they handle the remainder of elements with the slower sequential instruction which we do in the final loop at the end. We can construct SIMD objects easily using from_slice</code> and just passing a reference to our elements. Here the parallel action we must do is gather_or</code> which retrieves all elements given indices. Funnily enough this is one of the slower operations since the bottleneck for these operations are not the CPU but instead the memory register which must fetch the vectors which are not contiguous and not guaranteed to be in the same cache line as the jets we have already taken in. However, we can see how we can use many other primary operators like inequalities, addition, multiplication in the same way and chain these operations together.</p>
After overhauling all of our code we found that before optimizing our simple_n2_cluster</code> algorithm that we achieved a 45 percent performance improvement</strong>, and we were officially slightly faster than our C++ “competitor” 🥳.</p>
micro optimizations that are more than micro in practice</strong></h2>
However, it turns out that just a couple of changes in our previous naive implementation that help</em> the compiler do it’s job also did wonders for performance.</p>
writing clean code really does count!</strong></h3>
Part of the reason that Rust touts ‘C’ performance with large safety guarantees is through its aggressive use of optimizations to construct Zero-Cost Abstractions. This means more verbose Rust code to check indices in comparison to unsafe pointers, Vectors instead of arrays compile down to almost the same assembly instruction as C’s unsafe implementation.</p>
This is important to note as more convoluted code has the effect of preventing the compiler from making such optimizations since user intent is unknown. This is why inlining most functions can result in faster performance since the compiler knows in what situations called functions are being used by the callee and can optimize accordingly. Take the following for loop:</p>
for</span> i</span> in</span> 0</span>..</span>tail</span> {</span></span>
   // some logic based on the value of nn_idx that only matters if jet_b != i</span></span>
   // if we find jet_b_idx is equal to i quit</span></span>
   if</span> jet_b_idx</span> ==</span> i</span> {</span></span>
      if</span> jets</span>[</span>jet_b_idx</span>]</span>.</span>nn_jet_index</span>()</span> ==</span> tail</span> {</span></span>
          jets</span>[</span>jet_b_idx</span>]</span>.</span>set_nn_jet</span>(</span>min_idx</span>);</span></span>
      }</span></span>
      continue</span>;</span></span>
   }</span></span>
   // update min dist for jet i and jet_b</span></span>
}</span></span></code></pre>
Given this function the compiler does not know that the if loop is only checking for one value, and one that is predetermined before the for loop even starts, since it is in the middle of the function. If we just place it on top, the compiler will split the function into the following:</p>
for</span> i</span> in</span> 0</span>..</span>jet_idx_b</span> {</span></span>
 // do logic</span></span>
}</span></span>
// perform jet_b_idx == i case</span></span>
</span>
for</span> i</span> in</span> jet_idx_b</span>+</span>1</span>..</span>tail</span> {</span></span>
 // do logic</span></span>
}</span></span></code></pre>
A small change like moving the if loop to the beginning of the for loop had around a 6 percent improvement</em> since this was a part of the code that was called very frequently with depth O(n²).</p>
performance impact of mut</code>s</strong></h3>
The next example highlighted to me why mut</code>s can actually decrease performance if not used sparingly especially in conjunction with the next example. When a jet is merged, we must set the NN for the old jets which previously pointed to its constituents, since we don’t have to update the other jets to point to it (since we removed them) as a NN we only need to update that jet. Here is the code to highlight this.</p>
#</span>[</span>inline</span>]</span></span>
fn</span> bj_set_nn_nocross</span><</span>J</span>:</span> ProxyJet</span>></span>(</span></span>
  &</span>self</span>,</span></span>
  curr_idx</span>:</span> usize</span>,</span></span>
  head_idx</span>:</span> usize</span>,</span></span>
  tail_idx</span>:</span> usize</span>,</span></span>
  jets</span>: &</span>[</span>J</span>],</span></span>
)  {</span></span>
   let mut</span> nn_dist</span> =</span> self</span>.</span>r2</span>;</span></span>
   let mut</span> nn</span>:</span> usize</span> =</span> curr_idx</span>;</span></span>
</span>
   for</span> jet_b_idx</span> in</span> head_idx</span>..</span>curr_idx</span> {</span></span>
       let</span> dist</span> =</span> J</span>::</span>_bj_dist</span>(</span>curr_jet</span>,</span> &</span>jets_ref</span>[</span>jet_b_idx</span>]);</span></span>
       if</span> dist</span> <</span> nn_dist</span> {</span></span>
           nn_dist</span> =</span> dist</span>;</span></span>
           nn</span> =</span> jet_b_idx</span>;</span></span>
       }</span></span>
   }</span></span>
</span>
   for</span> jet_b_idx</span> in</span> curr_idx</span> +</span> 1</span>..</span>tail_idx</span> {</span></span>
       let</span> dist</span> =</span> J</span>::</span>_bj_dist</span>(</span>curr_jet</span>,</span> &</span>jets_ref</span>[</span>jet_b_idx</span>]);</span></span>
       if</span> dist</span> <</span> nn_dist</span> {</span></span>
            nn_dist</span> =</span> dist</span>;</span></span>
            nn</span> =</span> jet_b_idx</span>;</span></span>
       }</span></span>
   }</span></span>
   jets</span>[</span>curr_idx</span>]</span>.</span>set_nn_jet</span>(</span>nn</span>);</span></span>
   jets</span>[</span>curr_idx</span>]</span>.</span>set_nn_dist</span>(</span>nn_dist</span>);</span></span>
}</span></span></code></pre>
The important things to watch are the function signature, and the last two lines. Since we need to modify jets[curr_idx]</code> we pass the entire jets as mutable, we also can’t just pass jets[curr_idx]</code> as mutable because then we would break Rust’s borrowing rules. Thus the only solution is to tell the callee function which element changes, and then modify that element. Here is how that following code looks like:</p>
let</span> (</span>new_nn</span>,</span> new_dist</span>)</span> =</span> self</span>.</span>bj_set_nn_nocross</span>(</span>i</span>,</span> 0</span>,</span> tail</span>,</span> jets</span>);</span></span>
</span>
let</span> jet_i</span> = &</span>mut</span> jets</span>[</span>i</span>];</span></span>
jet_i</span>.</span>set_nn_jet</span>(</span>new_nn</span>);</span></span>
jet_i</span>.</span>set_nn_dist</span>(</span>new_dist</span>);</span></span>
</span>
 fn</span> bj_set_nn_nocross</span><</span>J</span>:</span> ProxyJet</span>></span>(</span></span>
        &</span>self</span>,</span></span>
        curr_idx</span>:</span> usize</span>,</span></span>
        head_idx</span>:</span> usize</span>,</span></span>
        tail_idx</span>:</span> usize</span>,</span></span>
        jets</span>: &</span>[</span>J</span>],</span></span>
    )</span> -></span> (</span>usize</span>,</span> f64</span>) {</span></span>
        // logic</span></span>
        (</span>nn</span>,</span> nn_dist</span>)</span></span>
}</span></span></code></pre>
This allows us to avoid having to pass the entire jets collection as mutable preventing the need for the compiler to reload the entire jets collection after passing into the function. From the compiler’s eyes the entire</strong></em> vector could change. With this declaration we know that only jets[i]</code> changes. This change resulted in a 6 percent performance improvement</em>.</p>
eliding compiler bound checks</strong></h3>
This last example is arguably the most important. Each time a vector element is indexed, Rust checks whether the element is out of bounds (OOB) which in C leads to a host of UB. Given that our entire code relies on NN_index</code> and indexing our jets almost every time we require them, this becomes a large part of our performance penalty.</p>
Iterator efficiency in Rust can also be explained by the same phenomenon, since iterators already check elements exist, the compiler does not need to perform auxiliary bounds checking!</p>
For us, we can’t use iterators here because we need to pass the entire vector slice to internal functions alongside a jet from that slice. This doesn’t mean we have no options left though. Instead we can tell the compiler to stop bounds checking indexes by proving that we will never use an index that is OOB via assertions.</p>
In the code highlighted in the first optimization example, there is a lot of indexing. Almost everything is being indexed since we also have muts</code> sprinkled in the for loop. Thus before this entire loop we index according to i</code> and jet_b_idx</code> thus we add the following code before the loop.</p>
let</span> jets</span> = &</span>mut</span> bj_jets</span>[</span>..</span>tail</span>];</span></span>
let</span> dijs</span> = &</span>mut</span> di_j</span>[</span>..</span>tail</span>];</span></span>
</span>
assert!</span>(</span>jet_b_idx</span> <</span> jets</span>.</span>len</span>());</span></span></code></pre>
Since i</code> loops up to tail</code>, and jet_b</code> is less than the entire length of the jet, OOB cannot occur and the compiler removes all bounds checking for our code in this for loop and in our NN search due to the changes mentioned in the second example. This led to an astonishing 20% percent from just 3 lines of code!</strong></em></p>
Other not so micro optimizations that accounted for another 20% of performance improvements:</p>

Knowing our elements were never NaN</code> or INF</code> which require another check for f64</code> when sorting or min</li>
Removing lazy init since just calculating these numbers are cheaper than all of the dereferencing and heap retrieval</li>
Using Fused add_mul</code> in math calculations</li>
</ul>
Lastly, we found that testing different performance improvements with Rust was fairly easy as we didn’t have to worry about UB caused by our code changes that would normally be present in C++ pointer handling.</p>
so how much faster are we actually?</strong></h2>
We used Criterion</a> and Google Benchmarks</a> to benchmark our Rust functions simple_n2_cluster</code>, simple_n2_cluster_simd</code>, and tiled_n2_cluster</code> against the original C++ versions of the code. We initially wanted to also compare our implementation against the Julia code as well but after discovering that we were actually faster than the C++ implementation we thought that deserved our full attention.</p>
Previously, we just used the single-event.dat</code> file located in one of the example data folders of Fastjet to benchmark all of our code. This was good for debugging since we could make sure that our final calculated jets were the same as Fastjet but for performance testing we wanted a more diverse dataset, with varying numbers of particles to process.</p>
Luckily for us, there’s a way to generate simulated events using a package called Pythia</a>. We spent some time generating a diverse dataset of events ranging from 50 to 1500+ particles per event and ran all 3 algorithms on it.</p>
</p>
Let’s start with a macro view of our performance. Tiled clustering in C++ is still the fastest out of all the algorithms, however our tiling implementation is a pretty close second. The simple C++ implementation is also the slowest out of the algorithms with our SIMD and simple clustering consistently beating C++.</p>
To us, this is pretty surprising! We assumed that Rust would at best match C++ performance with the added benefit of memory safety (which was already a huge win from our perspective).</p>
Zooming in to a particular section gives us some more information too. Our tiled clustering algorithm has a slightly more unstable performance but the same points as the C++ code. We posit that this could be related to memory allocation and cache misses during reading tile neighbors? However, this would require some benchmarking with Memory profiling packages like dhat</a> that would allow us to observe the exact heap allocations made during each run.</p>
Another note here is that the benefits from a lot of the optimizations have a constant factor overhead (SIMD, tiling) so their benefit is really only felt at large input sizes. In fact, you can see that for smaller inputs, the simple n2 algorithm often outperforms our simd or tiled implementations.</p>
</p>
We hope by now it’s clear that paying attention to how code gets compiled can really pay off compared to manually hand tuning for performance. Who knew all of these seemingly trivial changes could actually turn out to be so powerful? Just as important though, is the fact that we could actually measure and test the impact of these changes with Criterion</code>.</p>
Never forget to benchmark your code folks!</p>
Until next time then :)</p>


Part 1: Rewriting C++ code to Rust (a FastJet experiment)
wency suo — Mon, 23 Feb 2026 00:00:00 +0000
what we are doing</strong></h3>
TLDR: This blog documents what we learned rewriting a scoped down fastjet 3.5.1</a> from C++ to Rust as our first real Rust crate, fastjet-rs</a>. We benchmark carefully hand-tuned work of physicists from 20 years ago and a more recent Julia rewrite</a> against our Rust implementation. This project is largely educational, but we also wanted to produce a crate that could become a meaningful contribution to the Rust ecosystem.</p>
One emerging area of Rust development is scientific high-performance computing. Workloads in computational biology or particle physics routinely handle petabytes of data and demand heavy optimization and parallelization to run. For this project, we took a particular interest in particle physics Rust crates since my collaborator started programming by analyzing lepton jets for CMS at the LHC (the world’s largest particle accelerator in CERN).</p>
Scientific computing seemed like natural Rust territory, but some deep diving into reddit threads</a> revealed that adoption outside of ML and computational biology is still nascent. In fact, Fortran and C/C++ still have a chokehold on HPC programs even when Rust is beginning to define modern programming elsewhere. The discussion boils down to three points:</p>

Scientists aren’t programers and rust has a steep learning curve</li>
C/C++ code when written well is already performant</li>
C/C++ ecosystems have decades of niche library support that Rust can’t match yet</li>
</ol>
Any memory bugs within applications like fastjet have been weeded out and corrected by the community over the past 20 years at the expense of many segfaults and memory leaks. When the community is already comfortable with a battle-tested Fortran or C program, fighting the borrow checker won’t always be worth it.</p>
That said, particle physicists haven’t been standing still. In the past few years, Python has gained serious traction among scientists who value ease of use and development speed. Binding tools like pybind11, Cython, SWIG give user-friendly interfaces to the underlying C++ code. There is no doubt that this is a step in the right direction. But accumulating tech debt by layering abstractions over aging C++ code risks the same fate as Fortran, where supporting new features and maintenance becomes more similar to witchcraft than engineering. One new line of code breaks a thousand others without rhyme or reason.</p>
</p>
Julia has emerged as one solution to this problem. Our hypothesis is that Rust could be another. Rust consistently matches or beats optimized C in benchmarks and its ownership model gives you fearless concurrency without a garbage collector. These are guarantees that Julia, for all its strengths, doesn’t offer at compile time.</p>
Our goal is to test this hypothesis by benchmarking fastjet across C++, Rust, and Julia.</p>
some basic things to know about jets and the problem we’re solving</strong></h3>
I had no physics background coming into this project, so we started with a crash course.</p>
</iframe>
Watching the two part series is not entirely necessary, although very entertaining. The production quality is peak 2006 internet and honestly that only makes them better.</p>
Ok so with that, what are jets?</h4>
</p>
proton proton collision that produces quarks and gluons which get recorded by the detectors calorimeters as jets</em></p>
As Matt Strassler’s</a> explains, jets are sprays of high-energy subatomic particles (hence the name jets) composing the building blocks of the universe that we examine to understand the inner workings of protons, neutrons and other hadrons. The particles that produce jets are extremely short-lived and never reach our detectors, so jets are the only observable evidence of their existence.</p>
Before we can analyze jets we need to reconstruct them from scattered event outputs collected by the calorimeters inside particle colliders. Historically, there are two methods for reconstructing particle collision events into jets: cone algorithms and hierarchical clustering. From the fastjet manual</a>:</p>

Cone algorithms put together particles within specific conical angular regions, notably such that the momentum sum of the particles contained in a given cone coincides with the cone axis (a “stable cone”).</em></p>
</blockquote>
What the manual calls sequential recombination algorithms can be understood more broadly as hierarchical clustering. Pairs of particles bound by their distance are clustered repeatedly until all particles are merged into stable jets. This statistical pattern can be found everywhere today. For our purposes, we can approximate jet reconstruction as an application of the nearest-neighbor problem common in CS.</p>
Both methods rely on a tunable distance parameter delta R to define either the radius of a cone from the origin particle or the furthest distance between two points that we would collimate into the same jet. Set delta R too low and we miss lower energy descendant particles (normally called “children”) or too high and background noise from other particles are included in our final jets.</p>
what did we do?</strong></h2>
Fastjet’s has three core classes that configure how jets are reconstructed:</p>

fastjet::PseudoJet</code> which defines jet objects as four-momenta vectors with additional values needed for different clustering algorithms</li>
fastjet::JetDefinition</code> which contains the specifications for how jet cluster should be carried out</li>
fastjet::ClusterSequence</code> which is the class that outputs the final jets after performing clustering as specified by JetDefinition on input PseudoJet objects</li>
</ul>
It is important to us that we keep the functionality of fastjet-rs close to fastjet which meant reimplementing PseudoJet, JetDefinition, ClusterSequence code as best we could in a rust-y manner.</p>
Heavy pointer manipulation and use of templates were the two characteristics of fastjet that made it difficult to translate to rust. You can read more about why raw pointer handling is an unsafe action in rust here</a>, but the tldr is that dereferencing raw pointers breaks rust’s memory safety guarantees. Of course, the advantage of pointer manipulation when done correctly lies in the performance benefits. So the main challenge is really just being explicit with memory safety while maintaining performance parity with fastjet’s unencumbered C++ implementations.</p>
Writing getters for PseudoJet</h3>
Each PseudoJet object is initialized by a four-momentum vector describing a particle’s x, y, z planar coordinates and an energy value e. These values are then used to derive the information we will need for clustering: kt2, rap, and phi. These values are expensive to calculate, and some jets may never need to call them so Fastjet initializes them lazily with an internal function _finish_init()</code>. _finish_init()</code></p>
Our first design of some of the PseudoJets get methods made them mutable. This seems fine at a glance but quickly complicated our code quite dramatically. During the clustering step we often need to calculate the distances between two jets using the following function:</p>
fn</span> _bj_dist</span><</span>J</span>:</span> ProxyJet</span>></span>(</span>jet_a</span>: &</span>mut</span> J</span>,</span> jet_b</span>: &</span>mut</span> J</span>)</span> -></span> f64</span> {</span></span>
        let</span> dphi</span>:</span> f64</span> =</span> PI</span>-</span>f64</span>::</span>abs</span>(</span>PI</span>-</span>f64</span>::</span>abs</span>(</span>jet_a</span>.</span>phi</span>()</span>-</span>jet_b</span>.</span>phi</span>()));</span></span>
        let</span> deta</span>:</span> f64</span> =</span> jet_a</span>.</span>eta</span>()</span>-</span>jet_b</span>.</span>eta</span>();</span></span>
        dphi</span> *</span> dphi</span> +</span> deta</span> *</span> deta</span></span>
}</span></span></code></pre>
Since we’re only accessing fields of jet_a</code> and jet_b</code>, theoretically we don’t actually need to pass in mutable references to jet_a</code> or jet_b</code>. However, since phi is a lazily initialized value with a mutable get method this aspect is passed onto the _bj_dist</code> function. Furthermore, jets are stored in a vector so when calling _bj_dist</code> we need to pass in two mutable references to elements of the same vector. This creates a major violation in rust since there cannot be multiple, simultaneous mutable references to the same object.</p>
Even though we could guarantee that there would be no data races when running our code single threaded, the Rust compiler does not. Our temporary fix was to create a helper function which breaks our jet vector into two separate mutable components each time we had to call _bj_dist</code>. You can probably see that this was a messy solution, not to mention a big performance hit to our naive implementation that we needed to fix.</p>
Our second solution was to turn to unsafe Rust, since as stated earlier we guaranteed that we would never be calling mut</code> on the same index, we could reduce the bloat of our function by calling the pointers directly. Unsafe code isn’t always bad, Rust just forces you to be deliberate about the abstractions that often lead to nasty memory bugs.</p>
Luckily, there is a much better way to solve this problem in Rust with a concept called interior mutability, a design pattern that allows you to mutate data even when there are immutable references to that data. I told you earlier that this is explicitly disallowed by rust, nothing has changed. Implementations of interior mutability like OnceCell</code> are just safe APIs for unsafe code, making it easier for us to directly use helpful abstractions for unsafe code.</p>
For lazy initialization specifically, the standard rust library has a type called OnceCell</code> which we can use to obtain shared immutable references</strong> to uninitialized data that becomes initialized once written. Getting rid of our vector split workarounds improves the performance, readability of our code, and prepares us for properly implementing concurrency.</p>
In fact, the authors of fastjet ran into this very problem with these getter methods when multithreading their code. There are many preprocessing macros modifying how these getters work for the exact reason that they can’t prevent data races here. This is where the rust compiler’s foresight really pays off, by designing early with restrictive borrowing and ownership rules from the start we get “fearless concurrency” for free!</p>
benchmarking</strong></h2>
To compare our implementations, we timed and generated flamegraphs for the C++, Julia, and Rust versions of the simple n² algorithm using the basic clustering strategy.</p>
Setting up profiling turned out to be more annoying than expected, especially on mac. We found that sample worked best for our purposes, but getting useful flamegraphs required some care. We had to reduce inlining (-g</code> for C++, #[inline(never)]</code> in Rust) and keep frame pointers intact so the profiler could actually record meaningful stack frames instead of collapsing everything into “the clustering function”.</p>
</p>
C++ Flamegraph</em></p>
</p>
Rust Flamegraph</em></p>
In our Rust flamegraph, we found that roughly half of the runtime was spent actual clustering while most of the remainder went to parsing event files. Some nice improvements can be seen when compared to earlier flamegraphs</a>, calculations for bj_dist</code> (which required calculating eta</code> and phi</code>) no longer take half the time that clustering currently takes.</p>
</p>
Julia Flamegraph</em></p>
This is where things got interesting. We initially thought Julia was running significantly faster than our Rust implementation, but through observing the flamegraph it turned out the Julia benchmarks were only measuring jet creation not event parsing or output. Once we accounted for that, the playing field leveled out considerably:</p>
</p>

Rust:</strong> 498.003 µs ± 0.687 µs</li>
Julia:</strong> 487.902 µs ± 22.156 µs</li>
C++:</strong> 365.222 µs ± 0.901 µs</li>
</ul>
Julia and Rust land in essentially the same ballpark, with C++ still comfortably ahead. Currently, Julia has similar performance to our Rust implementation because of SIMD (Single Instruction Multiple Data), which tells the compiler to vectorize loops in assembly. Rust currently only supports SIMD for floats in the nightly</code> crate, so for this first iteration we wanted to avoid its use, with it we most likely will pull fairly ahead of Julia.</p>
However since Julia is a runtime language, the first iteration of the code runs extremely slow, otherwise known as the ‘Time to First Plot” problem. Lengthened compile time in Rust is a deliberate sacrifice for faster runtime programs and guaranteed memory safety. Compared to C++, Rust loses on the compile time game, taking around 30 seconds to fully compile versus C++’s three seconds. Rust is thus a happy middle ground between Julia and C++ that balances speed and memory management.</p>
So why is our Rust implementation slower than C++?</p>
A few reasons most likely. Because we use indices to track nearest neighbors, we need an extra pass through all active particles after each merge to make sure NN pointers stay valid. That introduces an additional constant-factor loop inside the O(n²) main loop. One potential fix is wrapping each PseudoJet in an Rc, which would allow multiple references to mutable jet instances and eliminate the index bookkeeping. Although, there is a possibility that the reference counting overhead could end up costing more than the loop it replaces. We’re also paying a cost by passing entire vectors by reference into one of our distance functions, and we’re investigating whether leveraging const more aggressively in our Rust code could close the gap, since the C++ implementation makes heavy use of inline const templating.</p>
That said, profiling and iterating paid off. With the help of the Rust Performance Book</a> and some build configuration changes, we brought our runtime down from 1.4 milliseconds to 650 microseconds which is roughly a 2x improvement from relatively simple optimizations (lazy initialization with OnceCell and updating NN indices for only active particles rather than the full list.)!</p>
next steps</strong></h2>
Fastjet-rs is very much an ongoing project and there are many other features that still need to be implemented. To start, we want to increase the number of jet finding algorithms we support as we currently only have Anti-kt. Another major feature we are missing is an O(nlogn) Voronio clustering algorithm that leverages a fascinating geometry based optimization trick.</p>
So if you’re interested in seeing what we learn from any of these small projects stay tuned for the next part :)</p>
references</strong></h2>

https://fastjet.fr/</li>
https://github.com/JuliaHEP/JetReconstruction.jl?tab=readme-ov-file</a></li>
https://discord.com/blog/why-discord-is-switching-from-go-to-rust</a></li>
https://www.figma.com/blog/rust-in-production-at-figma/</a></li>
https://aws.amazon.com/blogs/opensource/why-aws-loves-rust-and-how-wed-like-to-help/</a></li>
</ol>

wency suo - blog

How To Play Cut The Rope on Your TV

things that almost worked</h2> I'll list here a few things that we couldn't debug or discovered too late to design around.</p>

disguising my online traffic :)

FastJet but faster? Part II

Part 1: Rewriting C++ code to Rust (a FastJet experiment)

things that almost worked</h2>
I'll list here a few things that we couldn't debug or discovered too late to design around.</p>