urpx.arrangements — energy.grid-coordination/clj-urpx 0.29.0

Enumerate the service arrangements a set of URPX documents expresses.

A SERVICE ARRANGEMENT is one urpx:RatePlanVersion, plus every urpx:RatePlanModifierVersion compatible with it, plus one urpx:ProfileAlternative for each dimension any of them leaves open. Fully determined: given an instant inside its window it resolves to prices with no further input. If a choice is still outstanding it is not one arrangement but several, and each of those is an arrangement in its own right.

urpx:ServiceArrangement IS NOT A URPX CLASS. It occurs zero times in the ontology and zero times in the SHACL shapes. It is a name for a thing the standard describes the parts of and does not name the whole of, and nothing here writes it into a document or claims a urpx: prefix for it. The concept and its evidence are set out in urpx-rate-plans doc/service-arrangements.md; the cardinalities this namespace relies on were checked against the shapes graph rather than recalled.

WHAT THIS CAN AND CANNOT ENUMERATE. Which compatible modifiers a given CUSTOMER has is a fact about the customer, and URPX places customer data outside its scope: urpx:AccountServiceAgreement carries the skos:note "Service account and agreement data lives in customer data, not URPX." So this enumerates the arrangements the DOCUMENTS EXPRESS, every combination the filings say is permitted. That set is larger than any one customer's and is what a price server can publish.

OPTIONAL BY CONSTRUCTION. This namespace requires urpx.price; urpx.price does not require this. A consumer that wants prices for a composition it already knows how to assemble uses urpx.price directly and never loads this file. Nothing here changes an existing arity or return shape.

applicable-modifiers clj

(applicable-modifiers documents base-version)

(applicable-modifiers documents base-version opts)

The urpx:RatePlanModifierVersions in documents that MAY apply to base-version.

This is the query a consumer actually wants, and it is the half URPX can answer. urpx:applicableToRatePlan states compatibility with a plan identity; urpx:applicableToRatePlanVersion states it against a specific version. Where a modifier names any versions, those are taken to be exhaustive, because the version-level statement is the more specific.

WHICH READING applies is a caller policy, :compatibility, defaulting to named-versions-narrow. URPX does not settle whether naming a version narrows the plan-level statement or adds to it, so this library does not settle it either; see the policies for the evidence on each side.

Counts below are AS MEASURED AT ONE CORPUS REVISION, urpx-rate-plans 9deae4dbaa8b, because a bare "37 of 37" is a claim with no stated conditions and this one had already drifted twice before it was pinned: 40 distinct modifier version nodes, applicableToRatePlan on 40 of 40 naming 3.40 plans on average, applicableToRatePlanVersion on 7 of 40.

WHAT THIS DOES NOT ANSWER, deliberately. Which of these a given customer HAS is a fact about the customer, and URPX places customer data outside its scope: urpx:AccountServiceAgreement carries the skos:note "Service account and agreement data lives in customer data, not URPX." Nor does URPX say which modifiers may be held TOGETHER: there is no property anywhere in the ontology expressing exclusivity or combinability between modifiers, and urpx:modifierCategory and urpx:modifierType, which might have served as a signal, are unset on all 40. So CARE and FERA are both returned for SCE Schedule D and nothing in the documents says a customer has at most one. Choosing among them is the caller's, which is why arrangements takes a combining policy rather than inventing one.

Options: :at a ZonedDateTime. Restricts to modifier versions current then. :compatibility fn [modifier-version base-version plan-id] -> boolean. Defaults to named-versions-narrow; named-versions-add is the monotone alternative.

arrangement-id clj

(arrangement-id arrangement)

The intrinsic identity of arrangement:

[base-version-iri [modifier-version-iris sorted] [[container alternative] sorted]]

Computable from the documents alone, stable across regeneration, external nothing. Two arrangements are the same when this matches and different otherwise, INCLUDING when they resolve to the same price: a bundled customer and one buying generation elsewhere may pay the same delivery rate and are on different arrangements.

arrangements clj

(arrangements documents)

(arrangements documents opts)

Every service arrangement documents expresses, as a vector.

documents is a seq of coerced urpx:RatePlan and urpx:RatePlanModifier documents, the same values urpx.price takes.

Options: :at a ZonedDateTime. Restricts to arrangements whose every component is CURRENT at that instant: the latest version of each identity to have taken effect and not expired. Omit to enumerate the whole expressed space across every version, a different and larger question. :combine fn from the compatible modifier versions of one base version to a seq of the modifier SETS a customer might hold. Defaults to one-modifier-at-most. :compatibility fn [modifier-version base-version plan-id] -> boolean deciding which modifiers MAY apply. Defaults to named-versions-narrow; named-versions-add is the monotone alternative. TWO POLICIES, not one, because URPX does not say whether naming a urpx:applicableToRatePlanVersion narrows urpx:applicableToRatePlan or adds to it. They are indistinguishable on the corpus this namespace can enumerate today; see the policies for where that stops being true.

THE COMBINING POLICY IS THE CALLER'S BECAUSE URPX CANNOT STATE IT. Nothing in the ontology expresses exclusivity or combinability between modifiers, and urpx:modifierCategory and urpx:modifierType, the only properties that might have served, are unset on all 40 modifier version nodes at urpx-rate-plans 9deae4dbaa8b. So CARE and FERA are both compatible with SCE Schedule D and no document says a customer has at most one. The default is conservative and knowingly incomplete; every-subset is complete and knowingly wrong; a caller holding its own program rules should pass those instead. Use applicable-modifiers to see what it is choosing among.

Each arrangement is a map: :urpx.arrangement/rate-plan the coerced base document :urpx.arrangement/version the base version snapshot :urpx.arrangement/version-id its @id :urpx.arrangement/plan-id the plan identity @id :urpx.arrangement/modifiers coerced modifier documents, in order :urpx.arrangement/modifier-versions their snapshots :urpx.arrangement/modifier-version-ids their @ids :urpx.arrangement/selections {container-@id alternative-@id}

Deterministic: sorted by arrangement-id, so regenerating the same documents gives the same order. Nothing here consults wall-clock time.

every-subset clj

(every-subset modifier-versions)

A combining policy yielding every subset, including the empty one.

Complete and unfiltered: it will pair mutually exclusive programs, since nothing in the documents marks them exclusive. 2^n per base version, so use it on a narrowed modifier list rather than a whole corpus.

named-versions-add clj

(named-versions-add mv bv plan-id)

The monotone policy: a version statement ADDS to urpx:applicableToRatePlan and never removes from it.

Sound under RDF, which is what URPX documents denote: merging graphs adds triples and never retracts, so a larger corpus can only ever yield more compatibility. It also stops the plan-level statement being cancelled by triples that never mention the plan it names.

KNOWN COST. It leaves urpx:applicableToRatePlanVersion with almost nothing to do: it can only widen, and only to a version whose plan is not already named. A publisher wanting to say "this modifier applies only to version X of plan P" has no way to say it under this reading.

named-versions-narrow clj

(named-versions-narrow mv bv plan-id)

The default policy: naming any urpx:applicableToRatePlanVersion means those versions and no others, overriding urpx:applicableToRatePlan.

Reads with the ontology's own wording, "Defines which SPECIFIC rate plan versions are compatible with this modifier version", and it is the only reading under which the property can express a restriction at all: under named-versions-add a version statement can only widen, and then only to a version whose plan is not already named, which no modifier in the production corpus does.

KNOWN COST, stated because it is not small. The rule is NON-MONOTONIC. Merging a document that adds a version statement REMOVES compatibility with a plan named only by urpx:applicableToRatePlan, and RDF merge never retracts. A partial view of a corpus can therefore yield MORE arrangements than the whole of it. It is the default because it is what the corpus and the peer reference implementation both assume today, not because it is known right.

offered-by clj

(offered-by versions)

Group version snapshots by the urpx:Organization @id that offers them, for a broader search than one plan at a time.

urpx:offeredBy is populated on all 40 modifier version nodes at urpx-rate-plans 9deae4dbaa8b.

This used to add that urpx:applicableToRateGroup and urpx:hasServiceClass "would also serve this purpose and are unset on all 37", which was wrong in kind rather than in degree: both appear ZERO times in RatePlanModifierVersionShape, so they cannot be set on a modifier version at all and there was never anything to be unset. Asserting a mechanism that is not in the ontology.

one-modifier-at-most clj

(one-modifier-at-most modifier-versions)

The default combining policy: the empty set, and each modifier on its own.

Conservative because URPX cannot state which modifiers combine. Every arrangement it yields is one the documents support, and it is knowingly INCOMPLETE: real multi-overlay arrangements exist, and California publishes identifiers for some of them, so a caller that knows its own program rules should pass its own policy rather than accept this one.

plan-versions clj

(plan-versions documents)

(plan-versions documents opts)

Every urpx:RatePlanVersion in documents, as a vector of snapshots.

:at restricts to the version of each plan identity in force at that instant. Omit it for every version the documents carry.

resolve-at clj

(resolve-at arrangement zdt)

(resolve-at arrangement zdt opts)

Resolve arrangement at zdt, returning what urpx.price/resolve-prices-with-modifiers returns.

A convenience over urpx.price, not a replacement: it binds each document to its own version and hands the arrangement's selections through as :profile-alternatives, so the opts cannot reach a document they do not belong to. Both :version defects fixed in 0.28.0 were an opt and a document failing to line up: one applied the base plan's snapshot to every modifier, the other re-derived the snapshot on the holiday path and ignored the opt entirely. An arrangement makes both unrepresentable rather than repeatedly fixable.

The binding does more than choose. Handed a document carrying several version snapshots, urpx.price refuses outright rather than picking one, so this is what makes such a document resolvable at all.

Extra opts merge over the arrangement's own, except :version and :profile-alternatives, which are refused. See bound-opts.

schedule-for clj

(schedule-for arrangement start end)

(schedule-for arrangement start end zone)

(schedule-for arrangement start end zone opts)

A stepped price schedule for arrangement across [start, end), as urpx.schedule/price-schedule-with-modifiers returns them.

Walks a grid, default hourly, merging adjacent steps whose resolution is equal. Use it when a caller genuinely wants a fixed cadence; use segments-for when they want the truth about where prices change, which for a price server is almost always the question.

Same zone and opts handling as segments-for.

segments-for clj

(segments-for arrangement start end)

(segments-for arrangement start end zone)

(segments-for arrangement start end zone opts)

Exact price segments for arrangement across [start, end), as urpx.schedule/price-segments returns them.

PREFER THIS over schedule-for for publishing. Boundaries are derived from the documents rather than discovered by sampling, so a segment ends where the tariff actually changes and not where a step grid happened to land. For a consumer handing intervals to an optimizer that is the difference between a schedule that is right and one that is right only because every bracket in that plan sits on an hour.

A resolution that throws inside the window becomes a segment carrying :urpx.interval/refused rather than aborting the horizon, and equal refusals merge, so a stretch the arrangement does not cover is one segment and not one per candidate instant. That is what lets a publisher emit the part of a window it can price and say plainly what it cannot.

zone may be nil when the plan declares urpx:timezoneIdentifier. Extra opts are as resolve-at: merged, except the two the arrangement determines, which are refused.