Skip to content

Commit

Permalink
New page describing Allen Temporal Relations for Aerie. Pending to re…
Browse files Browse the repository at this point in the history
…solve how to illustrate images
  • Loading branch information
JMVictor authored and JMVictor committed Aug 11, 2023
1 parent dbef007 commit 0f909f0
Show file tree
Hide file tree
Showing 11 changed files with 1,770 additions and 10,592 deletions.
3 changes: 3 additions & 0 deletions docs/scheduling/assets/xbeforey.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
3 changes: 3 additions & 0 deletions docs/scheduling/assets/xcontainsy.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
3 changes: 3 additions & 0 deletions docs/scheduling/assets/xequalsy.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
3 changes: 3 additions & 0 deletions docs/scheduling/assets/xfinishesy.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
3 changes: 3 additions & 0 deletions docs/scheduling/assets/xmeetsy.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
3 changes: 3 additions & 0 deletions docs/scheduling/assets/xoverlapsy.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
3 changes: 3 additions & 0 deletions docs/scheduling/assets/xstartsy.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
140 changes: 140 additions & 0 deletions docs/scheduling/modelling-temporal-relations.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,140 @@
import xbeforey from './assets/xbeforey.png';
import xequalsy from './assets/xequalsy.png';
import xmeetsy from './assets/xmeetsy.png';
import xoverlapsy from './assets/xoverlapsy.png';
import xcontainsy from './assets/xcontainsy.png';
import xstartsy from './assets/xstartsy.png';

# Modelling Temporal Relations with Coexistence Goal
In mission modeling and planning for space systems, having the capability to establish temporal dependencies between events or activities is crucial.
Aerie includes the capability to model flexible temporal relations through the use of `Coexistence Goals`.

A Coexistence Goal can be used to define a causality relation between two activities: the first activity is a directive that should be already included in the plan,
while the second is an activity type to be added to the plan under certain conditions. Both activities can be instantaneous or have a duration, and can be related temporally
in several ways. The [Allen’s Temporal Relations](https://en.wikipedia.org/wiki/Allen%27s_interval_algebra) describe 14 different ways in which two time intervals relate to each other.
Many of these relations can be easily generalized to relations between timepoints for instantaneous activities.

The following sections introduce the syntax to represent temporal relations in Aerie and provide a number of examples.

## Flexible Time Intervals in eDSL
Consider a time interval as a time range defined by two timepoints that specify the lower and upper bounds of the interval. For example, `[lb, ub]` represents a closed time interval bounded by the timepoints `lb` and `ub`.
We define a flexible interval as a time range where its timepoints are specified relative to another timepoint. For example, considering `ae` as the timepoint at which an activity `a` ends, we can define a time interval relative to it
as follows: `[ae + x, ae + y]` where `x` and `y` represents the delta lower and upper bounds with respect to`a`'s end.

Flexible Time Intervals are represented in Aerie by means of `TimingConstraint.bounds`, which are composed of two `TimingConstraint.singletons` to model the lower and upper bound.
For example,
```ts
TimingConstraint.bounds(TimingConstraint.singleton(WindowProperty.START).plus(Temporal.Duration.from({ minutes : 5})), TimingConstraint.singleton(WindowProperty.START).plus(Temporal.Duration.from({ minutes : 10})))
```
represents a time interval that ranges between 5 and 10 units of time after the start timepoint of a `Window` (`WindowProperty.START`).

`bounds` represent the core expression to model Allen relations.

## Allen's Temporal Relations
The following paragraphs provide examples for 7 Allen relations, while the other 7 are the opposite relation (e.g. Starts vs Started_by).
The examples are based on the Banananation scenario. GrowBanana and DurationParameterActivity are used as examples of durative activities while peelBanana is used whenever instantaneous activities are applicable.

### Before
The relation `x BEFORE[lb, ub] y` indicates that y must start between `[lb, ub]` units of time after x completes. Both activities can be instantaneous or durative.
In the example below, peelBanana starts between `[5, 10]` units of time after GrowBanana finishes.

<figure align="center">
<img alt="Allen Relation BEFORE" src={xbeforey} width="350" />
<figcaption>Figure 1: Relation x BEFORE [lb, ub] y</figcaption>
</figure>

```ts
export default () => Goal.CoexistenceGoal({
forEach: ActivityExpression.ofType(ActivityTypes.GrowBanana),
activityTemplate: (span) => ActivityTemplates.PeelBanana({peelDirection: "fromStem"}),
startsWithin: TimingConstraint.bounds(TimingConstraint.singleton(WindowProperty.END).plus(Temporal.Duration.from({ minutes : 5})), TimingConstraint.singleton(WindowProperty.END).plus(Temporal.Duration.from({ minutes : 10})))
})
```

### Equals
The relation `x EQUALS y` indicates that y starts and finishes at the same time as x. Both activities must be durative. The timepont variant would need to consider the start value.
In the example below, DurationParameterActivity starts and finishes at the same time as GrowBanana.

<figure align="center">
<img alt="Allen Relation EQUALS" src={xequalsy} width="200" />
<figcaption>Figure 2: Relation x EQUALS y</figcaption>
</figure>

```ts
export default () => Goal.CoexistenceGoal({
forEach: ActivityExpression.ofType(ActivityTypes.GrowBanana),
activityTemplate: (span) => ActivityTemplates.DurationParameterActivity({duration: Temporal.Duration.from({ hours : 1})}),
startsAt: TimingConstraint.singleton(WindowProperty.START),
endsAt: TimingConstraint.singleton(WindowProperty.END)
})
```

### Meets
The relation `x MEETS y` indicates that y starts right after the time x finishes. x must be a durative activity while y could be durative or instantaneous.
In the example below, peelBanana takes place at the time when GrowBanana finishes.

<figure align="center">
<img alt="Allen Relation MEETS" src={xmeetsy} width="300" />
<figcaption>Figure 3: Relation x MEETS y</figcaption>
</figure>

```ts
export default () => Goal.CoexistenceGoal({
forEach: ActivityExpression.ofType(ActivityTypes.GrowBanana),
activityTemplate: (span) => ActivityTemplates.PeelBanana({peelDirection: "fromStem"}),
startsAt: TimingConstraint.singleton(WindowProperty.END)
})
```

### Overlaps
The relation `x OVERLAPS[lb,ub] y` indicates that y start time overlaps x end time by an amount of time between `lb` and `ub`. Both activities must be durative.
In the example below, DurationParameterActivity starts between [5,10] units of time before GrowBanana finishes.

<figure align="center">
<img alt="Allen Relation OVERLAPS" src={xoverlapsy} width="300" />
<figcaption>Figure 4: Relation x OVERLAPS y</figcaption>
</figure>

```ts
export default () => Goal.CoexistenceGoal({
forEach: ActivityExpression.ofType(ActivityTypes.GrowBanana),
activityTemplate: (span) => ActivityTemplates.DurationParameterActivity({duration: Temporal.Duration.from({ hours : 1})}),
startsWithin: TimingConstraint.bounds(TimingConstraint.singleton(WindowProperty.END).minus(Temporal.Duration.from({ minutes : 10})), TimingConstraint.singleton(WindowProperty.END).minus(Temporal.Duration.from({minutes : 5})))
})
```

### Contains
The relation `x CONTAINS[lb1,ub1] [lb2, ub2] y` indicates that y starts between `[lb1,ub1]` units of time after x does, and it ends between `[lb2,ub2]` before x does. Both activities must be durative.
In the example below, DurationParameterActivity starts between `[5,10]` units of time after GrowBanana starts and finishes between `[5,10]` units of time before GrowBanana does.


<figure align="center">
<img alt="Allen Relation CONTAINS" src={xcontainsy} width="300" />
<figcaption>Figure 5: Relation x CONTAINS y</figcaption>
</figure>

```ts
export default () => Goal.CoexistenceGoal({
forEach: ActivityExpression.ofType(ActivityTypes.GrowBanana),
activityTemplate: (span) => ActivityTemplates.DurationParameterActivity({duration: Temporal.Duration.from({ minutes : 50})}),
startsWithin: TimingConstraint.bounds(TimingConstraint.singleton(WindowProperty.START).plus(Temporal.Duration.from({ minutes : 5})), TimingConstraint.singleton(WindowProperty.START).plus(Temporal.Duration.from({minutes : 10}))),
endsWithin: TimingConstraint.bounds(TimingConstraint.singleton(WindowProperty.END).minus(Temporal.Duration.from({ minutes : 10})), TimingConstraint.singleton(WindowProperty.END).minus(Temporal.Duration.from({ minutes : 5})))
})
```

### Starts
The relation `x STARTS[lb,ub] y` indicates that y starts between `[lb,ub]` after x does. x must be durative.
In the example below, DurationParameterActivity starts between `[5,10]` units of time after GrowBanana does.

<figure align="center">
<img alt="Allen Relation STARTS" src={xstartsy} width="300" />
<figcaption>Figure 5: Relation x STARTS y</figcaption>
</figure>

```ts
export default () => Goal.CoexistenceGoal({
forEach: ActivityExpression.ofType(ActivityTypes.GrowBanana),
activityTemplate: (span) => ActivityTemplates.PeelBanana({peelDirection: "fromStem"}),
startsWithin: TimingConstraint.bounds(TimingConstraint.singleton(WindowProperty.START).plus(Temporal.Duration.from({ minutes : 5})), TimingConstraint.singleton(WindowProperty.START).plus(Temporal.Duration.from({ minutes : 10})))
})
```
Loading

0 comments on commit 0f909f0

Please sign in to comment.