PeriodicDecisionElement

A decision element reviewed on a fixed period, declared and scheduled in one construction.

A DecisionElement does not own its timing: a caller decides when a decision is due and calls decide. That is what makes a decision at a stockout, or at a point inside a process, expressible at all. It is also more than a modeler wants to think about when all they want is a review every thirty days — so this is that, packaged, and it is the shape most models should use.

val review = PeriodicDecisionElement(this, interval = 30.0, name = "Review") {
    observe(position)
    lever(this@StockRoom, 0..200, neutral = Neutral.Value(0.0)) { q -> placeOrder(q) }
    reward(onHand, rate = 0.5, sense = RewardSense.COST)
    policy = OrderUpTo(s = 20.0, bigS = 60.0)
}

It is a composition, not a special case. It holds an ordinary element and calls its ordinary public entry point from an ordinary event. Nothing here is reachable only from inside the library: a modeler who needs something this does not do writes their own, and PeriodicReview in the examples is the same thing with the declaration left to the caller.

What being a composition buys back

The construction guarantee. The DSL used to refuse an element that declared no timing, on the ground that it would be built, never decide, and report nothing. With timing owned by the caller that refusal had nothing to check — an element that declares none is now the ordinary shape. Here it comes back exactly: interval is a constructor argument, validated at construction, and an element built this way always has a caller. The silent no-decisions failure is unreachable.

R2b, by construction. The caller of decide warrants that the state it can observe is consistent, because the model is not guaranteed to be between events wherever a modeler chooses to call. This review runs inside an event of its own and does not change anything itself, so there is no half-finished update for it to be inside of. The caveat is the one the old scheduled epoch had too: other events at the same instant may not have run yet, so the state is consistent rather than final.

No runaway. A review that only fires on a timer cannot ask for a decision during a decision, which is the fault RunawayDecisionRequestException exists to diagnose.

Parameters