Assume False

Recreating Recipes Using SMT

2025-02-27T00:00:00.000Z

{: .prompt-warning }

This post is a draft, so it will likely change in the future. Also, I make no guarantees that the post is currently coherent, legible, or enjoyable to read. Read at your own risk :)

I love snacks, in fact I love them so much that I have attained the holy status of "snack monster" in my household. If my wife and I go on roadtrips, we usually end up buying our own bags of snacks and labelling them so that I don't accidentally eat all the snacks before she gets some. Unfortunately, all this snacking comes at a cost. Literally. It costs money to buy snacks. This post is about how I used Z3, an SMT solver, to derive recipes for one of my favorite snacks.

The Target Snack

I will not out the exact snack here that I like, but there is a local business where I live that makes a protein bite style snack. If you google protein bite you will be greeted with many such snacks, but the basic idea of the snack is that you make a small uncooked ball of chocolate chips, peanut butter, honey, and protien powder and then you let it sit overnight to harden and shazam, you have yourself a snack.

These sound easy to make by yourself and typically they are, but I've tried making variations on my own that replicate the macros of the specific version available in my town, and they always end up gross. Likely I just have the wrong combination of ingredients and perhaps an incorrect mixing style. To correct the first problem of incorrect ingredient balance, I decided that I could write a program using the Z3 SMT solver and python to determine exactly what ratio of ingredients I could use!

Setting up an Example Problem

I haven't really used an SMT solver for anything before, but I'm aware of the basic concept. You specify a formula, and Z3 determines if it can assign a specific value to each variable in the formula and have the formula result in true. If it can assign each variable a value, then the equation is said to be satisfied, or sat. If you can't assign a variable a value, the equation is unsatisfied, or unsat.

For example, let's say we have two floating point variables, $$x$$ and $$y$$. One possible formula we could make with these variables would be the following:

$$ x \le y \wedge x \ge 5 \wedge y \le 6 $$

An SMT solver asks itself if there is a possible assignment to $$x$$ and $$y$$ that would satisfy this equation. In this case, there is at least one possible assignment:

$$ x = 5, y = 5 $$

So Z3 returns sat and gives us these values for the assignment. If we change the formula slightly, we can see that there will not be a possible solution as $$x$$ must be greater than 5 and $$y$$ must be less than 4. Let's see what happens when we pass this formula to the computer though.

$$ x \le y \wedge x > 5 \wedge y < 4 $$

Z3 returns "no solution" indicating that there is not a possible assignment of real number to $$x$$ or $$y$$ that can satify this formula. For reference, here's how I encoded this problem into Z3 using python.

from z3 import *

x = Real('X')
y = Real('Y')

solve(And(And(x <= y, x >= 5), y <= 6))
# Output: [Y = 5, X = 5]

solve(And(And(x <= y, x > 5), y < 5))
# Output: no solution

Now Onto... Recipes?

I know what you're thinking, "that's really cool, but how in the world are you going to steal recipes with it?" Well, let's try to talk through it together.

First, we need to define what a "recipe" is going to be to the SMT solver. This is going to be quite different from what we as humans view as a recipe, but it will maintain the same purpose.

Macro Triple : A triple $$\langle F, C, P \rangle$$ where $$F$$ is fat in grams, $$C$$ is carbs in grams, and $$P$$ is protein in grams.

Recipe : A combination of ingredients that when combined together result in a equivalently proportioned macro triple to the target recipe. We can represent a target recipe by the following equation.

$$ \sum_{i=0}^{n} k_i I_i = R $$

$$n$$ is the number of ingredients,
$$I_i$$ is the macro triple for each ingredient in the recipe
$$k_i$$ is the coeffiecient that represents how many multiples of the ingredient we will use in the recipe, and
$$R$$ is the macro triple for the target recipe.

To put this into the SMT solver we're first going to need some constraints. First off, we need to make sure that the ingredient coeffiecients can't be zero. If we had only two ingredients, and one of them had the same macros as the target recipe, then the SMT solver might just say that for our "recipe" we only need the one ingredient.

Ingredient	Macros
Bacon	$$b = \langle 10, 0, 2 \rangle$$
Eggs	$$e = \langle 5, 0, 3 \rangle$$

$$ R = \langle 20, 0, 4 \rangle $$

Given the above ingredients and the target recipe, then the SMT solver may just decide that assignments for $$k_b$$ and $$k_e$$ are 2 and 0.

$$ \begin{align*} R = \langle 20, 0, 4 \rangle &= \sum_{i=0}^{n} k_i I_i\ &= k_b b + k_e e \ &= 2 \langle 10, 0, 2 \rangle + 0 \langle 5, 0, 3 \rangle \ &= \langle 20, 0, 4 \rangle \ \end{align*} $$

So our first constraint will be all $$k_i$$ must be greater than 0.

$$ \forall k, k > 0 $$

At the moment I can't think of any other constraints, so we'll keep going from here.

Recipes As a Formula

Now that we have an abstract mathematical way of representing our recipes, we need to be able to encode these recipes as formulas that we can pass to Z3. Z3 has no concept of a macro triple, so we'll need to figure out how we can tell the Z3 solver what that is. The good news is that it's actually pretty easy. Basically, we just need to make the transformation from this:

$$ \sum_{i=0}^{n} k_i I_i = R $$

To this:

$$ \sum_{i=0}^{n} k_i F_i = R_F\ \sum_{i=0}^{n} k_i C_i = R_C\ \sum_{i=0}^{n} k_i P_i = R_P\ $$

All we are doing here is splitting out the ingredient triple into each of its separate components, and sharing the coeffiecients for each portion of the triple. We're also going to make the transistion into coding land here.

Representing the Recipe in Python

We'll start by creating a small python class to represent a macro triple. This will be the core data structure we'll use to store the ingredients and the target recipe. Our class will have the three key data values we need, fat, carbs, and protien, and we'll also add a name to each triple to differentiate triples from one another. We'll use this later to generate names for our coeffiecients.

class MacroTriple:
    def __init__(self, name, fat, carbs, protien, gramsPerServing):
        self.name = name
        self.fat = fat / gramsPerServing
        self.carbs = carbs / gramsPerServing
        self.protien = protien / gramsPerServing

Next, we'll need a way to generate our recipe formula. To do this we'll need a list of MacroTriples for the ingredients and a MacroTriple for the target recipe. Based off our equations from above, we'll need to generate a constraint for each ingredient ($$k_i > 0$$) and create the sum of coeffiecients that are equal to the target recipe.

To create all this we'll introduce the concept of a Z3 solver. A solver is an object that we can add formulas to in different places and then we can call the check() method on the object to find satisfying assignments (or show that the formula is unsat).

import z3 

def recipeFormula(ingredients, target):
    s = z3.Solver()

    # initial constraint
    k0 = z3.Real(f"k_{ingredients[0].name}")
    s.add(k0 > 0)

    # initial equations 
    fatEquation = k0 * ingredients[0].fat
    carbsEquation = k0 * ingredients[0].carbs
    protienEquation = k0 * ingredients[0].protien

    # the rest of the equation and constraints 
    for ingredient in ingredients[1::]:
        kn = z3.Real(f"k_{ingredient.name}")
        s.add(kn > 0)

        fatEquation += kn * ingredient.fat
        carbsEquation += kn * ingredient.carbs
        protienEquation += kn * ingredient.protien

    # adding the final equations to the solver 
    s.add(fatEquation == target.fat)
    s.add(carbsEquation == target.carbs)
    s.add(proteinEquation == target.protien)

    return s

Now that we have this formula we can start generating recipes! First, we'll need to set
up the list of ingredients.

{: width="80%" }

Using the ingredients from the bag as a starting point, I grabbed all the macros of the ingredients from Cronometer, a macro tracking app, and I entered them into my python file.

Ingredients = [
        MacroTriple("Pb", 46.9, 25.0, 21.9, 100),
        MacroTriple("Honey", 0, 82.4, 0.3, 100),
        MacroTriple("Oats", 5.9, 68.7, 13.5, 100),
        MacroTriple("Protien", 0, 8, 20, 34),
        MacroTriple("ChocChips", 29.2, 66.7, 4.2, 100),
    ]

Next we need to set up the target recipe, which also is conveniently on the bag.

Target = MacroTriple("Bites", 5, 11, 4, 1)

Finally, we create the recipe formula, call check() on it to find a satisfying assignment and then print it to get our recipe!

formula = recipeFormula(Ingredients, Target)
formula.check()
print(formula.model())

When we run this we get:

[K_Pb = 8.915?,
 K_Oats = 11.399?,
 K_Honey = 0.5,
 K_Protien = 0.826?,
 K_ChocChips = 0.5]

We can read this recipe as 8.9 grams of peanut butter, 11.4 grams of oats, and so on. Right off the bat this recipe looks a little strange, and definitely gives me the sense that the peanut butter and oats will overpower everything else. To fix this I added two parameters to the recipeFormula function, min_bound and max_bound. These build off the same idea as the constraint we added early that all $$k$$ must be greater than 0. Now we can use these bound variables to additionally specifiy that $$\texttt{min_bound} < k < \texttt{max_bound}$$.

Final Bites

This brings me to the end of this blog post, but not to the end of my recipe generating. After I attempt to construct some of these recipes I'll update this post with the results.

If you'd like to explore the code yourself, check it our on my GitHub.

Additional Optimizations to the Recipe Generator

In the US, ingredients on labels are listed in descending weight order, so we could add an additional constraint that the weight of all ingredients must be ordered to get more precise recipes.

Impacts of Compiler Optimization on Cache Latency Profiling

2025-02-26T00:00:00.000Z

{: .prompt-warning }

This post is a draft, so it will likely change in the future. Also, I make no guarantees that the post is currently coherent, legible, or enjoyable to read. Read at your own risk :)

As a TA for the computer hardware security course taught at Utah State University I helped create and run a lab where the students used a cache side channel to transmit information between processes using only memory access time latencies to communicate bytes. Likely I'll one day write a blog post about the whole lab, as it was one of my favorite things I did in university, but alas today is just about a part of it, timing memory accesses.

We ran the lab on machine that had Intel chips, which have hierarchical set-associative memory caches (L1, L2, and L3) inbetween the logical cores and DRAM in order to improve memory access times for data that was accessed regularly. There are many posts about what CPU caches are, so I won't really offer an explanation beyond this here.

As a general rule of thumb, access to each successive level of cache takes longer than accessing the previous level of cache. The L2 cache is also shared between two cores. Given this information we can take advantage of it to create a covert side channel, where we can pass information between processes using the shared L2 cache. The lab we ran used a basic "prime and probe" attack, where one process would "prime" the L2 cache, effectively filling it for a time, then it would sleep. During that time, the victim process would access some data inside the L2 cache, evicting the data stored by the attacker process. The attacker process would then probe the cache, and based on which data was evicted by the victim the attacker could receive a message.

That was far to short an explanation likely, but hopefully enough for this post to make some sense. A key part in a cache side channel is timing. If you can't accurately measure how long it takes to load a particular address from memory, you'll never be able to probe effectively enough to receive a message across the side channel.

What is "Now"?

In modern processors, unfortunately the concept of "now" is a bit amorphous. Modern processors are out-of-order pipelined beasts that speculatively execute your code whenever they feel like it. At any time, you could have 10's (or more) instructions being executed at once in your processor. Because of this, it's really hard to tell exactly what instant an instruction is being executed. As you'll see, we'll pick and prod at the processor in order to get it to do what we want, but we'll still see noise and spurious data in our timing analysis.

With poor code, compiler optimizations can get in the way of this timing as well. If the compiler decides to reorder some statements (which it is allowed to do in many circumstances), unroll our loops, or optimize away spurious memory accesses we'll get no useful timing information at all. Here's how we managed to get reasonable timing results with both out of order processors and compiler optimizations turned on.

The Psuedocode

Basically, to measure the access time of a specific cache we want to execute some code that looks like this:

Target Cache = L2

1. Access a single piece of memory, known as the 
    target line, pulling it into the L1 cache 

2. Access a chunk of memory the size of the cache 
    immediately lower than our target cache, 
    in this case L1

3. Time the access of the target line. Due to step 
    2 the target line should not reside in our 
    target cache, so the time it takes to access 
    should be the time it takes to access our 
    target cache.

In practice, we can basically transform this algorithm into C-code, and then start generating results. A key part of this algorithm (step 3) is timing the access to the target line though, and how do we even do that?

Enter `rdtsc`

rdtsc is the x86 instruction to read the timestamp counter, which nominally is a counter that tracks which clock cycle the processor is on. As discussed before "now" is a bit of a unreachable state with out-of-order speculative CPUs, but reading the timestamp will give us accurate enough measurements to perform a side channel attack. Using rdtsc (and it's sibling, rdtscp) is apparently not as easy as just writing out the assembly instruction, and to get the best use out of it I had to read a classic book, the Intel Software Developer Manual. Several volumes thick, this bad boy is a giant pdf that talks about what Intel processors do and don't do. In the comments of my code I highlight the specific sections I used to generate my functions.

// Reads the time stamp counter as a 64-bit integer value. 
// (Code is derived from https://gcc.gnu.org/onlinedocs/gcc/Extended-Asm.html)
//
// This function uses the `rdtscp` instruction to retrieve the 
// timestamp. According to the Intel Software Developer Manual 
// Vol. 2B, pg. 4-560 `rdtscp` is "not a serializing instruction" 
// but it does wait for all previous _loads_ to become visible 
// and all previous instructions to execute. It also states that 
// for this instruction to complete prior to any following 
// instructions running that an `lfence` instruction can be inserted 
// immediately following the instruction.
// 
// The `rdtsc` instruction returns the lower 32-bits of the timestamp 
// into the EAX register, and the upper 32-bits of the timestamp into 
// the EDX register. The IA32_TSC_AUX is also stored in the RCX 
// register. We don't use this value but we indicate in the inline 
// assembly that it's used so that the compiler knows that the value in 
// RCX will be overwritten.
static inline __attribute__((always_inline)) uint64_t read_timestamp() {
    uint64_t time;
    asm volatile(
        "rdtscp\n\t"            // Returns the time in EDX:EAX.
        "shl $32, %%rdx\n\t"    // Shift the upper bits left.
        "or %%rdx, %0"          // 'Or' in the lower bits.
        : "=a" (time)           // Put result from RAX into `time` variable
        : 
        : "rdx", "rcx");        // Indicate that RDX and RCX will be written to
    return time;
}

If you've never written inline assembly before in C, this may look like a mess. That's because it kind of is. Also, technically, this inline assembly is only valid using GCC's extended assembly syntax, so I don't really know if you can even compile this code with Clang or MSVC. Luckily, portability is not a goal for this code.

So, despite it being a mess, we now have a function that we can get the timestamp value of the processor at any time! So, timing an access should be as simple as this:

uint64_t start = read_timestamp();
x = *ptr; // access to time 
uint64_t elapsed = read_timestamp() - start;

Right? Please?

Unfortunately, our new bible the Intel Software Developer's Manual says "maybe not".

Insert SDM quotes here.

Go over fence instructions.

// Load fence (Intel Software Developer Manual Vol. 1 - 11.4.4.3)
// This function guarantees ordering between two loads and prevents 
// speculative loads until all load prior to this instruction have 
// been carried out.
static inline __attribute__((always_inline)) void lfence() {
    asm volatile("lfence");
}

// Memory fence (Intel Software Developer Manual Vol. 1 - 11.4.4.3) 
// This functions ensures that no loads or stores after this instruction 
// will be globally visible until after all loads or stored previous to 
// this instruction are globally visible.
static inline __attribute__((always_inline)) void mfence() {
    asm volatile("mfence");
}

Finally, we can complete what we came here to do an write a function that reliabily times accesses to a specific memory address.

// Uses `read_timestamp()` and fencing instruction to time a read access 
// to *addr.
static inline __attribute__((always_inline)) uint64_t time_one_line_read_access(const byte *addr) {
    volatile byte b;

    mfence(); // ensure all previous memory access is complete
    const uint64_t time_init = read_timestamp();
    lfence(); // inserted due to the advice in Intel SDM Vol. 2B 4-560
    b = *addr; // read address
    const uint64_t elapsed_time = read_timestamp() - time_init;
    return elapsed_time;
}

Timing Results and Optimizations

As usual, I'm realizing that writing is hard, and I'm doing a lot more it than I originally bargained for. We haven't even covered the title of this post yet! Here's the thing, the code we wrote before may be slightly transformed by optimizations.

Insert assembly generated by the timing functions

To see the impact that optimization had on timing, I ran the timing analysis on optimization levels O0-O3, and plotted the results. All of the results were generated on an Intel I7-4790 and were run pinned to CPU core 4.

The results show a bar graph of the the timings generated by each run, and the L2 upper bound and L3 lower bound are calculated by taking the mean of each group of measurements and adding one standard deviation to it.

In general, adding optimizations seems to shift the access time of all measurements down by 10 clock cycles or so. The relative separation between the L2 and L3 bounds however remains fairly constant. This means that as long as we profile well and are careful, we should be able to enable optimizations in our cache side channel attack code without a decrease in transmission performance.

-O0

{: width="100%" }

-O1

{: width="100%" }

-O2

{: width="100%" }

-O3

{: width="100%" }

SPAC 2025

2025-02-22T00:00:00.000Z

Basic Examples

Map example

Filter example

Reduce example

Longer Examples

Cpp

Rust

[](){}();

2025-02-11T00:00:00.000Z

Recently I had the opportunity to write a multi-threaded histogram generator for my high performance computing (HPC) class at university. The assignment was the first time I'd completed a "larger" project since finding my way around the Flux project. When attempting to contribute to Flux, something I found interesting was the use of "immediately applied lambdas". This is the idiom where a variable is assigned to the output of a lambda function that is immediately invoked, thus resulting in the variable being assigned a value as opposed to a closure type.

auto x = [](){
    return 0;
}(); // immediately call the lambda to return a value.

assert(x == 0);

The above is possibly the simplest example of an immediately applied lambda, with x simply being assigned to 0 through it. For such a trivial use it's definitely not good practice to use an immediately applied lambda, but we'll build out some more concrete examples in the future. For an example in Flux, take a look at line 113 of the flatten adaptor.

Why?

Based on the example above, using this "trick" seems to be a very verbose and confusing method to assign variables. However, I think that using immediately applied lambdas leads to code that easier to reason about, understand, and refactor. While I don't yet have any experience working on industrial scale codebases, I still feel the pain of going back to an old project that I didn't document and trying to parse the code that I previously wrote. I think that using this idiom makes that process less painful, and through the power of constant expressions and optimization there is little if any performance penalty.

The Syntax

The syntax for creating an immediately applied lambda is simple. Simply call the lambda using the () operator immediately after the lambda's closing bracket. The example below shows the difference between creating a closure object and creating a value by immediately calling the lambda.

auto closure = [](){ /*...*/ };
auto value   = [](){ /*...*/ }();

An Example

When working on my histogram generator I needed a way to break down a input of randomly generated floating point numbers (simulating real data) into different slices for each thread to operate on. To do this I used std::span to wrap the input data, and then used .subspan() to get the slice for each thread.

It's important that every element in the original dataset is

eventually assigned to a thread, and
no element is assigned to two threads.

If either of those properties are violated, then we'll have either the case where the histogram did not accurately count all the elements in the input dataset, or that an element was counted twice. Both lead to incorrect results.

Since the dataset size and number of threads have to be determined at runtime for this assignment (according to the assignment description), we'll have to calculate the slices for each thread at runtime. My first attempt at doing so worked successfully like this:

auto thread_func(
    int thread_id,
    int number_threads,
    const std::span<float> dataset) -> void
{
    const auto slice_size = dataset.size() / number_threads;
    const auto slice_starting_index = thread_id * slice_size;

    const auto dataset_slice
        = dataset.subspan(slice_starting_index, slice_size);
}

The thread_id corresponds to which thread is currently operating on the data, and is assigned by me when the threads are created and ranges from 0 to n-1, where n is the desired number of threads. Looking over this code it should not be hard to convince yourself that in general, dataset_slice will be a subspan over the elements that the current thread is to operate on.

However, this function has a flaw. What if the datasize is not easily divisible by the number of threads. For example, what if you have three threads, and 11 elements?

Using our function, we'll generate three dataset slices, one for each thread. The table below tells us what the corresponding starting index and size of each slice will be:

Thread ID	Slice Size	Slice Starting Index	Slice Range
0	3	0	[0:2]
1	3	3	[3:5]
2	3	6	[6:8]

Immediately, the issue becomes clear. Elements 9 and 10 will not be accessed by any thread, as the last subspan assigned (to thread 2) is the elements from 6 to 8. Clearly this algorithm for splitting up work is not correct, because we are not calculating the histogram from all of the input data.

An easy way to fix this algorithm would be to just have the last slice cover all of the remaining data. That way, the last thread may do more work but all of the data will be covered.

Thread ID	Slice Size	Slice Starting Index	Slice Range
0	3	0	[0:2]
1	3	3	[3:5]
2	3	6	[6:10]

For this assignment it was reasonable to assume that the datasize would be much larger than the number of threads (e.g. 10'000'000'000 elements vs. 16 threads), so it wouldn't be an issue if one thread processed at most n-1 more elements than the other threads. The design decision I made was to have the last thread process all of the remaining elements.

Now thread two is processing elements 6 through 10, and no elements are missed.

Now we run into the issue of changing our code. A simple refactoring results in something like this:

auto thread_func(
    int thread_id,
    int number_threads,
    const std::span<float> dataset) -> void
{
    const auto slice_size = dataset.size() / number_threads;
    const auto slice_starting_index = thread_id * slice_size;

    std::span<float> dataset_slice;

    if (thread_id == number_threads - 1) { 
        dataset_slice
            = dataset.subspan(slice_starting_index, slice_size);
    } else {
        dataset_slice
            = dataset.subspan(slice_starting_index);
    }
}

Calling .subspan() without a size just returns a span from the given index to the end of the input data.

To me, this looks messy. First, we lose the const specifier on our dataset slice. While the code still compiles (at least on GCC 14 on compiler explorer) it's quite misleading as we definitely do not want the underlying data changed. We annotated that by marking the input dataset span as const, so it feels bad to get rid of it now.

Also, we lose the ability to use auto. While not the end of the world, there are many reasons to use auto over explicitly declaring the type. Far smarter people than me have given reasons, so to learn more about prefering auto I would check out the following:

Finally, this code introduces a new if-statement to be analyzed when trying to determine what the code is doing. It's not immediately clear that this if-statement relates to dataset_slice, and opens up the opportunity for more convoluted code to be created in the future as other operations could be stuffed into the statement, further muddying the waters.

By using an immediately applied lambda, we can solve these problems and more! Here's the updated code:

auto thread_func(
    int thread_id,
    int number_threads,
    const std::span<float> dataset) -> void
{
    const auto slice_size = dataset.size() / number_threads;
    const auto slice_starting_index = thread_id * slice_size;

    const auto dataset_slice = [&](){
        if (thread_id == number_threads - 1) { 
            return dataset.subspan(slice_starting_index, slice_size);
        } else {
            return dataset.subspan(slice_starting_index);
        }
    }();
}

In basically the same number of lines of code we have brought back the ability to use auto, the const specifier, and we now have a clearly defined purpose for our if-statement defined by the way we wrote the code. When reading this, (if you know about immediately applied lambdas) it's easy to see that, "Oh, this line of code gets the slice of the dataset that applies to this thread". All of the logic is in one location, and it's easy to reason about.

I'd argue as well that using this approach coupled with optimizations actually makes it possible for code to become even more readable as well. Consider the following small change:

const auto dataset_slice = [&](){
    const auto max_thread_id = number_threads - 1;

    if (thread_id == max_thread_id) { 
        return dataset.subspan(slice_starting_index, slice_size);
    } else {
        return dataset.subspan(slice_starting_index);
    }
}();

This introduces a variable local to the lambda (inaccessible outside of it) that gives meaning to the statement number_threads - 1. With optimizations this code will function just the same as the code before, but now it's more maintainable and clear as to what it's purpose is.

While there are other, likely more optimal ways to implement this functionality, we'll end this example here as it has shown the general point.

Other Tips and Tricks

You can use this to initialize class members:

class X {
    const y = [](){ /*...*/ }();
    constexpr static x = [](){ /*...*/ }();
};

You can use this in statements:

while([]() -> bool { /*...*/ }()) /*...*/

You can use this in constant expressions:

const auto x = 10;
const auto y = [&](){
        return 2*x;
    }();

static_assert(y == 20);

You can also use this in template parameters:

template<size_t Size = [](){ return 0; }()>
auto x() -> Type;

The End

Overall, I think this is a great idiom to have in your toolbox, and it may come in handy more often than you think!

Flux Permutations Adaptor (1/4)

2025-01-02T00:00:00.000Z

I've been using the Flux C++ library for a while now, ever since hearing Tristan Brindle talk about it on the ADSP podcast. As a brief introdution for the unintroduced, Flux is a library for "sequence-oriented programming, similar in spirit to C++20 ranges, Python itertools, and Rust iterators." Flux provides an easy API to apply algorithms to sequences. For example, this is how you might sum all even integers from 0 to 10 using Flux.

auto sum = flux::ints() // [0, 1, 2, 3, ...]
    .take(10)           // [0, 1, 2, 3, ..., 10]
    .filter(is_even)    // [0, 2, 4, 6, 8, 10]
    .sum();             // 30

Flux is also an open source project, and I thought it would a great library to make a contribution to. I saw on GitHub that there was a request for a permutations adaptor I thought this would be something that I could handle, so I commented on the GitHub issue that I would try to implement it. After a busy Christmas season I was able to get a working implementation. These four articles detail how I implemented the adaptor.

The Idea

A permutations adapator (or iterator, or function, etc.) is a common tool in other iteration libraries. The adaptor takes in an input sequence, and returns a sequence made up of sequences that are a permutation of the previous sequence. A basic example would be as follows (in Python).

import itertools as it 

for permutation in it.permutations([1, 2]):
    print(permutation)

""" Output:
(1, 2)
(2, 1)
"""

The goal would be to add an adaptor to Flux such that operations like the previous example would be possible.

flux::ints()         // [1, 2, 3, ...]
    .take(2)         // [1, 2]
    .permutations(); // [[1, 2], [2, 1]]

Defining a Permutation

Before doing some implementation, let's spend a few minutes trying to understand what a permutation actually is, and how the word is used in mathematics and programming. The Wikipedia page for permutation is displayed from a mathematics perspective, and states as follows.

Permutation (Wikipedia) : In mathematics, a permutation of a set can mean one of two different things: an arrangement of its members in a sequence or linear order, or the act or process of changing the linear order of an ordered set. (Wikipedia/Permutation)

Our adaptor will fulfil both definitions. We want the adaptor to (1) produce every permutation of the input sequence and (2) perform the process of generating new permutations from the sequence. Based on this we'll make some definitions for our adaptor.

Input Sequence : The original sequence to perform the permutations on. This must be a flux::bounded_sequence, because there have to be a finite number of elements to permute.

Output Sequence : A sequence of sub-sequences where the sub-sequences are all of the permutations of the input sequence. The order of the sub-sequence is in lexicographical order.

Sub-Sequence : A sequence of length r that contains a permutation of the input sequence.

The Simplest Permutations Adaptor

While the Python itertools and Rust itertools iterators allow the user to specify the length of each sub-sequence, the simplest permutations adaptor will always output sub-sequences the length of the original sequence.

Flux allows for C++ coroutines to be used to specify simple adaptors, which is great for quickly developing a new adaptor. For a introduction to coroutines I would recommend Joel Schumacher's Yet Another C++ Coroutine Tutorial or David Mazieres' My tutorial and take on C++20 Coroutines. The basics for using a coroutine to create a Flux adaptor are as follows:

// Construction
auto adaptor_name = []<flux::sequence Seq>(Seq seq)
    -> flux::generator<flux::element_t<Seq>>
{
    // Implementation
};

// Usage
flux::ints()
    .take(2)
    ._(adaptor_name)
    . //...

The flux::generator type implements the flux::sequence functionality we need, and the _ function applies the adaptor to the input sequence.

Now to create the permutations adaptor we'll consider what steps we need to take. First, we'll need to cache the input sequence. We do this because each output-subsequence will be composed of the input values and the input sequence may be a single pass input so that if we don't cache it we'll only be able to produce the first output.

auto permutations_adaptor = []<flux::sequence Seq>(Seq seq)
    -> flux::generator</* subsequence type */>
{
    std::vector<flux::value_t<Seq>> cache;
    for (auto &&elem : seq) { cache.emplace_back(elem); }
};

Now we need to consider what the subsequence type should be. Since we want our output to be a sequence of subsequences, and we already have our input values cached in a std::vector we might as well just have the subsequence type be a std::vector as well. There are other types we could use in order to limit extraneous memory allocation, but we'll talk about that another day.

auto permutations_adaptor = []<flux::sequence Seq>(Seq seq)
    -> flux::generator<std::vector<flux::value_t<Seq>>>
// ...

Producing the First Sub-Sequence

The first permutation in the sequence is the easiest, as it's just the exact same as the input sequence. To return the first sequence, we'll use co_yield to return the first element.

auto permutations_adaptor = []<flux::sequence Seq>(Seq seq)
    -> flux::generator<std::vector<flux::value_t<Seq>>>
{
    std::vector<flux::value_t<Seq>> cache;
    for (auto &&elem : seq) { cache.emplace_back(elem); }

    co_yield cache; // first subsequence
};

Producing Following Sub-Sequences

To get later sequences we can use the std::next_permutation to produce the permutations. According to the documentation the function permutes the input sequence to the next permutation, and returns true if there is another permutation possible, or false if all permutations have been exhausted. We can use the return value of std::next_permutation to determine if we should continue producing elements and permute the elements in one step.

auto permutations_adaptor = /* function signature */
{
    /* cache input */

    co_yield cache; // first subsequence

    while (std::next_permutation(cache.begin(), cache.end())) {
        co_yield cache; // following subsequences
    }
};

If we do a simple test with this adaptor and compare it with the Rust and Python implementations, we see that for simple input sequences we get the correct result! (See the examples on compiler explorer)

Language	Output
C++	`[[0, 1, 2], [0, 2, 1], [1, 0, 2], [1, 2, 0],` `[2, 0, 1], [2, 1, 0]]`
Python	`[(0, 1, 2), (0, 2, 1), (1, 0, 2), (1, 2, 0),` `(2, 0, 1), (2, 1, 0)]`
Rust	`[[0, 1, 2], [0, 2, 1], [1, 0, 2], [1, 2, 0],` `[2, 0, 1], [2, 1, 0]]`

The number of possible permutations can be caculated using the following formula:

$$ P(n,r) = \frac{n!}{(n - r)!} $$

If we calculate that for an input of size three (e.g. size of [0, 1, 2]) and a sub-sequence size of three as well, we calculate that the number of permutations should be six.

$$ P(3,3) = \frac{3!}{0!} = 6 $$

This just verifies the output is the correct length.

Let's add another test though really quick, we'll do the input sequence [2,1,0].

Language	Output
C++	`[[2, 1, 0]]`
Python	`[(2, 1, 0), (2, 0, 1), (1, 2, 0), (1, 0, 2)` `(0, 2, 1), (0, 1, 2)]`
Rust	`[[2, 1, 0], [2, 0, 1], [1, 2, 0], [1, 0, 2]` `[0, 2, 1], [0, 1, 2]]`

Well, that's clearly not correct. If we step through the code using lldb (or any other debugger) the issue becomes apparent: std::next_permutation returns false on the first call to it, so the adaptor only returns the very first sub-sequence in the result, which is not what we expected. Let's return back to the documentation.

Permutes the range [first, last) into the next permutation. Returns true if such a “next permutation” exists; otherwise transforms the range into the lexicographically first permutation (as if by std::sort) and returns false.
cppreference/next_permutation

This function does the permutation in-place on the input sequence, using the ordering of the values of the sequence itself. Since the input sequence is sorted in reverse order ([2, 1, 0]) then the next lexicographical permutation of the sequence should be [0, 1, 2] (the sequence in sorted order). Clearly, we can see that the Python and Rust sequences don't return this as the next value. The second value of both of other implementations is [2, 0, 1], which isn't the next lexicographical permutation of the input sequence. So what is going on here?

I pulled up the source for both the Python and the Rust implementations, and I found that both implementations don't actually permute the input based off the input values, but rather they permute the input based off the indices of the input. Here's an example:

Input:
  [2, 1, 0]

Permutations based off value:
  [[2, 0, 1], [0, 1, 2], [0, 2, 1], [1, 0, 2], ...]

Permutations based off index:
  Values:  [[2, 1, 0], [2, 0, 1], [1, 2, 0], ...]
  Indices: [[0, 1, 2], [0, 2, 1], [1, 0, 2], ...]

Based on this information, we can change our adaptor in a few ways. First, we need to keep track of all of the permuted indices of the input sequence. Secondly, we need a way to reindex the cached input sequence by the permuted indices. Let's write the reindex function first.

using std::vector;

template<typename T>
auto reindex_sequence(const vector<T> &input,
                      const vector<size_t> &indices
                      ) -> vector<T>
{
    vector<T> output;

    for (const auto &index : indices) {
        output.push_back(input[index]);
    }

    return output;
}

Great! Now that we have a function that can take in the vectors of indices and inputs and return a vector with the input values ordered by the indices vector. Let's add indices into our adaptor now.

auto permutations_adaptor = []<flux::sequence Seq>(Seq seq)
    -> flux::generator<std::vector<flux::value_t<Seq>>>
{
    std::vector<flux::value_t<Seq>> cache;
    for (auto &&elem : seq) { cache.emplace_back(elem); }

    std::vector<size_t> indices(cache.size());
    std::iota(indices.begin(), indices.end(), 0);

    co_yield cache; // first subsequence

    while (std::next_permutation(indices.begin(), indices.end())) {
        // following subsequences
        co_yield reindex_sequence(cache, indices); 
    }
};

Great! Our output now matches our reference implementations in Python and Rust.

Language	Output
C++	`[[2, 1, 0], [2, 0, 1], [1, 2, 0], [1, 0, 2]` `[0, 2, 1], [0, 1, 2]]`
Python	`[(2, 1, 0), (2, 0, 1), (1, 2, 0), (1, 0, 2)` `(0, 2, 1), (0, 1, 2)]`
Rust	`[[2, 1, 0], [2, 0, 1], [1, 2, 0], [1, 0, 2]` `[0, 2, 1], [0, 1, 2]]`

With that complete, our simple permutations adaptor is now complete! To follow the process of adding this adaptor into the official Flux library read the follow up articles to this one.

Thanks for reading!

Complete Adaptor

// Made with Flux 0.4.0 and C++20

#include <algorithm>
#include <iostream>
#include <numeric>

#include <flux.hpp>

// Return a vector containing a permutation of the 
// input values in the order of the indices given in 
// the indices vector
template<typename T>
auto reindex_sequence(const std::vector<T> &input,
                      const std::vector<size_t> &indices
                      ) -> std::vector<T>
{
    std::vector<T> output;

    for (const auto &index : indices) {
        output.push_back(input[index]);
    }

    return output;
}

// Generates all permutations of a given input sequence
auto permutations_adaptor = []<flux::sequence Seq>(Seq seq)
    -> flux::generator<std::vector<flux::value_t<Seq>>>
{
    // cache the input
    std::vector<flux::value_t<Seq>> cache;
    for (auto &&elem : seq) { cache.emplace_back(elem); }

    // generate the indices vector from [0, n) where 
    // n is the size of the input sequence 
    std::vector<size_t> indices(cache.size());
    std::iota(indices.begin(), indices.end(), 0);

    co_yield cache; // first subsequence

    // permute the indices, and return the input reindexed by 
    // the indices
    while (std::next_permutation(indices.begin(), indices.end())) {
        // following subsequences
        co_yield reindex_sequence<flux::value_t<Seq>>(cache, indices); 
    }
};

How to Write a Flux Adaptor Using Coroutines

2024-12-30T00:00:00.000Z

Todo:

[ ] Fix date when finished.

$$ T_{over} = p \sum{x} $$

Target Audience

Professional C++ programmers and students/researchers who are familiar with C++.

Goal

Provide a resource that details how to write a quick adaptor using coroutines in Flux.
Provide working examples version locked on compiler explorer.

Outline

Quick intro to flux
- Example of sequence oriented programming
- Links to some talks and source
Basics of coyield
- Explain how cpp implements coroutines, and what it actually means to use a coroutine
Very basics of writing an adaptor
- We need a resumable function that yields elements in the sequence and returns when complete.
Writing a simple adaptor using coyield
- Replicate the adaptor made by tcbrindle in his tutorial file
Writing a more complex adaptor using coyield
- Write a permutations adaptor using coyield
Optional. Performance and usage tradeoffs

WaddoupsNet - A TCP/IP Stack on Linux

2024-10-23T00:00:00.000Z

In ECE 5600 I created a TCP/IP stack for a lab that we worked on throughout the semester. This is a document of what I did and how I did it. It's also a good change to learn jekyll better. One other note, I started these labs before I started making notes here, so it's definitely going to feel disjoint until I have time to clean this post up after the semester.

Lab 3 - Adding IP v4 and ICMP

Having added the ability to unwrap ether frames and handle ARP requests / replies, we are now ready to sprinkle some IP v4 all over our project with a dash of ICMP on top.

Here's how our stack is going to look after we are done.

Code wise in our stack application we hopefully will be able to end up with something similar to this for our IP and ICMP handler:

auto ipv4_handler(
    channel<ether_frame> ether_frames,
    channel<ipv4_packet> ipv4_packets) -> void;

auto icmp_handler(channel<ipv4_packet> ipv4_packets) -> void;

Adding the IP v4 Packet `Struct`

In line with what we have done previously in creating a struct to represent ether frames we'll do the same for IP v4 packets. For reference, the current description of an IP v4 packet is given in RFC 791, but I just used the wikipedia page as my reference. It gets tiresome to continually refer to the packet as an "IP v4" packet so from now on we'll assume that anytime called IP is just referring to IP v4, unless otherwise stated.

struct ipv4_packet
{
    constexpr static octet version{ 0x4U };
    octet ihl{};

    octet dscp{};
    octet ecn{};

    uint16_t total_length{};
    uint16_t identification{};

    octet flags{};
    uint16_t fragment_offset{};

    octet time_to_live{};
    octet protocol{};
    uint16_t checksum{};

    ip_v4_address source;
    ip_v4_address dest;

    std::vector<octet> options;
    std::vector<octet> data;

    constexpr ipv4_packet() = default;
    constexpr explicit ipv4_packet(const raw_packet rpacket)
    {
        from_raw(rpacket);
    }

    constexpr auto from_raw(const raw_packet rpacket) -> void;
    [[nodiscard]] constexpr auto to_raw() const -> std::vector<octet>;
};

One of the challenges with going from and ether frame into an IP packet is that a single packet may be spread across several frames. We can see that the total_length of a packet is determined by a 16-bit unsigned integer, which means that an IP packet can be about 65000 bytes long! Our ether frames are only limited to about 1500 bytes, so we will have to handle the case where a single IP packet is scattered across many frames when we build up a packet.

Finding all n-sized subgraphs in a given graph

2024-08-13T00:00:00.000Z

A few weeks ago a co-worker approached with me with an interesting problem he was dealing with. How could one find all n-sized subtrees in any given undirected graph?

We were driving at the time, and so we talked and hand-waved our way through how we thought we could implement an algorithm that finds all the subtrees of size n.

Originally, this problem was solved in MATLAB, but since MATLAB is not free and not commonly used outside of engineering companies, I reimplemented a solution in Python and then a solution in C++ using the Boost Graph Library (coming soon... eventually...).

A Motivating Demonstration

{: width="50%" }

Say we want to find all the subtrees with only two vertices in the graph shown here. How would we go about doing it by hand? I would start by choosing a random vertex, and then I would make a list of all the neighboring vertices. When combined with the original vertex as a pair, I now have all subgraphs of size two that include our initial vertex.

Initial vertex = 4
Neighbors of V[4] = 7, 0

Subgraphs of size 2 = [
    [4, 7],
    [4, 0],
]

After I make a list of pairs for the chosen vetex, I would move on to another vertex and make a list of the pairs following the same steps, then I would concatenate that list onto some global list of all of the subgraphs of size 2. After doing this process for each vertex, there will be many duplicate subgraphs in the global list, so I'll need to filter out duplicates, and then I will finally have the list of all subgraphs of size 2 of the given graph.

This process is not too hard to do by hand, but it is time consuming, even for this To do this process repeatedly on larger graphs we need to automate it in some way.

Automating the Process

Please note that code in this section does not actually run due to the way python lists work, but is used to show my thought process in discovering the initial algorithm

When I don't know exactly how an algorithm or a process is going to look before I write it out, I like to start with what I do know. For this problem, I know that I'll probably need to start by iterating over each of the vertices in the original graph, as that is essentially how I started when doing this problem by hand. Each vertex in the original graph may be part of a n-sized subgraph, so we need to consider each one. That means that from the get-go, we are looking at a minimum of O(V) complexity, where V is the number of vertices in the starting graph.

g = Graph()

for vertex in g.vertices:
    ...

Next if we consider our hand algorithm, we can see that from each vertex we need to get a list of all the neighbors of the vertex. We do this to consider what the "next vertex" in our subgraph may be.

g = Graph()

for vertex in g.vertices:
    next_vertices = g.neighbors(vertex)

    ...

For our previous example of finding all subgraphs of size two, this is essentially all we need to do! We just need to find the neighbors of each nodes in the graph, enumerate all the unique pairs, and call it a day. A python implementation of this simple case might look something like this.

g = Graph()

subgraphs = []

for vertex in g.vertices:
    next_vertices = g.neighbors(vertex)

    pairs = [(vertex, v2) for v2 in next_vertices]

    subgraphs.append(pairs)

unique_subgraphs = set(subgraphs)

This approach works great for when n = 2, but has no way to track the size of the current subgraph we are looking at which is needed for n to be genericized. That way we can tell when we have created a subgraph of size n, and we can return the subgraph once we have reached the desired size. We actually do this in our previous implementation, but it is not clear unless we rewrite the solution to include comments that track n.

g = Graph()

subgraphs = []

for vertex in g.vertices:
    n = 0
    next_vertices = g.neighbors(vertex)

    current_subgraph = [vertex]
    n = len(current_subgraph) # n = 1

    for v2 in next_vertices:
        current_subgraph = current_subgraph + [v2]
        n = len(current_subgraph) # n = 2
       
        if n == 2:
            subgraphs.append(updated_current_subgraph)

Now it's clear that we actually are building up subgraphs until we reach the desired size (in this case 2) and then stopping and moving on to the next subgraph. If we wanted to extend this to find subgraphs of size 3, it's as simple as adding one more step to get to n = 3.

...
for vertex in g.vertices:
    current_subgraph = [vertex]
    n = len(current_subgraph) # n = 1

    for v2 in g.neighbors(current_subgraph[-1]):
        current_subgraph = current_subgraph + [v2]
        n = len(current_subgraph) # n = 2
       
        for v3 in g.neighbors(current_subgraph[-1]):
            current_subgraph = current_subgraph + [v3]
            n = len(current_subgraph) # n = 3

            if n == 3:
                subgraphs.append(updated_current_subgraph)

To extend this further we just need to another for loop, and another for loop, etc. etc. If we take a step back, we can see that we are actually taking recursive steps here. The structure of the for loop for v2 and for v3 is the same, so we can actually just write a recursive function to do this work. Here are the operations for the k_th step in the sequence.

Iterate over all the neighbors of the last node in the current subgraph
Append each neighbor to the subgraph
If k == n, append the subgraph to the global list of subgraphs and end

Here's what this might look like in python.

for v_k in g.neighbors(current_subgraph[-1]):
    current_subgraph = current_subgraph + [v_k]
    n = len(current_subgraph) # n = k

Algorithm Developement

Given the four generic steps we determined above, we can now refactor our code into a recursive function to calculate all the subgraphs. We'll call this function all_n_subgraphs(). We'll also take this opportunity to plan out what types to use, and how we want our calling specification laid out.

Types

Python doesn't have a built-in graph type, and hand rolling a graph type is out of scope, so we'll use a prebuilt graph package to represent our graphs. I did some some research, and I decided that the igraph package for python would suit our needs just fine. igraph has a lot of functionality, but for this algorithm to run, we really only need two functions from the igraph library:

Graph.neighbors(v: vertex) -- returns the neighbors to a vertex in a graph.
Graph.vs -- returns the list of all vertices in the graph.

Inputs and Outputs

Let's consider what we want all_n_subgraphs() to do, and build a specification for this function. The graph G, and the desired size of the subtrees, n, will be inputs to all_n_subgraphs(). Our output will be a list of all the subgraphs, represented by lists of size n with the vertex indices (integers) of the subgraph.

import igraph as ig

def all_n_subgraphs(G: ig.Graph, n: int) -> list[list[int]]

Another important part of creating a specification for a function is defining the input and output conditions. Considering our inputs, we can make a few assertions that should be fulfilled for the function to work properly. First, we know that n should be greater than zero. While it's certainly possible to represent a subgraph of size zero as an empty list, [], it's not that useful. Secondly, we should state that n cannot be greater than the number of vertices V in the graph G. This is because a subgraph of G cannot have more vertices than G. These two assertions can be formalized in assert statements at the top of our function.

Beyond declaring the type of our output, there isn't really anything we can state about the output of all_n_subgraphs(), as the list could theoretically be any size greater than or equal to zero.

Specification

When we bring all the parts together, we get a nice specification for our function.

import igraph as ig

def all_n_subgraphs(G: ig.Graph, n: int) -> list[list[int]]:
    assert n > 0, f"Error in 'all_n_subgraphs': n must be greater than 0"
    assert len(G.vs) >= n,
        f"Error in 'all_n_subgraphs': n is greater than len(Graph.vs)"

Now, is doing input validation in this way very pythonic? Probably not, but it's good enough for me in this example! Now we need to add in the rest of the logic to complete this function.

import igraph as ig

def all_n_subgraphs(G: ig.Graph, n: int) -> list[list[int]]:
    assert n > 0, f"Error in 'all_n_subgraphs': n must be greater than 0"
    assert len(G.vs) >= n,
        f"Error in 'all_n_subgraphs': n is greater than len(Graph.vs)"

    subgraphs: list[list[int]] = []

    for vertex in g.vertices:
        next_vertices = g.neighbors(vertex)
        current_subgraph = [vertex]

        subgraphs = subgraphs + subtrees(G, n - 1,
            current_subgraph, next_vertices)

def difference(a: list, b: list) -> list:
        return list(set(a) - set(b))

def subtrees(G: ig.Graph,
             n: int,
             current_subgraph, 
             next_vertices) -> list[list[int]]:
    
    if n <= 0:
        return [current_subgraph]

    subgraphs: list[list[int]] = []

    for vertex in next_vertices:
        # concat instead of appending because we need a copy
        new_subgraph = current_subgraph + [vertex]

        new_next_vertices = next_vertices + g.neighbors(vertex)
        unique_next_steps = difference(new_next_vertices, new_subgraph)
        subgraphs = subgraphs + next_subtree(g, n - 1,
            new_subgraph, unique_next_steps, original_vertex)

Assume False

Recreating Recipes Using SMT

The Target Snack

Setting up an Example Problem

Now Onto... Recipes?

Recipes As a Formula

Representing the Recipe in Python

Final Bites

Additional Optimizations to the Recipe Generator

Impacts of Compiler Optimization on Cache Latency Profiling

What is "Now"?

The Psuedocode

Enter rdtsc

Timing Results and Optimizations

-O0

-O1

-O2

-O3

SPAC 2025

Basic Examples

Longer Examples

[](){}();

Why?

The Syntax

An Example

Other Tips and Tricks

The End

Flux Permutations Adaptor (1/4)

The Idea

Defining a Permutation

The Simplest Permutations Adaptor

Producing the First Sub-Sequence

Producing Following Sub-Sequences

Complete Adaptor

How to Write a Flux Adaptor Using Coroutines

Target Audience

Goal

Outline

WaddoupsNet - A TCP/IP Stack on Linux

Lab 3 - Adding IP v4 and ICMP

Adding the IP v4 Packet Struct

Finding all n-sized subgraphs in a given graph

A Motivating Demonstration

Automating the Process

Algorithm Developement

Types

Inputs and Outputs

Specification

Enter `rdtsc`

Adding the IP v4 Packet `Struct`