Add more test assemblies (#103)

This PR helps probe the capabilities of the engine.

Also adjusts the realization triggering system to reduce redundant realizations as we set an assembly's regulators during loading. Specificially, consolidates all calls to `realize()` into a single effect, which is triggered by the `needs_realization` signal.
Also introduces a `keep_realized` signal and use it to pause realization while loading assemblies, but this signal is planned for removal as ultimately we do not want a separate "mode" of interpreting commands during loading, for maximal reproducibility of results (and simplicity of system).

Co-authored-by: Aaron Fenyes <aaron.fenyes@fareycircles.ooo>
Reviewed-on: StudioInfinity/dyna3#103
Co-authored-by: Vectornaut <vectornaut@nobody@nowhere.net>
Co-committed-by: Vectornaut <vectornaut@nobody@nowhere.net>

.forgejo/setup-trunk/action.yaml

@@ -0,0 +1,22 @@
+# set up the Trunk web build system
+#
+#   https://trunkrs.dev
+#
+# the `curl` call is based on David Tolnay's `rust-toolchain` action
+#
+#   https://github.com/dtolnay/rust-toolchain
+#
+runs:
+  using: "composite"
+  steps:
+    - run: rustup target add wasm32-unknown-unknown
+    
+    # install the Trunk binary to `ci-bin` within the workspace directory, which
+    # is determined by the `github.workspace` label and reflected in the
+    # `GITHUB_WORKSPACE` environment variable. then, make the `trunk` command
+    # available by placing the fully qualified path to `ci-bin` on the
+    # workflow's search path
+    - run: mkdir -p ci-bin
+    - run: curl --output - --proto '=https' --tlsv1.2 --retry 10 --retry-connrefused --location --silent --show-error --fail 'https://github.com/trunk-rs/trunk/releases/download/v0.21.12/trunk-x86_64-unknown-linux-gnu.tar.gz' | tar --gunzip --extract --file -
+      working-directory: ci-bin
+    - run: echo "${{ github.workspace }}/ci-bin" >> $GITHUB_PATH

.forgejo/workflows/continuous-integration.yaml

@@ -0,0 +1,29 @@
+on:
+  pull_request:
+  push:
+    branches: [main]
+jobs:
+  # run the automated tests, reporting success if the tests pass and were built
+  # without warnings. the examples are run as tests, because we've configured
+  # each example target with `test = true` and `harness = false` in Cargo.toml.
+  # Trunk build failures caused by problems outside the Rust source code, like
+  # missing assets, should be caught by `trunk_build_test`
+  test:
+    runs-on: docker
+    container:
+      image: cimg/rust:1.86-node
+    defaults:
+      run:
+        # set the default working directory for each `run` step, relative to the
+        # workspace directory. this default only affects `run` steps (and if we
+        # tried to set the `working-directory` label for any other kind of step,
+        # it wouldn't be recognized anyway)
+        working-directory: app-proto
+    steps:
+      # Check out the repository so that its top-level directory is the
+      # workspace directory (action variable `github.workspace`, environment
+      # variable `$GITHUB_WORKSPACE`):
+      - uses: https://code.forgejo.org/actions/checkout@v4
+      
+      - uses: ./.forgejo/setup-trunk
+      - run: RUSTFLAGS='-D warnings' cargo test

.gitignore

@@ -1,8 +1,2 @@
-node_modules
-site
-docbuild
-__tests__
-coverage
-dyna3.zip
-tmpproj
+ci-bin
 *~

README.md

@@ -17,3 +17,51 @@ Note that currently this is just the barest beginnings of the project, more of a
 * Able to run in browser (so implemented in WASM-compatible language)
 
 * Produce scalable graphics of 3D diagrams, and maybe STL files (or other fabricatable file format) as well.
+
+## Prototype
+
+The latest prototype is in the folder `app-proto`. It includes both a user interface and a numerical constraint-solving engine.
+
+### Install the prerequisites
+
+1. Install [`rustup`](https://rust-lang.github.io/rustup/): the officially recommended Rust toolchain manager
+   * It's available on Ubuntu as a [Snap](https://snapcraft.io/rustup)
+2. Call `rustup default stable` to "download the latest stable release of Rust and set it as your default toolchain"
+   * If you forget, the `rustup` [help system](https://github.com/rust-lang/rustup/blob/d9b3601c3feb2e88cf3f8ca4f7ab4fdad71441fd/src/errors.rs#L109-L112) will remind you
+3. Call `rustup target add wasm32-unknown-unknown` to add the [most generic 32-bit WebAssembly target](https://doc.rust-lang.org/nightly/rustc/platform-support/wasm32-unknown-unknown.html)
+4. Call `cargo install wasm-pack` to install the [WebAssembly toolchain](https://rustwasm.github.io/docs/wasm-pack/)
+5. Call `cargo install trunk` to install the [Trunk](https://trunkrs.dev/) web-build tool
+6. Add the `.cargo/bin` folder in your home directory to your executable search path
+   * This lets you call Trunk, and other tools installed by Cargo, without specifying their paths
+   * On POSIX systems, the search path is stored in the `PATH` environment variable
+
+### Play with the prototype
+
+1. From the `app-proto` folder, call `trunk serve --release` to build and serve the prototype
+   * *The crates the prototype depends on will be downloaded and served automatically*
+   * *For a faster build, at the expense of a much slower prototype, you can call `trunk serve` without the `--release` flag*
+   * *If you want to stay in the top-level folder, you can call `trunk serve --config app-proto [--release]`* from there instead.
+3. In a web browser, visit one of the URLs listed under the message `INFO 📡 server listening at:`
+   * *Touching any file in the `app-proto` folder will make Trunk rebuild and live-reload the prototype*
+4. Press *ctrl+C* in the shell where Trunk is running to stop serving the prototype
+
+### Run the engine on some example problems
+
+1. Go into the `app-proto` folder
+2. Call `./run-examples`
+   * *For each example problem, the engine will print the value of the loss function at each optimization step*
+   * *The first example that prints is the same as the Irisawa hexlet example from the Julia version of the engine prototype. If you go into `engine-proto/gram-test`, launch Julia, and then*
+     
+     ```julia
+     include("irisawa-hexlet.jl")
+     for (step, scaled_loss) in enumerate(history_alt.scaled_loss)
+       println(rpad(step-1, 4), " | ", scaled_loss)
+     end
+     ```
+     
+     *you should see that it prints basically the same loss history until the last few steps, when the lower default precision of the Rust engine really starts to show*
+
+### Run the automated tests
+
+1. Go into the `app-proto` folder
+2. Call `cargo test`

app-proto/.gitignore

@@ -0,0 +1,4 @@
+target
+dist
+profiling
+Cargo.lock

app-proto/Cargo.toml

@@ -0,0 +1,81 @@
+[package]
+name = "dyna3"
+version = "0.1.0"
+authors = ["Aaron Fenyes", "Glen Whitney"]
+edition = "2021"
+rust-version = "1.86"
+
+[features]
+default = ["console_error_panic_hook"]
+dev = []
+
+[dependencies]
+itertools = "0.13.0"
+js-sys = "0.3.70"
+lazy_static = "1.5.0"
+nalgebra = "0.33.0"
+readonly = "0.2.12"
+sycamore = "0.9.1"
+
+# We use Charming to help display engine diagnostics
+charming = { version = "0.5.1", features = ["wasm"] }
+
+# The `console_error_panic_hook` crate provides better debugging of panics by
+# logging them with `console.error`. This is great for development, but requires
+# all the `std::fmt` and `std::panicking` infrastructure, so isn't great for
+# code size when deploying.
+console_error_panic_hook = { version = "0.1.7", optional = true }
+
+[dependencies.web-sys]
+version = "0.3.69"
+features = [
+  'DomRect',
+  'HtmlCanvasElement',
+  'HtmlInputElement',
+  'Performance',
+  'WebGl2RenderingContext',
+  'WebGlBuffer',
+  'WebGlProgram',
+  'WebGlShader',
+  'WebGlUniformLocation',
+  'WebGlVertexArrayObject'
+]
+
+# the self-dependency specifies features to use for tests and examples
+#
+#   https://github.com/rust-lang/cargo/issues/2911#issuecomment-1483256987
+#
+[dev-dependencies]
+dyna3 = { path = ".", default-features = false, features = ["dev"] }
+wasm-bindgen-test = "0.3.34"
+
+# turn off spurious warnings about the custom config that Sycamore uses
+#
+#   https://sycamore.dev/book/troubleshooting#unexpected-cfg-condition-name--sycamore-force-ssr
+#
+[lints.rust]
+unexpected_cfgs = { level = "warn", check-cfg = ["cfg(sycamore_force_ssr)"] }
+
+[profile.release]
+opt-level = "s" # optimize for small code size
+debug = true # include debug symbols
+
+[[example]]
+name = "irisawa-hexlet"
+test = true
+harness = false
+
+[[example]]
+name = "kaleidocycle"
+test = true
+harness = false
+
+[[example]]
+name = "point-on-sphere"
+test = true
+harness = false
+
+[[example]]
+name = "three-spheres"
+test = true
+harness = false

app-proto/examples/common/print.rs

@@ -0,0 +1,36 @@
+#![allow(dead_code)]
+
+use nalgebra::DMatrix;
+
+use dyna3::engine::{Q, DescentHistory, Realization};
+
+pub fn title(title: &str) {
+    println!("─── {title} ───");
+}
+
+pub fn realization_diagnostics(realization: &Realization) {
+    let Realization { result, history } = realization;
+    println!();
+    if let Err(ref message) = result {
+        println!("❌️ {message}");
+    } else {
+        println!("✅️ Target accuracy achieved!");
+    }
+    println!("Steps: {}", history.scaled_loss.len() - 1);
+    println!("Loss: {}", history.scaled_loss.last().unwrap());
+}
+
+pub fn gram_matrix(config: &DMatrix<f64>) {
+    println!("\nCompleted Gram matrix:{}", (config.tr_mul(&*Q) * config).to_string().trim_end());
+}
+
+pub fn config(config: &DMatrix<f64>) {
+    println!("\nConfiguration:{}", config.to_string().trim_end());
+}
+
+pub fn loss_history(history: &DescentHistory) {
+    println!("\nStep │ Loss\n─────┼────────────────────────────────");
+    for (step, scaled_loss) in history.scaled_loss.iter().enumerate() {
+        println!("{:<4} │ {}", step, scaled_loss);
+    }
+}

app-proto/examples/irisawa-hexlet.rs

@@ -0,0 +1,23 @@
+#[path = "common/print.rs"]
+mod print;
+
+use dyna3::engine::{ConfigNeighborhood, examples::realize_irisawa_hexlet};
+
+fn main() {
+    const SCALED_TOL: f64 = 1.0e-12;
+    let realization = realize_irisawa_hexlet(SCALED_TOL);
+    print::title("Irisawa hexlet");
+    print::realization_diagnostics(&realization);
+    if let Ok(ConfigNeighborhood { config, .. }) = realization.result {
+        // print the diameters of the chain spheres
+        println!("\nChain diameters:");
+        println!("  {} sun (given)", 1.0 / config[(3, 3)]);
+        for k in 4..9 {
+            println!("  {} sun", 1.0 / config[(3, k)]);
+        }
+        
+        // print the completed Gram matrix
+        print::gram_matrix(&config);
+    }
+    print::loss_history(&realization.history);
+}

app-proto/examples/kaleidocycle.rs

@@ -0,0 +1,32 @@
+#[path = "common/print.rs"]
+mod print;
+
+use nalgebra::{DMatrix, DVector};
+
+use dyna3::engine::{ConfigNeighborhood, examples::realize_kaleidocycle};
+
+fn main() {
+    const SCALED_TOL: f64 = 1.0e-12;
+    let realization = realize_kaleidocycle(SCALED_TOL);
+    print::title("Kaleidocycle");
+    print::realization_diagnostics(&realization);
+    if let Ok(ConfigNeighborhood { config, nbhd: tangent }) = realization.result {
+        // print the completed Gram matrix and the realized configuration
+        print::gram_matrix(&config);
+        print::config(&config);
+        
+        // find the kaleidocycle's twist motion by projecting onto the tangent
+        // space
+        const N_POINTS: usize = 12;
+        let up = DVector::from_column_slice(&[0.0, 0.0, 1.0, 0.0]);
+        let down = -&up;
+        let twist_motion: DMatrix<_> = (0..N_POINTS).step_by(4).flat_map(
+            |n| [
+                tangent.proj(&up.as_view(), n),
+                tangent.proj(&down.as_view(), n+1)
+            ]
+        ).sum();
+        let normalization = 5.0 / twist_motion[(2, 0)];
+        println!("\nTwist motion:{}", (normalization * twist_motion).to_string().trim_end());
+    }
+}

app-proto/examples/point-on-sphere.rs

@@ -0,0 +1,33 @@
+#[path = "common/print.rs"]
+mod print;
+
+use dyna3::engine::{
+    point,
+    realize_gram,
+    sphere,
+    ConfigNeighborhood,
+    ConstraintProblem
+};
+
+fn main() {
+    let mut problem = ConstraintProblem::from_guess(&[
+        point(0.0, 0.0, 2.0),
+        sphere(0.0, 0.0, 0.0, 1.0)
+    ]);
+    for j in 0..2 {
+        for k in j..2 {
+            problem.gram.push_sym(j, k, if (j, k) == (1, 1) { 1.0 } else { 0.0 });
+        }
+    }
+    problem.frozen.push(3, 0, problem.guess[(3, 0)]);
+    let realization = realize_gram(
+        &problem, 1.0e-12, 0.5, 0.9, 1.1, 200, 110
+    );
+    print::title("Point on a sphere");
+    print::realization_diagnostics(&realization);
+    if let Ok(ConfigNeighborhood{ config, .. }) = realization.result {
+        print::gram_matrix(&config);
+        print::config(&config);
+    }
+    print::loss_history(&realization.history);
+}

app-proto/examples/three-spheres.rs

@@ -0,0 +1,34 @@
+#[path = "common/print.rs"]
+mod print;
+
+use dyna3::engine::{
+    realize_gram,
+    sphere,
+    ConfigNeighborhood,
+    ConstraintProblem
+};
+
+fn main() {
+    let mut problem = ConstraintProblem::from_guess({
+        let a: f64 = 0.75_f64.sqrt();
+        &[
+            sphere(1.0, 0.0, 0.0, 1.0),
+            sphere(-0.5, a, 0.0, 1.0),
+            sphere(-0.5, -a, 0.0, 1.0)
+        ]
+    });
+    for j in 0..3 {
+        for k in j..3 {
+            problem.gram.push_sym(j, k, if j == k { 1.0 } else { -1.0 });
+        }
+    }
+    let realization = realize_gram(
+        &problem, 1.0e-12, 0.5, 0.9, 1.1, 200, 110
+    );
+    print::title("Three spheres");
+    print::realization_diagnostics(&realization);
+    if let Ok(ConfigNeighborhood{ config, .. }) = realization.result {
+        print::gram_matrix(&config);
+    }
+    print::loss_history(&realization.history);
+}

app-proto/index.html

@@ -0,0 +1,17 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <meta charset="utf-8"/>
+    <title>dyna3</title>
+    <link data-trunk rel="css" href="main.css"/>
+    <link href="https://fonts.bunny.net/css?family=fira-sans:ital,wght@0,400;1,400&display=swap" rel="stylesheet">
+    <link href="https://fonts.bunny.net/css?family=noto-emoji:wght@400&text=%f0%9f%94%97%e2%9a%a0&display=swap" rel="stylesheet">
+    
+    <!--
+      the Charming visualization crate, which we use to show engine diagnostics,
+      depends the ECharts JavaScript package
+    -->
+    <script src="https://cdn.jsdelivr.net/npm/echarts@5.5.1/dist/echarts.min.js"></script>
+  </head>
+  <body></body>
+</html>

app-proto/main.css

@@ -0,0 +1,240 @@
+:root {
+  --text: #fcfcfc; /* almost white */
+  --text-bright: white;
+  --text-invalid: #f58fc2; /* bright pink */
+  --border: #555; /* light gray */
+  --border-focus-dark: #aaa; /* bright gray */
+  --border-focus-light: white;
+  --border-invalid: #70495c; /* dusky pink */
+  --selection-highlight: #444; /* medium gray */
+  --page-background: #222; /* dark gray */
+  --display-background: #020202; /* almost black */
+}
+
+body {
+  margin: 0px;
+  color: var(--text);
+  background-color: var(--page-background);
+  font-family: 'Fira Sans', sans-serif;
+}
+
+.invalid {
+  color: var(--text-invalid);
+}
+
+.status {
+  width: 20px;
+  text-align: center;
+  font-family: 'Noto Emoji';
+  font-style: normal;
+}
+
+/* sidebar */
+
+#sidebar {
+  display: flex;
+  flex-direction: column;
+  float: left;
+  width: 500px;
+  height: 100vh;
+  margin: 0px;
+  padding: 0px;
+  border-width: 0px 1px 0px 0px;
+  border-style: solid;
+  border-color: var(--border);
+}
+
+/* add-remove */
+
+#add-remove {
+  display: flex;
+  gap: 8px;
+  margin: 8px;
+}
+
+#add-remove > button {
+  height: 32px;
+}
+
+/* KLUDGE */
+/*
+  for convenience, we're using emoji as temporary icons for some buttons. these
+  buttons need to be displayed in an emoji font
+*/
+#add-remove > button.emoji {
+  width: 32px;
+  font-family: 'Noto Emoji', sans-serif;
+  font-size: large;
+}
+
+/* outline */
+
+#outline {
+  flex-grow: 1;
+  margin: 0px;
+  padding: 0px;
+  overflow-y: scroll;
+}
+
+li {
+  user-select: none;
+}
+
+summary {
+  display: flex;
+}
+
+summary.selected {
+  color: var(--text-bright);
+  background-color: var(--selection-highlight);
+}
+
+summary > div, .regulator {
+  padding-top: 4px;
+  padding-bottom: 4px;
+}
+
+.element, .regulator {
+  display: flex;
+  flex-grow: 1;
+  padding-left: 8px;
+  padding-right: 8px;
+}
+
+.element > input {
+  margin-left: 8px;
+}
+
+.element-switch {
+  width: 18px;
+  padding-left: 2px;
+  text-align: center;
+}
+
+details:has(li) .element-switch::after {
+  content: '▸';
+}
+
+details[open]:has(li) .element-switch::after {
+  content: '▾';
+}
+
+.element-label {
+  flex-grow: 1;
+}
+
+.regulator-label {
+  flex-grow: 1;
+}
+
+.element-representation {
+  display: flex;
+}
+
+.element-representation > div {
+  padding: 2px 0px 0px 0px;
+  font-size: 10pt;
+  font-variant-numeric: tabular-nums;
+  text-align: right;
+  width: 56px;
+}
+
+.regulator {
+  font-style: italic;
+}
+
+.regulator-type {
+  padding: 2px 8px 0px 8px;
+  font-size: 10pt;
+}
+
+.regulator-input {
+  margin-right: 4px;
+  color: inherit;
+  background-color: inherit;
+  border: 1px solid var(--border);
+  border-radius: 2px;
+}
+
+.regulator-input::placeholder {
+  color: inherit;
+  opacity: 54%;
+  font-style: italic;
+}
+
+.regulator-input.constraint {
+  background-color: var(--display-background);
+}
+
+.regulator-input.invalid {
+  color: var(--text-invalid);
+  border-color: var(--border-invalid);
+}
+
+.regulator-input.invalid + .status::after, details:has(.invalid):not([open]) .status::after {
+  content: '⚠';
+  color: var(--text-invalid);
+}
+
+/* diagnostics */
+
+#diagnostics {
+  margin: 10px;
+}
+
+#diagnostics-bar {
+  display: flex;
+}
+
+#realization-status {
+  display: flex;
+  flex-grow: 1;
+}
+
+#realization-status .status {
+  margin-right: 4px;
+}
+
+#realization-status :not(.status) {
+  flex-grow: 1;
+}
+
+#realization-status .status::after {
+  content: '✓';
+}
+
+#realization-status.invalid .status::after {
+  content: '⚠';
+}
+
+.diagnostics-panel {
+  margin-top: 10px;
+  min-height: 180px;
+}
+
+.diagnostics-chart {
+  background-color: var(--display-background);
+  border: 1px solid var(--border);
+  border-radius: 8px;
+}
+
+/* display */
+
+#display {
+  float: left;
+  margin-left: 20px;
+  margin-top: 20px;
+  background-color: var(--display-background);
+  border: 1px solid var(--border);
+  border-radius: 16px;
+}
+
+#display:focus {
+  border-color: var(--border-focus-dark);
+  outline: none;
+}
+
+input:focus {
+  border-color: var(--border-focus-light);
+  outline: none;
+}

app-proto/run-examples.sh

@@ -0,0 +1,20 @@
+# run all Cargo examples, as described here:
+#
+#   Karol Kuczmarski. "Add examples to your Rust libraries"
+#   http://xion.io/post/code/rust-examples.html
+#
+# you should invoke this script by calling `sh` or another interpreter, rather
+# than calling `souce`, to ensure that the script can find the manifest file for
+# the application prototype
+
+# find the manifest file for the application prototype
+MANIFEST="$(dirname -- $0)/Cargo.toml"
+
+# set up the command that runs each example
+RUN_EXAMPLE="cargo run --manifest-path $MANIFEST --example"
+
+# run the examples
+$RUN_EXAMPLE irisawa-hexlet; echo
+$RUN_EXAMPLE three-spheres; echo
+$RUN_EXAMPLE point-on-sphere; echo
+$RUN_EXAMPLE kaleidocycle

app-proto/src/assembly.rs

@@ -0,0 +1,935 @@
+use nalgebra::{DMatrix, DVector, DVectorView};
+use std::{
+    cell::Cell,
+    collections::{BTreeMap, BTreeSet},
+    cmp::Ordering,
+    fmt,
+    fmt::{Debug, Formatter},
+    hash::{Hash, Hasher},
+    rc::Rc,
+    sync::{atomic, atomic::AtomicU64}
+};
+use sycamore::prelude::*;
+use web_sys::{console, wasm_bindgen::JsValue}; /* DEBUG */
+
+use crate::{
+    components::{display::DisplayItem, outline::OutlineItem},
+    engine::{
+        Q,
+        change_half_curvature,
+        local_unif_to_std,
+        point,
+        project_point_to_normalized,
+        project_sphere_to_normalized,
+        realize_gram,
+        sphere,
+        ConfigNeighborhood,
+        ConfigSubspace,
+        ConstraintProblem,
+        DescentHistory,
+        Realization
+    },
+    specified::SpecifiedValue
+};
+
+pub type ElementColor = [f32; 3];
+
+/* KLUDGE */
+// we should reconsider this design when we build a system for switching between
+// assemblies. at that point, we might want to switch to hierarchical keys,
+// where each each item has a key that identifies it within its assembly and
+// each assembly has a key that identifies it within the sesssion
+static NEXT_SERIAL: AtomicU64 = AtomicU64::new(0);
+
+pub trait Serial {
+    // a serial number that uniquely identifies this element
+    fn serial(&self) -> u64;
+    
+    // take the next serial number, panicking if that was the last one left
+    fn next_serial() -> u64 where Self: Sized {
+        // the technique we use to panic on overflow is taken from _Rust Atomics
+        // and Locks_, by Mara Bos
+        //
+        //   https://marabos.nl/atomics/atomics.html#example-handle-overflow
+        //
+        NEXT_SERIAL.fetch_update(
+            atomic::Ordering::SeqCst, atomic::Ordering::SeqCst,
+            |serial| serial.checked_add(1)
+        ).expect("Out of serial numbers for elements")
+    }
+}
+
+impl Hash for dyn Serial {
+    fn hash<H: Hasher>(&self, state: &mut H) {
+        self.serial().hash(state)
+    }
+}
+
+impl PartialEq for dyn Serial {
+    fn eq(&self, other: &Self) -> bool {
+        self.serial() == other.serial()
+    }
+}
+
+impl Eq for dyn Serial {}
+
+impl PartialOrd for dyn Serial {
+    fn partial_cmp(&self, other: &Self) -> Option<Ordering> {
+        Some(self.cmp(other))
+    }
+}
+
+impl Ord for dyn Serial {
+    fn cmp(&self, other: &Self) -> Ordering {
+        self.serial().cmp(&other.serial())
+    }
+}
+
+pub trait ProblemPoser {
+    fn pose(&self, problem: &mut ConstraintProblem);
+}
+
+pub trait Element: Serial + ProblemPoser + DisplayItem {
+    // the default identifier for an element of this type
+    fn default_id() -> String where Self: Sized;
+    
+    // the default example of an element of this type
+    fn default(id: String, id_num: u64) -> Self where Self: Sized;
+    
+    // the default regulators that come with this element
+    fn default_regulators(self: Rc<Self>) -> Vec<Rc<dyn Regulator>> {
+        Vec::new()
+    }
+    
+    fn id(&self) -> &String;
+    fn label(&self) -> &String;
+    fn representation(&self) -> Signal<DVector<f64>>;
+    fn ghost(&self) -> Signal<bool>;
+    
+    // the regulators the element is subject to. the assembly that owns the
+    // element is responsible for keeping this set up to date
+    fn regulators(&self) -> Signal<BTreeSet<Rc<dyn Regulator>>>;
+    
+    // project a representation vector for this kind of element onto its
+    // normalization variety
+    fn project_to_normalized(&self, rep: &mut DVector<f64>);
+    
+    // the configuration matrix column index that was assigned to the element
+    // last time the assembly was realized, or `None` if the element has never
+    // been through a realization
+    fn column_index(&self) -> Option<usize>;
+    
+    // assign the element a configuration matrix column index. this method must
+    // be used carefully to preserve invariant (1), described in the comment on
+    // the `tangent` field of the `Assembly` structure
+    fn set_column_index(&self, index: usize);
+}
+
+impl Debug for dyn Element {
+    fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), fmt::Error> {
+        self.id().fmt(f)
+    }
+}
+
+impl Hash for dyn Element {
+    fn hash<H: Hasher>(&self, state: &mut H) {
+        <dyn Serial>::hash(self, state)
+    }
+}
+
+impl PartialEq for dyn Element {
+    fn eq(&self, other: &Self) -> bool {
+        <dyn Serial>::eq(self, other)
+    }
+}
+
+impl Eq for dyn Element {}
+
+impl PartialOrd for dyn Element {
+    fn partial_cmp(&self, other: &Self) -> Option<Ordering> {
+        <dyn Serial>::partial_cmp(self, other)
+    }
+}
+
+impl Ord for dyn Element {
+    fn cmp(&self, other: &Self) -> Ordering {
+        <dyn Serial>::cmp(self, other)
+    }
+}
+
+pub struct Sphere {
+    pub id: String,
+    pub label: String,
+    pub color: ElementColor,
+    pub representation: Signal<DVector<f64>>,
+    pub ghost: Signal<bool>,
+    pub regulators: Signal<BTreeSet<Rc<dyn Regulator>>>,
+    serial: u64,
+    column_index: Cell<Option<usize>>
+}
+
+impl Sphere {
+    const CURVATURE_COMPONENT: usize = 3;
+    
+    pub fn new(
+        id: String,
+        label: String,
+        color: ElementColor,
+        representation: DVector<f64>
+    ) -> Sphere {
+        Sphere {
+            id: id,
+            label: label,
+            color: color,
+            representation: create_signal(representation),
+            ghost: create_signal(false),
+            regulators: create_signal(BTreeSet::new()),
+            serial: Self::next_serial(),
+            column_index: None.into()
+        }
+    }
+}
+
+impl Element for Sphere {
+    fn default_id() -> String {
+        "sphere".to_string()
+    }
+    
+    fn default(id: String, id_num: u64) -> Sphere {
+        Sphere::new(
+            id,
+            format!("Sphere {id_num}"),
+            [0.75_f32, 0.75_f32, 0.75_f32],
+            sphere(0.0, 0.0, 0.0, 1.0)
+        )
+    }
+    
+    fn default_regulators(self: Rc<Self>) -> Vec<Rc<dyn Regulator>> {
+        vec![Rc::new(HalfCurvatureRegulator::new(self))]
+    }
+    
+    fn id(&self) -> &String {
+        &self.id
+    }
+    
+    fn label(&self) -> &String {
+        &self.label
+    }
+    
+    fn representation(&self) -> Signal<DVector<f64>> {
+        self.representation
+    }
+    
+    fn ghost(&self) -> Signal<bool> {
+        self.ghost
+    }
+    
+    fn regulators(&self) -> Signal<BTreeSet<Rc<dyn Regulator>>> {
+        self.regulators
+    }
+    
+    fn project_to_normalized(&self, rep: &mut DVector<f64>) {
+        project_sphere_to_normalized(rep);
+    }
+    
+    fn column_index(&self) -> Option<usize> {
+        self.column_index.get()
+    }
+    
+    fn set_column_index(&self, index: usize) {
+        self.column_index.set(Some(index));
+    }
+}
+
+impl Serial for Sphere {
+    fn serial(&self) -> u64 {
+        self.serial
+    }
+}
+
+impl ProblemPoser for Sphere {
+    fn pose(&self, problem: &mut ConstraintProblem) {
+        let index = self.column_index().expect(
+            format!("Sphere \"{}\" should be indexed before writing problem data", self.id).as_str()
+        );
+        problem.gram.push_sym(index, index, 1.0);
+        problem.guess.set_column(index, &self.representation.get_clone_untracked());
+    }
+}
+
+pub struct Point {
+    pub id: String,
+    pub label: String,
+    pub color: ElementColor,
+    pub representation: Signal<DVector<f64>>,
+    pub ghost: Signal<bool>,
+    pub regulators: Signal<BTreeSet<Rc<dyn Regulator>>>,
+    serial: u64,
+    column_index: Cell<Option<usize>>
+}
+
+impl Point {
+    const WEIGHT_COMPONENT: usize = 3;
+    
+    pub fn new(
+        id: String,
+        label: String,
+        color: ElementColor,
+        representation: DVector<f64>
+    ) -> Point {
+        Point {
+            id,
+            label,
+            color,
+            representation: create_signal(representation),
+            ghost: create_signal(false),
+            regulators: create_signal(BTreeSet::new()),
+            serial: Self::next_serial(),
+            column_index: None.into()
+        }
+    }
+}
+
+impl Element for Point {
+    fn default_id() -> String {
+        "point".to_string()
+    }
+    
+    fn default(id: String, id_num: u64) -> Point {
+        Point::new(
+            id,
+            format!("Point {id_num}"),
+            [0.75_f32, 0.75_f32, 0.75_f32],
+            point(0.0, 0.0, 0.0)
+        )
+    }
+    
+    fn id(&self) -> &String {
+        &self.id
+    }
+    
+    fn label(&self) -> &String {
+        &self.label
+    }
+    
+    fn representation(&self) -> Signal<DVector<f64>> {
+        self.representation
+    }
+    
+    fn ghost(&self) -> Signal<bool> {
+        self.ghost
+    }
+    
+    fn regulators(&self) -> Signal<BTreeSet<Rc<dyn Regulator>>> {
+        self.regulators
+    }
+    
+    fn project_to_normalized(&self, rep: &mut DVector<f64>) {
+        project_point_to_normalized(rep);
+    }
+    
+    fn column_index(&self) -> Option<usize> {
+        self.column_index.get()
+    }
+    
+    fn set_column_index(&self, index: usize) {
+        self.column_index.set(Some(index));
+    }
+}
+
+impl Serial for Point {
+    fn serial(&self) -> u64 {
+        self.serial
+    }
+}
+
+impl ProblemPoser for Point {
+    fn pose(&self, problem: &mut ConstraintProblem) {
+        let index = self.column_index().expect(
+            format!("Point \"{}\" should be indexed before writing problem data", self.id).as_str()
+        );
+        problem.gram.push_sym(index, index, 0.0);
+        problem.frozen.push(Point::WEIGHT_COMPONENT, index, 0.5);
+        problem.guess.set_column(index, &self.representation.get_clone_untracked());
+    }
+}
+
+pub trait Regulator: Serial + ProblemPoser + OutlineItem {
+    fn subjects(&self) -> Vec<Rc<dyn Element>>;
+    fn measurement(&self) -> ReadSignal<f64>;
+    fn set_point(&self) -> Signal<SpecifiedValue>;
+    
+    // this method is used to responsively precondition the assembly for
+    // realization when the regulator becomes a constraint, or is edited while
+    // acting as a constraint. it should track the set point, do any desired
+    // preconditioning when the set point is present, and use its return value
+    // to report whether the set is present. the default implementation does no
+    // preconditioning
+    fn try_activate(&self) -> bool {
+        self.set_point().with(|set_pt| set_pt.is_present())
+    }
+}
+
+impl Hash for dyn Regulator {
+    fn hash<H: Hasher>(&self, state: &mut H) {
+        <dyn Serial>::hash(self, state)
+    }
+}
+
+impl PartialEq for dyn Regulator {
+    fn eq(&self, other: &Self) -> bool {
+        <dyn Serial>::eq(self, other)
+    }
+}
+
+impl Eq for dyn Regulator {}
+
+impl PartialOrd for dyn Regulator {
+    fn partial_cmp(&self, other: &Self) -> Option<Ordering> {
+        <dyn Serial>::partial_cmp(self, other)
+    }
+}
+
+impl Ord for dyn Regulator {
+    fn cmp(&self, other: &Self) -> Ordering {
+        <dyn Serial>::cmp(self, other)
+    }
+}
+
+pub struct InversiveDistanceRegulator {
+    pub subjects: [Rc<dyn Element>; 2],
+    pub measurement: ReadSignal<f64>,
+    pub set_point: Signal<SpecifiedValue>,
+    serial: u64
+}
+
+impl InversiveDistanceRegulator {
+    pub fn new(subjects: [Rc<dyn Element>; 2]) -> InversiveDistanceRegulator {
+        let representations = subjects.each_ref().map(|subj| subj.representation());
+        let measurement = create_memo(move || {
+            representations[0].with(|rep_0|
+                representations[1].with(|rep_1|
+                    rep_0.dot(&(&*Q * rep_1))
+                )
+            )
+        });
+        
+        let set_point = create_signal(SpecifiedValue::from_empty_spec());
+        let serial = Self::next_serial();
+        
+        InversiveDistanceRegulator { subjects, measurement, set_point, serial }
+    }
+}
+
+impl Regulator for InversiveDistanceRegulator {
+    fn subjects(&self) -> Vec<Rc<dyn Element>> {
+        self.subjects.clone().into()
+    }
+    
+    fn measurement(&self) -> ReadSignal<f64> {
+        self.measurement
+    }
+    
+    fn set_point(&self) -> Signal<SpecifiedValue> {
+        self.set_point
+    }
+}
+
+impl Serial for InversiveDistanceRegulator {
+    fn serial(&self) -> u64 {
+        self.serial
+    }
+}
+
+impl ProblemPoser for InversiveDistanceRegulator {
+    fn pose(&self, problem: &mut ConstraintProblem) {
+        self.set_point.with_untracked(|set_pt| {
+            if let Some(val) = set_pt.value {
+                let [row, col] = self.subjects.each_ref().map(
+                    |subj| subj.column_index().expect(
+                        "Subjects should be indexed before inversive distance regulator writes problem data"
+                    )
+                );
+                problem.gram.push_sym(row, col, val);
+            }
+        });
+    }
+}
+
+pub struct HalfCurvatureRegulator {
+    pub subject: Rc<dyn Element>,
+    pub measurement: ReadSignal<f64>,
+    pub set_point: Signal<SpecifiedValue>,
+    serial: u64
+}
+
+impl HalfCurvatureRegulator {
+    pub fn new(subject: Rc<dyn Element>) -> HalfCurvatureRegulator {
+        let measurement = subject.representation().map(
+            |rep| rep[Sphere::CURVATURE_COMPONENT]
+        );
+        
+        let set_point = create_signal(SpecifiedValue::from_empty_spec());
+        let serial = Self::next_serial();
+        
+        HalfCurvatureRegulator { subject, measurement, set_point, serial }
+    }
+}
+
+impl Regulator for HalfCurvatureRegulator {
+    fn subjects(&self) -> Vec<Rc<dyn Element>> {
+        vec![self.subject.clone()]
+    }
+    
+    fn measurement(&self) -> ReadSignal<f64> {
+        self.measurement
+    }
+    
+    fn set_point(&self) -> Signal<SpecifiedValue> {
+        self.set_point
+    }
+    
+    fn try_activate(&self) -> bool {
+        match self.set_point.with(|set_pt| set_pt.value) {
+            Some(half_curv) => {
+                self.subject.representation().update(
+                    |rep| change_half_curvature(rep, half_curv)
+                );
+                true
+            }
+            None => false
+        }
+    }
+}
+
+impl Serial for HalfCurvatureRegulator {
+    fn serial(&self) -> u64 {
+        self.serial
+    }
+}
+
+impl ProblemPoser for HalfCurvatureRegulator {
+    fn pose(&self, problem: &mut ConstraintProblem) {
+        self.set_point.with_untracked(|set_pt| {
+            if let Some(val) = set_pt.value {
+                let col = self.subject.column_index().expect(
+                    "Subject should be indexed before half-curvature regulator writes problem data"
+                );
+                problem.frozen.push(Sphere::CURVATURE_COMPONENT, col, val);
+            }
+        });
+    }
+}
+
+// the velocity is expressed in uniform coordinates
+pub struct ElementMotion<'a> {
+    pub element: Rc<dyn Element>,
+    pub velocity: DVectorView<'a, f64>
+}
+
+type AssemblyMotion<'a> = Vec<ElementMotion<'a>>;
+
+// a complete, view-independent description of an assembly
+#[derive(Clone)]
+pub struct Assembly {
+    // elements and regulators
+    pub elements: Signal<BTreeSet<Rc<dyn Element>>>,
+    pub regulators: Signal<BTreeSet<Rc<dyn Regulator>>>,
+    
+    // solution variety tangent space. the basis vectors are stored in
+    // configuration matrix format, ordered according to the elements' column
+    // indices. when you realize the assembly, every element that's present
+    // during realization gets a column index and is reflected in the tangent
+    // space. since the methods in this module never assign column indices
+    // without later realizing the assembly, we get the following invariant:
+    //
+    //  (1) if an element has a column index, its tangent motions can be found
+    //      in that column of the tangent space basis matrices
+    //
+    pub tangent: Signal<ConfigSubspace>,
+    
+    // indexing
+    pub elements_by_id: Signal<BTreeMap<String, Rc<dyn Element>>>,
+    
+    // realization control
+    pub keep_realized: Signal<bool>,
+    pub needs_realization: Signal<bool>,
+    
+    // realization diagnostics
+    pub realization_status: Signal<Result<(), String>>,
+    pub descent_history: Signal<DescentHistory>
+}
+
+impl Assembly {
+    pub fn new() -> Assembly {
+        // create an assembly
+        let assembly = Assembly {
+            elements: create_signal(BTreeSet::new()),
+            regulators: create_signal(BTreeSet::new()),
+            tangent: create_signal(ConfigSubspace::zero(0)),
+            elements_by_id: create_signal(BTreeMap::default()),
+            keep_realized: create_signal(true),
+            needs_realization: create_signal(false),
+            realization_status: create_signal(Ok(())),
+            descent_history: create_signal(DescentHistory::new())
+        };
+        
+        // realize the assembly whenever it becomes simultaneously true that
+        // we're trying to keep it realized and it needs realization
+        let assembly_for_effect = assembly.clone();
+        create_effect(move || {
+            let should_realize = assembly_for_effect.keep_realized.get()
+                && assembly_for_effect.needs_realization.get();
+            if should_realize {
+                assembly_for_effect.realize();
+            }
+        });
+        
+        assembly
+    }
+    
+    // --- inserting elements and regulators ---
+    
+    // insert an element into the assembly without checking whether we already
+    // have an element with the same identifier. any element that does have the
+    // same identifier will get kicked out of the `elements_by_id` index
+    fn insert_element_unchecked(&self, elt: impl Element + 'static) {
+        // insert the element
+        let id = elt.id().clone();
+        let elt_rc = Rc::new(elt);
+        self.elements.update(|elts| elts.insert(elt_rc.clone()));
+        self.elements_by_id.update(|elts_by_id| elts_by_id.insert(id, elt_rc.clone()));
+        
+        // create and insert the element's default regulators
+        for reg in elt_rc.default_regulators() {
+            self.insert_regulator(reg);
+        }
+    }
+    
+    pub fn try_insert_element(&self, elt: impl Element + 'static) -> bool {
+        let can_insert = self.elements_by_id.with_untracked(
+            |elts_by_id| !elts_by_id.contains_key(elt.id())
+        );
+        if can_insert {
+            self.insert_element_unchecked(elt);
+        }
+        can_insert
+    }
+    
+    pub fn insert_element_default<T: Element + 'static>(&self) {
+        // find the next unused identifier in the default sequence
+        let default_id = T::default_id();
+        let mut id_num = 1;
+        let mut id = format!("{default_id}{id_num}");
+        while self.elements_by_id.with_untracked(
+            |elts_by_id| elts_by_id.contains_key(&id)
+        ) {
+            id_num += 1;
+            id = format!("{default_id}{id_num}");
+        }
+        
+        // create and insert the default example of `T`
+        let _ = self.insert_element_unchecked(T::default(id, id_num));
+    }
+    
+    pub fn insert_regulator(&self, regulator: Rc<dyn Regulator>) {
+        // add the regulator to the assembly's regulator list
+        self.regulators.update(
+            |regs| regs.insert(regulator.clone())
+        );
+        
+        // add the regulator to each subject's regulator list
+        let subject_regulators: Vec<_> = regulator.subjects().into_iter().map(
+            |subj| subj.regulators()
+        ).collect();
+        for regulators in subject_regulators {
+            regulators.update(|regs| regs.insert(regulator.clone()));
+        }
+        
+        // request a realization when the regulator becomes a constraint, or is
+        // edited while acting as a constraint
+        let self_for_effect = self.clone();
+        create_effect(move || {
+            /* DEBUG */
+            // log the regulator update
+            console_log!("Updated regulator with subjects {:?}", regulator.subjects());
+            
+            if regulator.try_activate() {
+                self_for_effect.needs_realization.set(true);
+            }
+        });
+        
+        /* DEBUG */
+        // print an updated list of regulators
+        console_log!("Regulators:");
+        self.regulators.with_untracked(|regs| {
+            for reg in regs.into_iter() {
+                console_log!(
+                    "  {:?}: {}",
+                    reg.subjects(),
+                    reg.set_point().with_untracked(
+                        |set_pt| {
+                            let spec = &set_pt.spec;
+                            if spec.is_empty() {
+                                "__".to_string()
+                            } else {
+                                spec.clone()
+                            }
+                        }
+                    )
+                );
+            }
+        });
+    }
+    
+    // --- realization ---
+    
+    pub fn realize(&self) {
+        // index the elements
+        self.elements.update_silent(|elts| {
+            for (index, elt) in elts.iter().enumerate() {
+                elt.set_column_index(index);
+            }
+        });
+        
+        // set up the constraint problem
+        let problem = self.elements.with_untracked(|elts| {
+            let mut problem = ConstraintProblem::new(elts.len());
+            for elt in elts {
+                elt.pose(&mut problem);
+            }
+            self.regulators.with_untracked(|regs| {
+                for reg in regs {
+                    reg.pose(&mut problem);
+                }
+            });
+            problem
+        });
+        
+        /* DEBUG */
+        // log the Gram matrix
+        console_log!("Gram matrix:\n{}", problem.gram);
+        
+        /* DEBUG */
+        // log the initial configuration matrix
+        console_log!("Old configuration:{:>8.3}", problem.guess);
+        
+        // look for a configuration with the given Gram matrix
+        let Realization { result, history } = realize_gram(
+            &problem, 1.0e-12, 0.5, 0.9, 1.1, 200, 110
+        );
+        
+        /* DEBUG */
+        // report the outcome of the search in the browser console
+        if let Err(ref message) = result {
+            console_log!("❌️ {message}");
+        } else {
+            console_log!("✅️ Target accuracy achieved!");
+        }
+        console_log!("Steps: {}", history.scaled_loss.len() - 1);
+        console_log!("Loss: {}", history.scaled_loss.last().unwrap());
+        
+        // report the loss history
+        self.descent_history.set(history);
+        
+        match result {
+            Ok(ConfigNeighborhood { config, nbhd: tangent }) => {
+                /* DEBUG */
+                // report the tangent dimension
+                console_log!("Tangent dimension: {}", tangent.dim());
+                
+                // report the realization status
+                self.realization_status.set(Ok(()));
+                
+                // read out the solution
+                for elt in self.elements.get_clone_untracked() {
+                    elt.representation().update(
+                        |rep| rep.set_column(0, &config.column(elt.column_index().unwrap()))
+                    );
+                }
+                
+                // save the tangent space
+                self.tangent.set_silent(tangent);
+                
+                // clear the realization request flag
+                self.needs_realization.set(false);
+            },
+            Err(message) => {
+                // report the realization status. the `Err(message)` we're
+                // setting the status to has a different type than the
+                // `Err(message)` we received from the match: we're changing the
+                // `Ok` type from `Realization` to `()`
+                self.realization_status.set(Err(message))
+            }
+        }
+    }
+    
+    // --- deformation ---
+    
+    // project the given motion to the tangent space of the solution variety and
+    // move the assembly along it. the implementation is based on invariant (1)
+    // from above and the following additional invariant:
+    //
+    //  (2) if an element is affected by a constraint, it has a column index
+    //
+    // we have this invariant because the assembly gets realized each time you
+    // add a constraint
+    pub fn deform(&self, motion: AssemblyMotion) {
+        /* KLUDGE */
+        // when the tangent space is zero, deformation won't do anything, but
+        // the attempt to deform should be registered in the UI. this console
+        // message will do for now
+        if self.tangent.with(|tan| tan.dim() <= 0 && tan.assembly_dim() > 0) {
+            console::log_1(&JsValue::from("The assembly is rigid"));
+        }
+        
+        // give a column index to each moving element that doesn't have one yet.
+        // this temporarily breaks invariant (1), but the invariant will be
+        // restored when we realize the assembly at the end of the deformation.
+        // in the process, we find out how many matrix columns we'll need to
+        // hold the deformation
+        let realized_dim = self.tangent.with(|tan| tan.assembly_dim());
+        let motion_dim = {
+            let mut next_column_index = realized_dim;
+            for elt_motion in motion.iter() {
+                let moving_elt = &elt_motion.element;
+                if moving_elt.column_index().is_none() {
+                    moving_elt.set_column_index(next_column_index);
+                    next_column_index += 1;
+                }
+            }
+            next_column_index
+        };
+        
+        // project the element motions onto the tangent space of the solution
+        // variety and sum them to get a deformation of the whole assembly. the
+        // matrix `motion_proj` that holds the deformation has extra columns for
+        // any moving elements that aren't reflected in the saved tangent space
+        const ELEMENT_DIM: usize = 5;
+        let mut motion_proj = DMatrix::zeros(ELEMENT_DIM, motion_dim);
+        for elt_motion in motion {
+            // we can unwrap the column index because we know that every moving
+            // element has one at this point
+            let column_index = elt_motion.element.column_index().unwrap();
+            
+            if column_index < realized_dim {
+                // this element had a column index when we started, so by
+                // invariant (1), it's reflected in the tangent space
+                let mut target_columns = motion_proj.columns_mut(0, realized_dim);
+                target_columns += self.tangent.with(
+                    |tan| tan.proj(&elt_motion.velocity, column_index)
+                );
+            } else {
+                // this element didn't have a column index when we started, so
+                // by invariant (2), it's unconstrained
+                let mut target_column = motion_proj.column_mut(column_index);
+                let unif_to_std = elt_motion.element.representation().with_untracked(
+                    |rep| local_unif_to_std(rep.as_view())
+                );
+                target_column += unif_to_std * elt_motion.velocity;
+            }
+        }
+        
+        // step the assembly along the deformation. this changes the elements'
+        // normalizations, so we restore those afterward
+        for elt in self.elements.get_clone_untracked() {
+            elt.representation().update_silent(|rep| {
+                match elt.column_index() {
+                    Some(column_index) => {
+                        // step the element along the deformation and then
+                        // restore its normalization
+                        *rep += motion_proj.column(column_index);
+                        elt.project_to_normalized(rep);
+                    },
+                    None => {
+                        console_log!("No velocity to unpack for fresh element \"{}\"", elt.id())
+                    }
+                };
+            });
+        }
+        
+        // request a realization to bring the configuration back onto the
+        // solution variety. this also gets the elements' column indices and the
+        // saved tangent space back in sync
+        self.needs_realization.set(true);
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    
+    use crate::engine;
+    
+    #[test]
+    #[should_panic(expected = "Sphere \"sphere\" should be indexed before writing problem data")]
+    fn unindexed_element_test() {
+        let _ = create_root(|| {
+            let elt = Sphere::default("sphere".to_string(), 0);
+            elt.pose(&mut ConstraintProblem::new(1));
+        });
+    }
+    
+    #[test]
+    #[should_panic(expected = "Subjects should be indexed before inversive distance regulator writes problem data")]
+    fn unindexed_subject_test_inversive_distance() {
+        let _ = create_root(|| {
+            let subjects = [0, 1].map(
+                |k| Rc::new(Sphere::default(format!("sphere{k}"), k)) as Rc<dyn Element>
+            );
+            subjects[0].set_column_index(0);
+            InversiveDistanceRegulator {
+                subjects: subjects,
+                measurement: create_memo(|| 0.0),
+                set_point: create_signal(SpecifiedValue::try_from("0.0".to_string()).unwrap()),
+                serial: InversiveDistanceRegulator::next_serial()
+            }.pose(&mut ConstraintProblem::new(2));
+        });
+    }
+    
+    #[test]
+    fn curvature_drift_test() {
+        const INITIAL_RADIUS: f64 = 0.25;
+        let _ = create_root(|| {
+            // set up an assembly containing a single sphere centered at the
+            // origin
+            let assembly = Assembly::new();
+            let sphere_id = "sphere0";
+            let _ = assembly.try_insert_element(
+                // we create the sphere by hand for two reasons: to choose the
+                // curvature (which can affect drift rate) and to make the test
+                // independent of `Sphere::default`
+                Sphere::new(
+                    String::from(sphere_id),
+                    String::from("Sphere 0"),
+                    [0.75_f32, 0.75_f32, 0.75_f32],
+                    engine::sphere(0.0, 0.0, 0.0, INITIAL_RADIUS)
+                )
+            );
+            
+            // nudge the sphere repeatedly along the `z` axis
+            const STEP_SIZE: f64 = 0.0025;
+            const STEP_CNT: usize = 400;
+            let sphere = assembly.elements_by_id.with(|elts_by_id| elts_by_id[sphere_id].clone());
+            let velocity = DVector::from_column_slice(&[0.0, 0.0, STEP_SIZE, 0.0]);
+            for _ in 0..STEP_CNT {
+                assembly.deform(
+                    vec![
+                        ElementMotion {
+                            element: sphere.clone(),
+                            velocity: velocity.as_view()
+                        }
+                    ]
+                );
+            }
+            
+            // check how much the sphere's curvature has drifted
+            const INITIAL_HALF_CURV: f64 = 0.5 / INITIAL_RADIUS;
+            const DRIFT_TOL: f64 = 0.015;
+            let final_half_curv = sphere.representation().with_untracked(
+                |rep| rep[Sphere::CURVATURE_COMPONENT]
+            );
+            assert!((final_half_curv / INITIAL_HALF_CURV - 1.0).abs() < DRIFT_TOL);
+        });
+    }
+}

app-proto/src/components.rs

@@ -0,0 +1,5 @@
+pub mod add_remove;
+pub mod diagnostics;
+pub mod display;
+pub mod outline;
+pub mod test_assembly_chooser;

app-proto/src/components/add_remove.rs

@@ -0,0 +1,54 @@
+use std::rc::Rc;
+use sycamore::prelude::*;
+
+use super::test_assembly_chooser::TestAssemblyChooser;
+use crate::{
+    AppState,
+    assembly::{InversiveDistanceRegulator, Point, Sphere}
+};
+
+#[component]
+pub fn AddRemove() -> View {
+    view! {
+        div(id="add-remove") {
+            button(
+                on:click=|_| {
+                    let state = use_context::<AppState>();
+                    state.assembly.insert_element_default::<Sphere>();
+                }
+            ) { "Add sphere" }
+            button(
+                on:click=|_| {
+                    let state = use_context::<AppState>();
+                    state.assembly.insert_element_default::<Point>();
+                }
+            ) { "Add point" }
+            button(
+                class="emoji", /* KLUDGE */ // for convenience, we're using an emoji as a temporary icon for this button
+                disabled={
+                    let state = use_context::<AppState>();
+                    state.selection.with(|sel| sel.len() != 2)
+                },
+                on:click=|_| {
+                    let state = use_context::<AppState>();
+                    let subjects: [_; 2] = state.selection.with(
+                        // the button is only enabled when two elements are
+                        // selected, so we know the cast to a two-element array
+                        // will succeed
+                        |sel| sel
+                            .clone()
+                            .into_iter()
+                            .collect::<Vec<_>>()
+                            .try_into()
+                            .unwrap()
+                    );
+                    state.assembly.insert_regulator(
+                        Rc::new(InversiveDistanceRegulator::new(subjects))
+                    );
+                    state.selection.update(|sel| sel.clear());
+                }
+            ) { "🔗" }
+            TestAssemblyChooser {}
+        }
+    }
+}

app-proto/src/components/diagnostics.rs

@@ -0,0 +1,258 @@
+use charming::{
+    Chart,
+    WasmRenderer,
+    component::{Axis, DataZoom, Grid},
+    element::{AxisType, Symbol},
+    series::{Line, Scatter},
+};
+use sycamore::prelude::*;
+
+use crate::AppState;
+
+#[derive(Clone)]
+struct DiagnosticsState {
+    active_tab: Signal<String>
+}
+
+impl DiagnosticsState {
+    fn new(initial_tab: String) -> DiagnosticsState {
+        DiagnosticsState {
+            active_tab: create_signal(initial_tab)
+        }
+    }
+}
+
+// a realization status indicator
+#[component]
+fn RealizationStatus() -> View {
+    let state = use_context::<AppState>();
+    let realization_status = state.assembly.realization_status;
+    view! {
+        div(
+            id="realization-status",
+            class=realization_status.with(
+                |status| match status {
+                    Ok(_) => "",
+                    Err(_) => "invalid"
+                }
+            )
+        ) {
+            div(class="status")
+            div {
+                (realization_status.with(
+                    |status| match status {
+                        Ok(_) => "Target accuracy achieved".to_string(),
+                        Err(message) => message.clone()
+                    }
+                ))
+            }
+        }
+    }
+}
+
+fn into_log10_time_point((step, value): (usize, f64)) -> Vec<Option<f64>> {
+    vec![
+        Some(step as f64),
+        if value == 0.0 { None } else { Some(value.abs().log10()) }
+    ]
+}
+
+// the loss history from the last realization
+#[component]
+fn LossHistory() -> View {
+    const CONTAINER_ID: &str = "loss-history";
+    let state = use_context::<AppState>();
+    let renderer = WasmRenderer::new_opt(None, Some(178));
+    
+    on_mount(move || {
+        create_effect(move || {
+            // get the loss history
+            let scaled_loss: Vec<_> = state.assembly.descent_history.with(
+                |history| history.scaled_loss
+                    .iter()
+                    .enumerate()
+                    .map(|(step, &loss)| (step, loss))
+                    .map(into_log10_time_point)
+                    .collect()
+            );
+            
+            // initialize the chart axes
+            let step_axis = Axis::new()
+                .type_(AxisType::Category)
+                .boundary_gap(false);
+            let scaled_loss_axis = Axis::new();
+            
+            // load the chart data. when there's no history, we load the data
+            // point (0, None) to clear the chart. it would feel more natural to
+            // load empty data vectors, but that turns out not to clear the
+            // chart: it instead leads to previous data being re-used
+            let scaled_loss_series = Line::new().data(
+                if scaled_loss.len() > 0 {
+                    scaled_loss
+                } else {
+                    vec![vec![Some(0.0), None::<f64>]]
+                }
+            );
+            let chart = Chart::new()
+                .animation(false)
+                .data_zoom(DataZoom::new().y_axis_index(0).right(40))
+                .x_axis(step_axis)
+                .y_axis(scaled_loss_axis)
+                .grid(Grid::new().top(20).right(80).bottom(30).left(60))
+                .series(scaled_loss_series);
+            renderer.render(CONTAINER_ID, &chart).unwrap();
+        });
+    });
+    
+    view! {
+        div(id=CONTAINER_ID, class="diagnostics-chart")
+    }
+}
+
+// the spectrum of the Hessian during the last realization
+#[component]
+fn SpectrumHistory() -> View {
+    const CONTAINER_ID: &str = "spectrum-history";
+    let state = use_context::<AppState>();
+    let renderer = WasmRenderer::new(478, 178);
+    
+    on_mount(move || {
+        create_effect(move || {
+            // get the spectrum of the Hessian at each step, split into its
+            // positive, negative, and strictly-zero parts
+            let (
+                hess_eigvals_zero,
+                hess_eigvals_nonzero
+            ): (Vec<_>, Vec<_>) = state.assembly.descent_history.with(
+                |history| history.hess_eigvals
+                    .iter()
+                    .enumerate()
+                    .map(
+                        |(step, eigvals)| eigvals.iter().map(
+                            move |&val| (step, val)
+                        )
+                    )
+                    .flatten()
+                    .partition(|&(_, val)| val == 0.0)
+            );
+            let zero_level = hess_eigvals_nonzero
+                .iter()
+                .map(|(_, val)| val.abs())
+                .reduce(f64::min)
+                .map(|val| 0.1 * val)
+                .unwrap_or(1.0);
+            let (
+                hess_eigvals_pos,
+                hess_eigvals_neg
+            ): (Vec<_>, Vec<_>) = hess_eigvals_nonzero
+                .into_iter()
+                .partition(|&(_, val)| val > 0.0);
+            
+            // initialize the chart axes
+            let step_axis = Axis::new()
+                .type_(AxisType::Category)
+                .boundary_gap(false);
+            let eigval_axis = Axis::new();
+            
+            // load the chart data. when there's no history, we load the data
+            // point (0, None) to clear the chart. it would feel more natural to
+            // load empty data vectors, but that turns out not to clear the
+            // chart: it instead leads to previous data being re-used
+            let eigval_series_pos = Scatter::new()
+                .symbol_size(4.5)
+                .data(
+                    if hess_eigvals_pos.len() > 0 {
+                        hess_eigvals_pos
+                            .into_iter()
+                            .map(into_log10_time_point)
+                            .collect()
+                    } else {
+                        vec![vec![Some(0.0), None::<f64>]]
+                    }
+                );
+            let eigval_series_neg = Scatter::new()
+                .symbol(Symbol::Diamond)
+                .symbol_size(6.0)
+                .data(
+                    if hess_eigvals_neg.len() > 0 {
+                        hess_eigvals_neg
+                            .into_iter()
+                            .map(into_log10_time_point)
+                            .collect()
+                    } else {
+                        vec![vec![Some(0.0), None::<f64>]]
+                    }
+                );
+            let eigval_series_zero = Scatter::new()
+                .symbol(Symbol::Triangle)
+                .symbol_size(5.0)
+                .data(
+                    if hess_eigvals_zero.len() > 0 {
+                        hess_eigvals_zero
+                            .into_iter()
+                            .map(|(step, _)| (step, zero_level))
+                            .map(into_log10_time_point)
+                            .collect()
+                    } else {
+                        vec![vec![Some(0.0), None::<f64>]]
+                    }
+                );
+            let chart = Chart::new()
+                .animation(false)
+                .data_zoom(DataZoom::new().y_axis_index(0).right(40))
+                .x_axis(step_axis)
+                .y_axis(eigval_axis)
+                .grid(Grid::new().top(20).right(80).bottom(30).left(60))
+                .series(eigval_series_pos)
+                .series(eigval_series_neg)
+                .series(eigval_series_zero);
+            renderer.render(CONTAINER_ID, &chart).unwrap();
+        });
+    });
+    
+    view! {
+        div(id=CONTAINER_ID, class="diagnostics-chart")
+    }
+}
+
+#[component(inline_props)]
+fn DiagnosticsPanel(name: &'static str, children: Children) -> View {
+    let diagnostics_state = use_context::<DiagnosticsState>();
+    view! {
+        div(
+            class="diagnostics-panel",
+            "hidden"=diagnostics_state.active_tab.with(
+                |active_tab| {
+                    if active_tab == name {
+                        None
+                    } else {
+                        Some("")
+                    }
+                }
+            )
+        ) {
+            (children)
+        }
+    }
+}
+
+#[component]
+pub fn Diagnostics() -> View {
+    let diagnostics_state = DiagnosticsState::new("loss".to_string());
+    let active_tab = diagnostics_state.active_tab.clone();
+    provide_context(diagnostics_state);
+    
+    view! {
+        div(id="diagnostics") {
+            div(id="diagnostics-bar") {
+                RealizationStatus {}
+                select(bind:value=active_tab) {
+                    option(value="loss") { "Loss" }
+                    option(value="spectrum") { "Spectrum" }
+                }
+            }
+            DiagnosticsPanel(name="loss") { LossHistory {} }
+            DiagnosticsPanel(name="spectrum") { SpectrumHistory {} }
+        }
+    }
+}

app-proto/src/components/display.rs

@@ -0,0 +1,900 @@
+use core::array;
+use nalgebra::{DMatrix, DVector, Rotation3, Vector3};
+use std::rc::Rc;
+use sycamore::{prelude::*, motion::create_raf};
+use web_sys::{
+    console,
+    window,
+    KeyboardEvent,
+    MouseEvent,
+    WebGl2RenderingContext,
+    WebGlBuffer,
+    WebGlProgram,
+    WebGlShader,
+    WebGlUniformLocation,
+    wasm_bindgen::{JsCast, JsValue}
+};
+
+use crate::{
+    AppState,
+    assembly::{Element, ElementColor, ElementMotion, Point, Sphere}
+};
+
+// --- color ---
+
+const COLOR_SIZE: usize = 3;
+type ColorWithOpacity = [f32; COLOR_SIZE + 1];
+
+fn combine_channels(color: ElementColor, opacity: f32) -> ColorWithOpacity {
+    let mut color_with_opacity = [0.0; COLOR_SIZE + 1];
+    color_with_opacity[..COLOR_SIZE].copy_from_slice(&color);
+    color_with_opacity[COLOR_SIZE] = opacity;
+    color_with_opacity
+}
+
+// --- scene data ---
+
+struct SceneSpheres {
+    representations: Vec<DVector<f64>>,
+    colors_with_opacity: Vec<ColorWithOpacity>,
+    highlights: Vec<f32>
+}
+
+impl SceneSpheres {
+    fn new() -> SceneSpheres{
+        SceneSpheres {
+            representations: Vec::new(),
+            colors_with_opacity: Vec::new(),
+            highlights: Vec::new()
+        }
+    }
+    
+    fn len_i32(&self) -> i32 {
+        self.representations.len().try_into().expect("Number of spheres must fit in a 32-bit integer")
+    }
+    
+    fn push(&mut self, representation: DVector<f64>, color: ElementColor, opacity: f32, highlight: f32) {
+        self.representations.push(representation);
+        self.colors_with_opacity.push(combine_channels(color, opacity));
+        self.highlights.push(highlight);
+    }
+}
+
+struct ScenePoints {
+    representations: Vec<DVector<f64>>,
+    colors_with_opacity: Vec<ColorWithOpacity>,
+    highlights: Vec<f32>,
+    selections: Vec<f32>
+}
+
+impl ScenePoints {
+    fn new() -> ScenePoints {
+        ScenePoints {
+            representations: Vec::new(),
+            colors_with_opacity: Vec::new(),
+            highlights: Vec::new(),
+            selections: Vec::new()
+        }
+    }
+    
+    fn push(&mut self, representation: DVector<f64>, color: ElementColor, opacity: f32, highlight: f32, selected: bool) {
+        self.representations.push(representation);
+        self.colors_with_opacity.push(combine_channels(color, opacity));
+        self.highlights.push(highlight);
+        self.selections.push(if selected { 1.0 } else { 0.0 });
+    }
+}
+
+pub struct Scene {
+    spheres: SceneSpheres,
+    points: ScenePoints
+}
+
+impl Scene {
+    fn new() -> Scene {
+        Scene {
+            spheres: SceneSpheres::new(),
+            points: ScenePoints::new()
+        }
+    }
+}
+
+pub trait DisplayItem {
+    fn show(&self, scene: &mut Scene, selected: bool);
+    
+    // the smallest positive depth, represented as a multiple of `dir`, where
+    // the line generated by `dir` hits the element. returns `None` if the line
+    // misses the element
+    fn cast(&self, dir: Vector3<f64>, assembly_to_world: &DMatrix<f64>, pixel_size: f64) -> Option<f64>;
+}
+
+impl DisplayItem for Sphere {
+    fn show(&self, scene: &mut Scene, selected: bool) {
+        /* SCAFFOLDING */
+        const DEFAULT_OPACITY: f32 = 0.5;
+        const GHOST_OPACITY: f32 = 0.2;
+        const HIGHLIGHT: f32 = 0.2;
+        
+        let representation = self.representation.get_clone_untracked();
+        let color = if selected { self.color.map(|channel| 0.2 + 0.8*channel) } else { self.color };
+        let opacity = if self.ghost.get() { GHOST_OPACITY } else { DEFAULT_OPACITY };
+        let highlight = if selected { 1.0 } else { HIGHLIGHT };
+        scene.spheres.push(representation, color, opacity, highlight);
+    }
+    
+    // this method should be kept synchronized with `sphere_cast` in
+    // `spheres.frag`, which does essentially the same thing on the GPU side
+    fn cast(&self, dir: Vector3<f64>, assembly_to_world: &DMatrix<f64>, _pixel_size: f64) -> Option<f64> {
+        // if `a/b` is less than this threshold, we approximate
+        // `a*u^2 + b*u + c` by the linear function `b*u + c`
+        const DEG_THRESHOLD: f64 = 1e-9;
+        
+        let rep = self.representation.with_untracked(|rep| assembly_to_world * rep);
+        let a = -rep[3] * dir.norm_squared();
+        let b = rep.rows_range(..3).dot(&dir);
+        let c = -rep[4];
+        
+        let adjust = 4.0*a*c/(b*b);
+        if adjust < 1.0 {
+            // as long as `b` is non-zero, the linear approximation of
+            //
+            //   a*u^2 + b*u + c
+            //
+            // at `u = 0` will reach zero at a finite depth `u_lin`. the root of
+            // the quadratic adjacent to `u_lin` is stored in `lin_root`. if
+            // both roots have the same sign, `lin_root` will be the one closer
+            // to `u = 0`
+            let square_rect_ratio = 1.0 + (1.0 - adjust).sqrt();
+            let lin_root = -(2.0*c)/b / square_rect_ratio;
+            if a.abs() > DEG_THRESHOLD * b.abs() {
+                if lin_root > 0.0 {
+                    Some(lin_root)
+                } else {
+                    let other_root = -b/(2.*a) * square_rect_ratio;
+                    (other_root > 0.0).then_some(other_root)
+                }
+            } else {
+                (lin_root > 0.0).then_some(lin_root)
+            }
+        } else {
+            // the line through `dir` misses the sphere completely
+            None
+        }
+    }
+}
+
+impl DisplayItem for Point {
+    fn show(&self, scene: &mut Scene, selected: bool) {
+        /* SCAFFOLDING */
+        const GHOST_OPACITY: f32 = 0.4;
+        const HIGHLIGHT: f32 = 0.5;
+        
+        let representation = self.representation.get_clone_untracked();
+        let color = if selected { self.color.map(|channel| 0.2 + 0.8*channel) } else { self.color };
+        let opacity = if self.ghost.get() { GHOST_OPACITY } else { 1.0 };
+        let highlight = if selected { 1.0 } else { HIGHLIGHT };
+        scene.points.push(representation, color, opacity, highlight, selected);
+    }
+    
+    /* SCAFFOLDING */
+    fn cast(&self, dir: Vector3<f64>, assembly_to_world: &DMatrix<f64>, pixel_size: f64) -> Option<f64> {
+        let rep = self.representation.with_untracked(|rep| assembly_to_world * rep);
+        if rep[2] < 0.0 {
+            // this constant should be kept synchronized with `point.frag`
+            const POINT_RADIUS_PX: f64 = 4.0;
+            
+            // find the radius of the point in screen projection units
+            let point_radius_proj = POINT_RADIUS_PX * pixel_size;
+            
+            // find the squared distance between the screen projections of the
+            // ray and the point
+            let dir_proj = -dir.fixed_rows::<2>(0) / dir[2];
+            let rep_proj = -rep.fixed_rows::<2>(0) / rep[2];
+            let dist_sq = (dir_proj - rep_proj).norm_squared();
+            
+            // if the ray hits the point, return its depth
+            if dist_sq < point_radius_proj * point_radius_proj {
+                Some(rep[2] / dir[2])
+            } else {
+                None
+            }
+        } else {
+            None
+        }
+    }
+}
+
+// --- WebGL utilities ---
+
+fn compile_shader(
+    context: &WebGl2RenderingContext,
+    shader_type: u32,
+    source: &str,
+) -> WebGlShader {
+    let shader = context.create_shader(shader_type).unwrap();
+    context.shader_source(&shader, source);
+    context.compile_shader(&shader);
+    shader
+}
+
+fn set_up_program(
+    context: &WebGl2RenderingContext,
+    vertex_shader_source: &str,
+    fragment_shader_source: &str
+) -> WebGlProgram {
+    // compile the shaders
+    let vertex_shader = compile_shader(
+        &context,
+        WebGl2RenderingContext::VERTEX_SHADER,
+        vertex_shader_source,
+    );
+    let fragment_shader = compile_shader(
+        &context,
+        WebGl2RenderingContext::FRAGMENT_SHADER,
+        fragment_shader_source,
+    );
+    
+    // create the program and attach the shaders
+    let program = context.create_program().unwrap();
+    context.attach_shader(&program, &vertex_shader);
+    context.attach_shader(&program, &fragment_shader);
+    context.link_program(&program);
+    
+    /* DEBUG */
+    // report whether linking succeeded
+    let link_status = context
+        .get_program_parameter(&program, WebGl2RenderingContext::LINK_STATUS)
+        .as_bool()
+        .unwrap();
+    let link_msg = if link_status {
+        "Linked successfully"
+    } else {
+        "Linking failed"
+    };
+    console::log_1(&JsValue::from(link_msg));
+    
+    program
+}
+
+fn get_uniform_array_locations<const N: usize>(
+    context: &WebGl2RenderingContext,
+    program: &WebGlProgram,
+    var_name: &str,
+    member_name_opt: Option<&str>
+) -> [Option<WebGlUniformLocation>; N] {
+    array::from_fn(|n| {
+        let name = match member_name_opt {
+            Some(member_name) => format!("{var_name}[{n}].{member_name}"),
+            None => format!("{var_name}[{n}]")
+        };
+        context.get_uniform_location(&program, name.as_str())
+    })
+}
+
+// bind the given vertex buffer object to the given vertex attribute
+fn bind_to_attribute(
+    context: &WebGl2RenderingContext,
+    attr_index: u32,
+    attr_size: i32,
+    buffer: &Option<WebGlBuffer>
+) {
+    context.bind_buffer(WebGl2RenderingContext::ARRAY_BUFFER, buffer.as_ref());
+    context.vertex_attrib_pointer_with_i32(
+        attr_index,
+        attr_size,
+        WebGl2RenderingContext::FLOAT,
+        false, // don't normalize
+        0, // zero stride
+        0, // zero offset
+    );
+}
+
+// load the given data into a new vertex buffer object
+fn load_new_buffer(
+    context: &WebGl2RenderingContext,
+    data: &[f32]
+) -> Option<WebGlBuffer> {
+    // create a buffer and bind it to ARRAY_BUFFER
+    let buffer = context.create_buffer();
+    context.bind_buffer(WebGl2RenderingContext::ARRAY_BUFFER, buffer.as_ref());
+    
+    // load the given data into the buffer. this block is unsafe because
+    // `Float32Array::view` creates a raw view into our module's
+    // `WebAssembly.Memory` buffer. allocating more memory will change the
+    // buffer, invalidating the view, so we have to make sure we don't allocate
+    // any memory until the view is dropped. we're okay here because the view is
+    // used as soon as it's created
+    unsafe {
+        context.buffer_data_with_array_buffer_view(
+            WebGl2RenderingContext::ARRAY_BUFFER,
+            &js_sys::Float32Array::view(&data),
+            WebGl2RenderingContext::STATIC_DRAW,
+        );
+    }
+    
+    buffer
+}
+
+fn bind_new_buffer_to_attribute(
+    context: &WebGl2RenderingContext,
+    attr_index: u32,
+    attr_size: i32,
+    data: &[f32]
+) {
+    let buffer = load_new_buffer(context, data);
+    bind_to_attribute(context, attr_index, attr_size, &buffer);
+}
+
+// the direction in camera space that a mouse event is pointing along
+fn event_dir(event: &MouseEvent) -> (Vector3<f64>, f64) {
+    let target: web_sys::Element = event.target().unwrap().unchecked_into();
+    let rect = target.get_bounding_client_rect();
+    let width = rect.width();
+    let height = rect.height();
+    let shortdim = width.min(height);
+    
+    // this constant should be kept synchronized with `spheres.frag` and
+    // `point.vert`
+    const FOCAL_SLOPE: f64 = 0.3;
+    
+    (
+        Vector3::new(
+            FOCAL_SLOPE * (2.0*(f64::from(event.client_x()) - rect.left()) - width) / shortdim,
+            FOCAL_SLOPE * (2.0*(rect.bottom() - f64::from(event.client_y())) - height) / shortdim,
+            -1.0
+        ),
+        FOCAL_SLOPE * 2.0 / shortdim
+    )
+}
+
+// --- display component ---
+
+#[component]
+pub fn Display() -> View {
+    let state = use_context::<AppState>();
+    
+    // canvas
+    let display = create_node_ref();
+    
+    // viewpoint
+    let assembly_to_world = create_signal(DMatrix::<f64>::identity(5, 5));
+    
+    // navigation
+    let pitch_up = create_signal(0.0);
+    let pitch_down = create_signal(0.0);
+    let yaw_right = create_signal(0.0);
+    let yaw_left = create_signal(0.0);
+    let roll_ccw = create_signal(0.0);
+    let roll_cw = create_signal(0.0);
+    let zoom_in = create_signal(0.0);
+    let zoom_out = create_signal(0.0);
+    let turntable = create_signal(false); /* BENCHMARKING */
+    
+    // manipulation
+    let translate_neg_x = create_signal(0.0);
+    let translate_pos_x = create_signal(0.0);
+    let translate_neg_y = create_signal(0.0);
+    let translate_pos_y = create_signal(0.0);
+    let translate_neg_z = create_signal(0.0);
+    let translate_pos_z = create_signal(0.0);
+    let shrink_neg = create_signal(0.0);
+    let shrink_pos = create_signal(0.0);
+    
+    // change listener
+    let scene_changed = create_signal(true);
+    create_effect(move || {
+        state.assembly.elements.with(|elts| {
+            for elt in elts {
+                elt.representation().track();
+                elt.ghost().track();
+            }
+        });
+        state.selection.track();
+        scene_changed.set(true);
+    });
+    
+    /* INSTRUMENTS */
+    const SAMPLE_PERIOD: i32 = 60;
+    let mut last_sample_time = 0.0;
+    let mut frames_since_last_sample = 0;
+    let mean_frame_interval = create_signal(0.0);
+    
+    let assembly_for_raf = state.assembly.clone();
+    on_mount(move || {
+        // timing
+        let mut last_time = 0.0;
+        
+        // viewpoint
+        const ROT_SPEED: f64 = 0.4; // in radians per second
+        const ZOOM_SPEED: f64 = 0.15; // multiplicative rate per second
+        const TURNTABLE_SPEED: f64 = 0.1; /* BENCHMARKING */
+        let mut orientation = DMatrix::<f64>::identity(5, 5);
+        let mut rotation = DMatrix::<f64>::identity(5, 5);
+        let mut location_z: f64 = 5.0;
+        
+        // manipulation
+        const TRANSLATION_SPEED: f64 = 0.15; // in length units per second
+        const SHRINKING_SPEED: f64 = 0.15; // in length units per second
+        
+        // display parameters
+        const LAYER_THRESHOLD: i32 = 0; /* DEBUG */
+        const DEBUG_MODE: i32 = 0; /* DEBUG */
+        
+        /* INSTRUMENTS */
+        let performance = window().unwrap().performance().unwrap();
+        
+        // get the display canvas
+        let canvas = display.get().unchecked_into::<web_sys::HtmlCanvasElement>();
+        let ctx = canvas
+            .get_context("webgl2")
+            .unwrap()
+            .unwrap()
+            .dyn_into::<WebGl2RenderingContext>()
+            .unwrap();
+        
+        // disable depth testing
+        ctx.disable(WebGl2RenderingContext::DEPTH_TEST);
+        
+        // set blend mode
+        ctx.enable(WebGl2RenderingContext::BLEND);
+        ctx.blend_func(WebGl2RenderingContext::SRC_ALPHA, WebGl2RenderingContext::ONE_MINUS_SRC_ALPHA);
+        
+        // set up the sphere rendering program
+        let sphere_program = set_up_program(
+            &ctx,
+            include_str!("identity.vert"),
+            include_str!("spheres.frag")
+        );
+        
+        // set up the point rendering program
+        let point_program = set_up_program(
+            &ctx,
+            include_str!("point.vert"),
+            include_str!("point.frag")
+        );
+        
+        /* DEBUG */
+        // print the maximum number of vectors that can be passed as
+        // uniforms to a fragment shader. the OpenGL ES 3.0 standard
+        // requires this maximum to be at least 224, as discussed in the
+        // documentation of the GL_MAX_FRAGMENT_UNIFORM_VECTORS parameter
+        // here:
+        //
+        //   https://registry.khronos.org/OpenGL-Refpages/es3.0/html/glGet.xhtml
+        //
+        // there are also other size limits. for example, on Aaron's
+        // machine, the the length of a float or genType array seems to be
+        // capped at 1024 elements
+        console::log_2(
+            &ctx.get_parameter(WebGl2RenderingContext::MAX_FRAGMENT_UNIFORM_VECTORS).unwrap(),
+            &JsValue::from("uniform vectors available")
+        );
+        
+        // find the sphere program's vertex attribute
+        let viewport_position_attr = ctx.get_attrib_location(&sphere_program, "position") as u32;
+        
+        // find the sphere program's uniforms
+        const SPHERE_MAX: usize = 200;
+        let sphere_cnt_loc = ctx.get_uniform_location(&sphere_program, "sphere_cnt");
+        let sphere_sp_locs = get_uniform_array_locations::<SPHERE_MAX>(
+            &ctx, &sphere_program, "sphere_list", Some("sp")
+        );
+        let sphere_lt_locs = get_uniform_array_locations::<SPHERE_MAX>(
+            &ctx, &sphere_program, "sphere_list", Some("lt")
+        );
+        let sphere_color_locs = get_uniform_array_locations::<SPHERE_MAX>(
+            &ctx, &sphere_program, "color_list", None
+        );
+        let sphere_highlight_locs = get_uniform_array_locations::<SPHERE_MAX>(
+            &ctx, &sphere_program, "highlight_list", None
+        );
+        let resolution_loc = ctx.get_uniform_location(&sphere_program, "resolution");
+        let shortdim_loc = ctx.get_uniform_location(&sphere_program, "shortdim");
+        let layer_threshold_loc = ctx.get_uniform_location(&sphere_program, "layer_threshold");
+        let debug_mode_loc = ctx.get_uniform_location(&sphere_program, "debug_mode");
+        
+        // load the viewport vertex positions into a new vertex buffer object
+        const VERTEX_CNT: usize = 6;
+        let viewport_positions: [f32; 3*VERTEX_CNT] = [
+            // northwest triangle
+            -1.0, -1.0, 0.0,
+            -1.0,  1.0, 0.0,
+             1.0,  1.0, 0.0,
+            // southeast triangle
+            -1.0, -1.0, 0.0,
+             1.0,  1.0, 0.0,
+             1.0, -1.0, 0.0
+        ];
+        let viewport_position_buffer = load_new_buffer(&ctx, &viewport_positions);
+        
+        // find the point program's vertex attributes
+        let point_position_attr = ctx.get_attrib_location(&point_program, "position") as u32;
+        let point_color_attr = ctx.get_attrib_location(&point_program, "color") as u32;
+        let point_highlight_attr = ctx.get_attrib_location(&point_program, "highlight") as u32;
+        let point_selection_attr = ctx.get_attrib_location(&point_program, "selected") as u32;
+        
+        // set up a repainting routine
+        let (_, start_animation_loop, _) = create_raf(move || {
+            // get the time step
+            let time = performance.now();
+            let time_step = 0.001*(time - last_time);
+            last_time = time;
+            
+            // get the navigation state
+            let pitch_up_val = pitch_up.get();
+            let pitch_down_val = pitch_down.get();
+            let yaw_right_val = yaw_right.get();
+            let yaw_left_val = yaw_left.get();
+            let roll_ccw_val = roll_ccw.get();
+            let roll_cw_val = roll_cw.get();
+            let zoom_in_val = zoom_in.get();
+            let zoom_out_val = zoom_out.get();
+            let turntable_val = turntable.get(); /* BENCHMARKING */
+            
+            // get the manipulation state
+            let translate_neg_x_val = translate_neg_x.get();
+            let translate_pos_x_val = translate_pos_x.get();
+            let translate_neg_y_val = translate_neg_y.get();
+            let translate_pos_y_val = translate_pos_y.get();
+            let translate_neg_z_val = translate_neg_z.get();
+            let translate_pos_z_val = translate_pos_z.get();
+            let shrink_neg_val = shrink_neg.get();
+            let shrink_pos_val = shrink_pos.get();
+            
+            // update the assembly's orientation
+            let ang_vel = {
+                let pitch = pitch_up_val - pitch_down_val;
+                let yaw = yaw_right_val - yaw_left_val;
+                let roll = roll_ccw_val - roll_cw_val;
+                if pitch != 0.0 || yaw != 0.0 || roll != 0.0 {
+                    ROT_SPEED * Vector3::new(-pitch, yaw, roll).normalize()
+                } else {
+                    Vector3::zeros()
+                }
+            } /* BENCHMARKING */ + if turntable_val {
+                Vector3::new(0.0, TURNTABLE_SPEED, 0.0)
+            } else {
+                Vector3::zeros()
+            };
+            let mut rotation_sp = rotation.fixed_view_mut::<3, 3>(0, 0);
+            rotation_sp.copy_from(
+                Rotation3::from_scaled_axis(time_step * ang_vel).matrix()
+            );
+            orientation = &rotation * &orientation;
+            
+            // update the assembly's location
+            let zoom = zoom_out_val - zoom_in_val;
+            location_z *= (time_step * ZOOM_SPEED * zoom).exp();
+            
+            // manipulate the assembly
+            if state.selection.with(|sel| sel.len() == 1) {
+                let sel = state.selection.with(
+                    |sel| sel.into_iter().next().unwrap().clone()
+                );
+                let translate_x = translate_pos_x_val - translate_neg_x_val;
+                let translate_y = translate_pos_y_val - translate_neg_y_val;
+                let translate_z = translate_pos_z_val - translate_neg_z_val;
+                let shrink = shrink_pos_val - shrink_neg_val;
+                let translating =
+                    translate_x != 0.0
+                    || translate_y != 0.0
+                    || translate_z != 0.0;
+                if translating || shrink != 0.0 {
+                    let elt_motion = {
+                        let u = if translating {
+                            TRANSLATION_SPEED * Vector3::new(
+                                translate_x, translate_y, translate_z
+                            ).normalize()
+                        } else {
+                            Vector3::zeros()
+                        };
+                        time_step * DVector::from_column_slice(
+                            &[u[0], u[1], u[2], SHRINKING_SPEED * shrink]
+                        )
+                    };
+                    assembly_for_raf.deform(
+                        vec![
+                            ElementMotion {
+                                element: sel,
+                                velocity: elt_motion.as_view()
+                            }
+                        ]
+                    );
+                    scene_changed.set(true);
+                }
+            }
+            
+            if scene_changed.get() {
+                const SPACE_DIM: usize = 3;
+                const COLOR_SIZE: usize = 3;
+                
+                /* INSTRUMENTS */
+                // measure mean frame interval
+                frames_since_last_sample += 1;
+                if frames_since_last_sample >= SAMPLE_PERIOD {
+                    mean_frame_interval.set((time - last_sample_time) / (SAMPLE_PERIOD as f64));
+                    last_sample_time = time;
+                    frames_since_last_sample = 0;
+                }
+                
+                // --- get the assembly ---
+                
+                let mut scene = Scene::new();
+                
+                // find the map from assembly space to world space
+                let location = {
+                    let u = -location_z;
+                    DMatrix::from_column_slice(5, 5, &[
+                        1.0, 0.0,   0.0, 0.0, 0.0,
+                        0.0, 1.0,   0.0, 0.0, 0.0,
+                        0.0, 0.0,   1.0, 0.0,   u,
+                        0.0, 0.0, 2.0*u, 1.0, u*u,
+                        0.0, 0.0,   0.0, 0.0, 1.0
+                    ])
+                };
+                let asm_to_world = &location * &orientation;
+                
+                // set up the scene
+                state.assembly.elements.with_untracked(
+                    |elts| for elt in elts {
+                        let selected = state.selection.with(|sel| sel.contains(elt));
+                        elt.show(&mut scene, selected);
+                    }
+                );
+                let sphere_cnt = scene.spheres.len_i32();
+                
+                // --- draw the spheres ---
+                
+                // use the sphere rendering program
+                ctx.use_program(Some(&sphere_program));
+                
+                // enable the sphere program's vertex attribute
+                ctx.enable_vertex_attrib_array(viewport_position_attr);
+                
+                // write the spheres in world coordinates
+                let sphere_reps_world: Vec<_> = scene.spheres.representations.into_iter().map(
+                    |rep| (&asm_to_world * rep).cast::<f32>()
+                ).collect();
+                
+                // set the resolution
+                let width = canvas.width() as f32;
+                let height = canvas.height() as f32;
+                ctx.uniform2f(resolution_loc.as_ref(), width, height);
+                ctx.uniform1f(shortdim_loc.as_ref(), width.min(height));
+                
+                // pass the scene data
+                ctx.uniform1i(sphere_cnt_loc.as_ref(), sphere_cnt);
+                for n in 0..sphere_reps_world.len() {
+                    let v = &sphere_reps_world[n];
+                    ctx.uniform3fv_with_f32_array(
+                        sphere_sp_locs[n].as_ref(),
+                        v.rows(0, 3).as_slice()
+                    );
+                    ctx.uniform2fv_with_f32_array(
+                        sphere_lt_locs[n].as_ref(),
+                        v.rows(3, 2).as_slice()
+                    );
+                    ctx.uniform4fv_with_f32_array(
+                        sphere_color_locs[n].as_ref(),
+                        &scene.spheres.colors_with_opacity[n]
+                    );
+                    ctx.uniform1f(
+                        sphere_highlight_locs[n].as_ref(),
+                        scene.spheres.highlights[n]
+                    );
+                }
+                
+                // pass the display parameters
+                ctx.uniform1i(layer_threshold_loc.as_ref(), LAYER_THRESHOLD);
+                ctx.uniform1i(debug_mode_loc.as_ref(), DEBUG_MODE);
+                
+                // bind the viewport vertex position buffer to the position
+                // attribute in the vertex shader
+                bind_to_attribute(&ctx, viewport_position_attr, SPACE_DIM as i32, &viewport_position_buffer);
+                
+                // draw the scene
+                ctx.draw_arrays(WebGl2RenderingContext::TRIANGLES, 0, VERTEX_CNT as i32);
+                
+                // disable the sphere program's vertex attribute
+                ctx.disable_vertex_attrib_array(viewport_position_attr);
+                
+                // --- draw the points ---
+                
+                if !scene.points.representations.is_empty() {
+                    // use the point rendering program
+                    ctx.use_program(Some(&point_program));
+                    
+                    // enable the point program's vertex attributes
+                    ctx.enable_vertex_attrib_array(point_position_attr);
+                    ctx.enable_vertex_attrib_array(point_color_attr);
+                    ctx.enable_vertex_attrib_array(point_highlight_attr);
+                    ctx.enable_vertex_attrib_array(point_selection_attr);
+                    
+                    // write the points in world coordinates
+                    let asm_to_world_sp = asm_to_world.rows(0, SPACE_DIM);
+                    let point_positions = DMatrix::from_columns(
+                        &scene.points.representations.into_iter().map(
+                            |rep| &asm_to_world_sp * rep
+                        ).collect::<Vec<_>>().as_slice()
+                    ).cast::<f32>();
+                    
+                    // load the point positions and colors into new buffers and
+                    // bind them to the corresponding attributes in the vertex
+                    // shader
+                    bind_new_buffer_to_attribute(&ctx, point_position_attr, SPACE_DIM as i32, point_positions.as_slice());
+                    bind_new_buffer_to_attribute(&ctx, point_color_attr, (COLOR_SIZE + 1) as i32, scene.points.colors_with_opacity.concat().as_slice());
+                    bind_new_buffer_to_attribute(&ctx, point_highlight_attr, 1 as i32, scene.points.highlights.as_slice());
+                    bind_new_buffer_to_attribute(&ctx, point_selection_attr, 1 as i32, scene.points.selections.as_slice());
+                    
+                    // draw the scene
+                    ctx.draw_arrays(WebGl2RenderingContext::POINTS, 0, point_positions.ncols() as i32);
+                    
+                    // disable the point program's vertex attributes
+                    ctx.disable_vertex_attrib_array(point_position_attr);
+                    ctx.disable_vertex_attrib_array(point_color_attr);
+                    ctx.disable_vertex_attrib_array(point_highlight_attr);
+                    ctx.disable_vertex_attrib_array(point_selection_attr);
+                }
+                
+                // --- update the display state ---
+                
+                // update the viewpoint
+                assembly_to_world.set(asm_to_world);
+                
+                // clear the scene change flag
+                scene_changed.set(
+                    pitch_up_val != 0.0
+                    || pitch_down_val != 0.0
+                    || yaw_left_val != 0.0
+                    || yaw_right_val != 0.0
+                    || roll_cw_val != 0.0
+                    || roll_ccw_val != 0.0
+                    || zoom_in_val != 0.0
+                    || zoom_out_val != 0.0
+                    || turntable_val /* BENCHMARKING */
+                );
+            } else {
+                frames_since_last_sample = 0;
+                mean_frame_interval.set(-1.0);
+            }
+        });
+        start_animation_loop();
+    });
+    
+    let set_nav_signal = move |event: &KeyboardEvent, value: f64| {
+        let mut navigating = true;
+        let shift = event.shift_key();
+        match event.key().as_str() {
+            "ArrowUp" if shift => zoom_in.set(value),
+            "ArrowDown" if shift => zoom_out.set(value),
+            "ArrowUp" => pitch_up.set(value),
+            "ArrowDown" => pitch_down.set(value),
+            "ArrowRight" if shift => roll_cw.set(value),
+            "ArrowLeft" if shift => roll_ccw.set(value),
+            "ArrowRight" => yaw_right.set(value),
+            "ArrowLeft" => yaw_left.set(value),
+            _ => navigating = false
+        };
+        if navigating {
+            scene_changed.set(true);
+            event.prevent_default();
+        }
+    };
+    
+    let set_manip_signal = move |event: &KeyboardEvent, value: f64| {
+        let mut manipulating = true;
+        let shift = event.shift_key();
+        match event.key().as_str() {
+            "d" | "D" => translate_pos_x.set(value),
+            "a" | "A" => translate_neg_x.set(value),
+            "w" | "W" if shift => translate_neg_z.set(value),
+            "s" | "S" if shift => translate_pos_z.set(value),
+            "w" | "W" => translate_pos_y.set(value),
+            "s" | "S" => translate_neg_y.set(value),
+            "]" | "}" => shrink_neg.set(value),
+            "[" | "{" => shrink_pos.set(value),
+            _ => manipulating = false
+        };
+        if manipulating {
+            event.prevent_default();
+        }
+    };
+    
+    view! {
+        /* TO DO */
+        // switch back to integer-valued parameters when that becomes possible
+        // again
+        canvas(
+            ref=display,
+            id="display",
+            width="600",
+            height="600",
+            tabindex="0",
+            on:keydown=move |event: KeyboardEvent| {
+                if event.key() == "Shift" {
+                    // swap navigation inputs
+                    roll_cw.set(yaw_right.get());
+                    roll_ccw.set(yaw_left.get());
+                    zoom_in.set(pitch_up.get());
+                    zoom_out.set(pitch_down.get());
+                    yaw_right.set(0.0);
+                    yaw_left.set(0.0);
+                    pitch_up.set(0.0);
+                    pitch_down.set(0.0);
+                    
+                    // swap manipulation inputs
+                    translate_pos_z.set(translate_neg_y.get());
+                    translate_neg_z.set(translate_pos_y.get());
+                    translate_pos_y.set(0.0);
+                    translate_neg_y.set(0.0);
+                } else {
+                    if event.key() == "Enter" { /* BENCHMARKING */
+                        turntable.set_fn(|turn| !turn);
+                        scene_changed.set(true);
+                    }
+                    set_nav_signal(&event, 1.0);
+                    set_manip_signal(&event, 1.0);
+                }
+            },
+            on:keyup=move |event: KeyboardEvent| {
+                if event.key() == "Shift" {
+                    // swap navigation inputs
+                    yaw_right.set(roll_cw.get());
+                    yaw_left.set(roll_ccw.get());
+                    pitch_up.set(zoom_in.get());
+                    pitch_down.set(zoom_out.get());
+                    roll_cw.set(0.0);
+                    roll_ccw.set(0.0);
+                    zoom_in.set(0.0);
+                    zoom_out.set(0.0);
+                    
+                    // swap manipulation inputs
+                    translate_pos_y.set(translate_neg_z.get());
+                    translate_neg_y.set(translate_pos_z.get());
+                    translate_pos_z.set(0.0);
+                    translate_neg_z.set(0.0);
+                } else {
+                    set_nav_signal(&event, 0.0);
+                    set_manip_signal(&event, 0.0);
+                }
+            },
+            on:blur=move |_| {
+                pitch_up.set(0.0);
+                pitch_down.set(0.0);
+                yaw_right.set(0.0);
+                yaw_left.set(0.0);
+                roll_ccw.set(0.0);
+                roll_cw.set(0.0);
+            },
+            on:click=move |event: MouseEvent| {
+                // find the nearest element along the pointer direction
+                let (dir, pixel_size) = event_dir(&event);
+                console::log_1(&JsValue::from(dir.to_string()));
+                let mut clicked: Option<(Rc<dyn Element>, f64)> = None;
+                let tangible_elts = state.assembly.elements
+                    .get_clone_untracked()
+                    .into_iter()
+                    .filter(|elt| !elt.ghost().get());
+                for elt in tangible_elts {
+                    match assembly_to_world.with(|asm_to_world| elt.cast(dir, asm_to_world, pixel_size)) {
+                        Some(depth) => match clicked {
+                            Some((_, best_depth)) => {
+                                if depth < best_depth {
+                                    clicked = Some((elt, depth))
+                                }
+                            },
+                            None => clicked = Some((elt, depth))
+                        }
+                        None => ()
+                    };
+                }
+                
+                // if we clicked something, select it
+                match clicked {
+                    Some((elt, _)) => state.select(&elt, event.shift_key()),
+                    None => state.selection.update(|sel| sel.clear())
+                };
+            }
+        )
+    }
+}

app-proto/src/components/identity.vert

@@ -0,0 +1,7 @@
+#version 300 es
+
+in vec4 position;
+
+void main() {
+    gl_Position = position;
+}

app-proto/src/components/outline.rs

@@ -0,0 +1,264 @@
+use itertools::Itertools;
+use std::rc::Rc;
+use sycamore::prelude::*;
+use web_sys::{
+    KeyboardEvent,
+    MouseEvent,
+    wasm_bindgen::JsCast
+};
+
+use crate::{
+    AppState,
+    assembly::{
+        Element,
+        HalfCurvatureRegulator,
+        InversiveDistanceRegulator,
+        Regulator
+    },
+    specified::SpecifiedValue
+};
+
+// an editable view of a regulator
+#[component(inline_props)]
+fn RegulatorInput(regulator: Rc<dyn Regulator>) -> View {
+    // get the regulator's measurement and set point signals
+    let measurement = regulator.measurement();
+    let set_point = regulator.set_point();
+    
+    // the `valid` signal tracks whether the last entered value is a valid set
+    // point specification
+    let valid = create_signal(true);
+    
+    // the `value` signal holds the current set point specification
+    let value = create_signal(
+        set_point.with_untracked(|set_pt| set_pt.spec.clone())
+    );
+    
+    // this `reset_value` closure resets the input value to the regulator's set
+    // point specification
+    let reset_value = move || {
+        batch(|| {
+            valid.set(true);
+            value.set(set_point.with(|set_pt| set_pt.spec.clone()));
+        })
+    };
+    
+    // reset the input value whenever the regulator's set point specification
+    // is updated
+    create_effect(reset_value);
+    
+    view! {
+        input(
+            r#type="text",
+            class=move || {
+                if valid.get() {
+                    set_point.with(|set_pt| {
+                        if set_pt.is_present() {
+                            "regulator-input constraint"
+                        } else {
+                            "regulator-input"
+                        }
+                    })
+                } else {
+                    "regulator-input invalid"
+                }
+            },
+            placeholder=measurement.with(|result| result.to_string()),
+            bind:value=value,
+            on:change=move |_| {
+                valid.set(
+                    match SpecifiedValue::try_from(value.get_clone_untracked()) {
+                        Ok(set_pt) => {
+                            set_point.set(set_pt);
+                            true
+                        }
+                        Err(_) => false
+                    }
+                )
+            },
+            on:keydown={
+                move |event: KeyboardEvent| {
+                    match event.key().as_str() {
+                        "Escape" => reset_value(),
+                        _ => ()
+                    }
+                }
+            }
+        )
+    }
+}
+
+pub trait OutlineItem {
+    fn outline_item(self: Rc<Self>, element: &Rc<dyn Element>) -> View;
+}
+
+impl OutlineItem for InversiveDistanceRegulator {
+    fn outline_item(self: Rc<Self>, element: &Rc<dyn Element>) -> View {
+        let other_subject_label = if self.subjects[0] == element.clone() {
+            self.subjects[1].label()
+        } else {
+            self.subjects[0].label()
+        }.clone();
+        view! {
+            li(class="regulator") {
+                div(class="regulator-label") { (other_subject_label) }
+                div(class="regulator-type") { "Inversive distance" }
+                RegulatorInput(regulator=self)
+                div(class="status")
+            }
+        }
+    }
+}
+
+impl OutlineItem for HalfCurvatureRegulator {
+    fn outline_item(self: Rc<Self>, _element: &Rc<dyn Element>) -> View {
+        view! {
+            li(class="regulator") {
+                div(class="regulator-label") // for spacing
+                div(class="regulator-type") { "Half-curvature" }
+                RegulatorInput(regulator=self)
+                div(class="status")
+            }
+        }
+    }
+}
+
+// a list item that shows an element in an outline view of an assembly
+#[component(inline_props)]
+fn ElementOutlineItem(element: Rc<dyn Element>) -> View {
+    let state = use_context::<AppState>();
+    let class = {
+        let element_for_class = element.clone();
+        state.selection.map(
+            move |sel| if sel.contains(&element_for_class) { "selected" } else { "" }
+        )
+    };
+    let label = element.label().clone();
+    let representation = element.representation().clone();
+    let rep_components = move || {
+        representation.with(
+            |rep| rep.iter().map(
+                |u| {
+                    let u_str = format!("{:.3}", u).replace("-", "\u{2212}");
+                    view! { div { (u_str) } }
+                }
+            ).collect::<Vec<_>>()
+        )
+    };
+    let regulated = element.regulators().map(|regs| regs.len() > 0);
+    let regulator_list = element.regulators().map(
+        |regs| regs
+            .clone()
+            .into_iter()
+            .sorted_by_key(|reg| reg.subjects().len())
+            .collect::<Vec<_>>()
+    );
+    let details_node = create_node_ref();
+    view! {
+        li {
+            details(ref=details_node) {
+                summary(
+                    class=class.get(),
+                    on:keydown={
+                        let element_for_handler = element.clone();
+                        move |event: KeyboardEvent| {
+                            match event.key().as_str() {
+                                "Enter" => {
+                                    state.select(&element_for_handler, event.shift_key());
+                                    event.prevent_default();
+                                },
+                                "ArrowRight" if regulated.get() => {
+                                    let _ = details_node
+                                        .get()
+                                        .unchecked_into::<web_sys::Element>()
+                                        .set_attribute("open", "");
+                                },
+                                "ArrowLeft" => {
+                                    let _ = details_node
+                                        .get()
+                                        .unchecked_into::<web_sys::Element>()
+                                        .remove_attribute("open");
+                                },
+                                _ => ()
+                            }
+                        }
+                    }
+                ) {
+                    div(
+                        class="element-switch",
+                        on:click=|event: MouseEvent| event.stop_propagation()
+                    )
+                    div(
+                        class="element",
+                        on:click={
+                            let state_for_handler = state.clone();
+                            let element_for_handler = element.clone();
+                            move |event: MouseEvent| {
+                                state_for_handler.select(&element_for_handler, event.shift_key());
+                                event.stop_propagation();
+                                event.prevent_default();
+                            }
+                        }
+                    ) {
+                        div(class="element-label") { (label) }
+                        div(class="element-representation") { (rep_components) }
+                        input(
+                            r#type="checkbox",
+                            bind:checked=element.ghost(),
+                            on:click=|event: MouseEvent| event.stop_propagation()
+                        )
+                    }
+                }
+                ul(class="regulators") {
+                    Keyed(
+                        list=regulator_list,
+                        view=move |reg| reg.outline_item(&element),
+                        key=|reg| reg.serial()
+                    )
+                }
+            }
+        }
+    }
+}
+
+// a component that lists the elements of the current assembly, showing each
+// element's regulators in a collapsible sub-list. its implementation is based
+// on Kate Morley's HTML + CSS tree views:
+//
+//   https://iamkate.com/code/tree-views/
+//
+#[component]
+pub fn Outline() -> View {
+    let state = use_context::<AppState>();
+    
+    // list the elements alphabetically by ID
+    /* TO DO */
+    // this code is designed to generalize easily to other sort keys. if we only
+    // ever wanted to sort by ID, we could do that more simply using the
+    // `elements_by_id` index
+    let element_list = state.assembly.elements.map(
+        |elts| elts
+            .clone()
+            .into_iter()
+            .sorted_by_key(|elt| elt.id().clone())
+            .collect::<Vec<_>>()
+    );
+    
+    view! {
+        ul(
+            id="outline",
+            on:click={
+                let state = use_context::<AppState>();
+                move |_| state.selection.update(|sel| sel.clear())
+            }
+        ) {
+            Keyed(
+                list=element_list,
+                view=|elt| view! {
+                    ElementOutlineItem(element=elt)
+                },
+                key=|elt| elt.serial()
+            )
+        }
+    }
+}

app-proto/src/components/point.frag

@@ -0,0 +1,19 @@
+#version 300 es
+
+precision highp float;
+
+in vec4 point_color;
+in float point_highlight;
+in float total_radius;
+
+out vec4 outColor;
+
+void main() {
+    float r = total_radius * length(2.*gl_PointCoord - vec2(1.));
+    
+    const float POINT_RADIUS = 4.;
+    float border = smoothstep(POINT_RADIUS - 1., POINT_RADIUS, r);
+    float disk = 1. - smoothstep(total_radius - 1., total_radius, r);
+    vec4 color = mix(point_color, vec4(1.), border * point_highlight);
+    outColor = vec4(vec3(1.), disk) * color;
+}

app-proto/src/components/point.vert

@@ -0,0 +1,24 @@
+#version 300 es
+
+in vec4 position;
+in vec4 color;
+in float highlight;
+in float selected;
+
+out vec4 point_color;
+out float point_highlight;
+out float total_radius;
+
+// camera
+const float focal_slope = 0.3;
+
+void main() {
+    total_radius = 5. + 0.5*selected;
+    
+    float depth = -focal_slope * position.z;
+    gl_Position = vec4(position.xy / depth, 0., 1.);
+    gl_PointSize = 2.*total_radius;
+    
+    point_color = color;
+    point_highlight = highlight;
+}

app-proto/src/components/spheres.frag

@@ -0,0 +1,235 @@
+#version 300 es
+
+precision highp float;
+
+out vec4 outColor;
+
+// --- inversive geometry ---
+
+struct vecInv {
+    vec3 sp;
+    vec2 lt;
+};
+
+// --- uniforms ---
+
+// assembly
+const int SPHERE_MAX = 200;
+uniform int sphere_cnt;
+uniform vecInv sphere_list[SPHERE_MAX];
+uniform vec4 color_list[SPHERE_MAX];
+uniform float highlight_list[SPHERE_MAX];
+
+// view
+uniform vec2 resolution;
+uniform float shortdim;
+
+// controls
+uniform int layer_threshold;
+uniform bool debug_mode;
+
+// light and camera
+const float focal_slope = 0.3;
+const vec3 light_dir = normalize(vec3(2., 2., 1.));
+const float ixn_threshold = 0.005;
+const float INTERIOR_DIMMING = 0.7;
+
+// --- sRGB ---
+
+// map colors from RGB space to sRGB space, as specified in the sRGB standard
+// (IEC 61966-2-1:1999)
+//
+//   https://www.color.org/sRGB.pdf
+//   https://www.color.org/chardata/rgb/srgb.xalter
+//
+// in RGB space, color value is proportional to light intensity, so linear
+// color-vector interpolation corresponds to physical light mixing. in sRGB
+// space, the color encoding used by many monitors, we use more of the value
+// interval to represent low intensities, and less of the interval to represent
+// high intensities. this improves color quantization
+
+float sRGB(float t) {
+    if (t <= 0.0031308) {
+        return 12.92*t;
+    } else {
+        return 1.055*pow(t, 5./12.) - 0.055;
+    }
+}
+
+vec3 sRGB(vec3 color) {
+    return vec3(sRGB(color.r), sRGB(color.g), sRGB(color.b));
+}
+
+// --- shading ---
+
+struct Fragment {
+    vec3 pt;
+    vec3 normal;
+    vec4 color;
+};
+
+Fragment sphere_shading(vecInv v, vec3 pt, vec4 base_color) {
+    // the expression for normal needs to be checked. it's supposed to give the
+    // negative gradient of the lorentz product between the impact point vector
+    // and the sphere vector with respect to the coordinates of the impact
+    // point. i calculated it in my head and decided that the result looked good
+    // enough for now
+    vec3 normal = normalize(-v.sp + 2.*v.lt.s*pt);
+    
+    float incidence = dot(normal, light_dir);
+    float illum = mix(0.4, 1.0, max(incidence, 0.0));
+    return Fragment(pt, normal, vec4(illum * base_color.rgb, base_color.a));
+}
+
+float intersection_dist(Fragment a, Fragment b) {
+    float intersection_sin = length(cross(a.normal, b.normal));
+    vec3 disp = a.pt - b.pt;
+    return max(
+        abs(dot(a.normal, disp)),
+        abs(dot(b.normal, disp))
+    ) / intersection_sin;
+}
+
+// --- ray-casting ---
+
+struct TaggedDepth {
+    float depth;
+    float dimming;
+    int id;
+};
+
+// if `a/b` is less than this threshold, we approximate `a*u^2 + b*u + c` by
+// the linear function `b*u + c`
+const float DEG_THRESHOLD = 1e-9;
+
+// the depths, represented as multiples of `dir`, where the line generated by
+// `dir` hits the sphere represented by `v`. if both depths are positive, the
+// smaller one is returned in the first component. if only one depth is
+// positive, it could be returned in either component
+vec2 sphere_cast(vecInv v, vec3 dir) {
+    float a = -v.lt.s * dot(dir, dir);
+    float b = dot(v.sp, dir);
+    float c = -v.lt.t;
+    
+    float adjust = 4.*a*c/(b*b);
+    if (adjust < 1.) {
+        // as long as `b` is non-zero, the linear approximation of
+        //
+        //   a*u^2 + b*u + c
+        //
+        // at `u = 0` will reach zero at a finite depth `u_lin`. the root of the
+        // quadratic adjacent to `u_lin` is stored in `lin_root`. if both roots
+        // have the same sign, `lin_root` will be the one closer to `u = 0`
+        float square_rect_ratio = 1. + sqrt(1. - adjust);
+        float lin_root = -(2.*c)/b / square_rect_ratio;
+        if (abs(a) > DEG_THRESHOLD * abs(b)) {
+            return vec2(lin_root, -b/(2.*a) * square_rect_ratio);
+        } else {
+            return vec2(lin_root, -1.);
+        }
+    } else {
+        // the line through `dir` misses the sphere completely
+        return vec2(-1., -1.);
+    }
+}
+
+void main() {
+    vec2 scr = (2.*gl_FragCoord.xy - resolution) / shortdim;
+    vec3 dir = vec3(focal_slope * scr, -1.);
+    
+    // cast rays through the spheres
+    const int LAYER_MAX = 12;
+    TaggedDepth top_hits [LAYER_MAX];
+    int layer_cnt = 0;
+    for (int id = 0; id < sphere_cnt; ++id) {
+        // find out where the ray hits the sphere
+        vec2 hit_depths = sphere_cast(sphere_list[id], dir);
+        
+        // insertion-sort the points we hit into the hit list
+        float dimming = 1.;
+        for (int side = 0; side < 2; ++side) {
+            float depth = hit_depths[side];
+            if (depth > 0.) {
+                for (int layer = layer_cnt; layer >= 0; --layer) {
+                    if (layer < 1 || top_hits[layer-1].depth <= depth) {
+                        // we're not as close to the screen as the hit before
+                        // the empty slot, so insert here
+                        if (layer < LAYER_MAX) {
+                            top_hits[layer] = TaggedDepth(depth, dimming, id);
+                        }
+                        break;
+                    } else {
+                        // we're closer to the screen than the hit before the
+                        // empty slot, so move that hit into the empty slot
+                        top_hits[layer] = top_hits[layer-1];
+                    }
+                }
+                layer_cnt = min(layer_cnt + 1, LAYER_MAX);
+                dimming = INTERIOR_DIMMING;
+            }
+        }
+    }
+    
+    /* DEBUG */
+    // in debug mode, show the layer count instead of the shaded image
+    if (debug_mode) {
+        // at the bottom of the screen, show the color scale instead of the
+        // layer count
+        if (gl_FragCoord.y < 10.) layer_cnt = int(16. * gl_FragCoord.x / resolution.x);
+        
+        // convert number to color
+        ivec3 bits = layer_cnt / ivec3(1, 2, 4);
+        vec3 color = mod(vec3(bits), 2.);
+        if (layer_cnt % 16 >= 8) {
+            color = mix(color, vec3(0.5), 0.5);
+        }
+        outColor = vec4(color, 1.);
+        return;
+    }
+    
+    // composite the sphere fragments
+    vec3 color = vec3(0.);
+    int layer = layer_cnt - 1;
+    TaggedDepth hit = top_hits[layer];
+    vec4 sphere_color = color_list[hit.id];
+    Fragment frag_next = sphere_shading(
+        sphere_list[hit.id],
+        hit.depth * dir,
+        vec4(hit.dimming * sphere_color.rgb, sphere_color.a)
+    );
+    float highlight_next = highlight_list[hit.id];
+    --layer;
+    for (; layer >= layer_threshold; --layer) {
+        // load the current fragment
+        Fragment frag = frag_next;
+        float highlight = highlight_next;
+        
+        // shade the next fragment
+        hit = top_hits[layer];
+        sphere_color = color_list[hit.id];
+        frag_next = sphere_shading(
+            sphere_list[hit.id],
+            hit.depth * dir,
+            vec4(hit.dimming * sphere_color.rgb, sphere_color.a)
+        );
+        highlight_next = highlight_list[hit.id];
+        
+        // highlight intersections
+        float ixn_dist = intersection_dist(frag, frag_next);
+        float max_highlight = max(highlight, highlight_next);
+        float ixn_highlight = 0.5 * max_highlight * (1. - smoothstep(2./3.*ixn_threshold, 1.5*ixn_threshold, ixn_dist));
+        frag.color = mix(frag.color, vec4(1.), ixn_highlight);
+        frag_next.color = mix(frag_next.color, vec4(1.), ixn_highlight);
+        
+        // highlight cusps
+        float cusp_cos = abs(dot(dir, frag.normal));
+        float cusp_threshold = 2.*sqrt(ixn_threshold * sphere_list[hit.id].lt.s);
+        float cusp_highlight = highlight * (1. - smoothstep(2./3.*cusp_threshold, 1.5*cusp_threshold, cusp_cos));
+        frag.color = mix(frag.color, vec4(1.), cusp_highlight);
+        
+        // composite the current fragment
+        color = mix(color, frag.color.rgb, frag.color.a);
+    }
+    color = mix(color, frag_next.color.rgb, frag_next.color.a);
+    outColor = vec4(sRGB(color), 1.);
+}

app-proto/src/components/test_assembly_chooser.rs

@@ -0,0 +1,947 @@
+use itertools::izip;
+use std::{f64::consts::{FRAC_1_SQRT_2, PI}, rc::Rc};
+use nalgebra::Vector3;
+use sycamore::prelude::*;
+use web_sys::{console, wasm_bindgen::JsValue};
+
+use crate::{
+    AppState,
+    engine,
+    engine::DescentHistory,
+    assembly::{
+        Assembly,
+        Element,
+        ElementColor,
+        InversiveDistanceRegulator,
+        Point,
+        Sphere
+    },
+    specified::SpecifiedValue
+};
+
+// --- loaders ---
+
+/* DEBUG */
+// each of these functions loads an example assembly for testing. once we've
+// done more work on saving and loading assemblies, we should come back to this
+// code to see if it can be simplified
+
+fn load_gen_assemb(assembly: &Assembly) {
+    let _ = assembly.try_insert_element(
+        Sphere::new(
+            String::from("gemini_a"),
+            String::from("Castor"),
+            [1.00_f32, 0.25_f32, 0.00_f32],
+            engine::sphere(0.5, 0.5, 0.0, 1.0)
+        )
+    );
+    let _ = assembly.try_insert_element(
+        Sphere::new(
+            String::from("gemini_b"),
+            String::from("Pollux"),
+            [0.00_f32, 0.25_f32, 1.00_f32],
+            engine::sphere(-0.5, -0.5, 0.0, 1.0)
+        )
+    );
+    let _ = assembly.try_insert_element(
+        Sphere::new(
+            String::from("ursa_major"),
+            String::from("Ursa major"),
+            [0.25_f32, 0.00_f32, 1.00_f32],
+            engine::sphere(-0.5, 0.5, 0.0, 0.75)
+        )
+    );
+    let _ = assembly.try_insert_element(
+        Sphere::new(
+            String::from("ursa_minor"),
+            String::from("Ursa minor"),
+            [0.25_f32, 1.00_f32, 0.00_f32],
+            engine::sphere(0.5, -0.5, 0.0, 0.5)
+        )
+    );
+    let _ = assembly.try_insert_element(
+        Sphere::new(
+            String::from("moon_deimos"),
+            String::from("Deimos"),
+            [0.75_f32, 0.75_f32, 0.00_f32],
+            engine::sphere(0.0, 0.15, 1.0, 0.25)
+        )
+    );
+    let _ = assembly.try_insert_element(
+        Sphere::new(
+            String::from("moon_phobos"),
+            String::from("Phobos"),
+            [0.00_f32, 0.75_f32, 0.50_f32],
+            engine::sphere(0.0, -0.15, -1.0, 0.25)
+        )
+    );
+}
+
+fn load_low_curv_assemb(assembly: &Assembly) {
+    // create the spheres
+    let a = 0.75_f64.sqrt();
+    let _ = assembly.try_insert_element(
+        Sphere::new(
+            "central".to_string(),
+            "Central".to_string(),
+            [0.75_f32, 0.75_f32, 0.75_f32],
+            engine::sphere(0.0, 0.0, 0.0, 1.0)
+        )
+    );
+    let _ = assembly.try_insert_element(
+        Sphere::new(
+            "assemb_plane".to_string(),
+            "Assembly plane".to_string(),
+            [0.75_f32, 0.75_f32, 0.75_f32],
+            engine::sphere_with_offset(0.0, 0.0, 1.0, 0.0, 0.0)
+        )
+    );
+    let _ = assembly.try_insert_element(
+        Sphere::new(
+            "side1".to_string(),
+            "Side 1".to_string(),
+            [1.00_f32, 0.00_f32, 0.25_f32],
+            engine::sphere_with_offset(1.0, 0.0, 0.0, 1.0, 0.0)
+        )
+    );
+    let _ = assembly.try_insert_element(
+        Sphere::new(
+            "side2".to_string(),
+            "Side 2".to_string(),
+            [0.25_f32, 1.00_f32, 0.00_f32],
+            engine::sphere_with_offset(-0.5, a, 0.0, 1.0, 0.0)
+        )
+    );
+    let _ = assembly.try_insert_element(
+        Sphere::new(
+            "side3".to_string(),
+            "Side 3".to_string(),
+            [0.00_f32, 0.25_f32, 1.00_f32],
+            engine::sphere_with_offset(-0.5, -a, 0.0, 1.0, 0.0)
+        )
+    );
+    let _ = assembly.try_insert_element(
+        Sphere::new(
+            "corner1".to_string(),
+            "Corner 1".to_string(),
+            [0.75_f32, 0.75_f32, 0.75_f32],
+            engine::sphere(-4.0/3.0, 0.0, 0.0, 1.0/3.0)
+        )
+    );
+    let _ = assembly.try_insert_element(
+        Sphere::new(
+            "corner2".to_string(),
+            "Corner 2".to_string(),
+            [0.75_f32, 0.75_f32, 0.75_f32],
+            engine::sphere(2.0/3.0, -4.0/3.0 * a, 0.0, 1.0/3.0)
+        )
+    );
+    let _ = assembly.try_insert_element(
+        Sphere::new(
+            String::from("corner3"),
+            String::from("Corner 3"),
+            [0.75_f32, 0.75_f32, 0.75_f32],
+            engine::sphere(2.0/3.0, 4.0/3.0 * a, 0.0, 1.0/3.0)
+        )
+    );
+    
+    // impose the desired tangencies and make the sides planar
+    let index_range = 1..=3;
+    let [central, assemb_plane] = ["central", "assemb_plane"].map(
+        |id| assembly.elements_by_id.with_untracked(
+            |elts_by_id| elts_by_id[id].clone()
+        )
+    );
+    let sides = index_range.clone().map(
+        |k| assembly.elements_by_id.with_untracked(
+            |elts_by_id| elts_by_id[&format!("side{k}")].clone()
+        )
+    );
+    let corners = index_range.map(
+        |k| assembly.elements_by_id.with_untracked(
+            |elts_by_id| elts_by_id[&format!("corner{k}")].clone()
+        )
+    );
+    for plane in [assemb_plane.clone()].into_iter().chain(sides.clone()) {
+        // fix the curvature of each plane
+        let curvature = plane.regulators().with_untracked(
+            |regs| regs.first().unwrap().clone()
+        );
+        curvature.set_point().set(SpecifiedValue::try_from("0".to_string()).unwrap());
+    }
+    let all_perpendicular = [central.clone()].into_iter()
+        .chain(sides.clone())
+        .chain(corners.clone());
+    for sphere in all_perpendicular {
+        // make each side and packed sphere perpendicular to the assembly plane
+        let right_angle = InversiveDistanceRegulator::new([sphere, assemb_plane.clone()]);
+        right_angle.set_point.set(SpecifiedValue::try_from("0".to_string()).unwrap());
+        assembly.insert_regulator(Rc::new(right_angle));
+    }
+    for sphere in sides.clone().chain(corners.clone()) {
+        // make each side and corner sphere tangent to the central sphere
+        let tangency = InversiveDistanceRegulator::new([sphere.clone(), central.clone()]);
+        tangency.set_point.set(SpecifiedValue::try_from("-1".to_string()).unwrap());
+        assembly.insert_regulator(Rc::new(tangency));
+    }
+    for (side_index, side) in sides.enumerate() {
+        // make each side tangent to the two adjacent corner spheres
+        for (corner_index, corner) in corners.clone().enumerate() {
+            if side_index != corner_index {
+                let tangency = InversiveDistanceRegulator::new([side.clone(), corner]);
+                tangency.set_point.set(SpecifiedValue::try_from("-1".to_string()).unwrap());
+                assembly.insert_regulator(Rc::new(tangency));
+            }
+        }
+    }
+}
+
+fn load_pointed_assemb(assembly: &Assembly) {
+    let _ = assembly.try_insert_element(
+        Point::new(
+            format!("point_front"),
+            format!("Front point"),
+            [0.75_f32, 0.75_f32, 0.75_f32],
+            engine::point(0.0, 0.0, FRAC_1_SQRT_2)
+        )
+    );
+    let _ = assembly.try_insert_element(
+        Point::new(
+            format!("point_back"),
+            format!("Back point"),
+            [0.75_f32, 0.75_f32, 0.75_f32],
+            engine::point(0.0, 0.0, -FRAC_1_SQRT_2)
+        )
+    );
+    for index_x in 0..=1 {
+        for index_y in 0..=1 {
+            let x = index_x as f64 - 0.5;
+            let y = index_y as f64 - 0.5;
+            
+            let _ = assembly.try_insert_element(
+                Sphere::new(
+                    format!("sphere{index_x}{index_y}"),
+                    format!("Sphere {index_x}{index_y}"),
+                    [0.5*(1.0 + x) as f32, 0.5*(1.0 + y) as f32, 0.5*(1.0 - x*y) as f32],
+                    engine::sphere(x, y, 0.0, 1.0)
+                )
+            );
+            
+            let _ = assembly.try_insert_element(
+                Point::new(
+                    format!("point{index_x}{index_y}"),
+                    format!("Point {index_x}{index_y}"),
+                    [0.5*(1.0 + x) as f32, 0.5*(1.0 + y) as f32, 0.5*(1.0 - x*y) as f32],
+                    engine::point(x, y, 0.0)
+                )
+            );
+        }
+    }
+}
+
+// to finish describing the tridiminished icosahedron, set the inversive
+// distance regulators as follows:
+//   A-A   -0.25
+//   A-B     "
+//   B-C     "
+//   C-C     "
+//   A-C   -0.25 * φ^2 = -0.6545084971874737
+fn load_tridim_icosahedron_assemb(assembly: &Assembly) {
+    // create the vertices
+    const COLOR_A: ElementColor = [1.00_f32, 0.25_f32, 0.25_f32];
+    const COLOR_B: ElementColor = [0.75_f32, 0.75_f32, 0.75_f32];
+    const COLOR_C: ElementColor = [0.25_f32, 0.50_f32, 1.00_f32];
+    let vertices = [
+        Point::new(
+            "a1".to_string(),
+            "A₁".to_string(),
+            COLOR_A,
+            engine::point(0.25, 0.75, 0.75)
+        ),
+        Point::new(
+            "a2".to_string(),
+            "A₂".to_string(),
+            COLOR_A,
+            engine::point(0.75, 0.25, 0.75)
+        ),
+        Point::new(
+            "a3".to_string(),
+            "A₃".to_string(),
+            COLOR_A,
+            engine::point(0.75, 0.75, 0.25)
+        ),
+        Point::new(
+            "b1".to_string(),
+            "B₁".to_string(),
+            COLOR_B,
+            engine::point(0.75, -0.25, -0.25)
+        ),
+        Point::new(
+            "b2".to_string(),
+            "B₂".to_string(),
+            COLOR_B,
+            engine::point(-0.25, 0.75, -0.25)
+        ),
+        Point::new(
+            "b3".to_string(),
+            "B₃".to_string(),
+            COLOR_B,
+            engine::point(-0.25, -0.25, 0.75)
+        ),
+        Point::new(
+            "c1".to_string(),
+            "C₁".to_string(),
+            COLOR_C,
+            engine::point(0.0, -1.0, -1.0)
+        ),
+        Point::new(
+            "c2".to_string(),
+            "C₂".to_string(),
+            COLOR_C,
+            engine::point(-1.0, 0.0, -1.0)
+        ),
+        Point::new(
+            "c3".to_string(),
+            "C₃".to_string(),
+            COLOR_C,
+            engine::point(-1.0, -1.0, 0.0)
+        )
+    ];
+    for vertex in vertices {
+        let _ = assembly.try_insert_element(vertex);
+    }
+    
+    // create the faces
+    const COLOR_FACE: ElementColor = [0.75_f32, 0.75_f32, 0.75_f32];
+    let frac_1_sqrt_6 = 1.0 / 6.0_f64.sqrt();
+    let frac_2_sqrt_6 = 2.0 * frac_1_sqrt_6;
+    let faces = [
+        Sphere::new(
+            "face1".to_string(),
+            "Face 1".to_string(),
+            COLOR_FACE,
+            engine::sphere_with_offset(frac_2_sqrt_6, -frac_1_sqrt_6, -frac_1_sqrt_6, -frac_1_sqrt_6, 0.0)
+        ),
+        Sphere::new(
+            "face2".to_string(),
+            "Face 2".to_string(),
+            COLOR_FACE,
+            engine::sphere_with_offset(-frac_1_sqrt_6, frac_2_sqrt_6, -frac_1_sqrt_6, -frac_1_sqrt_6, 0.0)
+        ),
+        Sphere::new(
+            "face3".to_string(),
+            "Face 3".to_string(),
+            COLOR_FACE,
+            engine::sphere_with_offset(-frac_1_sqrt_6, -frac_1_sqrt_6, frac_2_sqrt_6, -frac_1_sqrt_6, 0.0)
+        )
+    ];
+    for face in faces {
+        face.ghost().set(true);
+        let _ = assembly.try_insert_element(face);
+    }
+    
+    let index_range = 1..=3;
+    for j in index_range.clone() {
+        // make each face planar
+        let face = assembly.elements_by_id.with_untracked(
+            |elts_by_id| elts_by_id[&format!("face{j}")].clone()
+        );
+        let curvature_regulator = face.regulators().with_untracked(
+            |regs| regs.first().unwrap().clone()
+        );
+        curvature_regulator.set_point().set(
+            SpecifiedValue::try_from("0".to_string()).unwrap()
+        );
+        
+        // put each A vertex on the face it belongs to
+        let vertex_a = assembly.elements_by_id.with_untracked(
+            |elts_by_id| elts_by_id[&format!("a{j}")].clone()
+        );
+        let incidence_a = InversiveDistanceRegulator::new([face.clone(), vertex_a.clone()]);
+        incidence_a.set_point.set(SpecifiedValue::try_from("0".to_string()).unwrap());
+        assembly.insert_regulator(Rc::new(incidence_a));
+        
+        // regulate the B-C vertex distances
+        let vertices_bc = ["b", "c"].map(
+            |series| assembly.elements_by_id.with_untracked(
+                |elts_by_id| elts_by_id[&format!("{series}{j}")].clone()
+            )
+        );
+        assembly.insert_regulator(
+            Rc::new(InversiveDistanceRegulator::new(vertices_bc))
+        );
+        
+        // get the pair of indices adjacent to `j`
+        let adjacent_indices = [j % 3 + 1, (j + 1) % 3 + 1];
+        
+        for k in adjacent_indices.clone() {
+            for series in ["b", "c"] {
+                // put each B and C vertex on the faces it belongs to
+                let vertex = assembly.elements_by_id.with_untracked(
+                    |elts_by_id| elts_by_id[&format!("{series}{k}")].clone()
+                );
+                let incidence = InversiveDistanceRegulator::new([face.clone(), vertex.clone()]);
+                incidence.set_point.set(SpecifiedValue::try_from("0".to_string()).unwrap());
+                assembly.insert_regulator(Rc::new(incidence));
+                
+                // regulate the A-B and A-C vertex distances
+                assembly.insert_regulator(
+                    Rc::new(InversiveDistanceRegulator::new([vertex_a.clone(), vertex]))
+                );
+            }
+        }
+        
+        // regulate the A-A and C-C vertex distances
+        let adjacent_pairs = ["a", "c"].map(
+            |series| adjacent_indices.map(
+                |index| assembly.elements_by_id.with_untracked(
+                    |elts_by_id| elts_by_id[&format!("{series}{index}")].clone()
+                )
+            )
+        );
+        for pair in adjacent_pairs {
+            assembly.insert_regulator(
+                Rc::new(InversiveDistanceRegulator::new(pair))
+            );
+        }
+    }
+}
+
+// to finish describing the dodecahedral circle packing, set the inversive
+// distance regulators to -1. some of the regulators have already been set
+fn load_dodeca_packing_assemb(assembly: &Assembly) {
+    // add the substrate
+    let _ = assembly.try_insert_element(
+        Sphere::new(
+            "substrate".to_string(),
+            "Substrate".to_string(),
+            [0.75_f32, 0.75_f32, 0.75_f32],
+            engine::sphere(0.0, 0.0, 0.0, 1.0)
+        )
+    );
+    let substrate = assembly.elements_by_id.with_untracked(
+        |elts_by_id| elts_by_id["substrate"].clone()
+    );
+    
+    // fix the substrate's curvature
+    substrate.regulators().with_untracked(
+        |regs| regs.first().unwrap().clone()
+    ).set_point().set(
+        SpecifiedValue::try_from("0.5".to_string()).unwrap()
+    );
+    
+    // add the circles to be packed
+    const COLOR_A: ElementColor = [1.00_f32, 0.25_f32, 0.00_f32];
+    const COLOR_B: ElementColor = [1.00_f32, 0.00_f32, 0.25_f32];
+    const COLOR_C: ElementColor = [0.25_f32, 0.00_f32, 1.00_f32];
+    let phi = 0.5 + 1.25_f64.sqrt(); /* TO DO */ // replace with std::f64::consts::PHI when that gets stabilized
+    let phi_inv = 1.0 / phi;
+    let coord_scale = (phi + 2.0).sqrt();
+    let face_scales = [phi_inv, (13.0 / 12.0) / coord_scale];
+    let face_radii = [phi_inv, 5.0 / 12.0];
+    let mut faces = Vec::<Rc<dyn Element>>::new();
+    let subscripts = ["₀", "₁"];
+    for j in 0..2 {
+        for k in 0..2 {
+            let small_coord = face_scales[k] * (2.0*(j as f64) - 1.0);
+            let big_coord = face_scales[k] * (2.0*(k as f64) - 1.0) * phi;
+            
+            let id_num = format!("{j}{k}");
+            let label_sub = format!("{}{}", subscripts[j], subscripts[k]);
+            
+            // add the A face
+            let id_a = format!("a{id_num}");
+            let _ = assembly.try_insert_element(
+                Sphere::new(
+                    id_a.clone(),
+                    format!("A{label_sub}"),
+                    COLOR_A,
+                    engine::sphere(0.0, small_coord, big_coord, face_radii[k])
+                )
+            );
+            faces.push(
+                assembly.elements_by_id.with_untracked(
+                    |elts_by_id| elts_by_id[&id_a].clone()
+                )
+            );
+            
+            // add the B face
+            let id_b = format!("b{id_num}");
+            let _ = assembly.try_insert_element(
+                Sphere::new(
+                    id_b.clone(),
+                    format!("B{label_sub}"),
+                    COLOR_B,
+                    engine::sphere(small_coord, big_coord, 0.0, face_radii[k])
+                )
+            );
+            faces.push(
+                assembly.elements_by_id.with_untracked(
+                    |elts_by_id| elts_by_id[&id_b].clone()
+                )
+            );
+            
+            // add the C face
+            let id_c = format!("c{id_num}");
+            let _ = assembly.try_insert_element(
+                Sphere::new(
+                    id_c.clone(),
+                    format!("C{label_sub}"),
+                    COLOR_C,
+                    engine::sphere(big_coord, 0.0, small_coord, face_radii[k])
+                )
+            );
+            faces.push(
+                assembly.elements_by_id.with_untracked(
+                    |elts_by_id| elts_by_id[&id_c].clone()
+                )
+            );
+        }
+    }
+    
+    // make each face sphere perpendicular to the substrate
+    for face in faces {
+        let right_angle = InversiveDistanceRegulator::new([face, substrate.clone()]);
+        right_angle.set_point.set(SpecifiedValue::try_from("0".to_string()).unwrap());
+        assembly.insert_regulator(Rc::new(right_angle));
+    }
+    
+    // set up the tangencies that define the packing
+    for [long_edge_plane, short_edge_plane] in [["a", "b"], ["b", "c"], ["c", "a"]] {
+        for k in 0..2 {
+            let long_edge_ids = [
+                format!("{long_edge_plane}{k}0"),
+                format!("{long_edge_plane}{k}1")
+            ];
+            let short_edge_ids = [
+                format!("{short_edge_plane}0{k}"),
+                format!("{short_edge_plane}1{k}")
+            ];
+            let [long_edge, short_edge] = [long_edge_ids, short_edge_ids].map(
+                |edge_ids| edge_ids.map(
+                    |id| assembly.elements_by_id.with_untracked(
+                        |elts_by_id| elts_by_id[&id].clone()
+                    )
+                )
+            );
+            
+            // set up the short-edge tangency
+            let short_tangency = InversiveDistanceRegulator::new(short_edge.clone());
+            if k == 0 {
+                short_tangency.set_point.set(SpecifiedValue::try_from("-1".to_string()).unwrap());
+            }
+            assembly.insert_regulator(Rc::new(short_tangency));
+            
+            // set up the side tangencies
+            for i in 0..2 {
+                for j in 0..2 {
+                    let side_tangency = InversiveDistanceRegulator::new(
+                        [long_edge[i].clone(), short_edge[j].clone()]
+                    );
+                    if i == 0 && k == 0 {
+                        side_tangency.set_point.set(SpecifiedValue::try_from("-1".to_string()).unwrap());
+                    }
+                    assembly.insert_regulator(Rc::new(side_tangency));
+                }
+            }
+        }
+    }
+}
+
+// the initial configuration of this test assembly deliberately violates the
+// constraints, so loading the assembly will trigger a non-trivial realization
+fn load_balanced_assemb(assembly: &Assembly) {
+    // create the spheres
+    const R_OUTER: f64 = 10.0;
+    const R_INNER: f64 = 4.0;
+    let spheres = [
+        Sphere::new(
+            "outer".to_string(),
+            "Outer".to_string(),
+            [0.75_f32, 0.75_f32, 0.75_f32],
+            engine::sphere(0.0, 0.0, 0.0, R_OUTER)
+        ),
+        Sphere::new(
+            "a".to_string(),
+            "A".to_string(),
+            [1.00_f32, 0.00_f32, 0.25_f32],
+            engine::sphere(0.0, 4.0, 0.0, R_INNER)
+        ),
+        Sphere::new(
+            "b".to_string(),
+            "B".to_string(),
+            [0.00_f32, 0.25_f32, 1.00_f32],
+            engine::sphere(0.0, -4.0, 0.0, R_INNER)
+        ),
+    ];
+    for sphere in spheres {
+        let _ = assembly.try_insert_element(sphere);
+    }
+    
+    // get references to the spheres
+    let [outer, a, b] = ["outer", "a", "b"].map(
+        |id| assembly.elements_by_id.with_untracked(
+            |elts_by_id| elts_by_id[id].clone()
+        )
+    );
+    
+    // fix the diameters of the outer, sun, and moon spheres
+    for (sphere, radius) in [
+        (outer.clone(), R_OUTER),
+        (a.clone(), R_INNER),
+        (b.clone(), R_INNER)
+    ] {
+        let curvature_regulator = sphere.regulators().with_untracked(
+            |regs| regs.first().unwrap().clone()
+        );
+        let curvature = 0.5 / radius;
+        curvature_regulator.set_point().set(
+            SpecifiedValue::try_from(curvature.to_string()).unwrap()
+        );
+    }
+    
+    // set the inversive distances between the spheres. as described above, the
+    // initial configuration deliberately violates these constraints
+    for inner in [a, b] {
+        let tangency = InversiveDistanceRegulator::new([outer.clone(), inner]);
+        tangency.set_point.set(SpecifiedValue::try_from("1".to_string()).unwrap());
+        assembly.insert_regulator(Rc::new(tangency));
+    }
+}
+
+// the initial configuration of this test assembly deliberately violates the
+// constraints, so loading the assembly will trigger a non-trivial realization
+fn load_off_center_assemb(assembly: &Assembly) {
+    // create a point almost at the origin and a sphere centered on the origin
+    let _ = assembly.try_insert_element(
+        Point::new(
+            "point".to_string(),
+            "Point".to_string(),
+            [0.75_f32, 0.75_f32, 0.75_f32],
+            engine::point(1e-9, 0.0, 0.0)
+        ),
+    );
+    let _ = assembly.try_insert_element(
+        Sphere::new(
+            "sphere".to_string(),
+            "Sphere".to_string(),
+            [0.75_f32, 0.75_f32, 0.75_f32],
+            engine::sphere(0.0, 0.0, 0.0, 1.0)
+        ),
+    );
+    
+    // get references to the elements
+    let point_and_sphere = ["point", "sphere"].map(
+        |id| assembly.elements_by_id.with_untracked(
+            |elts_by_id| elts_by_id[id].clone()
+        )
+    );
+    
+    // put the point on the sphere
+    let incidence = InversiveDistanceRegulator::new(point_and_sphere);
+    incidence.set_point.set(SpecifiedValue::try_from("0".to_string()).unwrap());
+    assembly.insert_regulator(Rc::new(incidence));
+}
+
+// setting the inversive distances between the vertices to -2 gives a regular
+// tetrahedron with side length 1, whose insphere and circumsphere have radii
+// sqrt(1/6) and sqrt(3/2), respectively. to measure those radii, set an
+// inversive distance of -1 between the insphere and each face, and then set an
+// inversive distance of 0 between the circumsphere and each vertex
+fn load_radius_ratio_assemb(assembly: &Assembly) {
+    let index_range = 1..=4;
+    
+    // create the spheres
+    const GRAY: ElementColor = [0.75_f32, 0.75_f32, 0.75_f32];
+    let spheres = [
+        Sphere::new(
+            "sphere_faces".to_string(),
+            "Insphere".to_string(),
+            GRAY,
+            engine::sphere(0.0, 0.0, 0.0, 0.5)
+        ),
+        Sphere::new(
+            "sphere_vertices".to_string(),
+            "Circumsphere".to_string(),
+            GRAY,
+            engine::sphere(0.0, 0.0, 0.0, 0.25)
+        )
+    ];
+    for sphere in spheres {
+        let _ = assembly.try_insert_element(sphere);
+    }
+    
+    // create the vertices
+    let vertices = izip!(
+        index_range.clone(),
+        [
+            [1.00_f32, 0.50_f32, 0.75_f32],
+            [1.00_f32, 0.75_f32, 0.50_f32],
+            [1.00_f32, 1.00_f32, 0.50_f32],
+            [0.75_f32, 0.50_f32, 1.00_f32]
+        ].into_iter(),
+        [
+            engine::point(-0.6, -0.8, -0.6),
+            engine::point(-0.6, 0.8, 0.6),
+            engine::point(0.6, -0.8, 0.6),
+            engine::point(0.6, 0.8, -0.6)
+        ].into_iter()
+    ).map(
+        |(k, color, representation)| {
+            Point::new(
+                format!("v{k}"),
+                format!("Vertex {k}"),
+                color,
+                representation
+            )
+        }
+    );
+    for vertex in vertices {
+        let _ = assembly.try_insert_element(vertex);
+    }
+    
+    // create the faces
+    let base_dir = Vector3::new(1.0, 0.75, 1.0).normalize();
+    let offset = base_dir.dot(&Vector3::new(-0.6, 0.8, 0.6));
+    let faces = izip!(
+        index_range.clone(),
+        [
+            [1.00_f32, 0.00_f32, 0.25_f32],
+            [1.00_f32, 0.25_f32, 0.00_f32],
+            [0.75_f32, 0.75_f32, 0.00_f32],
+            [0.25_f32, 0.00_f32, 1.00_f32]
+        ].into_iter(),
+        [
+            engine::sphere_with_offset(base_dir[0], base_dir[1], base_dir[2], offset, 0.0),
+            engine::sphere_with_offset(base_dir[0], -base_dir[1], -base_dir[2], offset, 0.0),
+            engine::sphere_with_offset(-base_dir[0], base_dir[1], -base_dir[2], offset, 0.0),
+            engine::sphere_with_offset(-base_dir[0], -base_dir[1], base_dir[2], offset, 0.0)
+        ].into_iter()
+    ).map(
+        |(k, color, representation)| {
+            Sphere::new(
+                format!("f{k}"),
+                format!("Face {k}"),
+                color,
+                representation
+            )
+        }
+    );
+    for face in faces {
+        face.ghost().set(true);
+        let _ = assembly.try_insert_element(face);
+    }
+    
+    // impose the constraints
+    for j in index_range.clone() {
+        let [face_j, vertex_j] = [
+            format!("f{j}"),
+            format!("v{j}")
+        ].map(
+            |id| assembly.elements_by_id.with_untracked(
+                |elts_by_id| elts_by_id[&id].clone()
+            )
+        );
+        
+        // make the faces planar
+        let curvature_regulator = face_j.regulators().with_untracked(
+            |regs| regs.first().unwrap().clone()
+        );
+        curvature_regulator.set_point().set(
+            SpecifiedValue::try_from("0".to_string()).unwrap()
+        );
+        
+        for k in index_range.clone().filter(|&index| index != j) {
+            let vertex_k = assembly.elements_by_id.with_untracked(
+                |elts_by_id| elts_by_id[&format!("v{k}")].clone()
+            );
+            
+            // fix the distances between the vertices
+            if j < k {
+                let distance_regulator = InversiveDistanceRegulator::new(
+                    [vertex_j.clone(), vertex_k.clone()]
+                );
+                assembly.insert_regulator(Rc::new(distance_regulator));
+            }
+            
+            // put the vertices on the faces
+            let incidence_regulator = InversiveDistanceRegulator::new([face_j.clone(), vertex_k.clone()]);
+            incidence_regulator.set_point.set(SpecifiedValue::try_from("0".to_string()).unwrap());
+            assembly.insert_regulator(Rc::new(incidence_regulator));
+        }
+    }
+}
+
+// to finish setting up the problem, fix the following curvatures:
+//   sun      1
+//   moon     5/3 = 1.666666666666666...
+//   chain1   2
+// a tiny `x` or `z` nudge of the outer sphere reliably prevents realization
+// failures before they happen, or resolves them after they happen. the result
+// depends sensitively on the translation direction, suggesting that realization
+// is failing because the engine is having trouble breaking a symmetry
+// /* TO DO */
+// the engine's performance on this problem is scale-dependent! with the current
+// initial conditions, realization fails for any order of imposing the remaining
+// curvature constraints. scaling everything up by a factor of ten, as done in
+// the original problem, makes realization succeed reliably. one potentially
+// relevant difference is that a lot of the numbers in the current initial
+// conditions are exactly representable as floats, unlike the analogous numbers
+// in the scaled-up problem. the inexact representations might break the
+// symmetry that's getting the engine stuck
+fn load_irisawa_hexlet_assemb(assembly: &Assembly) {
+    let index_range = 1..=6;
+    let colors = [
+        [1.00_f32, 0.00_f32, 0.25_f32],
+        [1.00_f32, 0.25_f32, 0.00_f32],
+        [0.75_f32, 0.75_f32, 0.00_f32],
+        [0.25_f32, 1.00_f32, 0.00_f32],
+        [0.00_f32, 0.25_f32, 1.00_f32],
+        [0.25_f32, 0.00_f32, 1.00_f32]
+    ].into_iter();
+    
+    // create the spheres
+    let spheres = [
+        Sphere::new(
+            "outer".to_string(),
+            "Outer".to_string(),
+            [0.5_f32, 0.5_f32, 0.5_f32],
+            engine::sphere(0.0, 0.0, 0.0, 1.5)
+        ),
+        Sphere::new(
+            "sun".to_string(),
+            "Sun".to_string(),
+            [0.75_f32, 0.75_f32, 0.75_f32],
+            engine::sphere(0.0, -0.75, 0.0, 0.75)
+        ),
+        Sphere::new(
+            "moon".to_string(),
+            "Moon".to_string(),
+            [0.25_f32, 0.25_f32, 0.25_f32],
+            engine::sphere(0.0, 0.75, 0.0, 0.75)
+        ),
+    ].into_iter().chain(
+        index_range.clone().zip(colors).map(
+            |(k, color)| {
+                let ang = (k as f64) * PI/3.0;
+                Sphere::new(
+                    format!("chain{k}"),
+                    format!("Chain {k}"),
+                    color,
+                    engine::sphere(1.0 * ang.sin(), 0.0, 1.0 * ang.cos(), 0.5)
+                )
+            }
+        )
+    );
+    for sphere in spheres {
+        let _ = assembly.try_insert_element(sphere);
+    }
+    
+    // put the outer sphere in ghost mode and fix its curvature
+    let outer = assembly.elements_by_id.with_untracked(
+        |elts_by_id| elts_by_id["outer"].clone()
+    );
+    outer.ghost().set(true);
+    let outer_curvature_regulator = outer.regulators().with_untracked(
+        |regs| regs.first().unwrap().clone()
+    );
+    outer_curvature_regulator.set_point().set(
+        SpecifiedValue::try_from((1.0 / 3.0).to_string()).unwrap()
+    );
+    
+    // impose the desired tangencies
+    let [outer, sun, moon] = ["outer", "sun", "moon"].map(
+        |id| assembly.elements_by_id.with_untracked(
+            |elts_by_id| elts_by_id[id].clone()
+        )
+    );
+    let chain = index_range.map(
+        |k| assembly.elements_by_id.with_untracked(
+            |elts_by_id| elts_by_id[&format!("chain{k}")].clone()
+        )
+    );
+    for (chain_sphere, chain_sphere_next) in chain.clone().zip(chain.cycle().skip(1)) {
+        for (other_sphere, inversive_distance) in [
+            (outer.clone(), "1"),
+            (sun.clone(), "-1"),
+            (moon.clone(), "-1"),
+            (chain_sphere_next.clone(), "-1")
+        ] {
+            let tangency = InversiveDistanceRegulator::new([chain_sphere.clone(), other_sphere]);
+            tangency.set_point.set(SpecifiedValue::try_from(inversive_distance.to_string()).unwrap());
+            assembly.insert_regulator(Rc::new(tangency));
+        }
+    }
+    
+    let outer_sun_tangency = InversiveDistanceRegulator::new([outer.clone(), sun]);
+    outer_sun_tangency.set_point.set(SpecifiedValue::try_from("1".to_string()).unwrap());
+    assembly.insert_regulator(Rc::new(outer_sun_tangency));
+    
+    let outer_moon_tangency = InversiveDistanceRegulator::new([outer.clone(), moon]);
+    outer_moon_tangency.set_point.set(SpecifiedValue::try_from("1".to_string()).unwrap());
+    assembly.insert_regulator(Rc::new(outer_moon_tangency));
+}
+
+// --- chooser ---
+
+/* DEBUG */
+#[component]
+pub fn TestAssemblyChooser() -> View {
+    // create an effect that loads the selected test assembly
+    let assembly_name = create_signal("general".to_string());
+    create_effect(move || {
+        // get name of chosen assembly
+        let name = assembly_name.get_clone();
+        console::log_1(
+            &JsValue::from(format!("Showing assembly \"{}\"", name.clone()))
+        );
+        
+        batch(|| {
+            let state = use_context::<AppState>();
+            let assembly = &state.assembly;
+            
+            // pause realization
+            assembly.keep_realized.set(false);
+            
+            // clear state
+            assembly.regulators.update(|regs| regs.clear());
+            assembly.elements.update(|elts| elts.clear());
+            assembly.elements_by_id.update(|elts_by_id| elts_by_id.clear());
+            assembly.descent_history.set(DescentHistory::new());
+            state.selection.update(|sel| sel.clear());
+            
+            // load assembly
+            match name.as_str() {
+                "general" => load_gen_assemb(assembly),
+                "low-curv" => load_low_curv_assemb(assembly),
+                "pointed" => load_pointed_assemb(assembly),
+                "tridim-icosahedron" => load_tridim_icosahedron_assemb(assembly),
+                "dodeca-packing" => load_dodeca_packing_assemb(assembly),
+                "balanced" => load_balanced_assemb(assembly),
+                "off-center" => load_off_center_assemb(assembly),
+                "radius-ratio" => load_radius_ratio_assemb(assembly),
+                "irisawa-hexlet" => load_irisawa_hexlet_assemb(assembly),
+                _ => ()
+            };
+            
+            // resume realization
+            assembly.keep_realized.set(true);
+        });
+    });
+    
+    // build the chooser
+    view! {
+        select(bind:value=assembly_name) {
+            option(value="general") { "General" }
+            option(value="low-curv") { "Low-curvature" }
+            option(value="pointed") { "Pointed" }
+            option(value="tridim-icosahedron") { "Tridiminished icosahedron" }
+            option(value="dodeca-packing") { "Dodecahedral packing" }
+            option(value="balanced") { "Balanced" }
+            option(value="off-center") { "Off-center" }
+            option(value="radius-ratio") { "Radius ratio" }
+            option(value="irisawa-hexlet") { "Irisawa hexlet" }
+            option(value="empty") { "Empty" }
+        }
+    }
+}

app-proto/src/lib.rs

@@ -0,0 +1 @@
+pub mod engine;

app-proto/src/main.rs

@@ -0,0 +1,69 @@
+mod assembly;
+mod components;
+mod engine;
+mod specified;
+
+#[cfg(test)]
+mod tests;
+
+use std::{collections::BTreeSet, rc::Rc};
+use sycamore::prelude::*;
+
+use assembly::{Assembly, Element};
+use components::{
+    add_remove::AddRemove,
+    diagnostics::Diagnostics,
+    display::Display,
+    outline::Outline
+};
+
+#[derive(Clone)]
+struct AppState {
+    assembly: Assembly,
+    selection: Signal<BTreeSet<Rc<dyn Element>>>
+}
+
+impl AppState {
+    fn new() -> AppState {
+        AppState {
+            assembly: Assembly::new(),
+            selection: create_signal(BTreeSet::default())
+        }
+    }
+    
+    // in single-selection mode, select the given element. in multiple-selection
+    // mode, toggle whether the given element is selected
+    fn select(&self, element: &Rc<dyn Element>, multi: bool) {
+        if multi {
+            self.selection.update(|sel| {
+                if !sel.remove(element) {
+                    sel.insert(element.clone());
+                }
+            });
+        } else {
+            self.selection.update(|sel| {
+                sel.clear();
+                sel.insert(element.clone());
+            });
+        }
+    }
+}
+
+fn main() {
+    // set the console error panic hook
+    #[cfg(feature = "console_error_panic_hook")]
+    console_error_panic_hook::set_once();
+    
+    sycamore::render(|| {
+        provide_context(AppState::new());
+        
+        view! {
+            div(id="sidebar") {
+                AddRemove {}
+                Outline {}
+                Diagnostics {}
+            }
+            Display {}
+        }
+    });
+}

app-proto/src/specified.rs

@@ -0,0 +1,44 @@
+use std::num::ParseFloatError;
+
+// a real number described by a specification string. since the structure is
+// read-only, we can guarantee that `spec` always specifies `value` in the
+// following format
+//   ┌──────────────────────────────────────────────────────┬───────────┐
+//   │ `spec`                                               │ `value`   │
+//   ┝━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┿━━━━━━━━━━━┥
+//   │ a string that parses to the floating-point value `x` │ `Some(x)` │
+//   ├──────────────────────────────────────────────────────┼───────────┤
+//   │ the empty string                                     │ `None`    │
+//   └──────────────────────────────────────────────────────┴───────────┘
+#[readonly::make]
+pub struct SpecifiedValue {
+    pub spec: String,
+    pub value: Option<f64>
+}
+
+impl SpecifiedValue {
+    pub fn from_empty_spec() -> SpecifiedValue {
+        SpecifiedValue { spec: String::new(), value: None }
+    }
+    
+    pub fn is_present(&self) -> bool {
+        matches!(self.value, Some(_))
+    }
+}
+
+// a `SpecifiedValue` can be constructed from a specification string, formatted
+// as described in the comment on the structure definition. the result is `Ok`
+// if the specification is properly formatted, and `Error` if not
+impl TryFrom<String> for SpecifiedValue {
+    type Error = ParseFloatError;
+    
+    fn try_from(spec: String) -> Result<Self, Self::Error> {
+        if spec.is_empty() {
+            Ok(SpecifiedValue::from_empty_spec())
+        } else {
+            spec.parse::<f64>().map(
+                |value| SpecifiedValue { spec: spec, value: Some(value) }
+            )
+        }
+    }
+}

app-proto/src/tests.rs

@@ -0,0 +1,14 @@
+use std::process::Command;
+
+// build and bundle the application, reporting success if there are no errors or
+// warnings. to see this test fail while others succeed, try moving `index.html`
+// or one of the assets that it links to
+#[test]
+fn trunk_build_test() {
+    let build_status = Command::new("trunk")
+        .arg("build")
+        .env("RUSTFLAGS", "-D warnings")
+        .status()
+        .expect("Call to Trunk failed");
+    assert!(build_status.success());
+}

engine-proto/alg-test/ConstructionViewer.jl

@@ -0,0 +1,223 @@
+module Viewer
+
+using Blink
+using Colors
+using Printf
+
+using Main.Engine
+
+export ConstructionViewer, display!, opentools!, closetools!
+
+# === Blink utilities ===
+
+append_to_head!(w, type, content) = @js w begin
+  @var element = document.createElement($type)
+  element.appendChild(document.createTextNode($content))
+  document.head.appendChild(element)
+end
+
+style!(w, stylesheet) = append_to_head!(w, "style", stylesheet)
+
+script!(w, code) = append_to_head!(w, "script", code)
+
+# === construction viewer ===
+
+mutable struct ConstructionViewer
+  win::Window
+  
+  function ConstructionViewer()
+    # create window and open developer console
+    win = Window(Blink.Dict(:width => 620, :height => 830))
+    
+    # set stylesheet
+    style!(win, """
+      body {
+        background-color: #ccc;
+      }
+      
+      /* the maximum dimensions keep Ganja from blowing up the canvas */
+      #view {
+        display: block;
+        width: 600px;
+        height: 600px;
+        margin-top: 10px;
+        margin-left: 10px;
+        border-radius: 10px;
+        background-color: #f0f0f0;
+      }
+      
+      #control-panel {
+        width: 600px;
+        height: 200px;
+        box-sizing: border-box;
+        padding: 5px 10px 5px 10px;
+        margin-top: 10px;
+        margin-left: 10px;
+        overflow-y: scroll;
+        border-radius: 10px;
+        background-color: #f0f0f0;
+      }
+      
+      #control-panel > div {
+        margin-top: 5px;
+        padding: 4px;
+        border-radius: 5px;
+        border: solid;
+        font-family: monospace;
+      }
+    """)
+    
+    # load Ganja.js. for an automatically updated web-hosted version, load from
+    #
+    #   https://unpkg.com/ganja.js
+    #
+    # instead
+    loadjs!(win, "http://localhost:8000/ganja-1.0.204.js")
+    
+    # create global functions and variables
+    script!(win, """
+      // create algebra
+      var CGA3 = Algebra(4, 1);
+      
+      // initialize element list and palette
+      var elements = [];
+      var palette = [];
+      
+      // declare handles for the view and its options
+      var view;
+      var viewOpt;
+      
+      // declare handles for the controls
+      var controlPanel;
+      var visToggles;
+      
+      // create scene function
+      function scene() {
+        commands = [];
+        for (let n = 0; n < elements.length; ++n) {
+          if (visToggles[n].checked) {
+            commands.push(palette[n], elements[n]);
+          }
+        }
+        return commands;
+      }
+      
+      function updateView() {
+        requestAnimationFrame(view.update.bind(view, scene));
+      }
+    """)
+    
+    @js win begin
+      # create view
+      viewOpt = Dict(
+        :conformal => true,
+        :gl => true,
+        :devicePixelRatio => window.devicePixelRatio
+      )
+      view = CGA3.graph(scene, viewOpt)
+      view.setAttribute(:id, "view")
+      view.removeAttribute(:style)
+      document.body.replaceChildren(view)
+      
+      # create control panel
+      controlPanel = document.createElement(:div)
+      controlPanel.setAttribute(:id, "control-panel")
+      document.body.appendChild(controlPanel)
+    end
+    
+    new(win)
+  end
+end
+
+mprod(v, w) =
+  v[1]*w[1] + v[2]*w[2] + v[3]*w[3] + v[4]*w[4] - v[5]*w[5]
+
+function display!(viewer::ConstructionViewer, elements::Matrix)
+  # load elements
+  elements_full = []
+  for elt in eachcol(Engine.unmix * elements)
+    if mprod(elt, elt) < 0.5
+      elt_full = [0; elt; fill(0, 26)]
+    else
+      # `elt` is a spacelike vector, representing a generalized sphere, so we
+      # take its Hodge dual before passing it to Ganja.js. the dual represents
+      # the same generalized sphere, but Ganja.js only displays planes when
+      # they're represented by vectors in grade 4 rather than grade 1
+      elt_full = [fill(0, 26); -elt[5]; -elt[4]; elt[3]; -elt[2]; elt[1]; 0]
+    end
+    push!(elements_full, elt_full)
+  end
+  @js viewer.win elements = $elements_full.map((elt) -> @new CGA3(elt))
+  
+  # generate palette. this is Gadfly's `default_discrete_colors` palette,
+  # available under the MIT license
+  palette = distinguishable_colors(
+    length(elements_full),
+    [LCHab(70, 60, 240)],
+    transform = c -> deuteranopic(c, 0.5),
+    lchoices = Float64[65, 70, 75, 80],
+    cchoices = Float64[0, 50, 60, 70],
+    hchoices = range(0, stop=330, length=24)
+  )
+  palette_packed = [RGB24(c).color for c in palette]
+  @js viewer.win palette = $palette_packed
+  
+  # create visibility toggles
+  @js viewer.win begin
+    controlPanel.replaceChildren()
+    visToggles = []
+  end
+  for (elt, c) in zip(eachcol(elements), palette)
+    vec_str = join(map(t -> @sprintf("%.3f", t), elt), ", ")
+    color_str = "#$(hex(c))"
+    style_str = "background-color: $color_str; border-color: $color_str;"
+    @js viewer.win begin
+      @var toggle = document.createElement(:div)
+      toggle.setAttribute(:style, $style_str)
+      toggle.checked = true
+      toggle.addEventListener(
+        "click",
+        () -> begin
+          toggle.checked = !toggle.checked
+          toggle.style.backgroundColor = toggle.checked ? $color_str : "inherit";
+          updateView()
+        end
+      )
+      toggle.appendChild(document.createTextNode($vec_str))
+      visToggles.push(toggle);
+      controlPanel.appendChild(toggle);
+    end
+  end
+  
+  # update view
+  @js viewer.win updateView()
+end
+
+function opentools!(viewer::ConstructionViewer)
+  size(viewer.win, 1240, 830)
+  opentools(viewer.win)
+end
+
+function closetools!(viewer::ConstructionViewer)
+  closetools(viewer.win)
+  size(viewer.win, 620, 830)
+end
+
+end
+
+# ~~~ sandbox setup ~~~
+
+elements = let
+  a = sqrt(BigFloat(3)/2)
+  sqrt(0.5) * BigFloat[
+    1    1   -1   -1    0
+    1   -1    1   -1    0
+    1   -1   -1    1    0
+    0.5  0.5  0.5  0.5  1+a
+    0.5  0.5  0.5  0.5  1-a
+  ]
+end
+
+# show construction
+viewer = Viewer.ConstructionViewer()
+Viewer.display!(viewer, elements)

engine-proto/alg-test/Engine.Algebraic.jl

@@ -0,0 +1,203 @@
+module Algebraic
+
+export
+  codimension, dimension,
+  Construction, realize,
+  Element, Point, Sphere,
+  Relation, LiesOn, AlignsWithBy, mprod
+
+import Subscripts
+using LinearAlgebra
+using AbstractAlgebra
+using Groebner
+using ...HittingSet
+
+# --- commutative algebra ---
+
+# as of version 0.36.6, AbstractAlgebra only supports ideals in multivariate
+# polynomial rings when the coefficients are integers. we use Groebner to extend
+# support to rationals and to finite fields of prime order
+Generic.reduce_gens(I::Generic.Ideal{U}) where {T <: FieldElement, U <: MPolyRingElem{T}} =
+  Generic.Ideal{U}(base_ring(I), groebner(gens(I)))
+
+function codimension(I::Generic.Ideal{U}, maxdepth = Inf) where {T <: RingElement, U <: MPolyRingElem{T}}
+  leading = [exponent_vector(f, 1) for f in gens(I)]
+  targets = [Set(findall(.!iszero.(exp_vec))) for exp_vec in leading]
+  length(HittingSet.solve(HittingSetProblem(targets), maxdepth))
+end
+
+dimension(I::Generic.Ideal{U}, maxdepth = Inf) where {T <: RingElement, U <: MPolyRingElem{T}} =
+  length(gens(base_ring(I))) - codimension(I, maxdepth)
+
+# --- primitve elements ---
+
+abstract type Element{T} end
+
+mutable struct Point{T} <: Element{T}
+  coords::Vector{MPolyRingElem{T}}
+  vec::Union{Vector{MPolyRingElem{T}}, Nothing}
+  rel::Nothing
+  
+  ## [to do] constructor argument never needed?
+  Point{T}(
+    coords::Vector{MPolyRingElem{T}} = MPolyRingElem{T}[],
+    vec::Union{Vector{MPolyRingElem{T}}, Nothing} = nothing
+  ) where T = new(coords, vec, nothing)
+end
+
+function buildvec!(pt::Point)
+  coordring = parent(pt.coords[1])
+  pt.vec = [one(coordring), dot(pt.coords, pt.coords), pt.coords...]
+end
+
+mutable struct Sphere{T} <: Element{T}
+  coords::Vector{MPolyRingElem{T}}
+  vec::Union{Vector{MPolyRingElem{T}}, Nothing}
+  rel::Union{MPolyRingElem{T}, Nothing}
+  
+  ## [to do] constructor argument never needed?
+  Sphere{T}(
+    coords::Vector{MPolyRingElem{T}} = MPolyRingElem{T}[],
+    vec::Union{Vector{MPolyRingElem{T}}, Nothing} = nothing,
+    rel::Union{MPolyRingElem{T}, Nothing} = nothing
+  ) where T = new(coords, vec, rel)
+end
+
+function buildvec!(sph::Sphere)
+  coordring = parent(sph.coords[1])
+  sph.vec = sph.coords
+  sph.rel = mprod(sph.coords, sph.coords) + one(coordring)
+end
+
+const coordnames = IdDict{Symbol, Vector{Union{Symbol, Nothing}}}(
+  nameof(Point) => [nothing, nothing, :xₚ, :yₚ, :zₚ],
+  nameof(Sphere) => [:rₛ, :sₛ, :xₛ, :yₛ, :zₛ]
+)
+
+coordname(elt::Element, index) = coordnames[nameof(typeof(elt))][index]
+
+function pushcoordname!(coordnamelist, indexed_elt::Tuple{Any, Element}, coordindex)
+  eltindex, elt = indexed_elt
+  name = coordname(elt, coordindex)
+  if !isnothing(name)
+    subscript = Subscripts.sub(string(eltindex))
+    push!(coordnamelist, Symbol(name, subscript))
+  end
+end
+
+function takecoord!(coordlist, indexed_elt::Tuple{Any, Element}, coordindex)
+  elt = indexed_elt[2]
+  if !isnothing(coordname(elt, coordindex))
+    push!(elt.coords, popfirst!(coordlist))
+  end
+end
+
+# --- primitive relations ---
+
+abstract type Relation{T} end
+
+mprod(v, w) = (v[1]*w[2] + w[1]*v[2]) / 2 - dot(v[3:end], w[3:end])
+
+# elements: point, sphere
+struct LiesOn{T} <: Relation{T}
+  elements::Vector{Element{T}}
+  
+  LiesOn{T}(pt::Point{T}, sph::Sphere{T}) where T = new{T}([pt, sph])
+end
+
+equation(rel::LiesOn) = mprod(rel.elements[1].vec, rel.elements[2].vec)
+
+# elements: sphere, sphere
+struct AlignsWithBy{T} <: Relation{T}
+  elements::Vector{Element{T}}
+  cos_angle::T
+  
+  AlignsWithBy{T}(sph1::Sphere{T}, sph2::Sphere{T}, cos_angle::T) where T = new{T}([sph1, sph2], cos_angle)
+end
+
+equation(rel::AlignsWithBy) = mprod(rel.elements[1].vec, rel.elements[2].vec) - rel.cos_angle
+
+# --- constructions ---
+
+mutable struct Construction{T}
+  points::Vector{Point{T}}
+  spheres::Vector{Sphere{T}}
+  relations::Vector{Relation{T}}
+  
+  function Construction{T}(; elements = Vector{Element{T}}(), relations = Vector{Relation{T}}()) where T
+    allelements = union(elements, (rel.elements for rel in relations)...)
+    new{T}(
+      filter(elt -> isa(elt, Point), allelements),
+      filter(elt -> isa(elt, Sphere), allelements),
+      relations
+    )
+  end
+end
+
+function Base.push!(ctx::Construction{T}, elt::Point{T}) where T
+  push!(ctx.points, elt)
+end
+
+function Base.push!(ctx::Construction{T}, elt::Sphere{T}) where T
+  push!(ctx.spheres, elt)
+end
+
+function Base.push!(ctx::Construction{T}, rel::Relation{T}) where T
+  push!(ctx.relations, rel)
+  for elt in rel.elements
+    push!(ctx, elt)
+  end
+end
+
+function realize(ctx::Construction{T}) where T
+  # collect coordinate names
+  coordnamelist = Symbol[]
+  eltenum = enumerate(Iterators.flatten((ctx.spheres, ctx.points)))
+  for coordindex in 1:5
+    for indexed_elt in eltenum
+      pushcoordname!(coordnamelist, indexed_elt, coordindex)
+    end
+  end
+  
+  # construct coordinate ring
+  coordring, coordqueue = polynomial_ring(parent_type(T)(), coordnamelist, ordering = :degrevlex)
+  
+  # retrieve coordinates
+  for (_, elt) in eltenum
+    empty!(elt.coords)
+  end
+  for coordindex in 1:5
+    for indexed_elt in eltenum
+      takecoord!(coordqueue, indexed_elt, coordindex)
+    end
+  end
+  
+  # construct coordinate vectors
+  for (_, elt) in eltenum
+    buildvec!(elt)
+  end
+  
+  # turn relations into equations
+  eqns = vcat(
+    equation.(ctx.relations),
+    [elt.rel for (_, elt) in eltenum if !isnothing(elt.rel)]
+  )
+  
+  # add relations to center, orient, and scale the construction
+  # [to do] the scaling constraint, as written, can be impossible to satisfy
+  #         when all of the spheres have to go through the origin
+  if !isempty(ctx.points)
+    append!(eqns, [sum(pt.coords[k] for pt in ctx.points) for k in 1:3])
+  end
+  if !isempty(ctx.spheres)
+    append!(eqns, [sum(sph.coords[k] for sph in ctx.spheres) for k in 3:4])
+  end
+  n_elts = length(ctx.points) + length(ctx.spheres)
+  if n_elts > 0
+    push!(eqns, sum(elt.vec[2] for elt in Iterators.flatten((ctx.points, ctx.spheres))) - n_elts)
+  end
+  
+  (Generic.Ideal(coordring, eqns), eqns)
+end
+
+end

engine-proto/alg-test/Engine.Numerical.jl

@@ -0,0 +1,53 @@
+module Numerical
+
+using Random: default_rng
+using LinearAlgebra
+using AbstractAlgebra
+using HomotopyContinuation:
+  Variable, Expression, AbstractSystem, System, LinearSubspace,
+  nvariables, isreal, witness_set, results
+import GLMakie
+using ..Algebraic
+
+# --- polynomial conversion ---
+
+# hat tip Sascha Timme
+#   https://github.com/JuliaHomotopyContinuation/HomotopyContinuation.jl/issues/520#issuecomment-1317681521
+function Base.convert(::Type{Expression}, f::MPolyRingElem)
+  variables = Variable.(symbols(parent(f)))
+  f_data = zip(coefficients(f), exponent_vectors(f))
+  sum(cf * prod(variables .^ exp_vec) for (cf, exp_vec) in f_data)
+end
+
+# create a ModelKit.System from an ideal in a multivariate polynomial ring. the
+# variable ordering is taken from the polynomial ring
+function System(I::Generic.Ideal)
+  eqns = Expression.(gens(I))
+  variables = Variable.(symbols(base_ring(I)))
+  System(eqns, variables = variables)
+end
+
+# --- sampling ---
+
+function real_samples(F::AbstractSystem, dim; rng = default_rng())
+  # choose a random real hyperplane of codimension `dim` by intersecting
+  # hyperplanes whose normal vectors are uniformly distributed over the unit
+  # sphere
+  # [to do] guard against the unlikely event that one of the normals is zero
+  normals = transpose(hcat(
+    (normalize(randn(rng, nvariables(F))) for _ in 1:dim)...
+  ))
+  cut = LinearSubspace(normals, fill(0., dim))
+  filter(isreal, results(witness_set(F, cut, seed = 0x1974abba)))
+end
+
+AbstractAlgebra.evaluate(pt::Point, vals::Vector{<:RingElement}) =
+  GLMakie.Point3f([evaluate(u, vals) for u in pt.coords])
+
+function AbstractAlgebra.evaluate(sph::Sphere, vals::Vector{<:RingElement})
+  radius = 1 / evaluate(sph.coords[1], vals)
+  center = radius * [evaluate(u, vals) for u in sph.coords[3:end]]
+  GLMakie.Sphere(GLMakie.Point3f(center), radius)
+end
+
+end

engine-proto/alg-test/Engine.jl

@@ -0,0 +1,76 @@
+include("HittingSet.jl")
+
+module Engine
+
+include("Engine.Algebraic.jl")
+include("Engine.Numerical.jl")
+
+using .Algebraic
+using .Numerical
+
+export Construction, mprod, codimension, dimension
+
+end
+
+# ~~~ sandbox setup ~~~
+
+using Random
+using Distributions
+using LinearAlgebra
+using AbstractAlgebra
+using HomotopyContinuation
+using GLMakie
+
+CoeffType = Rational{Int64}
+
+spheres = [Engine.Sphere{CoeffType}() for _ in 1:3]
+tangencies = [
+  Engine.AlignsWithBy{CoeffType}(
+    spheres[n],
+    spheres[mod1(n+1, length(spheres))],
+    CoeffType(1)
+  )
+  for n in 1:3
+]
+ctx_tan_sph = Engine.Construction{CoeffType}(elements = spheres, relations = tangencies)
+ideal_tan_sph, eqns_tan_sph = Engine.realize(ctx_tan_sph)
+freedom = Engine.dimension(ideal_tan_sph)
+println("Three mutually tangent spheres: $freedom degrees of freedom")
+
+# --- test rational cut ---
+
+coordring = base_ring(ideal_tan_sph)
+vbls = Variable.(symbols(coordring))
+
+# test a random witness set
+system = CompiledSystem(System(eqns_tan_sph, variables = vbls))
+norm2 = vec -> real(dot(conj.(vec), vec))
+rng = MersenneTwister(6071)
+n_planes = 6
+samples = []
+for _ in 1:n_planes
+  real_solns = solution.(Engine.Numerical.real_samples(system, freedom, rng = rng))
+  for soln in real_solns
+    if all(norm2(soln - samp) > 1e-4*length(gens(coordring)) for samp in samples)
+      push!(samples, soln)
+    end
+  end
+end
+println("Found $(length(samples)) sample solutions")
+
+# show a sample solution
+function show_solution(ctx, vals)
+  # evaluate elements
+  real_vals = real.(vals)
+  disp_points = [Engine.Numerical.evaluate(pt, real_vals) for pt in ctx.points]
+  disp_spheres = [Engine.Numerical.evaluate(sph, real_vals) for sph in ctx.spheres]
+  
+  # create scene
+  scene = Scene()
+  cam3d!(scene)
+  scatter!(scene, disp_points, color = :green)
+  for sph in disp_spheres
+    mesh!(scene, sph, color = :gray)
+  end
+  scene
+end

engine-proto/alg-test/HittingSet.jl

@@ -0,0 +1,111 @@
+module HittingSet
+
+export HittingSetProblem, solve
+
+HittingSetProblem{T} = Pair{Set{T}, Vector{Pair{T, Set{Set{T}}}}}
+
+# `targets` should be a collection of Set objects
+function HittingSetProblem(targets, chosen = Set())
+  wholeset = union(targets...)
+  T = eltype(wholeset)
+  unsorted_moves = [
+    elt => Set(filter(s -> elt ∉ s, targets))
+    for elt in wholeset
+  ]
+  moves = sort(unsorted_moves, by = pair -> length(pair.second))
+  Set{T}(chosen) => moves
+end
+
+function Base.display(problem::HittingSetProblem{T}) where T
+  println("HittingSetProblem{$T}")
+  
+  chosen = problem.first
+  println(" {", join(string.(chosen), ", "), "}")
+  
+  moves = problem.second
+  for (choice, missed) in moves
+    println(" | ", choice)
+    for s in missed
+      println(" | | {", join(string.(s), ", "), "}")
+    end
+  end
+  println()
+end
+
+function solve(pblm::HittingSetProblem{T}, maxdepth = Inf) where T
+  problems = Dict(pblm)
+  while length(first(problems).first) < maxdepth
+    subproblems = typeof(problems)()
+    for (chosen, moves) in problems
+      if isempty(moves)
+        return chosen
+      else
+        for (choice, missed) in moves
+          to_be_chosen = union(chosen, Set([choice]))
+          if isempty(missed)
+            return to_be_chosen
+          elseif !haskey(subproblems, to_be_chosen)
+            push!(subproblems, HittingSetProblem(missed, to_be_chosen))
+          end
+        end
+      end
+    end
+    problems = subproblems
+  end
+  problems
+end
+
+function test(n = 1)
+  T = [Int64, Int64, Symbol, Symbol][n]
+  targets = Set{T}.([
+    [
+      [1, 3, 5],
+      [2, 3, 4],
+      [1, 4],
+      [2, 3, 4, 5],
+      [4, 5]
+    ],
+    # example from Amit Chakrabarti's graduate-level algorithms class (CS 105)
+    # notes by Valika K. Wan and Khanh Do Ba, Winter 2005
+    # https://www.cs.dartmouth.edu/~ac/Teach/CS105-Winter05/
+    [
+      [1, 3], [1,    4], [1,    5],
+      [1, 3], [1, 2, 4], [1, 2, 5],
+      [4, 3], [   2, 4], [   2, 5],
+      [6, 3], [6,    4], [      5]
+    ],
+    [
+      [:w, :x, :y],
+      [:x, :y, :z],
+      [:w, :z],
+      [:x, :y]
+    ],
+    # Wikipedia showcases this as an example of a problem where the greedy
+    # algorithm performs especially poorly
+    [
+      [:a, :x, :t1],
+      [:a, :y, :t2],
+      [:a, :y, :t3],
+      [:a, :z, :t4],
+      [:a, :z, :t5],
+      [:a, :z, :t6],
+      [:a, :z, :t7],
+      [:b, :x, :t8],
+      [:b, :y, :t9],
+      [:b, :y, :t10],
+      [:b, :z, :t11],
+      [:b, :z, :t12],
+      [:b, :z, :t13],
+      [:b, :z, :t14]
+    ]
+  ][n])
+  problem = HittingSetProblem(targets)
+  if isa(problem, HittingSetProblem{T})
+    println("Correct type")
+  else
+    println("Wrong type: ", typeof(problem))
+  end
+  problem
+end
+
+end

engine-proto/ganja-test/ganja-test.html

@@ -0,0 +1,96 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <style>
+    body {
+      background-color: #ffe0f0;
+    }
+    
+    /* needed to keep Ganja canvas from blowing up */
+    canvas {
+      min-width: 600px;
+      max-width: 600px;
+      min-height: 600px;
+      max-height: 600px;
+    }
+  </style>
+  <script src="https://unpkg.com/ganja.js"></script>
+</head>
+<body>
+  <p><button onclick="flip()">Flip</button></p>
+  <script>
+  // in the default view, e4 + e5 is the point at infinity
+  let CGA3 = Algebra(4, 1);
+  let elements = [
+    CGA3.inline(() => Math.sqrt(0.5)*( 1e1 + 1e2 + 1e3 + 1e5))(),
+    CGA3.inline(() => Math.sqrt(0.5)*( 1e1 - 1e2 - 1e3 + 1e5))(),
+    CGA3.inline(() => Math.sqrt(0.5)*(-1e1 + 1e2 - 1e3 + 1e5))(),
+    CGA3.inline(() => Math.sqrt(0.5)*(-1e1 - 1e2 + 1e3 + 1e5))(),
+    CGA3.inline(() => -Math.sqrt(3)*1e4 + Math.sqrt(2)*1e5)()
+  ];
+  /*
+    these blocks of commented-out code can be used to confirm that a spacelike
+    vector and its Hodge dual represent the same generalized sphere
+  */
+  /*let elements = [
+    CGA3.inline(() => Math.sqrt(0.5)*!( 1e1 + 1e2 + 1e3 + 1e5))(),
+    CGA3.inline(() => Math.sqrt(0.5)*!( 1e1 - 1e2 - 1e3 + 1e5))(),
+    CGA3.inline(() => Math.sqrt(0.5)*!(-1e1 + 1e2 - 1e3 + 1e5))(),
+    CGA3.inline(() => Math.sqrt(0.5)*!(-1e1 - 1e2 + 1e3 + 1e5))(),
+    CGA3.inline(() => !(-Math.sqrt(3)*1e4 + Math.sqrt(2)*1e5))()
+  ];*/
+  /*let elements = [
+    CGA3.inline(() =>  1e1 + 1e5)(),
+    CGA3.inline(() =>  1e2 + 1e5)(),
+    CGA3.inline(() =>  1e3 + 1e5)(),
+    CGA3.inline(() => -1e4 + 1e5)(),
+    CGA3.inline(() => Math.sqrt(0.5)*(1e1 + 1e2 + 1e3 + 1e5))(),
+    CGA3.inline(() => Math.sqrt(0.5)*!(1e1 + 1e2 + 1e3 - 0.01e4 + 1e5))()
+  ];*/
+  
+  // set up palette
+  var colorIndex;
+  var palette = [0xff00b0, 0x00ffb0, 0x00b0ff, 0x8040ff, 0xc0c0c0];
+  function nextColor() {
+    colorIndex = (colorIndex + 1) % palette.length;
+    return palette[colorIndex];
+  }
+  function resetColorCycle() {
+    colorIndex = palette.length - 1;
+  }
+  resetColorCycle();
+  
+  // create scene function
+  function scene() {
+    commands = [];
+    resetColorCycle();
+    elements.forEach((elt) => commands.push(nextColor(), elt));
+    return commands;
+  }
+  
+  // initialize graph
+  let graph = CGA3.graph(
+    scene,
+    {
+      conformal: true, gl: true, grid: true
+    }
+  )
+  document.body.appendChild(graph);
+  
+  function flip() {
+    let last = elements.length - 1;
+    for (let n = 0; n < last; ++n) {
+      // reflect
+      elements[n] = CGA3.Mul(CGA3.Mul(elements[last], elements[n]), elements[last]);
+      
+      // de-noise
+      for (let k = 6; k < elements[n].length; ++k) {
+      /*for (let k = 0; k < 26; ++k) {*/
+        elements[n][k] = 0;
+      }
+    }
+    requestAnimationFrame(graph.update.bind(graph, scene));
+  }
+  </script>
+</body>
+</html>

engine-proto/ganja-test/ganja-test.jl

@@ -0,0 +1,127 @@
+using Blink
+using Colors
+
+# === utilities ===
+
+append_to_head!(w, type, content) = @js w begin
+  @var element = document.createElement($type)
+  element.appendChild(document.createTextNode($content))
+  document.head.appendChild(element)
+end
+
+style!(w, stylesheet) = append_to_head!(w, "style", stylesheet)
+
+script!(w, code) = append_to_head!(w, "script", code)
+
+function add_element!(vec)
+  # add element
+  full_vec = [0; vec; fill(0, 26)]
+  n = @js win elements.push(@new CGA3($full_vec))
+  
+  # generate palette. this is Gadfly's `default_discrete_colors` palette,
+  # available under the MIT license
+  palette = distinguishable_colors(
+    n,
+    [LCHab(70, 60, 240)],
+    transform = c -> deuteranopic(c, 0.5),
+    lchoices = Float64[65, 70, 75, 80],
+    cchoices = Float64[0, 50, 60, 70],
+    hchoices = range(0, stop=330, length=24)
+  )
+  palette_packed = [RGB24(c).color for c in palette]
+  @js win palette = $palette_packed
+end
+
+# === build page ===
+
+# create window and open developer console
+win = Window()
+opentools(win)
+
+# set stylesheet
+style!(win, """
+  body {
+    background-color: #ffe0f0;
+  }
+
+  /* needed to keep Ganja canvas from blowing up */
+  canvas {
+    min-width: 600px;
+    max-width: 600px;
+    min-height: 600px;
+    max-height: 600px;
+  }
+""")
+
+# load Ganja.js
+loadjs!(win, "https://unpkg.com/ganja.js")
+
+# create global functions and variables
+script!(win, """
+  // create algebra
+  var CGA3 = Algebra(4, 1);
+  
+  // initialize element list and palette
+  var elements = [];
+  var palette = [];
+  
+  // declare visualization handle
+  var graph;
+  
+  // create scene function
+  function scene() {
+    commands = [];
+    for (let n = 0; n < elements.length; ++n) {
+      commands.push(palette[n], elements[n]);
+    }
+    return commands;
+  }
+  
+  function flip() {
+    let last = elements.length - 1;
+    for (let n = 0; n < last; ++n) {
+      // reflect
+      elements[n] = CGA3.Mul(CGA3.Mul(elements[last], elements[n]), elements[last]);
+      
+      // de-noise
+      for (let k = 6; k < elements[n].length; ++k) {
+        elements[n][k] = 0;
+      }
+    }
+    requestAnimationFrame(graph.update.bind(graph, scene));
+  }
+""")
+
+# set up controls
+body!(win, """
+  <p><button id="flip-button" onclick="flip()">Flip</button></p>
+""", async = false)
+
+# === set up visualization ===
+
+# list elements. in the default view, e4 + e5 is the point at infinity
+elements = sqrt(0.5) * BigFloat[
+  1  1 -1 -1  0;
+  1 -1  1 -1  0;
+  1 -1 -1  1  0;
+  0  0  0  0 -sqrt(6);
+  1  1  1  1  2
+]
+
+# load elements
+for vec in eachcol(elements)
+  add_element!(vec)
+end
+
+# initialize visualization
+@js win begin
+  graph = CGA3.graph(
+    scene,
+    Dict(
+      "conformal" => true,
+      "gl" => true,
+      "grid" => true
+    )
+  )
+  document.body.appendChild(graph)
+end

engine-proto/gram-test/Engine.jl

@@ -0,0 +1,573 @@
+module Engine
+
+using LinearAlgebra
+using GenericLinearAlgebra
+using SparseArrays
+using Random
+using Optim
+
+export
+  rand_on_shell, Q, DescentHistory,
+  realize_gram_gradient, realize_gram_newton, realize_gram_optim,
+  realize_gram_alt_proj, realize_gram
+
+# === guessing ===
+
+sconh(t, u) = 0.5*(exp(t) + u*exp(-t))
+
+function rand_on_sphere(rng::AbstractRNG, ::Type{T}, n) where T
+  out = randn(rng, T, n)
+  tries_left = 2
+  while dot(out, out) < 1e-6 && tries_left > 0
+    out = randn(rng, T, n)
+    tries_left -= 1
+  end
+  normalize(out)
+end
+
+##[TO DO] write a test to confirm that the outputs are on the correct shells
+function rand_on_shell(rng::AbstractRNG, shell::T) where T <: Number
+  space_part = rand_on_sphere(rng, T, 4)
+  rapidity = randn(rng, T)
+  sig = sign(shell)
+  nullmix * [sconh(rapidity, sig)*space_part; sconh(rapidity, -sig)]
+end
+
+rand_on_shell(rng::AbstractRNG, shells::Array{T}) where T <: Number =
+  hcat([rand_on_shell(rng, sh) for sh in shells]...)
+
+rand_on_shell(shells::Array{<:Number}) = rand_on_shell(Random.default_rng(), shells)
+
+# === elements ===
+
+point(pos) = [pos; 0.5; 0.5 * dot(pos, pos)]
+
+plane(normal, offset) = [-normal; 0; -offset]
+
+function sphere(center, radius)
+  dist_sq = dot(center, center)
+  [
+    center / radius;
+    0.5 / radius;
+    0.5 * (dist_sq / radius - radius)
+  ]
+end
+
+# === Gram matrix realization ===
+
+# basis changes
+nullmix = [Matrix{Int64}(I, 3, 3) zeros(Int64, 3, 2); zeros(Int64, 2, 3) [-1 1; 1 1]//2]
+unmix = [Matrix{Int64}(I, 3, 3) zeros(Int64, 3, 2); zeros(Int64, 2, 3) [-1 1; 1 1]]
+
+# the Lorentz form
+Q = [Matrix{Int64}(I, 3, 3) zeros(Int64, 3, 2); zeros(Int64, 2, 3) [0 -2; -2 0]]
+
+# project a matrix onto the subspace of matrices whose entries vanish away from
+# the given indices
+function proj_to_entries(mat, indices)
+  result = zeros(size(mat))
+  for (j, k) in indices
+    result[j, k] = mat[j, k]
+  end
+  result
+end
+
+# the difference between the matrices `target` and `attempt`, projected onto the
+# subspace of matrices whose entries vanish at each empty index of `target`
+function proj_diff(target::SparseMatrixCSC{T, <:Any}, attempt::Matrix{T}) where T
+  J, K, values = findnz(target)
+  result = zeros(size(target))
+  for (j, k, val) in zip(J, K, values)
+    result[j, k] = val - attempt[j, k]
+  end
+  result
+end
+
+# a type for keeping track of gradient descent history
+struct DescentHistory{T}
+  scaled_loss::Array{T}
+  neg_grad::Array{Matrix{T}}
+  base_step::Array{Matrix{T}}
+  hess::Array{Hermitian{T, Matrix{T}}}
+  slope::Array{T}
+  stepsize::Array{T}
+  positive::Array{Bool}
+  backoff_steps::Array{Int64}
+  last_line_L::Array{Matrix{T}}
+  last_line_loss::Array{T}
+  
+  function DescentHistory{T}(
+    scaled_loss = Array{T}(undef, 0),
+    neg_grad = Array{Matrix{T}}(undef, 0),
+    hess = Array{Hermitian{T, Matrix{T}}}(undef, 0),
+    base_step = Array{Matrix{T}}(undef, 0),
+    slope = Array{T}(undef, 0),
+    stepsize = Array{T}(undef, 0),
+    positive = Bool[],
+    backoff_steps = Int64[],
+    last_line_L = Array{Matrix{T}}(undef, 0),
+    last_line_loss = Array{T}(undef, 0)
+  ) where T
+    new(scaled_loss, neg_grad, hess, base_step, slope, stepsize, positive, backoff_steps, last_line_L, last_line_loss)
+  end
+end
+
+# seek a matrix `L` for which `L'QL` matches the sparse matrix `gram` at every
+# explicit entry of `gram`. use gradient descent starting from `guess`
+function realize_gram_gradient(
+  gram::SparseMatrixCSC{T, <:Any},
+  guess::Matrix{T};
+  scaled_tol = 1e-30,
+  min_efficiency = 0.5,
+  init_stepsize = 1.0,
+  backoff = 0.9,
+  max_descent_steps = 600,
+  max_backoff_steps = 110
+) where T <: Number
+  # start history
+  history = DescentHistory{T}()
+  
+  # scale tolerance
+  scale_adjustment = sqrt(T(nnz(gram)))
+  tol = scale_adjustment * scaled_tol
+  
+  # initialize variables
+  stepsize = init_stepsize
+  L = copy(guess)
+  
+  # do gradient descent
+  Δ_proj = proj_diff(gram, L'*Q*L)
+  loss = dot(Δ_proj, Δ_proj)
+  for _ in 1:max_descent_steps
+    # stop if the loss is tolerably low
+    if loss < tol
+      break
+    end
+    
+    # find the negative gradient of the loss function
+    neg_grad = 4*Q*L*Δ_proj
+    slope = norm(neg_grad)
+    dir = neg_grad / slope
+    
+    # store current position, loss, and slope
+    L_last = L
+    loss_last = loss
+    push!(history.scaled_loss, loss / scale_adjustment)
+    push!(history.neg_grad, neg_grad)
+    push!(history.slope, slope)
+    
+    # find a good step size using backtracking line search
+    push!(history.stepsize, 0)
+    push!(history.backoff_steps, max_backoff_steps)
+    empty!(history.last_line_L)
+    empty!(history.last_line_loss)
+    for backoff_steps in 0:max_backoff_steps
+      history.stepsize[end] = stepsize
+      L = L_last + stepsize * dir
+      Δ_proj = proj_diff(gram, L'*Q*L)
+      loss = dot(Δ_proj, Δ_proj)
+      improvement = loss_last - loss
+      push!(history.last_line_L, L)
+      push!(history.last_line_loss, loss / scale_adjustment)
+      if improvement >= min_efficiency * stepsize * slope
+        history.backoff_steps[end] = backoff_steps
+        break
+      end
+      stepsize *= backoff
+    end
+    
+    # [DEBUG] if we've hit a wall, quit
+    if history.backoff_steps[end] == max_backoff_steps
+      break
+    end
+  end
+  
+  # return the factorization and its history
+  push!(history.scaled_loss, loss / scale_adjustment)
+  L, history
+end
+
+function basis_matrix(::Type{T}, j, k, dims) where T
+  result = zeros(T, dims)
+  result[j, k] = one(T)
+  result
+end
+
+# seek a matrix `L` for which `L'QL` matches the sparse matrix `gram` at every
+# explicit entry of `gram`. use Newton's method starting from `guess`
+function realize_gram_newton(
+  gram::SparseMatrixCSC{T, <:Any},
+  guess::Matrix{T};
+  scaled_tol = 1e-30,
+  rate = 1,
+  max_steps = 100
+) where T <: Number
+  # start history
+  history = DescentHistory{T}()
+  
+  # find the dimension of the search space
+  dims = size(guess)
+  element_dim, construction_dim = dims
+  total_dim = element_dim * construction_dim
+  
+  # list the constrained entries of the gram matrix
+  J, K, _ = findnz(gram)
+  constrained = zip(J, K)
+  
+  # scale the tolerance
+  scale_adjustment = sqrt(T(length(constrained)))
+  tol = scale_adjustment * scaled_tol
+  
+  # use Newton's method
+  L = copy(guess)
+  for step in 0:max_steps
+    # evaluate the loss function
+    Δ_proj = proj_diff(gram, L'*Q*L)
+    loss = dot(Δ_proj, Δ_proj)
+    
+    # store the current loss
+    push!(history.scaled_loss, loss / scale_adjustment)
+    
+    # stop if the loss is tolerably low
+    if loss < tol || step > max_steps
+      break
+    end
+    
+    # find the negative gradient of the loss function
+    neg_grad = 4*Q*L*Δ_proj
+    
+    # find the negative Hessian of the loss function
+    hess = Matrix{T}(undef, total_dim, total_dim)
+    indices = [(j, k) for k in 1:construction_dim for j in 1:element_dim]
+    for (j, k) in indices
+      basis_mat = basis_matrix(T, j, k, dims)
+      neg_dΔ = basis_mat'*Q*L + L'*Q*basis_mat
+      neg_dΔ_proj = proj_to_entries(neg_dΔ, constrained)
+      deriv_grad = 4*Q*(-basis_mat*Δ_proj + L*neg_dΔ_proj)
+      hess[:, (k-1)*element_dim + j] = reshape(deriv_grad, total_dim)
+    end
+    hess = Hermitian(hess)
+    push!(history.hess, hess)
+    
+    # compute the Newton step
+    step = hess \ reshape(neg_grad, total_dim)
+    L += rate * reshape(step, dims)
+  end
+  
+  # return the factorization and its history
+  L, history
+end
+
+LinearAlgebra.eigen!(A::Symmetric{BigFloat, Matrix{BigFloat}}; sortby::Nothing) =
+  eigen!(Hermitian(A))
+
+function convertnz(type, mat)
+  J, K, values = findnz(mat)
+  sparse(J, K, type.(values))
+end
+
+function realize_gram_optim(
+  gram::SparseMatrixCSC{T, <:Any},
+  guess::Matrix{T}
+) where T <: Number
+  # find the dimension of the search space
+  dims = size(guess)
+  element_dim, construction_dim = dims
+  total_dim = element_dim * construction_dim
+  
+  # list the constrained entries of the gram matrix
+  J, K, _ = findnz(gram)
+  constrained = zip(J, K)
+  
+  # scale the loss function
+  scale_adjustment = length(constrained)
+  
+  function loss(L_vec)
+    L = reshape(L_vec, dims)
+    Δ_proj = proj_diff(gram, L'*Q*L)
+    dot(Δ_proj, Δ_proj) / scale_adjustment
+  end
+  
+  function loss_grad!(storage, L_vec)
+    L = reshape(L_vec, dims)
+    Δ_proj = proj_diff(gram, L'*Q*L)
+    storage .= reshape(-4*Q*L*Δ_proj, total_dim) / scale_adjustment
+  end
+  
+  function loss_hess!(storage, L_vec)
+    L = reshape(L_vec, dims)
+    Δ_proj = proj_diff(gram, L'*Q*L)
+    indices = [(j, k) for k in 1:construction_dim for j in 1:element_dim]
+    for (j, k) in indices
+      basis_mat = basis_matrix(T, j, k, dims)
+      neg_dΔ = basis_mat'*Q*L + L'*Q*basis_mat
+      neg_dΔ_proj = proj_to_entries(neg_dΔ, constrained)
+      deriv_grad = 4*Q*(-basis_mat*Δ_proj + L*neg_dΔ_proj) / scale_adjustment
+      storage[:, (k-1)*element_dim + j] = reshape(deriv_grad, total_dim)
+    end
+  end
+  
+  optimize(
+    loss, loss_grad!, loss_hess!,
+    reshape(guess, total_dim),
+    Newton()
+  )
+end
+
+# seek a matrix `L` for which `L'QL` matches the sparse matrix `gram` at every
+# explicit entry of `gram`. use gradient descent starting from `guess`, with an
+# alternate technique for finding the projected base step from the unprojected
+# Hessian
+function realize_gram_alt_proj(
+  gram::SparseMatrixCSC{T, <:Any},
+  guess::Matrix{T},
+  frozen = CartesianIndex[];
+  scaled_tol = 1e-30,
+  min_efficiency = 0.5,
+  backoff = 0.9,
+  reg_scale = 1.1,
+  max_descent_steps = 200,
+  max_backoff_steps = 110
+) where T <: Number
+  # start history
+  history = DescentHistory{T}()
+  
+  # find the dimension of the search space
+  dims = size(guess)
+  element_dim, construction_dim = dims
+  total_dim = element_dim * construction_dim
+  
+  # list the constrained entries of the gram matrix
+  J, K, _ = findnz(gram)
+  constrained = zip(J, K)
+  
+  # scale the tolerance
+  scale_adjustment = sqrt(T(length(constrained)))
+  tol = scale_adjustment * scaled_tol
+  
+  # convert the frozen indices to stacked format
+  frozen_stacked = [(index[2]-1)*element_dim + index[1] for index in frozen]
+  
+  # initialize search state
+  L = copy(guess)
+  Δ_proj = proj_diff(gram, L'*Q*L)
+  loss = dot(Δ_proj, Δ_proj)
+  
+  # use Newton's method with backtracking and gradient descent backup
+  for step in 1:max_descent_steps
+    # stop if the loss is tolerably low
+    if loss < tol
+      break
+    end
+    
+    # find the negative gradient of the loss function
+    neg_grad = 4*Q*L*Δ_proj
+    
+    # find the negative Hessian of the loss function
+    hess = Matrix{T}(undef, total_dim, total_dim)
+    indices = [(j, k) for k in 1:construction_dim for j in 1:element_dim]
+    for (j, k) in indices
+      basis_mat = basis_matrix(T, j, k, dims)
+      neg_dΔ = basis_mat'*Q*L + L'*Q*basis_mat
+      neg_dΔ_proj = proj_to_entries(neg_dΔ, constrained)
+      deriv_grad = 4*Q*(-basis_mat*Δ_proj + L*neg_dΔ_proj)
+      hess[:, (k-1)*element_dim + j] = reshape(deriv_grad, total_dim)
+    end
+    hess_sym = Hermitian(hess)
+    push!(history.hess, hess_sym)
+    
+    # regularize the Hessian
+    min_eigval = minimum(eigvals(hess_sym))
+    push!(history.positive, min_eigval > 0)
+    if min_eigval <= 0
+      hess -= reg_scale * min_eigval * I
+    end
+    
+    # compute the Newton step
+    neg_grad_stacked = reshape(neg_grad, total_dim)
+    for k in frozen_stacked
+      neg_grad_stacked[k] = 0
+      hess[k, :] .= 0
+      hess[:, k] .= 0
+      hess[k, k] = 1
+    end
+    base_step_stacked = Hermitian(hess) \ neg_grad_stacked
+    base_step = reshape(base_step_stacked, dims)
+    push!(history.base_step, base_step)
+    
+    # store the current position, loss, and slope
+    L_last = L
+    loss_last = loss
+    push!(history.scaled_loss, loss / scale_adjustment)
+    push!(history.neg_grad, neg_grad)
+    push!(history.slope, norm(neg_grad))
+    
+    # find a good step size using backtracking line search
+    push!(history.stepsize, 0)
+    push!(history.backoff_steps, max_backoff_steps)
+    empty!(history.last_line_L)
+    empty!(history.last_line_loss)
+    rate = one(T)
+    step_success = false
+    base_target_improvement = dot(neg_grad, base_step)
+    for backoff_steps in 0:max_backoff_steps
+      history.stepsize[end] = rate
+      L = L_last + rate * base_step
+      Δ_proj = proj_diff(gram, L'*Q*L)
+      loss = dot(Δ_proj, Δ_proj)
+      improvement = loss_last - loss
+      push!(history.last_line_L, L)
+      push!(history.last_line_loss, loss / scale_adjustment)
+      if improvement >= min_efficiency * rate * base_target_improvement
+        history.backoff_steps[end] = backoff_steps
+        step_success = true
+        break
+      end
+      rate *= backoff
+    end
+    
+    # if we've hit a wall, quit
+    if !step_success
+      return L_last, false, history
+    end
+  end
+  
+  # return the factorization and its history
+  push!(history.scaled_loss, loss / scale_adjustment)
+  L, loss < tol, history
+end
+
+# seek a matrix `L` for which `L'QL` matches the sparse matrix `gram` at every
+# explicit entry of `gram`. use gradient descent starting from `guess`
+function realize_gram(
+  gram::SparseMatrixCSC{T, <:Any},
+  guess::Matrix{T},
+  frozen = nothing;
+  scaled_tol = 1e-30,
+  min_efficiency = 0.5,
+  backoff = 0.9,
+  reg_scale = 1.1,
+  max_descent_steps = 200,
+  max_backoff_steps = 110
+) where T <: Number
+  # start history
+  history = DescentHistory{T}()
+  
+  # find the dimension of the search space
+  dims = size(guess)
+  element_dim, construction_dim = dims
+  total_dim = element_dim * construction_dim
+  
+  # list the constrained entries of the gram matrix
+  J, K, _ = findnz(gram)
+  constrained = zip(J, K)
+  
+  # scale the tolerance
+  scale_adjustment = sqrt(T(length(constrained)))
+  tol = scale_adjustment * scaled_tol
+  
+  # list the un-frozen indices
+  has_frozen = !isnothing(frozen)
+  if has_frozen
+    is_unfrozen = fill(true, size(guess))
+    is_unfrozen[frozen] .= false
+    unfrozen = findall(is_unfrozen)
+    unfrozen_stacked = reshape(is_unfrozen, total_dim)
+  end
+  
+  # initialize search state
+  L = copy(guess)
+  Δ_proj = proj_diff(gram, L'*Q*L)
+  loss = dot(Δ_proj, Δ_proj)
+  
+  # use Newton's method with backtracking and gradient descent backup
+  for step in 1:max_descent_steps
+    # stop if the loss is tolerably low
+    if loss < tol
+      break
+    end
+    
+    # find the negative gradient of the loss function
+    neg_grad = 4*Q*L*Δ_proj
+    
+    # find the negative Hessian of the loss function
+    hess = Matrix{T}(undef, total_dim, total_dim)
+    indices = [(j, k) for k in 1:construction_dim for j in 1:element_dim]
+    for (j, k) in indices
+      basis_mat = basis_matrix(T, j, k, dims)
+      neg_dΔ = basis_mat'*Q*L + L'*Q*basis_mat
+      neg_dΔ_proj = proj_to_entries(neg_dΔ, constrained)
+      deriv_grad = 4*Q*(-basis_mat*Δ_proj + L*neg_dΔ_proj)
+      hess[:, (k-1)*element_dim + j] = reshape(deriv_grad, total_dim)
+    end
+    hess = Hermitian(hess)
+    push!(history.hess, hess)
+    
+    # regularize the Hessian
+    min_eigval = minimum(eigvals(hess))
+    push!(history.positive, min_eigval > 0)
+    if min_eigval <= 0
+      hess -= reg_scale * min_eigval * I
+    end
+    
+    # compute the Newton step
+    neg_grad_stacked = reshape(neg_grad, total_dim)
+    if has_frozen
+      hess = hess[unfrozen_stacked, unfrozen_stacked]
+      neg_grad_compressed = neg_grad_stacked[unfrozen_stacked]
+    else
+      neg_grad_compressed = neg_grad_stacked
+    end
+    base_step_compressed = hess \ neg_grad_compressed
+    if has_frozen
+      base_step_stacked = zeros(total_dim)
+      base_step_stacked[unfrozen_stacked] .= base_step_compressed
+    else
+      base_step_stacked = base_step_compressed
+    end
+    base_step = reshape(base_step_stacked, dims)
+    push!(history.base_step, base_step)
+    
+    # store the current position, loss, and slope
+    L_last = L
+    loss_last = loss
+    push!(history.scaled_loss, loss / scale_adjustment)
+    push!(history.neg_grad, neg_grad)
+    push!(history.slope, norm(neg_grad))
+    
+    # find a good step size using backtracking line search
+    push!(history.stepsize, 0)
+    push!(history.backoff_steps, max_backoff_steps)
+    empty!(history.last_line_L)
+    empty!(history.last_line_loss)
+    rate = one(T)
+    step_success = false
+    base_target_improvement = dot(neg_grad, base_step)
+    for backoff_steps in 0:max_backoff_steps
+      history.stepsize[end] = rate
+      L = L_last + rate * base_step
+      Δ_proj = proj_diff(gram, L'*Q*L)
+      loss = dot(Δ_proj, Δ_proj)
+      improvement = loss_last - loss
+      push!(history.last_line_L, L)
+      push!(history.last_line_loss, loss / scale_adjustment)
+      if improvement >= min_efficiency * rate * base_target_improvement
+        history.backoff_steps[end] = backoff_steps
+        step_success = true
+        break
+      end
+      rate *= backoff
+    end
+    
+    # if we've hit a wall, quit
+    if !step_success
+      return L_last, false, history
+    end
+  end
+  
+  # return the factorization and its history
+  push!(history.scaled_loss, loss / scale_adjustment)
+  L, loss < tol, history
+end
+
+end

engine-proto/gram-test/basin-shapes.jl

@@ -0,0 +1,99 @@
+include("Engine.jl")
+
+using LinearAlgebra
+using SparseArrays
+
+function sphere_in_tetrahedron_shape()
+  # initialize the partial gram matrix for a sphere inscribed in a regular
+  # tetrahedron
+  J = Int64[]
+  K = Int64[]
+  values = BigFloat[]
+  for j in 1:5
+    for k in 1:5
+      push!(J, j)
+      push!(K, k)
+      if j == k
+        push!(values, 1)
+      elseif (j <= 4 && k <= 4)
+        push!(values, -1/BigFloat(3))
+      else
+        push!(values, -1)
+      end
+    end
+  end
+  gram = sparse(J, K, values)
+  
+  # plot loss along a slice
+  loss_lin = []
+  loss_sq = []
+  mesh = range(0.9, 1.1, 101)
+  for t in mesh
+    L = hcat(
+      Engine.plane(normalize(BigFloat[ 1,  1,  1]), BigFloat(1)),
+      Engine.plane(normalize(BigFloat[ 1, -1, -1]), BigFloat(1)),
+      Engine.plane(normalize(BigFloat[-1,  1, -1]), BigFloat(1)),
+      Engine.plane(normalize(BigFloat[-1, -1,  1]), BigFloat(1)),
+      Engine.sphere(BigFloat[0, 0, 0], BigFloat(t))
+    )
+    Δ_proj = Engine.proj_diff(gram, L'*Engine.Q*L)
+    push!(loss_lin, norm(Δ_proj))
+    push!(loss_sq, dot(Δ_proj, Δ_proj))
+  end
+  mesh, loss_lin, loss_sq
+end
+
+function circles_in_triangle_shape()
+  # initialize the partial gram matrix for a sphere inscribed in a regular
+  # tetrahedron
+  J = Int64[]
+  K = Int64[]
+  values = BigFloat[]
+  for j in 1:8
+    for k in 1:8
+      filled = false
+      if j == k
+        push!(values, 1)
+        filled = true
+      elseif (j == 1 || k == 1)
+        push!(values, 0)
+        filled = true
+      elseif (j == 2 || k == 2)
+        push!(values, -1)
+        filled = true
+      end
+      #=elseif (j <= 5 && j != 2 && k == 9 || k == 9 && k <= 5 && k != 2)
+        push!(values, 0)
+        filled = true
+      end=#
+      if filled
+        push!(J, j)
+        push!(K, k)
+      end
+    end
+  end
+  append!(J, [6, 4, 6, 5, 7, 5, 7, 3, 8, 3, 8, 4])
+  append!(K, [4, 6, 5, 6, 5, 7, 3, 7, 3, 8, 4, 8])
+  append!(values, fill(-1, 12))
+  
+  # plot loss along a slice
+  loss_lin = []
+  loss_sq = []
+  mesh = range(0.99, 1.01, 101)
+  for t in mesh
+    L = hcat(
+      Engine.plane(BigFloat[0, 0, 1], BigFloat(0)),
+      Engine.sphere(BigFloat[0, 0, 0], BigFloat(t)),
+      Engine.plane(BigFloat[1, 0, 0], BigFloat(1)),
+      Engine.plane(BigFloat[cos(2pi/3), sin(2pi/3), 0], BigFloat(1)),
+      Engine.plane(BigFloat[cos(-2pi/3), sin(-2pi/3), 0], BigFloat(1)),
+      Engine.sphere(4//3*BigFloat[-1, 0, 0], BigFloat(1//3)),
+      Engine.sphere(4//3*BigFloat[cos(-pi/3), sin(-pi/3), 0], BigFloat(1//3)),
+      Engine.sphere(4//3*BigFloat[cos(pi/3), sin(pi/3), 0], BigFloat(1//3))
+    )
+    Δ_proj = Engine.proj_diff(gram, L'*Engine.Q*L)
+    push!(loss_lin, norm(Δ_proj))
+    push!(loss_sq, dot(Δ_proj, Δ_proj))
+  end
+  mesh, loss_lin, loss_sq
+end

engine-proto/gram-test/circles-in-triangle.jl

@@ -0,0 +1,76 @@
+include("Engine.jl")
+
+using SparseArrays
+using Random
+
+# initialize the partial gram matrix for a sphere inscribed in a regular
+# tetrahedron
+J = Int64[]
+K = Int64[]
+values = BigFloat[]
+for j in 1:9
+  for k in 1:9
+    filled = false
+    if j == 9
+      if k <= 5 && k != 2
+        push!(values, 0)
+        filled = true
+      end
+    elseif k == 9
+      if j <= 5 && j != 2
+        push!(values, 0)
+        filled = true
+      end
+    elseif j == k
+      push!(values, 1)
+      filled = true
+    elseif j == 1 || k == 1
+      push!(values, 0)
+      filled = true
+    elseif j == 2 || k == 2
+      push!(values, -1)
+      filled = true
+    end
+    if filled
+      push!(J, j)
+      push!(K, k)
+    end
+  end
+end
+append!(J, [6, 4, 6, 5, 7, 5, 7, 3, 8, 3, 8, 4])
+append!(K, [4, 6, 5, 6, 5, 7, 3, 7, 3, 8, 4, 8])
+append!(values, fill(-1, 12))
+#= make construction rigid
+append!(J, [3, 4, 4, 5])
+append!(K, [4, 3, 5, 4])
+append!(values, fill(-0.5, 4))
+=#
+gram = sparse(J, K, values)
+
+# set initial guess
+Random.seed!(58271)
+guess = hcat(
+  Engine.plane(BigFloat[0, 0, 1], BigFloat(0)),
+  Engine.sphere(BigFloat[0, 0, 0], BigFloat(1//2)) + 0.1*Engine.rand_on_shell([BigFloat(-1)]),
+  Engine.plane(-BigFloat[1, 0, 0], BigFloat(-1)) + 0.1*Engine.rand_on_shell([BigFloat(-1)]),
+  Engine.plane(-BigFloat[cos(2pi/3), sin(2pi/3), 0], BigFloat(-1)) + 0.1*Engine.rand_on_shell([BigFloat(-1)]),
+  Engine.plane(-BigFloat[cos(-2pi/3), sin(-2pi/3), 0], BigFloat(-1)) + 0.1*Engine.rand_on_shell([BigFloat(-1)]),
+  Engine.sphere(BigFloat[-1, 0, 0], BigFloat(1//5)) + 0.1*Engine.rand_on_shell([BigFloat(-1)]),
+  Engine.sphere(BigFloat[cos(-pi/3), sin(-pi/3), 0], BigFloat(1//5)) + 0.1*Engine.rand_on_shell([BigFloat(-1)]),
+  Engine.sphere(BigFloat[cos(pi/3), sin(pi/3), 0], BigFloat(1//5)) + 0.1*Engine.rand_on_shell([BigFloat(-1)]),
+  BigFloat[0, 0, 0, 0, 1]
+)
+frozen = [CartesianIndex(j, 9) for j in 1:5]
+
+# complete the gram matrix using Newton's method with backtracking
+L, success, history = Engine.realize_gram(gram, guess, frozen)
+completed_gram = L'*Engine.Q*L
+println("Completed Gram matrix:\n")
+display(completed_gram)
+if success
+  println("\nTarget accuracy achieved!")
+else
+  println("\nFailed to reach target accuracy")
+end
+println("Steps: ", size(history.scaled_loss, 1))
+println("Loss: ", history.scaled_loss[end], "\n")

engine-proto/gram-test/gram-test.jl

@@ -0,0 +1,85 @@
+using LinearAlgebra
+using AbstractAlgebra
+
+function printgood(msg)
+  printstyled("✓", color = :green)
+  println(" ", msg)
+end
+
+function printbad(msg)
+  printstyled("✗", color = :red)
+  println(" ", msg)
+end
+
+F, gens = rational_function_field(AbstractAlgebra.Rationals{BigInt}(), ["a₁", "a₂", "b₁", "b₂", "c₁", "c₂"])
+a = gens[1:2]
+b = gens[3:4]
+c = gens[5:6]
+
+# three mutually tangent spheres which are all perpendicular to the x, y plane
+gram = [
+  -1  1  1;
+   1 -1  1;
+   1  1 -1
+]
+
+eig = eigen(gram)
+n_pos = count(eig.values .> 0.5)
+n_neg = count(eig.values .< -0.5)
+if n_pos + n_neg == size(gram, 1)
+  printgood("Non-degenerate subspace")
+else
+  printbad("Degenerate subspace")
+end
+sig_rem = Int64[ones(1-n_pos); -ones(4-n_neg)]
+unk = hcat(a, b, c)
+M = matrix_space(F, 5, 5)
+big_gram = M(F.([
+  diagm(sig_rem) unk;
+  transpose(unk) gram
+]))
+
+r, p, L, U = lu(big_gram)
+if isone(p)
+  printgood("Found a solution")
+else
+  printbad("Didn't find a solution")
+end
+solution = transpose(L)
+mform = U * inv(solution)
+
+vals = [0, 0, 0, 1, 0, -3//4]
+solution_ex = [evaluate(entry, vals) for entry in solution]
+mform_ex = [evaluate(entry, vals) for entry in mform]
+
+std_basis = [
+  0 0 0 1  1;
+  0 0 0 1 -1;
+  1 0 0 0  0;
+  0 1 0 0  0;
+  0 0 1 0  0
+]
+std_solution = M(F.(std_basis)) * solution
+std_solution_ex = std_basis * solution_ex
+
+println("Minkowski form:")
+display(mform_ex)
+
+big_gram_recovered = transpose(solution_ex) * mform_ex * solution_ex
+valid = all(iszero.(
+  [evaluate(entry, vals) for entry in big_gram] - big_gram_recovered
+))
+if valid
+  printgood("Recovered Gram matrix:")
+else
+  printbad("Didn't recover Gram matrix. Instead, got:")
+end
+display(big_gram_recovered)
+
+# this should be a solution
+hand_solution = [0 0 1 0 0; 0 0 -1 2 2; 0 0 0 1 -1; 1 0 0 0 0; 0 1 0 0 0]
+unmix = Rational{Int64}[[1//2 1//2; 1//2 -1//2] zeros(Int64, 2, 3); zeros(Int64, 3, 2) Matrix{Int64}(I, 3, 3)]
+hand_solution_diag = unmix * hand_solution
+big_gram_hand_recovered = transpose(hand_solution_diag) * diagm([1; -ones(Int64, 4)]) * hand_solution_diag
+println("Gram matrix from hand-written solution:")
+display(big_gram_hand_recovered)

engine-proto/gram-test/gram-test.sage

@@ -0,0 +1,27 @@
+F = QQ['a', 'b', 'c'].fraction_field()
+a, b, c = F.gens()
+
+# three mutually tangent spheres which are all perpendicular to the x, y plane
+gram = matrix([
+  [-1, 0,  0,  0,  0],
+  [0, -1,  a,  b,  c],
+  [0,  a, -1,  1,  1],
+  [0,  b,  1, -1,  1],
+  [0,  c,  1,  1, -1]
+])
+
+P, L, U = gram.LU()
+solution = (P * L).transpose()
+mform = U * L.transpose().inverse()
+
+concrete = solution.subs({a: 0, b: 1, c: -3/4})
+
+std_basis = matrix([
+  [0, 0, 0, 1,  1],
+  [0, 0, 0, 1, -1],
+  [1, 0, 0, 0,  0],
+  [0, 1, 0, 0,  0],
+  [0, 0, 1, 0,  0]
+])
+std_solution = std_basis * solution
+std_concrete = std_basis * concrete

engine-proto/gram-test/irisawa-hexlet.jl

@@ -0,0 +1,86 @@
+include("Engine.jl")
+
+using SparseArrays
+
+# this problem is from a sangaku by Irisawa Shintarō Hiroatsu. the article below
+# includes a nice translation of the problem statement, which was recorded in
+# Uchida Itsumi's book _Kokon sankan_ (_Mathematics, Past and Present_)
+#
+#   "Japan's 'Wasan' Mathematical Tradition", by Abe Haruki
+#   https://www.nippon.com/en/japan-topics/c12801/
+#
+
+# initialize the partial gram matrix
+J = Int64[]
+K = Int64[]
+values = BigFloat[]
+for s in 1:9
+  # each sphere is represented by a spacelike vector
+  push!(J, s)
+  push!(K, s)
+  push!(values, 1)
+  
+  # the circumscribing sphere is internally tangent to all of the other spheres
+  if s > 1
+    append!(J, [1, s])
+    append!(K, [s, 1])
+    append!(values, [1, 1])
+  end
+  
+  if s > 3
+    # each chain sphere is externally tangent to the "sun" and "moon" spheres
+    for n in 2:3
+      append!(J, [s, n])
+      append!(K, [n, s])
+      append!(values, [-1, -1])
+    end
+    
+    # each chain sphere is externally tangent to the next chain sphere
+    s_next = 4 + mod(s-3, 6)
+    append!(J, [s, s_next])
+    append!(K, [s_next, s])
+    append!(values, [-1, -1])
+  end
+end
+gram = sparse(J, K, values)
+
+# make an initial guess
+guess = hcat(
+  Engine.sphere(BigFloat[0, 0, 0], BigFloat(15)),
+  Engine.sphere(BigFloat[0, 0, -9], BigFloat(5)),
+  Engine.sphere(BigFloat[0, 0, 11], BigFloat(3)),
+  (
+    Engine.sphere(9*BigFloat[cos(k*π/3), sin(k*π/3), 0], BigFloat(2.5))
+    for k in 1:6
+  )...
+)
+frozen = [CartesianIndex(4, k) for k in 1:4]
+
+# complete the gram matrix using Newton's method with backtracking
+L, success, history = Engine.realize_gram(gram, guess, frozen)
+completed_gram = L'*Engine.Q*L
+println("Completed Gram matrix:\n")
+display(completed_gram)
+if success
+  println("\nTarget accuracy achieved!")
+else
+  println("\nFailed to reach target accuracy")
+end
+println("Steps: ", size(history.scaled_loss, 1))
+println("Loss: ", history.scaled_loss[end], "\n")
+if success
+  println("Chain diameters:")
+  println("  ", 1 / L[4,4], " sun (given)")
+  for k in 5:9
+    println("  ", 1 / L[4,k], " sun")
+  end
+end
+
+# test an alternate technique for finding the projected base step from the
+# unprojected Hessian
+L_alt, success_alt, history_alt = Engine.realize_gram_alt_proj(gram, guess, frozen)
+completed_gram_alt = L_alt'*Engine.Q*L_alt
+println("\nDifference in result using alternate projection:\n")
+display(completed_gram_alt - completed_gram)
+println("\nDifference in steps: ", size(history_alt.scaled_loss, 1) - size(history.scaled_loss, 1))
+println("Difference in loss: ", history_alt.scaled_loss[end] - history.scaled_loss[end], "\n")

engine-proto/gram-test/low-rank-test.jl

@@ -0,0 +1,49 @@
+using LowRankModels
+using LinearAlgebra
+using SparseArrays
+
+# testing Gram matrix recovery using the LowRankModels package
+
+# initialize the partial gram matrix for an arrangement of seven spheres in
+# which spheres 1 through 5 are mutually tangent, and spheres 3 through 7 are
+# also mutually tangent
+I = Int64[]
+J = Int64[]
+values = Float64[]
+for i in 1:7
+  for j in 1:7
+    if (i <= 5 && j <= 5) || (i >= 3 && j >= 3)
+      push!(I, i)
+      push!(J, j)
+      push!(values, i == j ? 1 : -1)
+    end
+  end
+end
+gram = sparse(I, J, values)
+
+# in this initial guess, the mutual tangency condition is satisfied for spheres
+# 1 through 5
+X₀ = sqrt(0.5) * [
+  1 0  1  1  1;
+  1 0  1 -1 -1;
+  1 0 -1  1 -1;
+  1 0 -1 -1  1;
+  2 -sqrt(6) 0 0 0;
+  0.2  0.3 -0.1 -0.2  0.1;
+  0.1 -0.2  0.3  0.4 -0.1
+]'
+Y₀ = diagm([-1, 1, 1, 1, 1]) * X₀
+
+# search parameters
+search_params = ProxGradParams(
+  1.0;
+  max_iter = 100,
+  inner_iter = 1,
+  abs_tol = 1e-16,
+  rel_tol = 1e-9,
+  min_stepsize = 0.01
+)
+
+# complete gram matrix
+model = GLRM(gram, QuadLoss(), ZeroReg(), ZeroReg(), 5, X = X₀, Y = Y₀)
+X, Y, history = fit!(model, search_params)

engine-proto/gram-test/overlap-test.jl

@@ -0,0 +1,37 @@
+using LinearAlgebra
+using AbstractAlgebra
+
+function printgood(msg)
+  printstyled("✓", color = :green)
+  println(" ", msg)
+end
+
+function printbad(msg)
+  printstyled("✗", color = :red)
+  println(" ", msg)
+end
+
+F, gens = rational_function_field(AbstractAlgebra.Rationals{BigInt}(), ["x", "t₁", "t₂", "t₃"])
+x = gens[1]
+t = gens[2:4]
+
+# three mutually tangent spheres which are all perpendicular to the x, y plane
+M = matrix_space(F, 7, 7)
+gram = M(F[
+   1    -1    -1 -1 -1  t[1] t[2];
+  -1     1    -1 -1 -1  x    t[3]
+  -1    -1     1 -1 -1 -1   -1;
+  -1    -1    -1  1 -1 -1   -1;
+  -1    -1    -1 -1  1 -1   -1;
+   t[1]  x    -1 -1 -1  1   -1;
+   t[2]  t[3] -1 -1 -1 -1    1
+])
+
+r, p, L, U = lu(gram)
+if isone(p)
+  printgood("Found a solution")
+else
+  printbad("Didn't find a solution")
+end
+solution = transpose(L)
+mform = U * inv(solution)

engine-proto/gram-test/overlapping-pyramids.jl

@@ -0,0 +1,90 @@
+include("Engine.jl")
+
+using SparseArrays
+using AbstractAlgebra
+using PolynomialRoots
+using Random
+
+# initialize the partial gram matrix for an arrangement of seven spheres in
+# which spheres 1 through 5 are mutually tangent, and spheres 3 through 7 are
+# also mutually tangent
+J = Int64[]
+K = Int64[]
+values = BigFloat[]
+for j in 1:7
+  for k in 1:7
+    if (j <= 5 && k <= 5) || (j >= 3 && k >= 3)
+      push!(J, j)
+      push!(K, k)
+      push!(values, j == k ? 1 : -1)
+    end
+  end
+end
+gram = sparse(J, K, values)
+
+# set the independent variable
+indep_val = -9//5
+gram[6, 1] = BigFloat(indep_val)
+gram[1, 6] = gram[6, 1]
+
+# in this initial guess, the mutual tangency condition is satisfied for spheres
+# 1 through 5
+Random.seed!(50793)
+guess = let
+  a = sqrt(BigFloat(3)/2)
+  hcat(
+    sqrt(1/BigFloat(2)) * BigFloat[
+      1    1   -1   -1    0
+      1   -1    1   -1    0
+      1   -1   -1    1    0
+      0.5  0.5  0.5  0.5  1+a
+      0.5  0.5  0.5  0.5  1-a
+    ] + 0.2*Engine.rand_on_shell(fill(BigFloat(-1), 5)),
+    Engine.rand_on_shell(fill(BigFloat(-1), 2))
+  )
+end
+
+# complete the gram matrix using Newton's method with backtracking
+L, success, history = Engine.realize_gram(gram, guess)
+completed_gram = L'*Engine.Q*L
+println("Completed Gram matrix:\n")
+display(completed_gram)
+if success
+  println("\nTarget accuracy achieved!")
+else
+  println("\nFailed to reach target accuracy")
+end
+println("Steps: ", size(history.scaled_loss, 1))
+println("Loss: ", history.scaled_loss[end], "\n")
+
+# === algebraic check ===
+
+#=
+R, gens = polynomial_ring(AbstractAlgebra.Rationals{BigInt}(), ["x", "t₁", "t₂", "t₃"])
+x = gens[1]
+t = gens[2:4]
+
+S, u = polynomial_ring(AbstractAlgebra.Rationals{BigInt}(), "u")
+
+M = matrix_space(R, 7, 7)
+gram_symb = M(R[
+   1    -1    -1 -1 -1  t[1] t[2];
+  -1     1    -1 -1 -1  x    t[3]
+  -1    -1     1 -1 -1 -1   -1;
+  -1    -1    -1  1 -1 -1   -1;
+  -1    -1    -1 -1  1 -1   -1;
+   t[1]  x    -1 -1 -1  1   -1;
+   t[2]  t[3] -1 -1 -1 -1    1
+])
+rank_constraints = det.([
+  gram_symb[1:6, 1:6],
+  gram_symb[2:7, 2:7],
+  gram_symb[[1, 3, 4, 5, 6, 7], [1, 3, 4, 5, 6, 7]]
+])
+
+# solve for x and t
+x_constraint = 25//16 * to_univariate(S, evaluate(rank_constraints[1], [2], [indep_val]))
+t₂_constraint = 25//16 * to_univariate(S, evaluate(rank_constraints[3], [2], [indep_val]))
+x_vals = PolynomialRoots.roots(x_constraint.coeffs)
+t₂_vals = PolynomialRoots.roots(t₂_constraint.coeffs)
+=#

engine-proto/gram-test/sphere-in-tetrahedron.jl

@@ -0,0 +1,76 @@
+include("Engine.jl")
+
+using SparseArrays
+using Random
+
+# initialize the partial gram matrix for a sphere inscribed in a regular
+# tetrahedron
+J = Int64[]
+K = Int64[]
+values = BigFloat[]
+for j in 1:6
+  for k in 1:6
+    filled = false
+    if j == 6
+      if k <= 4
+        push!(values, 0)
+        filled = true
+      end
+    elseif k == 6
+      if j <= 4
+        push!(values, 0)
+        filled = true
+      end
+    elseif j == k
+      push!(values, 1)
+      filled = true
+    elseif j <= 4 && k <= 4
+      push!(values, -1/BigFloat(3))
+      filled = true
+    else
+      push!(values, -1)
+      filled = true
+    end
+    if filled
+      push!(J, j)
+      push!(K, k)
+    end
+  end
+end
+gram = sparse(J, K, values)
+
+# set initial guess
+Random.seed!(99230)
+guess = hcat(
+  sqrt(1/BigFloat(3)) * BigFloat[
+    1  1 -1 -1  0
+    1 -1  1 -1  0
+    1 -1 -1  1  0
+    0  0  0  0  1.5
+    1  1  1  1 -0.5
+  ] + 0.2*Engine.rand_on_shell(fill(BigFloat(-1), 5)),
+  BigFloat[0, 0, 0, 0, 1]
+)
+frozen = [CartesianIndex(j, 6) for j in 1:5]
+
+# complete the gram matrix using Newton's method with backtracking
+L, success, history = Engine.realize_gram(gram, guess, frozen)
+completed_gram = L'*Engine.Q*L
+println("Completed Gram matrix:\n")
+display(completed_gram)
+if success
+  println("\nTarget accuracy achieved!")
+else
+  println("\nFailed to reach target accuracy")
+end
+println("Steps: ", size(history.scaled_loss, 1))
+println("Loss: ", history.scaled_loss[end], "\n")
+
+# test an alternate technique for finding the projected base step from the
+# unprojected Hessian
+L_alt, success_alt, history_alt = Engine.realize_gram_alt_proj(gram, guess, frozen)
+completed_gram_alt = L_alt'*Engine.Q*L_alt
+println("\nDifference in result using alternate projection:\n")
+display(completed_gram_alt - completed_gram)
+println("\nDifference in steps: ", size(history_alt.scaled_loss, 1) - size(history.scaled_loss, 1))
+println("Difference in loss: ", history_alt.scaled_loss[end] - history.scaled_loss[end], "\n")

engine-proto/gram-test/tetrahedron-radius-ratio.jl

@@ -0,0 +1,105 @@
+include("Engine.jl")
+
+using LinearAlgebra
+using SparseArrays
+using Random
+
+# initialize the partial gram matrix for a sphere inscribed in a regular
+# tetrahedron
+J = Int64[]
+K = Int64[]
+values = BigFloat[]
+for j in 1:11
+  for k in 1:11
+    filled = false
+    if j == 11
+      if k <= 4
+        push!(values, 0)
+        filled = true
+      end
+    elseif k == 11
+      if j <= 4
+        push!(values, 0)
+        filled = true
+      end
+    elseif j == k
+      push!(values, j <= 6 ? 1 : 0)
+      filled = true
+    elseif j <= 4
+      if k <= 4
+        push!(values, -1/BigFloat(3))
+        filled = true
+      elseif k == 5
+        push!(values, -1)
+        filled = true
+      elseif 7 <= k <= 10 && k - j != 6
+        push!(values, 0)
+        filled = true
+      end
+    elseif k <= 4
+      if j == 5
+        push!(values, -1)
+        filled = true
+      elseif 7 <= j <= 10 && j - k != 6
+        push!(values, 0)
+        filled = true
+      end
+    elseif j == 6 && 7 <= k <= 10 || k == 6 && 7 <= j <= 10
+      push!(values, 0)
+      filled = true
+    end
+    if filled
+      push!(J, j)
+      push!(K, k)
+    end
+  end
+end
+gram = sparse(J, K, values)
+
+# set initial guess
+Random.seed!(99230)
+guess = hcat(
+  sqrt(1/BigFloat(3)) * BigFloat[
+    1  1 -1 -1  0    0
+    1 -1  1 -1  0    0
+    1 -1 -1  1  0    0
+    0  0  0  0  1.5  0.5
+    1  1  1  1 -0.5 -1.5
+  ] + 0.0*Engine.rand_on_shell(fill(BigFloat(-1), 6)),
+  Engine.point([-0.5, -0.5, -0.5] + 0.3*randn(3)),
+  Engine.point([-0.5,  0.5,  0.5] + 0.3*randn(3)),
+  Engine.point([ 0.5, -0.5,  0.5] + 0.3*randn(3)),
+  Engine.point([ 0.5,  0.5, -0.5] + 0.3*randn(3)),
+  BigFloat[0, 0, 0, 0, 1]
+)
+frozen = vcat(
+  [CartesianIndex(4, k) for k in 7:10],
+  [CartesianIndex(j, 11) for j in 1:5]
+)
+
+# complete the gram matrix using Newton's method with backtracking
+L, success, history = Engine.realize_gram(gram, guess, frozen)
+completed_gram = L'*Engine.Q*L
+println("Completed Gram matrix:\n")
+display(completed_gram)
+if success
+  println("\nTarget accuracy achieved!")
+else
+  println("\nFailed to reach target accuracy")
+end
+println("Steps: ", size(history.scaled_loss, 1))
+println("Loss: ", history.scaled_loss[end])
+if success
+  infty = BigFloat[0, 0, 0, 0, 1]
+  radius_ratio = dot(infty, Engine.Q * L[:,5]) / dot(infty, Engine.Q * L[:,6])
+  println("\nCircumradius / inradius: ", radius_ratio)
+end
+
+# test an alternate technique for finding the projected base step from the
+# unprojected Hessian
+L_alt, success_alt, history_alt = Engine.realize_gram_alt_proj(gram, guess, frozen)
+completed_gram_alt = L_alt'*Engine.Q*L_alt
+println("\nDifference in result using alternate projection:\n")
+display(completed_gram_alt - completed_gram)
+println("\nDifference in steps: ", size(history_alt.scaled_loss, 1) - size(history.scaled_loss, 1))
+println("Difference in loss: ", history_alt.scaled_loss[end] - history.scaled_loss[end], "\n")

notes/inversive.md

@@ -2,28 +2,29 @@
 
 (proposed by Alex Kontorovich as a practical system for doing 3D geometric calculations)
 
-These coordinates are of form $I=(c, r, x, y, z)$ where we think of $c$ as the co-radius, $r$ as the radius, and $x, y, z$ as the "Euclidean" part, which we abbreviate $E_I$.  There is an underlying basic quadratic form $Q(I_1,I_2) = (c_1r_2+c_2r_1)/2 - x_1x_2 -y_1y_2-z_1z_2$ which aids in calculation/verification of coordinates in this representation. We have:
+These coordinates are of form $I=(c, b, x, y, z)$ where we think of $c$ as the co-radius, $b$ as the "bend" (reciprocal radius), and $x, y, z$ as the "Euclidean" part, which we abbreviate $E_I$.  There is an underlying basic quadratic form $Q(I_1,I_2) = (c_1b_2+c_2b_1)/2 - x_1x_2 -y_1y_2-z_1z_2$ which aids in calculation/verification of coordinates in this representation. We have:
 
-| Entity or Relationship                                                         | Representation                                                                                                                                                                                                                                                                                                                                                                                                                       | Comments/questions                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
-| ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Sphere s with radius r>0 centered on P = (x,y,z)                               | $I_s = (1/c, 1/r, x/r, y/r, z/r)$ satisfying $Q(I_s,I_s) = -1$, i.e., $c = r/(\|P\|^2 - r^2)$.                                                                                                                                                                                                                                                                                                                                       | Can also write $I_s = (\|P\|^2/r - r, 1/r, x/r. y/r, z/r)$ -- so there is no trouble if $\|E_{I_s}\| = r$, just get first coordinate to be 0.                                                                                                                                                                                                                                                                                                                                                                                                                                            |
-| Plane p with unit normal (x,y,z), a distance s from origin                     | $I_p = (2s, 0, x, y, z)$                                                                                                                                                                                                                                                                                                                                                                                                             | Note $Q(I_p, I_p)$ is still -1. Also, there are two representations for each plane through the origin, namely $(0,0,x,y,z)$ and $(0,0,-x,-y,-z)$                                                                                                                                                                                                                                                                                                                                                                                                                                         |
-| Point P with Euclidean coordinates (x,y,z)                                     | $I_P = (\|P\|^2, 1, x, y, z)$                                                                                                                                                                                                                                                                                                                                                                                                        | Note $Q(I_P,I_P) = 0$.  Because of this we might choose  some other scaling of the inversive coordinates, say $(\||P\||,1/\||P\||,x/\||P\||,y/\||P\||,z/\||P\||)$ instead, but that fails at the origin, and likely won't have some of the other nice properties listed below.  Note that scaling just the co-radius by $s$ and the radius by $1/s$ (which still preserves $Q=0$) dilates by a factor of $s$ about the origin, so that $(\|P\|, \|P\|, x, y, z)$, which might look symmetric, would actually have to represent the Euclidean point $(x/\||P\||, y/\||P\||, z/\||P\||)$ . |
-| ∞, the "point at infinity"                                                     | $I_\infty = (1,0,0,0,0)$                                                                                                                                                                                                                                                                                                                                                                                                             | The only solution to $Q(I,I) = 0$ not covered by the above case.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
-| P lies on sphere or plane given by I                                           | $Q(I_P, I) = 0$                                                                                                                                                                                                                                                                                                                                                                                                                      |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
-| Sphere/planes represented by I and J are tangent                               | $Q(I,J) = 1$ (??, see note at right)                                                                                                                                                                                                                                                                                                                                                                                                 | Seems as though this must be $Q(I,J) = \pm1$  ? For example, the $xy$ plane represented by (0,0,0,0,1)  is tangent to the unit circle centered at (0,0,1) rep'd by (0,1,0,0,1), but their Q-product is -1. And in general you can reflect any sphere tangent to any plane through the plane and it should flip the sign of $Q(I,J)$, if I am not mistaken.                                                                                                                                                                                                                               |
-| Sphere/planes represented by I and J intersect (respectively, don't intersect) | $\|Q(I,J)\| < (\text{resp. }>)\; 1$                                                                                                                                                                                                                                                                                                                                                                                                  | Follows from the angle formula, at least conceptually.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
-| P is center of sphere represented by I                                         | Well, $Q(I_P, I)$ comes out to be $(\|P\|^2/r - r + \|P\|^2/r)/2 - \|P\|^2/r$ or just $-r/2$ .                                                                                                                                                                                                                                                                                                                                       | Is it if and only if ?   No this probably doesn't work because center is not conformal quantity.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
-| Distance between P and R is d                                                  | $Q(I_P, I_R) = d^2/2$                                                                                                                                                                                                                                                                                                                                                                                                                |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
-| Distance between P and sphere/plane rep by I                                   |                                                                                                                                                                                                                                                                                                                                                                                                                                      | In the very simple case of a plane $I$ rep'd by $(2s, 0, x, y, z)$ and a point $P$ that lies on its perpendicular through the origin, rep'd by $(r^2, 1, rx, ry, rz)$ we get $Q(I, I_p) = s-r$, which is indeed the signed distance between $I$ and $P$. Not sure if this generalizes to other combinations?                                                                                                                                                                                                                                                                             |
-| Distance between sphere/planes rep by I and J                                  | Note that for any two Euclidean-concentric spheres rep by $I$ and $J$ with radius $r$ and $s,$ $Q(I,J) = -\frac12\left(\frac rs  + \frac sr\right)$ depends only on the ratio of $r$ and $s$. So this can't give something that determines the Euclidean distance between the two spheres, which presumably grows as the two spheres are blown up proportionally. For another example, for any two parallel planes, $Q(I,J) = \pm1$. | Alex had said: Q(I,J)=cosh^2 (d/2) maybe where d is distance in usual hyperbolic metric. Or maybe cosh d. That may be right depending on what's meant by the hyperbolic metric there, but it seems like it won't determine a reasonable Euclidean distance between planes, which should differ between different pairs of parallel planes.                                                                                                                                                                                                                                               |
-| Sphere centered on P through R                                                 |                                                                                                                                                                                                                                                                                                                                                                                                                                      | Probably just calculate distance etc.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
-| Plane rep'd by I goes through center of sphere rep'd by J                      | I think this is equivalent to the plane being perpendicular to the sphere, i.e.$Q(I,J) = 0$.                                                                                                                                                                                                                                                                                                                                         |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
-| Dihedral angle between planes (or spheres?) rep by I and J                     | $\theta = \arccos(Q(I,J))$                                                                                                                                                                                                                                                                                                                                                                                                           | Aaron Fenyes points out: The angle between spheres in $S^3$ matches the angle between the planes they bound in $R^{(1,4)}$, which matches the angle between the spacelike vectors perpendicular to those planes. So we should have $Q(I,J) = \cos\theta$. Note that when the spheres do not intersect, we can interpret this as the "imaginary angle" between them, via $\cosh t = \cos it$.                                                                                                                                                                                             |
-| R, P, S are collinear                                                          | Maybe just cross product of two differences is 0. Or, $R,P,S,\infty$ lie on a circle, or equivalently, $I_R,I_P,I_S,I_\infty$ span a plane (rather than a three-space).                                                                                                                                                                                                                                                              | Not a conformal property, but $R,P,S,\infty$ lying on a circle _is_.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
-| Plane through noncollinear R, P, S                                             | Should be, just solve Q(I, I_R) = 0 etc.                                                                                                                                                                                                                                                                                                                                                                                             |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
-| circle                                                                         | Maybe concentric sphere and the containing plane? Note it is easy to constrain the relationship between those two: they must be perpendicular.                                                                                                                                                                                                                                                                                       | Defn: circle is intersection of two spheres. That does cover lines. But you lose the canonicalness                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
-| line                                                                           | Maybe two perpendicular containing planes? Maybe the plane perpendicular to the line and through origin, together with the point of the line on that plane? Or maybe just as a bag of collinear points?                                                                                                                                                                                                                              | The first is the limiting case of the possible circle rep, but it is not canonical. The second appears to be canonical, but I don't see a circle rep that corresponds to it.                                                                                                                                                                                                                                                                                                                                                                                                             |
+| Entity or Relationship                                                             | Representation                                                                                                                                                                                                                                                                                                                                                                                                                       | Comments/questions                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Sphere $s$ with radius $r>0$ centered on $P = (x,y,z)$                             | $I_s = (\frac1{c}, \frac1{r}, \frac{x}{r}, \frac{y}{r}, \frac{z}{r})$ satisfying $Q(I_s,I_s) = -1,$ i.e., $c = r/(\|P\|^2 - r^2)$.                                                                                                                                                                                                                                                                                                   | Note that $1/c = \|P\|^2/r - r$, so there is no trouble if $\|P\| = r$; we just get first coordinate to be 0. Using the point representation $I_P$ from below, let's orient the sphere so that its normals point into the "positive side," where $Q(I_P, I_s) > 0$. The vector $I_s$ then represents a sphere with outward normals, while $-I_s$ represents one with inward normals.                                                                                                                                                                                                                                                                                                                                       |
+| Plane $p$ with unit normal $(x,y,z)$ through the (Euclidean) point $(sx,sy,sz)$    | $I_p = (-2s, 0, -x, -y, -z)$                                                                                                                                                                                                                                                                                                                                                                                                         | Note that $Q(I_p, I_p)$ is still $-1$. We orient planes using the same convention we use for spheres. For example, $(-2, 0, -1/\sqrt3, -1/\sqrt3, -1/\sqrt3)$ and $(2, 0, 1/\sqrt3, 1/\sqrt3, 1/\sqrt3)$ represent planes that coincide in space, which have their normals pointing away from and toward the origin, respectively. Note that the ray from $(sx, sy, sz) \in p$ in direction $(-x, -y, -z)$ is the ray perpendicular to the plane through the origin; since $(-x, -y, -z)$ is a unit vector, $(sx, sy, sz)$ and hence $p$ is at distance $s$ from the origin. These coordinates are essentially the limit of a sphere's coordinates as its radius goes to infinity, or equivalently, as its bend goes to 0. |
+| Point $P$ with Euclidean coordinates $(x,y,z)$                                     | $I_P = (\|P\|^2, 1, x, y, z)$                                                                                                                                                                                                                                                                                                                                                                                                        | Note $Q(I_P,I_P) = 0$. This gives us the freedom to choose a different normalization. For example, we could scale the representation shown here by $(\|P\|^2+1)^{-1}$, putting it on the sphere where the light cone intersects the plane where the first two coordinates sum to $1$.                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| ∞, the "point at infinity"                                                         | $I_\infty = (1,0,0,0,0)$                                                                                                                                                                                                                                                                                                                                                                                                             | The only solution to $Q(I,I) = 0$ not covered by (some normalization of) the above case.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| Point $P$ lies on sphere or plane given by $I$                                     | $Q(I_P, I) = 0$                                                                                                                                                                                                                                                                                                                                                                                                                      | Actually also works if $I$ is the coordinates of a point, in which case "lies on" simply means "coincides with".                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| Sphere/planes represented by $I$ and $J$ are tangent                               | If $I$ and $J$ have the same orientation where they touch, $Q(I,J) = -1$. If they have opposing orientations, $Q(I,J) = 1$.                                                                                                                                                                                                                                                                                                          | For example, the $xy$ plane with normal $-e_z$, represented by $(0,0,0,0,1)$, is tangent with matching orientation to the unit sphere centered at $(0,0,1)$ with outward normals, represented by $(0,1,0,0,1).$ Accordingly, their $Q$ - product is $-1$.                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| Sphere/planes represented by $I$ and $J$ intersect (respectively, don't intersect) | $\lvert Q(I,J)\rvert \le (\text{resp. }>)\; 1$                                                                                                                                                                                                                                                                                                                                                                                       | Follows from the angle formula and the tangency condition, at least conceptually. One subtlety: parallel planes have $Q$ - product $\pm 1$, because they intersect at infinity (and in fact, are "tangent" there)!                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| $P$ is center of sphere rep'd by $I$                                               | $Q(I, I_P) = -r/2$, where $1/r = 2Q(I_\infty, I)$ is the signed bend of the sphere, and $I_P$ is normalized in the standard way, which is to set $Q(I_\infty, I_P) = 1/2$                                                                                                                                                                                                                                                            | This relationship is equivalent to both of the following. (1) The point $P$ has signed distance $-r$ from the sphere. (2) Inversion across the sphere maps $\infty$ to $P$.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| Distance between points $P$ and $R$ is $d$                                         | $Q(I_P, I_R) = d^2/2$                                                                                                                                                                                                                                                                                                                                                                                                                | If $P$ and $R$ are represented by non-normalized vectors $V_P$ and $V_R$, the relation becomes $Q(V_P, V_R) = 2\,Q(V_P, I_\infty)\,Q(V_R, I_\infty)\,d^2$. This version of the relation makes it easier to see why $d$ goes to infinity as $P$ or $R$ approaches the point at infinity.                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| Signed distance between point rep'd by $V$ and sphere/plane rep'd by $I$ is $d$    | In general, $\frac{Q(I, V)}{2Q(I_\infty, V)} = Q(I_\infty, I)\,d^2 + d$. When $V$ is normalized in the usual way, this simplifies to $Q(I, V) = d^2/r + d$ for a sphere of radius $r$, and to $Q(I, V) = d$ for a plane.                                                                                                                                                                                                             | We can use a Euclidean motion, represented linearly by a Lorentz transformation that fixes $I_\infty$, to put the point on the $z$ axis and put the nearest point on the sphere/plane at the origin with its normal pointing in the positive $z$ direction. Then the sphere/plane is represented by $I = (0, 1/r, 0, 0, -1)$, and the point can be represented by any multiple of $I_P = (d^2, 1, 0, 0, d)$, giving $Q(I, I_P) = d^2/2r + d.$ We turn this into a general expression by writing it in terms of Lorentz-invariant quantities and making it independent of the normalization of $I_P$.                                                                                                                       |
+| Distance between sphere/planes rep by $I$ and $J$                                  | Note that for any two Euclidean-concentric spheres rep by $I$ and $J$ with radius $r$ and $s,$ $Q(I,J) = -\frac12\left(\frac rs + \frac sr\right)$ depends only on the ratio of $r$ and $s$. So this can't give something that determines the Euclidean distance between the two spheres, which presumably grows as the two spheres are blown up proportionally. For another example, for any two parallel planes, $Q(I,J) = \pm1$. | Alex had said: $Q(I,J)=\cosh(d/2)^2$ maybe where d is distance in usual hyperbolic metric. Or maybe $\cosh(d)$. That may be right depending on what's meant by the hyperbolic metric there, but it seems like it won't determine a reasonable Euclidean distance between planes, which should differ between different pairs of parallel planes.                                                                                                                                                                                                                                                                                                                                                                           |
+| Sphere centered on point $P$ through point $R$                                     |                                                                                                                                                                                                                                                                                                                                                                                                                                      | Probably just calculate distance etc.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| Plane rep'd by $I$ goes through center of sphere rep'd by $J$                      | This is equivalent to the plane being perpendicular to the sphere: that is, $Q(I, J) = 0$.                                                                                                                                                                                                                                                                                                                                           |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| Dihedral angle between planes or spheres rep by $I$ and $J$                        | $\theta = \arccos(Q(I,J))$                                                                                                                                                                                                                                                                                                                                                                                                           | Aaron Fenyes points out: The angle between spheres in $S^3$ matches the angle between the planes they bound in $R^{(1,4)}$, which matches the angle between the spacelike vectors perpendicular to those planes. So we should have $Q(I,J) = \cos(\theta)$. Note that when the spheres do not intersect, we can interpret this as the "imaginary angle" between them, via $\cosh(t) = \cos(it)$.                                                                                                                                                                                                                                                                                                                           |
+| Points $R, P, S$ are collinear                                                     | Maybe just cross product of two differences is 0. Or, $R,P,S,\infty$ lie on a circle, or equivalently, $I_R,I_P,I_S,I_\infty$ span a plane (rather than a three-space). Or we can add two planes constrained to be perpendicular with one constrained to contain the origin, and all three points constrained to lie on both. But that's a lot of auxiliary entities and constraints...                                                                                                                                                                                                                                                             | $R,P,S$ lying on a line isn't a conformal property, but $R,P,S,\infty$ lying on a circle is.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| Plane through noncollinear $R, P, S$                                               | Should be, just solve $Q(I, I_R) = 0$ etc.                                                                                                                                                                                                                                                                                                                                                                                           |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| circle                                                                             | Maybe concentric sphere and the containing plane? Note it is easy to constrain the relationship between those two: they must be perpendicular.                                                                                                                                                                                                                                                                                       | Defn: circle is intersection of two spheres. That does cover lines. But you lose the canonicalness                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| line                                                                               | Maybe two perpendicular containing planes? Maybe the plane perpendicular to the line and through origin, together with the point of the line on that plane? Or maybe just as a bag of collinear points?                                                                                                                                                                                                                              | The first is the limiting case of the possible circle rep, but it is not canonical. However, there is a distinguished "standard" choice we could make: always choose one plane to contain the origin and the line, and the other to be the perpendicular plane containing the line. That choice or Plücker coordinates might be the best we can do. If we use the standardized perpendicular planes choice, then adding a line would be equivalent to adding two planes and the two constraints that one contains the origin and the other is perpendicular to it. That doesn't seem so bad. The second convention (perpendicular plane through the origin and a point on it) appears to be canonical, but there doesn't seem to be a circle representation that tends to it in the limit.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| Inversion of entity represented by $v$ across sphere $s$, rep'd by $I_s$           | $v \mapsto v + 2Q(I_s, v)\,I_s$                                                                                                                                                                                                                                                                                                                                                                                                      | This is just an educated guess, but its behavior is consistent with inversion in at least two ways. (1) It fixes points on $s$ and spheres perpendicular to $s$. (2) It preserves dihedral angles with $s$.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
 
 The unification of spheres/planes is indeed attractive for a project like Dyna3. The relationship between this representation and Geometric Algebras is a bit murky; likely it somehow fits under the Geometric Algebra umbrella.
 
@@ -40,3 +41,25 @@ I will have to work out formulas for the Euclidean distance between two entities
 In this vein, it seems as though if J1 and J2 are the reps of two points, then Q(J1,J2) = d^2/2. So then the sphere centered at J1 through J2 is (J1-(2Q(J1,J2),0,0,0,0))/sqrt(2Q(J1,J2)). Ugh has a sqrt in it. Similarly for sphere centered at J3 through J2, (J3-(2Q(J3,J2),0000))/sqrt(2Q(J3,J2)). J1,J2,J3 are collinear if these spheres are tangent, i.e. if those vectors have Q-inner-product 1, which is to say Q(J1,J3) - Q(J1,J2) - Q(J3,J2) = 2sqrt(Q(J1,J2)Q(J2,J3)). But maybe that's not the simplest way of putting it. After all, we can just say that the cross-product of the two differences is 0; that has no square roots in it.
 
 One conceivable way to canonicalize lines is to use the *perpendicular* plane that goes through the origin, that's uniquely defined, and anyway just amounts to I = (0,0,d) where d is the ordinary direction vector of the line; and a point J in that plane that the line goes through, which just amounts to J=(r^2,1,E) with Q(I,J) = 0, i.e. E\dot d = 0. It's also the point on the line closest to the origin. The reason that we don't usually use that point as the companion to the direction vector is that the resulting set of six coordinates is not homogeneous. But here that's not an issue, since we have our standard point coordinates and plane coordinates; and for a plane through the origin, only two of the direction coordinates are really free, and then we have the one dot-product relation, so only two of the point coordinates are really free, giving us the correct dimensionality of 4 for the set of lines. So in some sense this says that we could take naively as coordinates for a line the projection of the unit direction vector to the xy plane and the projection of the line's closest point to the origin to the xy plane. That doesn't seem to have any weird gimbal locks or discontinuities or anything. And with these coordinates, you can test if the point E=x,y,z is on the line (dx,dy,cx,cy) by extending (dx,dy) to d via dz = sqrt(1-dx^2 - dy^2), extending (cx,cy) to c by determining cz via d\dot c = 0, and then checking if d\cross(E-c) = 0. And you can see if two lines are parallel just by checking if they have the same direction vector, and if not, you can see if they are coplanar by projecting both of their closest points perpendicularly onto the line in the direction of the cross product of their directions, and if the projections match they are coplanar.
+
+#### Engine Conventions
+
+The coordinate conventions used in the engine are different from the ones used in these notes. Marking the engine vectors and coordinates with $'$, we have
+$$I' = (x', y', z', b', c'),$$
+where
+$$
+\begin{align*}
+x' & = x & b' & = b/2 \\
+y' & = y & c' & = c/2. \\
+z' & = z
+\end{align*}
+$$
+The engine uses the quadratic form $Q' = -Q$, which is expressed in engine coordinates as
+$$Q'(I'_1, I'_2) = x'_1 x'_2 + y'_1 y'_2 + z'_1 z'_2 - 2(b'_1c'_2 + c'_1 b'_2).$$
+In the `engine` module, the matrix of $Q'$ is encoded in the lazy static variable `Q`.
+
+In the engine's coordinate conventions, a sphere with radius $r > 0$ centered on $P = (P_x, P_y, P_z)$ is represented by the vector
+$$I'_s = \left(\frac{P_x}{r}, \frac{P_y}{r}, \frac{P_z}{r}, \frac1{2r}, \frac{\|P\|^2 - r^2}{2r}\right),$$
+which has the normalization $Q'(I'_s, I'_s) = 1$. The point $P$ is represented by the vector
+$$I'_P = \left(P_x, P_y, P_z, \frac{1}{2}, \frac{\|P\|^2}{2}\right).$$
+In the `engine` module, these formulas are encoded in the `sphere` and `point` functions.