feat: Structural formula example

[keenancrane]

Description

This PR adds a new example of structural formula diagrams, used to illustrate molecular structures and chemical reaction equations. Some example output can be found here.

It also implements a variety of changes needed to support these diagrams. In particular:

• It adds an implementation of the arccos (acos) and arcsin (asin) functions to the autodiff engine, and exposes them via corresponding Style functions.
• Also added functions sgn (which gives the sign of a scalar value), toRadians (which converts an angle from degrees to radians), and toDegrees (which converts an angle from degrees to radians).
• It exposes a cross2D function to Style, which computes the cross product of two 2D vectors.
• It fixes long-standing bugs in the implementation of atan2(y,x) in the autodiff engine. Previously this function evaluated the product x*y rather than the 2-argument arc tangent. It also incorrectly swapped the derivatives with respect to x and y. The new implementation was briefly tested by displaying and optimizing the angles of a triangle (which now works as expected).
• It exposes two new Style functions for computing the angle between two vectors: angleBetween(u,v) and angleFrom(u,v). The former computes the unsigned angle between u and v; the latter computes the signed angle from u to v.
• It fixes the implementation of the constraint contains(Rectangle,Circle). Previously, this constraint used a circle as a proxy for the rectangle, leading to unexpected and undesirable behavior (e.g., shapes not actually being constrained to the rectangle interior). The new implementation has been tested and validated on a large number of examples (molecular diagrams, with many circles that must remain inside the canvas rectangle).
• It exposes the SVG feature stroke-linecap in Style. In particular, Line and Arrow shapes now have a field strokeLineCap: which can be set to butt, round, or square. This feature has been tested and validated in the structural-formula/psuedo-3d.sty style.

Finally, this PR includes a file DevLog.md which documents the process of developing this domain, and various conceptual & technical hurdles encountered along the way. This metadata may be useful for future expert studies, etc.

Related issue/PR: # (issue/PR)

NA

Implementation strategy and design decisions

The only real "design decision" was how to implement the contains(Rectangle,Circle) constraint. I didn't do anything unconventional—here's the comment from Constraints.ts that spells out the new constraint implementation:

      // Return maximum violation in either the x- or y-direction.
      // In each direction, the distance from the circle center (cx,cy) to
      // the rectangle center (rx,ry) must be no greater than the size of
      // the rectangle (w/h), minus the radius of the circle (r) and the
      // offset (o).  We can compute this violation via the function
      //    max( |cx-rx| - (w/2-r-o),
      //         |cy-ry| - (h/2-r-o) )

Examples with steps to reproduce them

This PR includes:

• a Domain schema (structural-formula)
• three Styles (structural-formula.sty, pseudo-3d.sty, pseudo-3d-reaction.sty)
• a variety of molecules and reactions expressed as Substance programs (in /molecules and /reactions)

For convenience, these examples can be run using the run script in the root directory. Edit this file to try out different combinations of molecules and styles. Note that reactions must use the pseudo-3d-reaction.sty style, and likewise, individual molecules will not play well with pseudo-3d-reaction.sty (which expects molecules to be grouped into reactants and products).

Checklist

• I have commented my code, particularly in hard-to-understand areas
• My changes generate no new warnings
• New and existing tests pass locally using yarn test
• I ran yarn docs and there were no errors when generating the HTML site
• My code follows the style guidelines of this project (e.g.: no ESLint warnings)

Open questions

NA

Questions that require more discussion or to be addressed in future development:

NA

[codecov]

Codecov Report

Merging #734 (8070119) into main (28226dd) will decrease coverage by 0.38%.
The diff coverage is 28.94%.

@@            Coverage Diff             @@
##             main     #734      +/-   ##
==========================================
- Coverage   67.78%   67.39%   -0.39%     
==========================================
  Files          45       45              
  Lines        7375     7444      +69     
  Branches     1398     1416      +18     
==========================================
+ Hits         4999     5017      +18     
- Misses       2367     2418      +51     
  Partials        9        9              

Impacted Files	Coverage Δ
packages/core/src/contrib/Functions.ts	43.93% <0.00%> (-2.28%)	⬇️
packages/core/src/renderer/ShapeDef.ts	79.06% <ø> (ø)
packages/core/src/engine/Autodiff.ts	72.77% <10.52%> (-2.52%)	⬇️
packages/core/src/renderer/Arrow.ts	97.14% <60.00%> (-2.86%)	⬇️
packages/core/src/renderer/AttrHelper.ts	72.22% <60.00%> (-0.44%)	⬇️
packages/core/src/renderer/Line.ts	95.65% <83.33%> (-1.85%)	⬇️
packages/core/src/contrib/Constraints.ts	61.87% <100.00%> (+0.30%)	⬆️

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 28226dd...8070119. Read the comment docs.

[keenancrane]

@samestep I restored this branch because it's linked to from Twitter. 😬
https://twitter.com/keenanisalive/status/1476345418770493440
Next time I'll be more careful about linking to branches that are going to die…

[samestep]

@keenancrane Oh! 😮 Sorry about that, I was being too aggressive in deleting branches today; I won't do that from now on.