feat(protocol engine): add helpers for intra-frustum calculations

[caila-marashaj]

Overview

Within a given frustum, we know the math for finding both a volume given height, and a height given volume. This adds helper functions which perform that math for all shapes we have thus far (circular, rectangular, spherical).

The math for both the circular and rectangular frusta is found by integrating over the area of every cross section within a frustum, with respect to the height of the frustum.

I didn't personally derive the method for finding the volume of a spherical section, or spherical cap. This is where I got it from: https://www.cuemath.com/measurement/volume-of-a-section-of-a-sphere/

Changelog

• add height_from_volume_blank and volume_from_height_blank functions for all shapes (we'll have the caller dispatch by shape)
• add logic to narrow down potential height solutions from numpy.roots
• add InvalidLiquidHeightFound error in case we can't return 1 valid solution to our volume polynomial
• add fake circular and rectangular frusta to test on
• add tests for rectangular and circular frusta

Test Plan

I'm unsure how to go about testing the math for the spherical cap, but for rectangular and circular frusta, the tests are as follows:

I used google sheets to generate csv representations of both circular and rectangular frusta, where the area components (radius, length, width) grow or decay at a constant rate. I then translated each "frustum" into a python dictionary. The csv's are here and here if that's helpful.

The test functions I added use the height at some randomly determined row to find the volume at that height. They then use that volume to analytically determine what the height should be, and then it checks that the found height and the "actual" height from the dictionary are the same.

[sfoster1]

I think we can improve the type definitions, organization, and error handling but the math part and approach to testing looks good.

[jbleon95]

The actual body of the added functions look good besides for a couple nitpicks on that and some of the testing.

The bigger change I'm going to request here is moving the @staticmethod functions added to the GeometryView to be instead in its own helper function file. The reason for this has more to do with future unit testing than any dislike of static methods. If these methods remain where they are, future testing will have to make sure that any tested value will have to be mathematically accurate, even for unrelated tests or tests for code structure and not functional value testing.

If these are moved to their own file, then we can follow the pattern of monkeypatching out these functions, allowing geometry tests to focus on the higher level organization and let the frustra calculations be tested purely in isolation.

[sfoster1]

Excellent, looks great!

[jbleon95]

Looking good, thanks for the changes.