Start assembly serial number at zero

Introduce an assembly serial number, which increments when we load a new
assembly. Include it in each element outline item's diff key.

README.md

@@ -17,51 +17,3 @@ 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. Go into the `app-proto` folder
-2. 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*
-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/Cargo.toml

@@ -6,7 +6,6 @@ edition = "2021"
 
 [features]
 default = ["console_error_panic_hook"]
-dev = []
 
 [dependencies]
 itertools = "0.13.0"
@@ -26,7 +25,6 @@ console_error_panic_hook = { version = "0.1.7", optional = true }
 [dependencies.web-sys]
 version = "0.3.69"
 features = [
-  'DomRect',
   'HtmlCanvasElement',
   'HtmlInputElement',
   'Performance',
@@ -38,12 +36,7 @@ features = [
   '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"
 
 [profile.release]

app-proto/examples/irisawa-hexlet.rs

@@ -1,25 +0,0 @@
-use dyna3::engine::{Q, irisawa::realize_irisawa_hexlet};
-
-fn main() {
-    const SCALED_TOL: f64 = 1.0e-12;
-    let (config, success, history) = realize_irisawa_hexlet(SCALED_TOL);
-    print!("\nCompleted Gram matrix:{}", config.tr_mul(&*Q) * &config);
-    if success {
-        println!("Target accuracy achieved!");
-    } else {
-        println!("Failed to reach target accuracy");
-    }
-    println!("Steps: {}", history.scaled_loss.len() - 1);
-    println!("Loss: {}", history.scaled_loss.last().unwrap());
-    if success {
-        println!("\nChain diameters:");
-        println!("  {} sun (given)", 1.0 / config[(3, 3)]);
-        for k in 4..9 {
-            println!("  {} sun", 1.0 / config[(3, k)]);
-        }
-    }
-    println!("\nStep │ Loss\n─────┼────────────────────────────────");
-    for (step, scaled_loss) in history.scaled_loss.into_iter().enumerate() {
-        println!("{:<4} │ {}", step, scaled_loss);
-    }
-}

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

@@ -1,38 +0,0 @@
-use nalgebra::DMatrix;
-
-use dyna3::engine::{Q, point, realize_gram, sphere, PartialMatrix};
-
-fn main() {
-    let gram = {
-        let mut gram_to_be = PartialMatrix::new();
-        for j in 0..2 {
-            for k in j..2 {
-                gram_to_be.push_sym(j, k, if (j, k) == (1, 1) { 1.0 } else { 0.0 });
-            }
-        }
-        gram_to_be
-    };
-    let guess = DMatrix::from_columns(&[
-        point(0.0, 0.0, 2.0),
-        sphere(0.0, 0.0, 0.0, 1.0)
-    ]);
-    let frozen = [(3, 0)];
-    println!();
-    let (config, success, history) = realize_gram(
-        &gram, guess, &frozen,
-        1.0e-12, 0.5, 0.9, 1.1, 200, 110
-    );
-    print!("\nCompleted Gram matrix:{}", config.tr_mul(&*Q) * &config);
-    print!("Configuration:{}", config);
-    if success {
-        println!("Target accuracy achieved!");
-    } else {
-        println!("Failed to reach target accuracy");
-    }
-    println!("Steps: {}", history.scaled_loss.len() - 1);
-    println!("Loss: {}", history.scaled_loss.last().unwrap());
-    println!("\nStep │ Loss\n─────┼────────────────────────────────");
-    for (step, scaled_loss) in history.scaled_loss.into_iter().enumerate() {
-        println!("{:<4} │ {}", step, scaled_loss);
-    }
-}

app-proto/examples/three-spheres.rs

@@ -1,40 +0,0 @@
-use nalgebra::DMatrix;
-
-use dyna3::engine::{Q, realize_gram, sphere, PartialMatrix};
-
-fn main() {
-    let gram = {
-        let mut gram_to_be = PartialMatrix::new();
-        for j in 0..3 {
-            for k in j..3 {
-                gram_to_be.push_sym(j, k, if j == k { 1.0 } else { -1.0 });
-            }
-        }
-        gram_to_be
-    };
-    let guess = {
-        let a: f64 = 0.75_f64.sqrt();
-        DMatrix::from_columns(&[
-            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)
-        ])
-    };
-    println!();
-    let (config, success, history) = realize_gram(
-        &gram, guess, &[],
-        1.0e-12, 0.5, 0.9, 1.1, 200, 110
-    );
-    print!("\nCompleted Gram matrix:{}", config.tr_mul(&*Q) * &config);
-    if success {
-        println!("Target accuracy achieved!");
-    } else {
-        println!("Failed to reach target accuracy");
-    }
-    println!("Steps: {}", history.scaled_loss.len() - 1);
-    println!("Loss: {}", history.scaled_loss.last().unwrap());
-    println!("\nStep │ Loss\n─────┼────────────────────────────────");
-    for (step, scaled_loss) in history.scaled_loss.into_iter().enumerate() {
-        println!("{:<4} │ {}", step, scaled_loss);
-    }
-}

app-proto/run-examples

@@ -1,11 +1,8 @@
-#!/bin/sh
-
-# run all Cargo examples, as described here:
+# based on "Enabling print statements in Cargo tests", by Jon Almeida
 #
-#   Karol Kuczmarski. "Add examples to your Rust libraries"
-#   http://xion.io/post/code/rust-examples.html
+#   https://jonalmeida.com/posts/2015/01/23/print-cargo/
 #
 
-cargo run --example irisawa-hexlet
-cargo run --example three-spheres
-cargo run --example point-on-sphere
+cargo test -- --nocapture engine::tests::irisawa_hexlet_test
+cargo test -- --nocapture engine::tests::three_spheres_example
+cargo test -- --nocapture engine::tests::point_on_sphere_example

app-proto/src/add_remove.rs

@@ -148,6 +148,9 @@ pub fn AddRemove() -> View {
             assembly.elements_by_id.update(|elts_by_id| elts_by_id.clear());
             state.selection.update(|sel| sel.clear());
             
+            // increment assembly serial number
+            state.assembly_serial.set_fn_silent(|serial| serial.wrapping_add(1));
+            
             // load assembly
             match name.as_str() {
                 "general" => load_gen_assemb(assembly),

app-proto/src/assembly.rs

@@ -1,7 +1,7 @@
-use nalgebra::{DMatrix, DVector, Vector3};
+use nalgebra::{DMatrix, DVector};
 use rustc_hash::FxHashMap;
 use slab::Slab;
-use std::{collections::BTreeSet, sync::atomic::{AtomicU64, Ordering}};
+use std::collections::BTreeSet;
 use sycamore::prelude::*;
 use web_sys::{console, wasm_bindgen::JsValue}; /* DEBUG */
 
@@ -13,13 +13,6 @@ pub type ConstraintKey = usize;
 
 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 element has a key that identifies it within its assembly and
-// each assembly has a key that identifies it within the sesssion
-static NEXT_ELEMENT_SERIAL: AtomicU64 = AtomicU64::new(0);
-
 #[derive(Clone, PartialEq)]
 pub struct Element {
     pub id: String,
@@ -27,10 +20,6 @@ pub struct Element {
     pub color: ElementColor,
     pub representation: Signal<DVector<f64>>,
     pub constraints: Signal<BTreeSet<ConstraintKey>>,
-
-    // a serial number, assigned by `Element::new`, that uniquely identifies
-    // each element
-    pub serial: u64,
     
     // the configuration matrix column index that was assigned to this element
     // last time the assembly was realized
@@ -44,70 +33,15 @@ impl Element {
         color: ElementColor,
         representation: DVector<f64>
     ) -> Element {
-        // take the next serial number, panicking if that was the last number we
-        // had left. 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
-        //
-        let serial = NEXT_ELEMENT_SERIAL.fetch_update(
-            Ordering::SeqCst, Ordering::SeqCst,
-            |serial| serial.checked_add(1)
-        ).expect("Out of serial numbers for elements");
-        
         Element {
             id: id,
             label: label,
             color: color,
             representation: create_signal(representation),
             constraints: create_signal(BTreeSet::default()),
-            serial: serial,
             column_index: 0
         }
     }
-    
-    // the smallest positive depth, represented as a multiple of `dir`, where
-    // the line generated by `dir` hits the element (which is assumed to be a
-    // sphere). returns `None` if the line misses the sphere. this function
-    // should be kept synchronized with `sphere_cast` in `inversive.frag`, which
-    // does essentially the same thing on the GPU side
-    pub fn cast(&self, dir: Vector3<f64>, assembly_to_world: &DMatrix<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
-        }
-    }
 }
             
 

app-proto/src/display.rs

@@ -4,9 +4,7 @@ use sycamore::{prelude::*, motion::create_raf};
 use web_sys::{
     console,
     window,
-    Element,
     KeyboardEvent,
-    MouseEvent,
     WebGl2RenderingContext,
     WebGlProgram,
     WebGlShader,
@@ -14,7 +12,7 @@ use web_sys::{
     wasm_bindgen::{JsCast, JsValue}
 };
 
-use crate::{AppState, assembly::ElementKey};
+use crate::AppState;
 
 fn compile_shader(
     context: &WebGl2RenderingContext,
@@ -84,24 +82,6 @@ fn bind_vertex_attrib(
     );
 }
 
-// the direction in camera space that a mouse event is pointing along
-fn event_dir(event: &MouseEvent) -> Vector3<f64> {
-    let target: 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 `inversive.frag`
-    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
-    )
-}
-
 #[component]
 pub fn Display() -> View {
     let state = use_context::<AppState>();
@@ -109,9 +89,6 @@ pub fn Display() -> View {
     // 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);
@@ -319,7 +296,7 @@ pub fn Display() -> View {
                         0.0, 0.0,   0.0, 0.0, 1.0
                     ])
                 };
-                let asm_to_world = &location * &orientation;
+                let assembly_to_world = &location * &orientation;
                 
                 // get the assembly
                 let (
@@ -334,7 +311,7 @@ pub fn Display() -> View {
                         
                         // representation vectors in world coordinates
                         elts.iter().map(
-                            |(_, elt)| elt.representation.with(|rep| &asm_to_world * rep)
+                            |(_, elt)| elt.representation.with(|rep| &assembly_to_world * rep)
                         ).collect::<Vec<_>>(),
                         
                         // colors
@@ -393,9 +370,6 @@ pub fn Display() -> View {
                 // draw the scene
                 ctx.draw_arrays(WebGl2RenderingContext::TRIANGLES, 0, VERTEX_CNT as i32);
                 
-                // update the viewpoint
-                assembly_to_world.set(asm_to_world);
-                
                 // clear the scene change flag
                 scene_changed.set(
                     pitch_up_val != 0.0
@@ -484,31 +458,6 @@ pub fn Display() -> View {
                 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 = event_dir(&event);
-                console::log_1(&JsValue::from(dir.to_string()));
-                let mut clicked: Option<(ElementKey, f64)> = None;
-                for (key, elt) in state.assembly.elements.get_clone_untracked() {
-                    match assembly_to_world.with(|asm_to_world| elt.cast(dir, asm_to_world)) {
-                        Some(depth) => match clicked {
-                            Some((_, best_depth)) => {
-                                if depth < best_depth {
-                                    clicked = Some((key, depth))
-                                }
-                            },
-                            None => clicked = Some((key, depth))
-                        }
-                        None => ()
-                    };
-                }
-                
-                // if we clicked something, select it
-                match clicked {
-                    Some((key, _)) => state.select(key, event.shift_key()),
-                    None => state.selection.update(|sel| sel.clear())
-                };
             }
         )
     }

app-proto/src/engine.rs

@@ -4,7 +4,7 @@ use web_sys::{console, wasm_bindgen::JsValue}; /* DEBUG */
 
 // --- elements ---
 
-#[cfg(feature = "dev")]
+#[cfg(test)]
 pub fn point(x: f64, y: f64, z: f64) -> DVector<f64> {
     DVector::from_column_slice(&[x, y, z, 0.5, 0.5*(x*x + y*y + z*z)])
 }
@@ -113,7 +113,7 @@ impl DescentHistory {
 
 // the Lorentz form
 lazy_static! {
-    pub static ref Q: DMatrix<f64> = DMatrix::from_row_slice(5, 5, &[
+    static ref Q: DMatrix<f64> = DMatrix::from_row_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,  0.0,
@@ -277,79 +277,12 @@ pub fn realize_gram(
 
 // --- tests ---
 
-// 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/
-//
-#[cfg(feature = "dev")]
-pub mod irisawa {
+#[cfg(test)]
+mod tests {
     use std::{array, f64::consts::PI};
     
     use super::*;
     
-    pub fn realize_irisawa_hexlet(scaled_tol: f64) -> (DMatrix<f64>, bool, DescentHistory) {
-        let gram = {
-            let mut gram_to_be = PartialMatrix::new();
-            for s in 0..9 {
-                // each sphere is represented by a spacelike vector
-                gram_to_be.push_sym(s, s, 1.0);
-                
-                // the circumscribing sphere is tangent to all of the other
-                // spheres, with matching orientation
-                if s > 0 {
-                    gram_to_be.push_sym(0, s, 1.0);
-                }
-                
-                if s > 2 {
-                    // each chain sphere is tangent to the "sun" and "moon"
-                    // spheres, with opposing orientation
-                    for n in 1..3 {
-                        gram_to_be.push_sym(s, n, -1.0);
-                    }
-                    
-                    // each chain sphere is tangent to the next chain sphere,
-                    // with opposing orientation
-                    let s_next = 3 + (s-2) % 6;
-                    gram_to_be.push_sym(s, s_next, -1.0);
-                }
-            }
-            gram_to_be
-        };
-        
-        let guess = DMatrix::from_columns(
-            [
-                sphere(0.0, 0.0, 0.0, 15.0),
-                sphere(0.0, 0.0, -9.0, 5.0),
-                sphere(0.0, 0.0, 11.0, 3.0)
-            ].into_iter().chain(
-                (1..=6).map(
-                    |k| {
-                        let ang = (k as f64) * PI/3.0;
-                        sphere(9.0 * ang.cos(), 9.0 * ang.sin(), 0.0, 2.5)
-                    }
-                )
-            ).collect::<Vec<_>>().as_slice()
-        );
-        
-        // the frozen entries fix the radii of the circumscribing sphere, the
-        // "sun" and "moon" spheres, and one of the chain spheres
-        let frozen: [(usize, usize); 4] = array::from_fn(|k| (3, k));
-        
-        realize_gram(
-            &gram, guess, &frozen,
-            scaled_tol, 0.5, 0.9, 1.1, 200, 110
-        )
-    }
-}
-
-#[cfg(test)]
-mod tests {
-    use super::{*, irisawa::realize_irisawa_hexlet};
-    
     #[test]
     fn sub_proj_test() {
         let target = PartialMatrix(vec![
@@ -395,20 +328,182 @@ mod tests {
         assert!(state.loss.abs() < f64::EPSILON);
     }
     
+    // 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/
+    //
     #[test]
     fn irisawa_hexlet_test() {
-        // solve Irisawa's problem
+        let gram = PartialMatrix({
+            let mut entries = Vec::<MatrixEntry>::new();
+            for s in 0..9 {
+                // each sphere is represented by a spacelike vector
+                entries.push(MatrixEntry { index: (s, s), value: 1.0 });
+                
+                // the circumscribing sphere is tangent to all of the other
+                // spheres, with matching orientation
+                if s > 0 {
+                    entries.push(MatrixEntry { index: (0, s), value: 1.0 });
+                    entries.push(MatrixEntry { index: (s, 0), value: 1.0 });
+                }
+                
+                if s > 2 {
+                    // each chain sphere is tangent to the "sun" and "moon"
+                    // spheres, with opposing orientation
+                    for n in 1..3 {
+                        entries.push(MatrixEntry { index: (s, n), value: -1.0 });
+                        entries.push(MatrixEntry { index: (n, s), value: -1.0 });
+                    }
+                    
+                    // each chain sphere is tangent to the next chain sphere,
+                    // with opposing orientation
+                    let s_next = 3 + (s-2) % 6;
+                    entries.push(MatrixEntry { index: (s, s_next), value: -1.0 });
+                    entries.push(MatrixEntry { index: (s_next, s), value: -1.0 });
+                }
+            }
+            entries
+        });
+        let guess = DMatrix::from_columns(
+            [
+                sphere(0.0, 0.0, 0.0, 15.0),
+                sphere(0.0, 0.0, -9.0, 5.0),
+                sphere(0.0, 0.0, 11.0, 3.0)
+            ].into_iter().chain(
+                (1..=6).map(
+                    |k| {
+                        let ang = (k as f64) * PI/3.0;
+                        sphere(9.0 * ang.cos(), 9.0 * ang.sin(), 0.0, 2.5)
+                    }
+                )
+            ).collect::<Vec<_>>().as_slice()
+        );
+        let frozen: [(usize, usize); 4] = array::from_fn(|k| (3, k));
         const SCALED_TOL: f64 = 1.0e-12;
-        let (config, _, _) = realize_irisawa_hexlet(SCALED_TOL);
-        
-        // check against Irisawa's solution
+        let (config, success, history) = realize_gram(
+            &gram, guess, &frozen,
+            SCALED_TOL, 0.5, 0.9, 1.1, 200, 110
+        );
         let entry_tol = SCALED_TOL.sqrt();
         let solution_diams = [30.0, 10.0, 6.0, 5.0, 15.0, 10.0, 3.75, 2.5, 2.0 + 8.0/11.0];
         for (k, diam) in solution_diams.into_iter().enumerate() {
             assert!((config[(3, k)] - 1.0 / diam).abs() < entry_tol);
         }
+        print!("\nCompleted Gram matrix:{}", config.tr_mul(&*Q) * &config);
+        if success {
+            println!("Target accuracy achieved!");
+        } else {
+            println!("Failed to reach target accuracy");
+        }
+        println!("Steps: {}", history.scaled_loss.len() - 1);
+        println!("Loss: {}", history.scaled_loss.last().unwrap());
+        if success {
+            println!("\nChain diameters:");
+            println!("  {} sun (given)", 1.0 / config[(3, 3)]);
+            for k in 4..9 {
+                println!("  {} sun", 1.0 / config[(3, k)]);
+            }
+        }
+        println!("\nStep │ Loss\n─────┼────────────────────────────────");
+        for (step, scaled_loss) in history.scaled_loss.into_iter().enumerate() {
+            println!("{:<4} │ {}", step, scaled_loss);
+        }
     }
     
+    // --- process inspection examples ---
+    
+    // these tests are meant for human inspection, not automated use. run them
+    // one at a time in `--nocapture` mode and read through the results and
+    // optimization histories that they print out. the `run-examples` script
+    // will run all of them
+    
+    #[test]
+    fn three_spheres_example() {
+        let gram = PartialMatrix({
+            let mut entries = Vec::<MatrixEntry>::new();
+            for j in 0..3 {
+                for k in 0..3 {
+                    entries.push(MatrixEntry {
+                        index: (j, k),
+                        value: if j == k { 1.0 } else { -1.0 }
+                    });
+                }
+            }
+            entries
+        });
+        let guess = {
+            let a: f64 = 0.75_f64.sqrt();
+            DMatrix::from_columns(&[
+                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)
+            ])
+        };
+        println!();
+        let (config, success, history) = realize_gram(
+            &gram, guess, &[],
+            1.0e-12, 0.5, 0.9, 1.1, 200, 110
+        );
+        print!("\nCompleted Gram matrix:{}", config.tr_mul(&*Q) * &config);
+        if success {
+            println!("Target accuracy achieved!");
+        } else {
+            println!("Failed to reach target accuracy");
+        }
+        println!("Steps: {}", history.scaled_loss.len() - 1);
+        println!("Loss: {}", history.scaled_loss.last().unwrap());
+        println!("\nStep │ Loss\n─────┼────────────────────────────────");
+        for (step, scaled_loss) in history.scaled_loss.into_iter().enumerate() {
+            println!("{:<4} │ {}", step, scaled_loss);
+        }
+    }
+    
+    #[test]
+    fn point_on_sphere_example() {
+        let gram = PartialMatrix({
+            let mut entries = Vec::<MatrixEntry>::new();
+            for j in 0..2 {
+                for k in 0..2 {
+                    entries.push(MatrixEntry {
+                        index: (j, k),
+                        value: if (j, k) == (1, 1) { 1.0 } else { 0.0 }
+                    });
+                }
+            }
+            entries
+        });
+        let guess = DMatrix::from_columns(&[
+            point(0.0, 0.0, 2.0),
+            sphere(0.0, 0.0, 0.0, 1.0)
+        ]);
+        let frozen = [(3, 0)];
+        println!();
+        let (config, success, history) = realize_gram(
+            &gram, guess, &frozen,
+            1.0e-12, 0.5, 0.9, 1.1, 200, 110
+        );
+        print!("\nCompleted Gram matrix:{}", config.tr_mul(&*Q) * &config);
+        print!("Configuration:{}", config);
+        if success {
+            println!("Target accuracy achieved!");
+        } else {
+            println!("Failed to reach target accuracy");
+        }
+        println!("Steps: {}", history.scaled_loss.len() - 1);
+        println!("Loss: {}", history.scaled_loss.last().unwrap());
+        println!("\nStep │ Loss\n─────┼────────────────────────────────");
+        for (step, scaled_loss) in history.scaled_loss.into_iter().enumerate() {
+            println!("{:<4} │ {}", step, scaled_loss);
+        }
+    }
+    
+    /* TO DO */
+    // --- new test placed here to avoid merge conflict ---
+    
     // at the frozen indices, the optimization steps should have exact zeros,
     // and the realized configuration should match the initial guess
     #[test]

app-proto/src/lib.rs

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

app-proto/src/main.rs

@@ -15,6 +15,7 @@ use outline::Outline;
 #[derive(Clone)]
 struct AppState {
     assembly: Assembly,
+    assembly_serial: Signal<u32>,
     selection: Signal<FxHashSet<ElementKey>>
 }
 
@@ -22,27 +23,10 @@ impl AppState {
     fn new() -> AppState {
         AppState {
             assembly: Assembly::new(),
+            assembly_serial: create_signal(0),
             selection: create_signal(FxHashSet::default())
         }
     }
-    
-    // in single-selection mode, select the element with the given key. in
-    // multiple-selection mode, toggle whether the element with the given key
-    // is selected
-    fn select(&self, key: ElementKey, multi: bool) {
-        if multi {
-            self.selection.update(|sel| {
-                if !sel.remove(&key) {
-                    sel.insert(key);
-                }
-            });
-        } else {
-            self.selection.update(|sel| {
-                sel.clear();
-                sel.insert(key);
-            });
-        }
-    }
 }
 
 fn main() {

app-proto/src/outline.rs

@@ -83,7 +83,18 @@ fn ElementOutlineItem(key: ElementKey, element: assembly::Element) -> View {
                         move |event: KeyboardEvent| {
                             match event.key().as_str() {
                                 "Enter" => {
-                                    state.select(key, event.shift_key());
+                                    if event.shift_key() {
+                                        state.selection.update(|sel| {
+                                            if !sel.remove(&key) {
+                                                sel.insert(key);
+                                            }
+                                        });
+                                    } else {
+                                        state.selection.update(|sel| {
+                                            sel.clear();
+                                            sel.insert(key);
+                                        });
+                                    }
                                     event.prevent_default();
                                 },
                                 "ArrowRight" if constrained.get() => {
@@ -169,11 +180,15 @@ pub fn Outline() -> View {
     
     // list the elements alphabetically by ID
     let element_list = state.assembly.elements.map(
-        |elts| elts
-            .clone()
-            .into_iter()
-            .sorted_by_key(|(_, elt)| elt.id.clone())
-            .collect()
+        move |elts| {
+            let asm_serial = state.assembly_serial.get_untracked();
+            elts
+                .clone()
+                .into_iter()
+                .sorted_by_key(|(_, elt)| elt.id.clone())
+                .map(|(key, elt)| (asm_serial, key, elt))
+                .collect()
+        }
     );
     
     view! {
@@ -186,10 +201,10 @@ pub fn Outline() -> View {
         ) {
             Keyed(
                 list=element_list,
-                view=|(key, elt)| view! {
+                view=|(_, key, elt)| view! {
                     ElementOutlineItem(key=key, element=elt)
                 },
-                key=|(_, elt)| elt.serial
+                key=|(asm_serial, key, _)| (asm_serial.clone(), key.clone())
             )
         }
     }