A conversation with a friend sent me into my second quaternion rabbit hole.
The conversation turned to the rather ambitious notion of solving space navigation. Not one tidy algorithm, but the larger problem of understanding where a spacecraft is, how it is oriented, where it needs to go and how its motion should be controlled. Quaternions kept appearing because they are fundamental to representing attitude and reasoning about rotation.
I have not solved space navigation. Quatopsy does not pretend that I have. It deliberately does not perform orbit determination, qualify flight hardware or approve commands. What came out of that conversation was something narrower and, I think, genuinely useful: a tool for engineers who work with spatial motion and need to understand why a quaternion trajectory has gone wrong.
That tool became Quatopsy, a local-first system for inspecting and diagnosing anomalies in quaternion attitude data.
It was not my first encounter with the mathematics. My journey began with Quaternion-Augmented TurboQuant, a speculative attempt to combine quaternion structure with Google’s TurboQuant approach to KV-cache compression. That question eventually became QATQ, an exact tensor-aware codec for exported KV caches and migration artefacts.
I did not set out to build a small family of quaternion projects. I kept following the maths. It has been a demanding journey, occasionally humbling, and far more interesting than I expected. I have gone from wondering whether four-dimensional algebra could help compress an AI model’s working state to thinking about spacecraft attitude histories, antipodal representations, controller unwinding and what trustworthy diagnostic evidence should look like.
The thread connecting those projects is not that quaternions are a magic ingredient. It is almost the opposite. The more I worked with them, the more I learned that elegant mathematics still has to earn its place in an engineering system.
The first question was about memory
The original Quaternion-Augmented TurboQuant idea came from a practical frustration. I do most of my local AI experimentation on a 24GB Apple Silicon Mac, and long-context inference makes memory limits difficult to ignore. Model weights are only part of the story. The key-value cache grows with the context, quietly consuming the memory that looked comfortable when the model first loaded.
Google’s TurboQuant research suggested a striking direction: rotate and quantise that cache efficiently enough to reduce its footprint without retraining the model. I began wondering whether quaternion structure could expose useful four-component relationships before or during that process.
It was an exciting proposal. It was also speculative.
When the idea became software, the claims had to become more disciplined. QATQ did not simply turn the whole proposal into a product and declare victory. It first became an exact codec for exported tensor bytes. Its contract is concrete: compress the data, transfer or store it, restore it bit-for-bit, and reject corrupt or truncated payloads.
The reversible quaternion-chain transform is one candidate inside that codec. It competes with simpler byte-plane, XOR and zstd-backed strategies. If it does not produce the best result for a payload, QATQ does not select it.
That decision taught me something I would carry into Quatopsy: if the mathematics appears in the name, it still has to justify its operational cost.
Then the rotations became the problem
QATQ uses quaternion-inspired structure as part of a codec. Quatopsy looks at the place where quaternions are already the native language: three-dimensional rotation.
Quaternions are a compact and robust way to represent orientation. They avoid the singularities associated with Euler angles and work well for interpolation, estimation and control. They also contain a property that is mathematically harmless but operationally awkward: a quaternion and its negative represent the same physical orientation.
That double cover is the beginning of several problems.
A recorded sequence can flip sign while the physical attitude remains unchanged. A component plot then appears to jump even though the body did not. If software differentiates that raw sequence without respecting the equivalence, the derived rate can be wildly wrong. Interpolation can take the long path around. A perfectly valid rotation near 180 degrees can become numerically ambiguous. A convention mismatch can produce plausible-looking numbers that describe the wrong attitude altogether.
None of these failures is improved by staring harder at four separate w, x, y and z traces.
The question behind Quatopsy became: could I make the geometry, provenance and uncertainty visible at the same time?
A linter for attitude trajectories
The simplest description of Quatopsy is a quaternion trajectory linter with a forensic viewer.
It accepts recorded orientation data, applies a closed set of deterministic checks and produces a canonical report. The current rules cover problems such as off-unit and zero quaternions, non-monotonic time, discontinuous lifts, suspicious sign changes, angular-rate inconsistencies, near-pi ambiguity, convention disagreement and commanded-path unwinding.
Every finding points back to source rows and timestamps. The original trajectory is read-only. If Quatopsy can propose a normalisation or sign-lift repair, that proposal is written separately and bound to the input it came from.
That separation sounds fussy until an investigation goes wrong. Once observed data and corrected data have been mixed together, it becomes surprisingly hard to explain which facts came from the system and which came from the analyst.
Quatopsy therefore treats refusal as a valid result. A malformed input, unsupported convention, resource-limit breach or incomplete parse cannot quietly become a passing report. A diagnostic tool should be useful when the data is awkward, not only when the demo is clean.
Seeing the same event in two spaces
The viewer became the part of the project that made the problem feel tangible.
Quatopsy generates a local, static investigation console with synchronised views of the physical orientation path in SO(3), a projected view of its lift on the quaternion unit sphere, a quotient-angle timeline and the underlying evidence. Selecting a finding in one view follows the same retained sample through the others.
This is not a quaternion teaching laboratory, and the browser is not allowed to invent a second set of diagnostic rules. It presents the canonical report produced by the Rust analysis kernel. Projection artefacts are labelled. Raw observations, derived values and proposed repairs use distinct visual states.
The distinction between physical orientation and quaternion representation is much easier to grasp when both paths move together. A sign discontinuity can look dramatic in quaternion space while the physical attitude remains smooth. A long-way commanded path tells a different story. The visualiser lets those differences become something an engineer can inspect rather than a paragraph they have to keep in working memory.
An incident is more than one CSV file
Real investigations rarely arrive as a neat trajectory and nothing else.
There may be event logs, command histories, operator notes, adapter-specific telemetry and several candidate explanations. Some of those files are evidence. Some are context. A command-history line may show that a command was sent from the ground, but it does not prove that the spacecraft received or executed it.
The quatopsy investigate workflow packages those distinctions into a bounded local evidence directory. It snapshots the source, preserves supplied context without allowing that context to alter the diagnostic verdict, creates the report and viewer, and writes a digest manifest over the resulting artefacts. A separate verification command detects later mutation.
The bundle is not an authenticated chain of custody, and it does not magically make sensitive telemetry safe to share. It is a reproducible handover format for deterministic local processing. That narrower promise is still valuable: another engineer can verify that the files have not changed and trace each result back to the captured source.
The controller question could not be ignored
Once a tool can explain a bad trajectory, the obvious question is whether it can produce a better one.
Quatopsy now includes bounded planning and software control candidates. It can generate torque-limited rest-to-rest trajectories, run a geometric attitude controller in software, evaluate estimator and guidance profiles, allocate reaction-wheel commands and exercise declared software plant models. Those generated trajectories are then passed back through the same diagnostic kernel.
This is where language matters.
A feasible candidate is not an optimal trajectory. A successful software-in-the-loop run is not permission to command hardware. Host-CPU processor-in-the-loop and a loopback actuator emulator are useful engineering evidence, but they are not flight-processor qualification or physical hardware-in-the-loop. Quatopsy does not open an actuator device, perform orbit determination, meet a hard real-time contract or produce certification evidence.
The planner and controller extend the investigation, but they do not own the verdict. They produce separately named candidates. The diagnostic kernel analyses them. The human still decides what the evidence means.
I prefer that boundary to a more impressive-sounding claim that the project has not earned.
Local-first was not merely a deployment choice
Attitude telemetry and incident context can be sensitive. They can also be large, awkward and governed by rules that make uploading them to an online service inappropriate.
Quatopsy runs locally, requires no account and collects no telemetry. Its viewer is a dependency-free static bundle rather than a hosted application. The analysis path has explicit input, sample, memory and time limits. A million-sample synthetic trajectory is part of the documented performance gate, although that benchmark is not a substitute for validation on every mission profile.
Keeping the project local also simplifies the trust story. There is no remote verdict service, database or background upload to explain. The bytes are snapshotted and hashed before parsing, outputs are committed without silently clobbering existing files, and the same report can be handed to the static viewer without moving the evidence elsewhere.
Local-first is therefore part privacy decision, part reproducibility decision and part refusal to build infrastructure the problem does not need.
What the rabbit hole actually taught me
Before these projects, I mostly thought of quaternions as a clever solution to a familiar rotation problem. That description is true, but incomplete.
Working on QATQ exposed me to quaternions as algebraic structure inside a data transform. Building Quatopsy exposed the representational choices, numerical edge cases and engineering consequences hiding behind an apparently clean orientation format. The same mathematics can be useful in compression, graphics, robotics, navigation, estimation and control, but usefulness does not transfer automatically from one domain to another.
There is also a broader lesson here about research software.
The interesting idea gets a project started. The boundaries make it trustworthy. For QATQ, that meant moving from an ambitious lossy-compression proposal to an exact codec whose quaternion strategy is selected only when it wins. For Quatopsy, it meant keeping observations immutable, separating candidates from verdicts and saying plainly that advisory software is not flight approval.
Those qualifications do not diminish either project. They are the work.
Where Quatopsy goes next
Quatopsy is now public as early-stage, production-quality research software for local advisory evaluation. The Rust workspace, CLI, viewer, evidence workflow, planning and software-control paths are open for inspection. The project is available through Cargo, and its local and hosted quality gates exercise the same authoritative checks.
What it needs next is use by people who have encountered the real failure modes: spacecraft GN&C engineers, roboticists, simulation teams and anyone who has lost an afternoon to an orientation trace that looked reasonable until it did not.
Independent reproduction, practitioner feedback and more representative incident workflows will teach the project more than another layer of speculative capability. I am especially interested in cases where Quatopsy refuses too early, reports something technically correct but operationally unhelpful, or misses the clue an experienced engineer reaches for first.
I still do not know where the quaternion rabbit hole ends. QATQ and Quatopsy have already taken it in directions I would not have predicted when I first started thinking about a constrained laptop and an oversized KV cache.
That unpredictability has been the rewarding part.
I have not solved space navigation. But the conversation that raised that impossible-sounding challenge led to a practical tool, and I think engineers working with spatial motion may find it useful. That feels like a worthwhile result from following the question.
You can explore Quatopsy at kabudu.github.io/quatopsy, inspect the source on GitHub, or install it with cargo install quatopsy. QATQ and the earlier part of the journey remain at qatq.org.