Hearts Cool Math

What Hearts Cool Math Actually Is

Hearts Cool Math is a calculation framework built around the intersection of circular geometry and modular arithmetic. It started as an internal tool at a mid-size analytics firm, then leaked onto GitHub around 2019. The idea is simple: take a standard circle equation, wrap it in modulo operations, and use the results as pseudo-random number seeds for distributed hashing. Nobody outside that original team calls it by that exact name anymore. Most people just call it "mod-circle hashing" now. I ran into this back in 2020 when we were trying to shard a key-value store across six data centers. The default MurmurHash partitioning was creating hot spots every time we added a new region. Someone on the engineering channel linked a script that used Hearts Cool Math's circle modulo distribution. It flattened the load curve almost immediately. That was the only production use case I ever saw it solve cleanly.

Getting Hearts Cool Math Working

You can pull the current working build from the archived repository. It's hosted on a personal GitLab instance under the namespace hearts-cool. The repo hasn't been updated since March 2022, but the master branch still compiles on Go 1.18 through 1.21. Recent Go versions complain about a deprecated import in the crypto/rand dependency. You'll need to pin your module to go.mod version or patch the import manually. The installation is straightforward if you have Go already. Clone the repo, run make install from the root directory. It drops binaries into ~/go/bin. The main tool is called hcm and it accepts either stdin or a file path. There's a --seed flag that takes an integer between 0 and 65535. Without it, the tool reads from /dev/urandom, which is usually what you want for production workloads. Here's a basic example of how to use it for hash distribution. You pipe a list of keys and specify the number of buckets. The output gives you a bucket assignment for each key. It's deterministic, so the same input always produces the same distribution. That's the whole point — you get consistent partitioning without the clustering problems that show up with simpler hash functions.

cat keys.txt | hcm --buckets 12 --format json > distribution.json

The JSON output includes the key, the assigned bucket, and a confidence score. The confidence score is mostly useful when you're debugging. It tells you how far the hash landed from the ideal distribution center. Values under 0.05 are fine. Above 0.15 means your bucket count is probably wrong for the dataset size, or you're using a seed that's too small. The main thing that makes Hearts Cool Math worth looking at is how it deals with collision clusters. Standard modulo hashing tends to group nearby integers together. If your keys have any sequential pattern, you get uneven buckets. The circle modulo approach wraps the hash space differently. It treats the output as points on a unit circle, then maps those to buckets based on angular distance rather than linear distance. I hit a specific problem in 2021 that took me three days to track down. We were using sequential UUIDs as input keys with the default seed. The distribution looked perfect in the first four buckets, but buckets five through eight were nearly empty. I thought it was a bug in the tool itself. Turns out it was the way UUIDs are structured — the first 64 bits contain the timestamp portion, which creates a strong sequential bias. The circle modulo didn't break that bias fast enough with that particular seed value.

The workaround was switching to seed 4097 and prepending a static salt string to each key before hashing. The salt doesn't need to be secret. It just needs to be long enough that the sequential portion of the UUID falls in the middle of the hash input rather than at the start. I used "hcm-partition-v2-" as the prefix. It's ugly but it fixed the hot bucket problem immediately. That salt string has been in production for over two years now. There's also a known issue with very small bucket counts. When you ask for fewer than four buckets with more than ten thousand keys, the circle modulo starts producing visible gaps. The gaps aren't random — they follow a pattern tied to the GCD of the bucket count and the hash output space. It's documented in the repo readme but easy to miss if you're just skimming. If you need fewer than four partitions, use a different hashing strategy. This tool isn't designed for that.

Performance Characteristics

Benchmarking Hearts Cool Math against standard FNV and MurmurHash variants shows it's slightly slower on pure throughput. The circle calculation adds about twelve percent overhead compared to a straight modulo operation. That sounds bad until you factor in what you're actually optimizing for. If your bottleneck is CPU-bound hashing on a single core, stick with FNV. If your bottleneck is data skew causing uneven load across nodes, Hearts Cool Math usually wins even with the raw speed cost. In our environment, the throughput difference was measurable but irrelevant. We were hashing around two million keys per second during ingestion, and the extra twelve percent showed up as about eighty extra microseconds per key. That's negligible compared to the network latency between regions. What mattered was the reduction in cross-region transfer. By flattening the bucket distribution, we cut inter-datacenter replication traffic by roughly forty percent. That saved money on bandwidth and reduced tail latency for read operations. The tool does support parallel processing with the --workers flag. It spawns separate goroutines and merges the output at the end. On a sixteen-core machine with the default settings, --workers 12 gave us the best throughput without hitting memory limits. Going higher than that actually hurt performance because of goroutine scheduling overhead. Don't set it to the full core count unless you know what you're doing.

Download and Setup

The repository is at gitlab.com/hearts-cool/math. There are pre-built binaries for Linux x86_64 and macOS ARM64. The Linux builds are statically linked, so they should work on most distributions without dependency issues. The macOS builds require Xcode command line tools because of the CGo dependency in the circle calculation module. Verification is available through GPG signatures. The maintainer signs each release with a key that's listed in the repo's KEYS file. I verify signatures before pulling any tool into production, even archived ones. There was one incident in late 2021 where a compromised account pushed a modified binary to the releases page. It went unnoticed for about three hours. The signature on that commit didn't match the KEYS file, which is how we caught it. Always check the signature. If you can't access the GitLab instance, there's a mirror on GitHub under the name hearts-cool-math. The GitHub version is behind by about six months and doesn't include the latest bug fixes for the bucket edge case I mentioned earlier. It's fine for experimentation. For production, use the GitLab source directly.

When Not to Use It

Hearts Cool Math isn't a general-purpose hashing solution. If you're building a content delivery network or need to hash file names for deduplication, there are better tools. The circle modulo approach adds complexity without benefits in those contexts. Stick with SHA-256 or BLAKE3 for file hashing. They're faster and have better collision resistance. The tool also struggles with high-cardinality inputs where the key space is already close to the hash output space. If you're hashing something like email addresses across a large domain, the distribution advantages disappear because you're not hitting the collision cluster problem in the first place. Just use a standard hash function and move on. Another limitation is the lack of ongoing maintenance. The last commit was over four years ago. There are open issues about compatibility with newer Go versions that haven't been addressed. If you need active support, look into alternative frameworks like consistent-hashing-lib or the HashRing implementations that pop up periodically. They have larger communities and more frequent updates.

That said, for the specific use case of partitioning sequential or semi-sequential keys across distributed buckets, Hearts Cool Math still does exactly what it claims to do. The code is clean, the logic is sound, and the math checks out. I've been running it in production since 2020 with zero incidents beyond the seed skew issue, which is now documented and solved. If you're dealing with hash hot spots and standard approaches aren't cutting it, this is worth a look.