urpx.price — energy.grid-coordination/clj-urpx 0.2.0

Resolve applicable per-energy prices for a URPX rate plan at a given instant.

Given a coerced rate plan (urpx.coerce/coerce-rate-plan) and a ZonedDateTime, resolve-prices returns the season, the matched TOU period (if any), and one entry per active per-energy ledger (commodity, distribution, public benefits, etc.). Each ledger entry carries a :tiers vector — for block-tiered ledgers (CPAU E-1) every tier's bound and unit-price is surfaced so the caller can pick the active one based on cumulative usage; for non-tiered ledgers the vector has a single entry.

Skipped:

• PriceDefinitions whose own :urpx/hasCalculationMethod is set (recurring fixed charges like a monthly customer charge — these are subscription-style and don't apply to instantaneous lookup).

Day types honored (URPX ontology): urpx:allDays, urpx:weekdayDays, urpx:weekendDays, urpx:customDays. Holiday inclusion is expressed by the TimeBracket's optional urpx:includeHolidays / urpx:includeNonHolidays booleans (both default to true when omitted). Holiday detection itself requires the caller to pass a :holiday? predicate (LocalDate -> bool); without it, every date is treated as a non-holiday.

marginal-unit-rate clj

(marginal-unit-rate resolved)

Sum the unit prices across all ledgers, picking the LOWEST tier in each block-tiered ledger as the marginal rate at the start of a billing period.

Useful for price signaling: when you don't know a customer's usage but want a single $/kWh number, this is the marginal rate at zero baseline usage.

resolve-modifier-prices clj

(resolve-modifier-prices modifier zdt)

Resolve every per-energy unit price that modifier (a coerced urpx:RatePlanModifier) contributes at zdt.

Returns the same shape as resolve-prices minus the season/TOU keys (modifier ledgers are flat add-ons): {:urpx.resolved/ledgers [...]}.

For matrix-style modifiers (e.g. CPAU E-HRA — a 4x4 matrix of reserve level x generation tier driven by external state), every applicable Price for each PriceDefinition is surfaced under :urpx.resolved/tiers. The caller is responsible for selecting the active value because the URPX condition vocabulary (operator + label conditionValue) is not yet specified in a way that's programmatically interpretable. Filter the returned :tiers vector on :urpx.resolved/price-id.

resolve-prices clj

(resolve-prices rate-plan zdt)

(resolve-prices rate-plan zdt opts)

Resolve all per-energy unit prices that apply to rate-plan at zdt (a java.time.ZonedDateTime in the rate plan's local timezone).

Optional opts map: :holiday? predicate (LocalDate -> bool) used to evaluate a bracket's urpx:includeHolidays / urpx:includeNonHolidays gates. A plain set of LocalDates works (sets are functions). When omitted, every date is treated as a non-holiday — so brackets that opt out of non-holidays (urpx:includeNonHolidays = false, e.g. holiday-only off-peak overrides) will never match.

Examples of :holiday?:

;; Static set — quickest to set up: (def us-federal-2026 #{(LocalDate/of 2026 1 1) ; New Year's Day (LocalDate/of 2026 1 19) ; Martin Luther King Jr. Day (LocalDate/of 2026 2 16) ; Presidents Day (LocalDate/of 2026 5 25) ; Memorial Day (LocalDate/of 2026 6 19) ; Juneteenth (LocalDate/of 2026 7 3) ; Independence Day (observed) (LocalDate/of 2026 9 7) ; Labor Day (LocalDate/of 2026 11 11) ; Veterans Day (LocalDate/of 2026 11 26) ; Thanksgiving (LocalDate/of 2026 12 25)}) ; Christmas (resolve-prices plan zdt {:holiday? us-federal-2026})

;; Composed predicate — if you maintain a calendar elsewhere: (resolve-prices plan zdt {:holiday? (fn [d] (calendar/observed? :us-federal d))})

Returns: {:urpx.resolved/season-name String or nil :urpx.resolved/tou-period-name String or nil :urpx.resolved/tou-period-number int or nil :urpx.resolved/ledgers [LedgerResult]}

where each LedgerResult is: {:urpx.resolved/ledger-id String :urpx.resolved/ledger-name String :urpx.resolved/ledger-type Ref :urpx.resolved/tiers [TierResult]}

and each TierResult is: {:urpx.resolved/price-definition-id String :urpx.resolved/price-id String :urpx.resolved/price-name String :urpx.resolved/unit-price BigDecimal :urpx.resolved/tier-number int (only on block-tiered ledgers) :urpx.resolved/tier-name String :urpx.resolved/tier-lower-bound BigDecimal :urpx.resolved/tier-upper-bound BigDecimal :urpx.resolved/tier-lower-bound-operator Ref :urpx.resolved/tier-upper-bound-operator Ref}

For non-tiered ledgers, :tiers has a single entry with no tier-* keys. For block-tiered ledgers (e.g. CPAU E-1), :tiers carries every tier sorted by tier-number — the caller chooses based on cumulative billing-period usage.

resolve-prices-with-modifiers clj

(resolve-prices-with-modifiers rate-plan modifiers zdt)

(resolve-prices-with-modifiers rate-plan modifiers zdt opts)

Resolve prices for rate-plan at zdt and append ledger results for each modifier in modifiers whose :urpx/applicableToRatePlan list includes the base plan's @id. Modifiers whose target lists don't include the plan are silently skipped — the caller decides whether to filter :urpx/isOptional modifiers in or out before calling.

Returns the resolve-prices shape with :urpx.resolved/ledgers extended by the modifier ledgers.