[AERIE-1953] Interval split operation for Windows and Spans

[JoelCourtney]

• Tickets addressed: AERIE-1953
• Review: By commit
• Merge strategy: Merge (no squash)

Description

Implements the split(N) operation, which splits each window into N equally sized sub-windows by removing N-1 points in the middle. Instantaneous point windows are left unchanged.

In practice since windows are defined in microseconds, the sub-windows might not be exactly equal, because the last sub-window might be up to N-1 microns longer than the others if the original duration is not a multiple of N. Also, if the original window is M microns long where M < N (however unlikely that might be), only M sub-windows will be produced.

Commits:

1. I added a basic parser for a nullable value. It is essentially chooseP(your parser, nullP) with some extra processing that turns it into Optional<your parser's output>.
2. Converts the CodeLocation record in ConstraintsCompilationError to have nullable fields, because runtime errors don't report code location
   • The TS API throws a runtime error if N < 1
3. Implements split
4. Tests split

Verification

Plenty of tests, see last commit.

Documentation

The API method is doc-commented. I'll update wiki after approval but before merge.

[JoelCourtney]

Marking as draft because I'm about to open a PR for basic Spans. Will implement Spans.split as well.

[JoelCourtney]

I've marked ready for review now that this PR includes Spans! This change introduces the IntervalContainer interface, which will be the unifying interface between Windows and Spans. Any operations that will exist on both container types (such as Split and many others) should be added to this interface. This way the Split node doesn't have to be duplicated for WindowsSplit and SpansSplit, and can just use the interface.

[dyst5422]

LGTM Thanks again for finding the user code runner bug!

[adrienmaillard]

I only have one (quite fundamental) question but otherwise all of this looks good to me.

[JoelCourtney]

Ok! Now that nullable windows is merged, the situation for split is a little different.

I'm thinking since windows gaps mean "unknown" instead of "undefined", it would technically be unknown where to split a window if a true segment neighbors a gap. So, I'm thinking split should throw an error if called on windows that have gaps.

Additionally, I'd like to make the inclusivity of any generated internal edges be configurable, with the defaults being internalStartInclusivity = Inclusive, internalEndInclusivity = Exclusive. The general patterns would be this:

• If calling split on Spans, just don't worry about it because its straightforward.
• If calling split on Windows:
  1. if your windows has gaps that you want to keep, save a copy of your windows object for step 5
  2. call assignGaps(true | false) (TODO) to remove any gaps
  3. call split(N, startInclusivity?, endInclusivity?), which always produces Spans just in case the chosen inclusivities would immediately cause coalescing (which would happen by default)
  4. either use your Spans object, or call .windows() and do step 5
  5. to optionally regain gaps, call .select(oldCopy) (TODO)

example code:

export default(): Constraint {
    let unsplitWindows = /* some external profile expression with gaps */;
    let splitWindows = unsplitWindows
        .assignGaps(false)
        .split(3, Inclusivity.Exclusive, Inclusivity.Exclusive)
        .windows()
        .select(unsplitWindows);
    // do whatever with your shiny new windows object
}

At some point if performance becomes a concern it may be helpful to implement a .cache() operation to avoid reevaluating things like unsplitWindows. The ast node would hash its children and store/lookup results in the environment variable in the expression interface. But that's a separate issue.

@adrienmaillard @dyst5422 @Twisol any thoughts?

[Twisol]

I think my first concern is what "N equally-sized windows" means if you happen to have a profile like true[-inf, 0] false[0,3] true[3, inf] (or heck, true[-inf, inf]). More generally, how should this behave on unbounded intervals?

(I know we use MIN_VALUE right now and not a proper -inf, but MIN_VALUE itself is a completely arbitrary value.)

[JoelCourtney]

More generally, how should this behave on unbounded intervals?

I suppose as long as we're trying to represent infinite intervals on a finite domain, simply leaving windows that touch MIN_VALUE or MAX_VALUE unchanged is fairly accurate.

[Twisol]

D'you think there are any valid use-cases for calling split when unbounded true intervals exist? It seems more likely to be the result of an incorrect windows expression -- maybe we'd prefer to throw when faced with such intervals, so that the author can correct their logic.

[JoelCourtney]

D'you think there are any valid use-cases for calling split when unbounded true intervals exist? It seems more likely to be the result of an incorrect windows expression -- maybe we'd prefer to throw when faced with such intervals, so that the author can correct their logic.

I can't think of any, so I'll add that check and throw an error. If such a use case ever comes up, it'll be very easy and I've left a comment explaining what to do.

[adrienmaillard]

Great work.