dyna3/README.md

# dyna3

### Abstract

Constraint-based three-dimensional dynamic geometry

## Description

From a thorough web search, there does not seem to be a dynamic geometry software package which (a) began its life handling three dimensions, rather than just two, and (b) allows you to express the desired geometric configuration in terms of constraints on the entities (e.g. l and k are parallel, a, b, and c a collinear, etc.) rather than as a construction (e.g. l is the perpendicular bisector of a and b). The goal of the dyna3 project is to close this gap.

Note that currently this is just the barest beginnings of the project, more of a framework for developing dyna3 rather than anything useful.

### Implementation goals

* Provide a comfortable, intuitive UI

* Allow execution 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.
   - In the future, `trunk` can be updated with the same command. (You may need the `--locked` flag if your ambient version of `rustc` does not match that required by `trunk`.)
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.
   - Alternatively, if you don't want to adjust your `PATH`, you can install `trunk` in another directory `DIR` via `cargo install --root DIR trunk`.

### 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. Use `sh` to run the script `tools/run-examples.sh`.
   - The script is location-independent, so you can do this from anywhere in the dyna3 repository.
   - The call from the top level of the repository is:
     
     ```bash
     sh tools/run-examples.sh
     ```
   - 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 execute
     
     ```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`.

### Deploy the prototype

1. From the `app-proto` folder, call `trunk build --release`.
   - Building in [release mode](https://doc.rust-lang.org/cargo/reference/profiles.html#release) produces an executable which is smaller and often much faster, but harder to debug and more time-consuming to build.
   - If you want to stay in the top-level folder, you can call `trunk build --config app-proto --release` from there instead.
2. Use `sh` to run the packaging script `tools/package-for-deployment.sh`.
   - The script is location-independent, so you can do this from anywhere in the dyna3 repository.
   - The call from the top level of the repository is:
     ```bash
     sh tools/package-for-deployment.sh
     ```
   - This will overwrite or replace the files in `deploy/dyna3`.
3. Put the contents of `deploy/dyna3` in the folder on your server that the prototype will be served from.
   - To simplify uploading, you might want to combine these files into an archive called `deploy/dyna3.zip`. Git has been set to ignore this path.