Andrew's Software

My open source software is packaged and deployed from a central repository: anixpkgs. See the navigation menu for individual package documentation.

Return to main site

LATEST RELEASE: v6.6.0

Repository

This repository of personally maintained Nix derivations, overlays, and machine closures is essentially the centralized mechanism by which I maintain all of the software I write and use for both personal projects and recreation. In other words, I employ Nix as both a package manager for my software as well as an operating system for all of my computers, Raspberry Pi’s, etc.

These docs provide an overview of how I manage the OS’s of my machines as well as the software that I personally maintain, all within the anixpkgs repo.

Why Nix?

Some of the main reasons why I prefer Nix as a package manager:

I highly value code that is not only compelling in its application but that is also maintainable. Code that is subject to compiler/interpreter and external dependency changes over time must be designed with the future in mind. Nix provides me an almost trivial mechanism to incrementally update (and roll back) external dependencies, compilers, or anything else pertaining to a software ecosystem that you can think of.
When I write a cool piece of software on one machine, I want to be able to “deploy” that software across all my machines with minimal effort and without having to worry about broken or missing dependencies. With its hermetic build system, I have the peace of mind that the code that I package in Nix will be transferable to essentially any other machine that uses Nix.

Some of the main reasons why I prefer NixOS as an operating system for all of my computers:

The same things I value in packaging software, I also value in “packaging an operating system.” NixOS allows me to have total control over every single package in my OS, allowing me to customize every aspect and make changes with the peace of mind that I can always roll back breaking changes.
There is something very satisfying and empowering to me about being able to declaratively define the OS closures for all of my machines in just several text files. The overlay-focused design of NixOS modules makes it so that I can design the OS’s of my machines hierarchically, defining packages that are shared between all of my computers as well as packages that are specific to certain computers only. Moreover, when I buy a replacement computer it takes a minimal amount of steps to turn that new computer into an all-intents-and-purposes clone of my old one, which is a capability I value very highly for a lot of reasons.

Given the above, why do I prefer Nix over Docker?

To be clear, I do think that Nix and Docker can be used together effectively. However:
In general, one will require a mishmash of custom or third-party build and deployment tooling to construct and glue a bunch of Docker containers together if one is trying to architect a complete system using Docker (as could be the case with code running on a robot). Nix provides more of a unified framework to achieve the same benefits, and that ecosystem is much more aesthetically pleasing to me than e.g., "YAML engineering."
Docker containers sit atop an already existing, fully fleshed out operating system. Nix allows me to (once agin, within a unified framework) control literally everything about even the operating system in an attempt to avoid unintended side effects at all levels of integration.

Installation and Usage Patterns

The packages defined in this repo are accessible to anyone who uses Nix, which can be installed in two forms:

“Standalone” Nix: This will just install the package manager and is the easiest option if you just want access to the packages in this repo. This option could be augmented with a tool called home-manager to at least be able to use some of the closure components alongside your normal OS as well.
NixOS: This option is much more invasive as it wholesale replaces your entire operating system, and should only be done if you really know what you’re doing (and love Nix). More instructions in the machines documentation.

For either method, ensure that your Nix version is >= 2.4.

The software packaged in anixpkgs is buildable both through Nix flakes as well as through traditional Nix shells. It’s recommended to use flakes, as that method is more "pure" and allows for more portable integration with the public cache.

Accessing the Packages Using Flakes

Here is a flake.nix file that will get you a shell with select anixpkgs software (version v6.6.0) while also giving you access to the public cache to avoid building from source on your machine:

{
  description = "Nix shell for anixpkgs.";
  nixConfig.substituters = [
    "https://cache.nixos.org/"
    "https://github-public.cachix.org"
  ];
  nixConfig.trusted-public-keys = [
    "cache.nixos.org-1:6NCHdD59X431o0gWypbMrAURkbJ16ZPMQFGspcDShjY="
    "github-public.cachix.org-1:xofQDaQZRkCqt+4FMyXS5D6RNenGcWwnpAXRXJ2Y5kc="
  ];
  inputs = {
    nixpkgs.url = "github:goromal/anixpkgs?ref=refs/tags/v6.6.0";
  };
  outputs = { self, nixpkgs }:
    let pkgs = nixpkgs.legacyPackages.x86_64-linux;
    in with pkgs; {
      devShell.x86_64-linux = mkShell {
        buildInputs = [
          pb
          fixfname
          pkgshell
        ];
      };
    };
}

Access the packages with nix develop.

Accessing the Packages Using shell.nix

Here are some shell.nix files to access Python packages (using version v6.6.0 of the packages):

let
  pkgs = import (builtins.fetchTarball
    "https://github.com/goromal/anixpkgs/archive/refs/tags/v6.6.0.tar.gz") {};
  python-with-my-packages = pkgs.python311.withPackages (p: with p; [
    numpy
    matplotlib
    geometry
    pyceres
  ]);
in
python-with-my-packages.env

or:

let
  pkgs = import (builtins.fetchTarball
    "https://github.com/goromal/anixpkgs/archive/refs/tags/v6.6.0.tar.gz") {};
in pkgs.mkShell {
  buildInputs = [
    pkgs.python311
    pkgs.python311.pkgs.numpy
    pkgs.python311.pkgs.geometry
    pkgs.python311.pkgs.find_rotational_conventions
  ];
  shellHook = ''
    # Tells pip to put packages into $PIP_PREFIX instead of the usual locations.
    # See https://pip.pypa.io/en/stable/user_guide/#environment-variables.
    export PIP_PREFIX=$(pwd)/_build/pip_packages
    export PYTHONPATH="$PIP_PREFIX/${pkgs.python311.sitePackages}:$PYTHONPATH"
    export PATH="$PIP_PREFIX/bin:$PATH"
    unset SOURCE_DATE_EPOCH
  '';
}

And for general software packages:

let
  pkgs = import (builtins.fetchTarball
    "https://github.com/goromal/anixpkgs/archive/refs/tags/v6.6.0.tar.gz") {};
in with pkgs; mkShell {
  buildInputs = [
    pb
    fixfname
    pkgshell
  ];
}

Access the packages with nix-shell.

Machine Management

These notes are still a work-in-progress and are currently largely for my personal use only.

Home-Manager Example

Install Nix standalone:

curl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix | sh -s -- install

Set proper Nix settings in /etc/nix/nix.conf:

substituters = https://cache.nixos.org/ https://github-public.cachix.org
trusted-public-keys = cache.nixos.org-1:6NCHdD59X431o0gWypbMrAURkbJ16ZPMQFGspcDShjY= github-public.cachix.org-1:xofQDaQZRkCqt+4FMyXS5D6RNenGcWwnpAXRXJ2Y5kc=
narinfo-cache-positive-ttl = 0
narinfo-cache-negative-ttl = 0
experimental-features = nix-command flakes auto-allocate-uids

Add these Nix channels via nix-channel --add URL NAME:

$ nix-channel --list
home-manager https://github.com/nix-community/home-manager/archive/release-24.05.tar.gz
nixpkgs https://nixos.org/channels/nixos-24.05

Install home-manager: https://nix-community.github.io/home-manager/index.xhtml#sec-install-standalone

Example home.nix file for personal use:

{ config, pkgs, lib, ... }:
let
  user = "andrew";
  homedir = "/home/${user}";
  anixsrc = ./path/to/sources/anixpkgs/.;
in with import ../dependencies.nix { inherit config; }; {
  home.username = user;
  home.homeDirectory = homedir;
  programs.home-manager.enable = true;

  imports = [
    "${anixsrc}/pkgs/nixos/components/opts.nix"
    "${anixsrc}/pkgs/nixos/components/base-pkgs.nix"
    "${anixsrc}/pkgs/nixos/components/base-dev-pkgs.nix"
    "${anixsrc}/pkgs/nixos/components/x86-rec-pkgs.nix"
    "${anixsrc}/pkgs/nixos/components/x86-graphical-pkgs.nix"
    "${anixsrc}/pkgs/nixos/components/x86-graphical-dev-pkgs.nix"
    "${anixsrc}/pkgs/nixos/components/x86-graphical-rec-pkgs.nix"
  ];

  mods.opts.standalone = true;
  mods.opts.homeDir = homedir;
  mods.opts.homeState = "23.05";
  mods.opts.browserExec = "google-chrome-stable";
}

*-rec-* packages can be removed for non-recreational use.

Symlink to ~/.config/home-manager/home.nix.

Corresponding ~/.bashrc:

export NIX_PATH=$HOME/.nix-defexpr/channels:/nix/var/nix/profiles/per-user/root/channels${NIX_PATH:+:$NIX_PATH}
. "$HOME/.nix-profile/etc/profile.d/hm-session-vars.sh"
export NIXPKGS_ALLOW_UNFREE=1
# alias code='codium'
# eval "$(direnv hook bash)"

Build and Deploy a Raspberry Pi NixOS SD Configuration

Since the hardware configuration for the Raspberry Pi is well understood, it makes sense to skip the installer step and deploy a fully-fledged clusure instead.

nixos-generate -f sd-aarch64 --system aarch64-linux -c /path/to/anixpkgs/pkgs/nixos/configurations/config.nix [-I nixpkgs=/path/to/alternative/nixpkgs]

nix-shell -p zstd --run "unzstd -d /nix/store/path/to/image.img.zst"

sudo dd if=/path/to/image.img of=/dev/sdX bs=4096 conv=fsync status=progress

On the Pi, connect to the internet, copy over SSH keys (maybe no need for /root/.ssh/) and then set up the Nix channel(s):

sudo nix-channel --add https://nixos.org/channels/nixos-[NIXOS-VERSION] nixos
sudo nix-channel --update

Note that the nixos-generate step may not have "aarch-ified" the anixpkgs packages (that's something for me to look into) so the anix-upgrade setup steps are especially important:

Make a ~/sources directory
Symlink the configuration file even if it doesn't exist yet
Run anix-upgrade to aarch-ify everything

Build a Raspberry Pi NixOS SD Installer Image

nixos-generate -f sd-aarch64-installer --system aarch64-linux -c /path/to/rpi/config.nix [-I nixpkgs=/path/to/alternative/nixpkgs]

nix-shell -p zstd --run "unzstd -d /nix/store/path/to/image.img.zst"

sudo dd if=/path/to/image.img of=/dev/sdX bs=4096 conv=fsync status=progress

On the Pi, copy over SSH keys (including to /root/.ssh/!) and then set up the Nix channel:

sudo nix-channel --add https://nixos.org/channels/nixos-[NIXOS-VERSION] nixos
sudo nix-channel --update

Installation Instructions on a New Machine

Sources

https://nixos.wiki/wiki/NixOS_Installation_Guide
https://alexherbo2.github.io/wiki/nixos/install-guide/

Note: You can replace steps 1-8 with a kexec kernel load and disk formatting with disko:

Download a NixOS ISO image.
Plug in a USB stick large enough to accommodate the image.
Find the right device with lsblk or fdisk -l. Replace /dev/sdX with the proper device (do not use /dev/sdX1 or partitions of the disk; use the whole disk /dev/sdX).
Burn ISO to USB stick with

cp nixos-xxx.iso /dev/sdX
# OR
dd if=nixos.iso of=/dev/sdX bs=4M status=progress conv=fdatasync

On the new machine, one-time boot UEFI into the USB stick on the computer (will need to disable Secure Boot from BIOS first)
Wipe the file system:

wipefs [--all -a] /dev/sda

gparted
1. Create a GUID table: Device > Create Partition Table > GPT
  1. Select /dev/sda
  2. Entire disk
2. Create the boot partition: Partition > New
  1. Free space preceding (MiB): 1
  2. New size (MiB): 512
  3. Free space following (MiB): Rest
  4. Align to: MiB
  5. Create as: Primary Partition
  6. Partition name: EFI
  7. File system: fat32
  8. Label: EFI
3. Add the boot flag
  1. Right-click on /dev/sda1 to manage flags
  2. Add the boot flag and enable esp (should be automatic with GPT)
4. Create the root partition: Partition > New
  1. Free space preceding (MiB): 0
  2. New size (MiB): Rest
  3. Free space following (MiB): 0
  4. Align to: MiB
  5. Create as: Primary Partition
  6. Partition name: NixOS
  7. File system: ext4
  8. Label: NixOS
5. Apply modifications
Mount root and boot partitions:

mkdir /mnt/nixos
mount /dev/disk/by-label/NixOS /mnt/nixos
mkdir /mnt/nixos/boot
mount /dev/disk/by-label/EFI /mnt/nixos/boot

Generate an initial configuration (you'll want it to enable WiFi connectivity and a web browser at least):

nixos-generate-config --root /mnt/nixos
# /etc/nixos/configuration.nix
# /etc/nixos/hardware-configuration.nix

Do the installation:

nixos-install --root /mnt/nixos

If everything went well:

reboot

Log into Github and generate an SSH key for authentication.
Clone and link an editable version of the configuration:

mkdir -p /data/andrew/sources # or in an alternate location, for now
git clone git@github.com:goromal/anixpkgs.git /data/andrew/sources/anixpkgs
cat /etc/nixos/hardware-configuration.nix > /data/andrew/sources/anixpkgs/pkgs/nixos/hardware/[hardware-configuration.nix] # update link/headings in configuration.nix
sudo mv /etc/nixos/configuration.nix /etc/nixos/old.configuration.nix
sudo mv /etc/nixos/hardware-configuration.nix /etc/nixos/old.hardware-configuration.nix
sudo ln -s /data/andrew/sources/anixpkgs/pkgs/nixos/configurations/[your-configuration.nix] /etc/nixos/configuration.nix

Make other needed updates to the configuration, then apply:

sudo nixos-rebuild boot
sudo reboot

Upgrading NixOS versions with `anixpkgs`

Aside from the source code changes in anixpkgs, ensure that your channels have been updated for the root user:

# e.g., upgrading to 24.05:
home-manager https://github.com/nix-community/home-manager/archive/release-24.05.tar.gz
nixos https://nixos.org/channels/nixos-24.05
nixpkgs https://nixos.org/channels/nixos-24.05

sudo nix-channel --update. Then upgrade with

anix-upgrade [source specification] --local --boot

Cloud Syncing

The following mount points are recommended (using rclone to set up):

dropbox:secrets -> rclone copy -> ~/secrets
dropbox:configs-> rclone copy -> ~/configs
dropbox:Games -> rclone copy -> ~/games
box:data -> rclone copy -> ~/data
box:.devrc -> rclone copy -> ~/.devrc
drive:Documents -> rclone copy -> ~/Documents

Build a NixOS ISO Image

TODO (untested); work out hardware configuration portion.

nixos-generate -f iso -c /path/to/personal/configuration.nix [-I nixpkgs=/path/to/alternative/nixpkgs]

sudo dd if=/path/to/nixos.iso of=/dev/sdX bs=4M conv=fsync status=progress

RFCs

Request For Comments (RFC) documents are convenient for organizing and iterating on designs for pieces of software. They can serve as north stars for the implementation of more complex software. Below are some examples of RFCs that I've used to guide some personal projects.

Continuous OS Deployment

RFC: Continuous OS Deployment

Summary

Operating System Continuous Deployment (OSCD) refers to the process of seamlessly upgrading my NixOS machines to the latest and greatest release with as little overhead and manual fiddling as possible. This RFC proposes an OSCD overhaul that achieves a greater level of automation and reproducibility in the OS upgrade process via a few added GitHub CD hooks, the new CLI tool anix-upgrade, and some development process changes.

Motivation

NixOS upgrades on my machines are done using the nixos-rebuild command, which builds the system configuration according to the (symlinked) file /etc/nixos/configuration.nix, which points to a mutable root configuration file in ~/sources/anixpkgs/.

This model lends itself best to rapid prototyping and test, as changes to the configuration can be immediately tested without having to commit any code. However, release deployment strategies are left to be more ad hoc and manual (and thus error-prone) under this model, as well. For example, to tag and deploy a new release off of master, the following manual steps must be taken:

The desired release commit is tagged, either locally or via the GitHub releases page.
The dependencies.nix file for all NixOS configurations is modified to refer to the new tag, manifesting as a new commit on the head of master.
~/sources/anixpkgs/ is checked out to the commit from step 2 (not step 1, ironically). Any local dev changes need to be stashed.
A nixos-rebuild command is run.

This RFC calls for a mature, stable OSCD pipeline that removes the need for the manual steps listed above while maintaining flexibility for rapid (and decoupled) on-machine development and testing.

Driving requirements

System-level requirements

[R1] OSCD shall be totally decoupled from development work; there shall be no possibility of one accidentally polluting the other.
[R2] OSCD shall be atomic such that an upgrade cannot be corrupted via a mismanagement or erroneous execution of steps.
[R3] OS release tagging shall be wholly executable within an anixpkgs pull request, and shall be entirely automated except for a manual specification of the level of release (e.g., major, minor, patch) that the pull request corresponds to.
[R4] An OS upgrade on-machine shall take no more than one step to complete.
[R5] The same upgrade mechanism from [SR4] shall enable rapid prototyping of active development branches.

Software-level requirements

[R1.1] Development within anixpkgs shall happen in a separate location from the symlinked ~/sources/anixpkgs directory, which shall be reserved for OS upgrades.
[R1.2] ~/sources/anixpkgs shall be read-only.
[R2.1] The release tagging process shall execute all required steps automatically, prompted by a single initiatory step, within the remote CD pipeline.
[R2.2] All automated steps for [R2.1] shall kick off only after a pull request merge into master, which is push-protected.
[R2.3] The OS upgrade process shall consist of an atomic source preparation step followed by an atomic rebuild step, both chained together automatically.
[R3.1] The tagging process from [R2.1] shall be initiated via adding labels to a pull request. No further action should be required.
[R4.1] OS upgrades shall be offered by a CLI tool that, with no arguments specified, will upgrade the system to the most recent anixpkgs release off of master.
[R4.2] The OS upgrade CLI tool shall perform rebuild switch by default, but allow for rebuild boot to be manually specified instead.
[R5.1] The OS upgrade CLI tool shall allow (via provided arguments) for an upgrade to any particular tag, branch, or commit within the remote anixpkgs repository.
[R5.2] The OS upgrade CLI tool shall allow for builds with packages local to the specified build target, and not necessarily tied to that target's prescribed release version.

Detailed design

The OSCD requirements are addressed with three components: an updated deployment pipeline within anixpkgs GitHub actions, an OS upgrade CLI tool, and a new policy for anixpkgs development and testing.

Deployment pipeline

Requirements [R2.1-2,3.1] are proposed to be fulfilled by adding three GitHub actions jobs with write permissions on master to the deployment workflow. Each of these three jobs will be responsible for either tagging a new major release, minor release, or patch release, and will be triggered by a corresponding pull request label on a merged pull request only.

Each of these jobs will consist of the following steps:

Only execute if a merged pull request had the appropriate release label.
Checkout anixpkgs master.
Run a version increment script that increments the release version according to the release label.
Commit the semantic version changes and tag that commit with the new semantic version string.
Push the commit and corresponding tag to master.

The version increment script will simply take as an input the release increment type (major, minor, or patch) and increment accordingly:

(Major) x.y.z -> x+1.0.0
(Minor) x.y.z -> x.y+1.0
(Patch) x.y.z -> x.y.z+1

In the event of a pull request getting merged with multiple labels, the execution order of the release tag jobs will be major -> minor -> patch, such that each successive tag will be visible in the resulting semantic version. If the order were reversed, for example, a patch release increment would be obscured by a minor release increment, which would zero out the patch field.

OS upgrade CLI tool: anix-upgrade

One a new release has been properly and automatically tagged on anixpkgs remote, a CLI tool called anix-upgrade is proposed to upgrade the system to the latest tag in an automated and incorruptible (i.e., no need nor opportunity to manually modify code or any configurations during the process) fashion and fulfill [R1.2,2.3,4.1-2,5.1-2].

As implied by [R2.3], anix-upgrade will do two things:

Prepare a read-only (and Git-less) version of anixpkgs in the ~/sources directory according to the exact version specified via arguments through the CLI.
Rebuild the system configuration according to the updated source/configuration.

(1) may be naturally accomplished via a Nix derivation, which by definition must consist of a read-only (and reproducible) output with no tolerance for side effects from things like .git directories. The CLI tool will allow for (1) to be constructed from:

No argument at all, which will assume that the target source corresponds to the current head of anixpkgs master. This will be the way to perform standard, non-dev-prototyping upgrades.
An alternative release tag string or a development branch name (assumed to be at the head of that branch) or a commit hash.
An optional specification that the OS packages should be built from the local packages in that specific version of the anixpkgs source tree, and not necessarily from the prescribed release version of the packages.

Because Nix derivations cannot clone Git repositories, the Nix built-in tools fetchGit and fetchTarball must be used to fetch the exact right version of the source. In my experience, fetchGit does not consistently fetch the expected "head-of" commit when only a branch name is specified, so in this implementation fetchTarball is to be used for any version of (1) that does not specify the full commit hash. This is possible because of GitHub's feature where it allows for URL-based fetching of zipped source archives from tag names and branch names (reliably delivering the head-of commit in the latter case).

(2) is accomplished by aliasing to the nixos-rebuild command (exposing an optional flag to require a reboot for changes to take effect as per [R4.2]) and only executing once (1) has successfully completed.

Development policy changes

All-in-all, the above changes serve to reduce the cognitive load associated with releasing and deploying a new version of anixpkgs once development is complete. In the same vein, the above changes are best served by fulfilling [R1.1] as well, which moves anixpkgs development out of the ~/sources directory and into the ~/dev directory, consistent with development on individual repositories. While mostly a clerical change, there are a couple of implications:

The machines docs should be updated to modify instructions for setting up a new machine from scratch. The setup process may now be slightly more complicated on a one-time basis.
The ~/.devrc file on every development machine (see devshell) should be modified to set the pkgs_dir variable to the ~/dev/ location and not the ~/sources/ one. This is to preserve the ability to mutate attribute-based sources with the same level of flexibility as before.

Drawbacks

The principal drawback of this design is the new requirement to commit OS prototype changes to GitHub when prototyping new OS versions via the specification of a remote tag, branch, or commit with the OS upgrade tool.

Alternatives

To address the slight OS prototyping drawback, an additional option may be added to anix-upgrade to point to a local anixpkgs source tree, which would symlink to the mutable source tree rather than an immutable nix derivation that pulls from GitHub.

Unresolved questions

Must OS upgrades always be manually triggered via anix-upgrade, or might it be fruitful to execute automatic upgrades in the future?
How may OSCD fruitfully apply to machine closures that import anixpkgs closures but specify their own configurations?

C++ Packages

Packages written in C++.

manif-geom-cpp

Templated, header-only implementations for SO(2), SE(2), SO(3), SE(3).

Repository

Operationally very similar to variations on Eigen's Quaternion<T> class, but with added chart maps and rules for addition and subtraction on tangent spaces. Meant to be used with nonlinear least-squares solvers like Ceres Solver which take advantage of templating to implement auto-differentiation on arbitrary mathematical formulations in code.

The SO(3) math is based on my notes on 3D rotation representations.

Including in Your Project With CMake

# ...

find_package(Eigen3 REQUIRED)
find_package(manif-geom-cpp REQUIRED)

include_directories(
    ${EIGEN3_INCLUDE_DIRS}
)


# ...

target_link_libraries(target INTERFACE manif-geom-cpp)

Example Usage

Example usage of SO(3):

// action
SO3d     q = SO3d::random();
Vector3d v;
v.setRandom();

Vector3d qv1 = q * v;
Vector3d qv2 = q.R() * v;
BOOST_CHECK_CLOSE(qv1.x(), qv2.x(), 1e-8);
BOOST_CHECK_CLOSE(qv1.y(), qv2.y(), 1e-8);
BOOST_CHECK_CLOSE(qv1.z(), qv2.z(), 1e-8);

// inversion and composition
SO3d q1    = SO3d::random();
SO3d q2    = SO3d::random();
SO3d q2inv = q2.inverse();
SO3d q1p   = q1 * q2 * q2inv;

BOOST_CHECK_CLOSE(q1.w(), q1p.w(), 1e-8);
BOOST_CHECK_CLOSE(q1.x(), q1p.x(), 1e-8);
BOOST_CHECK_CLOSE(q1.y(), q1p.y(), 1e-8);
BOOST_CHECK_CLOSE(q1.z(), q1p.z(), 1e-8);

// Euler conversions
Vector3d euler;
euler.setRandom();
euler *= M_PI;
SO3d q  = SO3d::fromEuler(euler.x(), euler.y(), euler.z());
SO3d q2 = SO3d::fromEuler(q.roll(), q.pitch(), q.yaw());

BOOST_CHECK_CLOSE(q.w(), q2.w(), 1e-8);
BOOST_CHECK_CLOSE(q.x(), q2.x(), 1e-8);
BOOST_CHECK_CLOSE(q.y(), q2.y(), 1e-8);
BOOST_CHECK_CLOSE(q.z(), q2.z(), 1e-8);

// plus / minus
SO3d     q1 = SO3d::random();
Vector3d q12;
q12.setRandom();
SO3d     q2   = q1 + q12;
Vector3d q12p = q2 - q1;
BOOST_CHECK_CLOSE(q12.x(), q12p.x(), 1e-8);
BOOST_CHECK_CLOSE(q12.y(), q12p.y(), 1e-8);
BOOST_CHECK_CLOSE(q12.z(), q12p.z(), 1e-8);

// chart maps
SO3d     q = SO3d::random();
Vector3d w;
w.setRandom();
Vector3d qLog = SO3d::Log(q);
SO3d     q2   = SO3d::Exp(qLog);
BOOST_CHECK_CLOSE(q.w(), q2.w(), 1e-8);
BOOST_CHECK_CLOSE(q.x(), q2.x(), 1e-8);
BOOST_CHECK_CLOSE(q.y(), q2.y(), 1e-8);
BOOST_CHECK_CLOSE(q.z(), q2.z(), 1e-8);

SO3d     wExp = SO3d::Exp(w);
Vector3d w2   = SO3d::Log(wExp);
BOOST_CHECK_CLOSE(w.x(), w2.x(), 1e-8);
BOOST_CHECK_CLOSE(w.y(), w2.y(), 1e-8);
BOOST_CHECK_CLOSE(w.z(), w2.z(), 1e-8);

// scaling
SO3d qI  = SO3d::identity();
SO3d qIs = 5.0 * qI;
BOOST_CHECK_CLOSE(qIs.w(), qI.w(), 1e-8);
BOOST_CHECK_CLOSE(qIs.x(), qI.x(), 1e-8);
BOOST_CHECK_CLOSE(qIs.y(), qI.y(), 1e-8);
BOOST_CHECK_CLOSE(qIs.z(), qI.z(), 1e-8);

SO3d qr  = SO3d::random();
SO3d qr2 = qr * 0.2; // if scale is too big, then the rotation will
                    // wrap around the sphere, resulting in a reversed
                    // or truncated tangent vector which can't be inverted
                    // through scalar division
SO3d qr3 = qr2 / 0.2;
BOOST_CHECK_CLOSE(qr.w(), qr3.w(), 1e-8);
BOOST_CHECK_CLOSE(qr.x(), qr3.x(), 1e-8);
BOOST_CHECK_CLOSE(qr.y(), qr3.y(), 1e-8);
BOOST_CHECK_CLOSE(qr.z(), qr3.z(), 1e-8);

Conventions

Ordering

Scalar term first:

$$\mathbf{R} \in SO(2) \triangleq \begin{bmatrix} q_w & q_x \end{bmatrix}.$$

$$\mathbf{R} \in SO(3) \triangleq \begin{bmatrix} q_w & q_x & q_y & q_z \end{bmatrix}.$$

Handedness

Right-handed:

$$\mathbf{q}_1 \otimes \mathbf{q}_2=[\mathbf{q}_1]_L\mathbf{q}_2=[\mathbf{q}_2]_R\mathbf{q}_1,$$

$$[\mathbf{q}]_L \triangleq \begin{bmatrix}q_w & -q_x & -q_y & -q_z \\ q_x & q_w & -q_z & q_y \\ q_y & q_z & q_w & -q_x \\ q_z & -q_y & q_x & q_w\end{bmatrix},$$

$$[\mathbf{q}]_R \triangleq \begin{bmatrix}q_w & -q_x & -q_y & -q_z \\ q_x & q_w & q_z & -q_y \\ q_y & -q_z & q_w & q_x \\ q_z & q_y & -q_x & q_w \end{bmatrix}.$$

Function

Passive:

$$\mathbf{R}_A^B~^A\mathbf{v}=^B\mathbf{v}.$$

Directionality and Perturbation

Body-to-world with local perturbations:

$$\mathbf{R}_B^W \oplus \tilde{\theta} \triangleq \mathbf{R}_B^W \text{Exp}\left(\tilde{\theta}\right).$$

aapis-cpp

C++ bindings for my custom APIs.

mscpp

Useful template classes for creating multithreaded, interdependent microservices in C++.

Repository

Use cases pending.

quad-sim-cpp

C++ library and daemon for simulating quadrotor dynamics from PWM motor inputs.

Repository

Under construction.

ceres-factors

C++ library with custom parameterizations and cost functions for the Ceres Solver.

Repository

Examples documented in the unit tests.

Articles/tutorials showcasing some of the custom cost functions and parameterizations:

signals-cpp

Header-only templated C++ library implementing rigid-body dynamics, derivatives, integrals, and interpolation.

Repository

Examples documented in the unit tests.

secure-delete

Secure file deletion utility, written in C.

Repository

The deletion process is as follows:

Overwrite the file with multiple passes. After each pass, the disk cache is flushed. The number of passes depends on the commanded mode:

(default / secure mode) 38 passes:
- 1x overwrite with 0xff.
- 5x random passes.
- 27x overwrites with special values to make the recovery from MFM- and RLL-encoded hard disks hard to impossible.
- 5x random passes.
(insecure mode) 2 passes:
- 1x overwrite with 0xff.
- 1x random pass.
(totally insecure mode) 1 pass:
- 1x random pass.

Truncate the file, so that an observer wouldn't know which diskblocks belonged to the file.
Rename the file.
Delete (unlink) the file.

In 1 second you can approximately overwrite 1 to 2 MB of data (on a hard disk).

In "totally insecure" mode, in 15 seconds you can approximately overwrite 100 MB of data. The same deletion takes about 60 minutes in totally secure mode.

Usage

secure-delete [-dflrvz] file1 file2 etc.

Options:
        -d  ignore the two dot special files "." and "..".
        -f  fast (and insecure mode): no /dev/urandom, no synchronize mode.
        -l  lessens the security (use twice for total insecure mode).
        -r  recursive mode, deletes all subdirectories.
        -v  is verbose mode.
        -z  last wipe writes zeros instead of random data.

Does a secure overwrite/rename/delete of the target file(s).
Default is secure mode (38 writes).

sorting

A C++ library for sporadic, incremental sorting with client-side comparators.

Repository

Tests

The main idea of this library is to take sorting algorithms like Quicksort and make them stateless across iterations. The sorting is performed within the "server" one step at a time where all the state information needed to perform the next step in the sort is passed in as an input from a "client." The client must keep track of this state and also perform the binary comparisons requested by the server at each step.

This non-traditional conception of sorting effectively allows a human to be placed in the middle of the sorting loop, dictating the atomic binary comparisons between elements in a sortable set. Since the outcomes of these comparisons dictate the final ordering of the elements from the sorting algorithm, this design provides a natural (and thorough) way for a person to topologically rank arbitrary sets of objects through the cognitively manageable task of successive binary choices of preference. The rankserver experiment is powered by this library.

crowcpp

A minimally-patched fork of Crow, a C++ webserver.

The patch allows one to dynamically specify where the website's assets directory is; a necessary feature for rankserver-cpp.

rankserver-cpp

A portable webserver for RESTfully ranking files via binary manual comparisons.

Repository

Spins up a crowcpp webserver (on the specified port) whose purpose is to help a user rank files in the chosen data-dir directory via manual binary comparisons. The ranking is done via an incremental "RESTful" sorting strategy implemented within the sorting library. State is created and maintained within the data-dir directory so that the ranking exercise can pick back up where it left off between different spawnings of the server. At this point, only the ranking of .txt and .png files is possible; other file types in data-dir will be ignored.