Package org.kigalisim.engine.recalc

Class StreamUpdate

java.lang.Object
org.kigalisim.engine.recalc.StreamUpdate
public final class StreamUpdate extends Object
Immutable class representing stream calculation instructions.

Contains parameters needed to execute a stream calculation operation in the engine, including timing constraints, scope, and behavioral flags. This class provides the "instructions" for how to calculate stream values, while SimulationStateUpdate contains the pre-computed "results" ready for storage.

Use StreamUpdate for operations that need calculation logic (set, change, cap, floor). Use SimulationStateUpdate for setting pre-calculated values (recalc strategies, emissions).

License:
BSD-3-Clause

  • Method Details

    • getName

      public String getName()
      Gets the name of the stream to update.
      Returns:
      the stream name (e.g., "domestic", "import", "sales")

    • getValue

      public EngineNumber getValue()
      Gets the value to set for the stream.
      Returns:
      the stream value with units

    • getYearMatcher

      public Optional<YearMatcher> getYearMatcher()
      Gets the optional year matcher constraining when this update applies.
      Returns:
      optional year matcher, empty if update applies to all years

    • getKey

      public Optional<UseKey> getKey()
      Gets the optional use key specifying the application/substance scope.
      Returns:
      optional use key, empty if using engine's current scope

    • getPropagateChanges

      public boolean getPropagateChanges()
      Gets whether this update should trigger recalculations.
      Returns:
      true if recalculations should be triggered, false otherwise

    • getUnitsToRecord

      public Optional<String> getUnitsToRecord()
      Gets the optional units string to record for this operation.
      Returns:
      optional units string for tracking purposes

    • getSubtractRecycling

      public boolean getSubtractRecycling()
      Gets whether recycling should be subtracted from the value.
      Returns:
      true if recycling should be subtracted, false otherwise

    • getForceUseFullRecharge

      public boolean getForceUseFullRecharge()
      Gets whether to force full recharge for sales substreams.
      Returns:
      true if full recharge should be used, false for proportional distribution

    • getDistribution

      public Optional<SalesStreamDistribution> getDistribution()
      Gets the optional pre-calculated distribution for sales streams.
      Returns:
      optional sales stream distribution, empty if none specified

    • getPreserveImplicitRecharge

      public boolean getPreserveImplicitRecharge()
      Gets whether the implicitRecharge/implicitPrecharge streams should be left untouched.

      Set by internal "shortcut" updates (see StreamUpdateShortcuts) that move kg volume into or out of a stream without genuinely re-specifying it in volume or unit terms (e.g. removing an amount for replace, or applying a displacement transfer). Such updates don't change any recharge/precharge parameters, so the servicing kg already recorded in implicitRecharge/implicitPrecharge remains accurate and should not be recomputed or cleared based on this update's own units.

      Returns:
      true if implicitRecharge/implicitPrecharge should be left as-is, false to update them normally based on whether this update's value carries equipment units

    • getPreserveLastSpecified

      public boolean getPreserveLastSpecified()
      Gets whether the standard lastSpecifiedValue/composite ("sales") tracking update should be skipped for this update.

      Set by internal "shortcut" updates (see StreamUpdateShortcuts #changeStreamWithoutReportingUnits) that already perform their own targeted lastSpecifiedValue restoration for the specific stream being changed. Without this flag, the standard tracking update in StreamUpdateExecutor would separately stamp lastSpecifiedValue (and the "sales" composite when a substream changes) with this update's raw kg value -- run before the shortcut's own restoration reaches the "sales" composite -- permanently flipping "sales" from unit-tracked to kg-tracked even though nothing about this update genuinely re-specified it in volume terms.

      Returns:
      true if the standard lastSpecifiedValue/composite tracking update should be skipped