Package org.kigalisim.engine.state

Interface StreamParameterization

All Known Implementing Classes:
FrozenStreamParameterization, MutableStreamParameterization
public interface StreamParameterization
Interface for managing stream-specific parameters and settings.

Implemented by MutableStreamParameterization for live, mutable substance parameterization during a simulation and by FrozenStreamParameterization for immutable snapshots captured for prior-year lookups.

  • Method Details

    • isInitialChargeStreamAllowed

      static boolean isInitialChargeStreamAllowed(String name)
      Determine whether a stream name is a sales-related substream on which initial charge may be set.

      Shared between MutableStreamParameterization and FrozenStreamParameterization so the set of valid substream names cannot drift between the two implementations.

      Parameters:
      name - The stream name to check
      Returns:
      True if the stream is a sales substream on which initial charge is allowed, false otherwise

    • setGhgIntensity

      void setGhgIntensity(EngineNumber newValue)
      Set the greenhouse gas intensity.
      Parameters:
      newValue - The new GHG intensity value

    • getGhgIntensity

      EngineNumber getGhgIntensity()
      Get the greenhouse gas intensity.
      Returns:
      The current GHG intensity value

    • setEnergyIntensity

      void setEnergyIntensity(EngineNumber newValue)
      Set the energy intensity.
      Parameters:
      newValue - The new energy intensity value

    • getEnergyIntensity

      EngineNumber getEnergyIntensity()
      Get the energy intensity.
      Returns:
      The current energy intensity value

    • setInitialCharge

      void setInitialCharge(String stream, EngineNumber newValue)
      Set the initial charge for a stream.
      Parameters:
      stream - The stream identifier ('domestic' or 'import')
      newValue - The new initial charge value
      Throws:
      IllegalArgumentException - If the stream is not a sales substream

    • getInitialCharge

      EngineNumber getInitialCharge(String stream)
      Get the initial charge for a stream.
      Parameters:
      stream - The stream identifier ('domestic' or 'import')
      Returns:
      The initial charge value for the stream
      Throws:
      IllegalArgumentException - If the stream is not a sales substream

    • setRechargePopulation

      void setRechargePopulation(EngineNumber newValue)
      Set the recharge population percentage.
      Parameters:
      newValue - The new recharge population value

    • getRechargePopulation

      EngineNumber getRechargePopulation()
      Get the recharge population percentage.
      Returns:
      The current recharge population value

    • setRechargeIntensity

      void setRechargeIntensity(EngineNumber newValue)
      Set the recharge intensity.
      Parameters:
      newValue - The new recharge intensity value

    • getRechargeIntensity

      EngineNumber getRechargeIntensity()
      Get the recharge intensity.
      Returns:
      The current recharge intensity value

    • setPrechargePopulation

      void setPrechargePopulation(EngineNumber newValue)
      Set the precharge population percentage.
      Parameters:
      newValue - The new precharge population value

    • getPrechargePopulation

      EngineNumber getPrechargePopulation()
      Get the precharge population percentage.
      Returns:
      The current precharge population value

    • setPrechargeIntensity

      void setPrechargeIntensity(EngineNumber newValue)
      Set the precharge intensity.
      Parameters:
      newValue - The new precharge intensity value

    • getPrechargeIntensity

      EngineNumber getPrechargeIntensity()
      Get the precharge intensity.
      Returns:
      The current precharge intensity value

    • setRecoveryRate

      void setRecoveryRate(EngineNumber newValue)
      Set the recovery rate percentage.
      Parameters:
      newValue - The new recovery rate value

    • setRecoveryRate

      void setRecoveryRate(EngineNumber newValue, RecoverOperation.RecoveryStage stage)
      Set the recovery rate percentage for a specific stage.
      Parameters:
      newValue - The new recovery rate value
      stage - The recovery stage (EOL or RECHARGE)

    • getRecoveryRate

      EngineNumber getRecoveryRate()
      Get the recovery rate percentage.
      Returns:
      The current recovery rate value

    • getRecoveryRate

      EngineNumber getRecoveryRate(RecoverOperation.RecoveryStage stage)
      Get the recovery rate percentage for a specific stage.
      Parameters:
      stage - The recovery stage (EOL or RECHARGE)
      Returns:
      The current recovery rate value

    • setYieldRate

      void setYieldRate(EngineNumber newValue)
      Set the yield rate percentage for recycling.
      Parameters:
      newValue - The new yield rate value

    • setYieldRate

      void setYieldRate(EngineNumber newValue, RecoverOperation.RecoveryStage stage)
      Set the yield rate percentage for recycling for a specific stage.
      Parameters:
      newValue - The new yield rate value
      stage - The recovery stage (EOL or RECHARGE)

    • getYieldRate

      EngineNumber getYieldRate()
      Get the yield rate percentage for recycling.
      Returns:
      The current yield rate value

    • getYieldRate

      EngineNumber getYieldRate(RecoverOperation.RecoveryStage stage)
      Get the yield rate percentage for recycling for a specific stage.
      Parameters:
      stage - The recovery stage (EOL or RECHARGE)
      Returns:
      The current yield rate value

    • setInductionRate

      void setInductionRate(EngineNumber newValue)
      Set the induction rate percentage for recycling.
      Parameters:
      newValue - The new induction rate value

    • setInductionRate

      void setInductionRate(EngineNumber newValue, RecoverOperation.RecoveryStage stage)
      Set the induction rate percentage for recycling for a specific stage.
      Parameters:
      newValue - The new induction rate value
      stage - The recovery stage (EOL or RECHARGE)

    • getInductionRate

      EngineNumber getInductionRate()
      Get the induction rate percentage for recycling.
      Returns:
      The current induction rate value

    • getInductionRate

      EngineNumber getInductionRate(RecoverOperation.RecoveryStage stage)
      Get the induction rate percentage for recycling for a specific stage.
      Parameters:
      stage - The recovery stage (EOL or RECHARGE)
      Returns:
      The current induction rate value

    • setRetirementRate

      void setRetirementRate(EngineNumber newValue)
      Set the retirement rate percentage.

      On a live (mutable) parameterization, this accumulates retirement rates across multiple retire commands in the same year to support cumulative retirement behavior. If the resulting retirement rate is negative, it is clamped to zero (no retirement).

      Parameters:
      newValue - The new retirement rate value to add

    • getRetirementRate

      EngineNumber getRetirementRate()
      Get the retirement rate percentage.
      Returns:
      The current retirement rate value

    • getRetirementBasePopulation

      Optional<EngineNumber> getRetirementBasePopulation()
      Get the retirement base population for cumulative calculations.
      Returns:
      The base population, or empty if not yet captured this step

    • setRetirementBasePopulation

      void setRetirementBasePopulation(EngineNumber value)
      Set the retirement base population for cumulative calculations.
      Parameters:
      value - The base population value

    • getAppliedRetirementAmount

      Optional<EngineNumber> getAppliedRetirementAmount()
      Get the applied retirement amount for cumulative calculations.
      Returns:
      The total amount already retired this step

    • setAppliedRetirementAmount

      void setAppliedRetirementAmount(EngineNumber value)
      Set the applied retirement amount for cumulative calculations.
      Parameters:
      value - The total amount retired this step

    • getHasReplacementThisStep

      boolean getHasReplacementThisStep()
      Get the replacement mode for this step's retire commands.
      Returns:
      true if with replacement, false if without replacement

    • setHasReplacementThisStep

      void setHasReplacementThisStep(boolean value)
      Set the replacement mode for this step's retire commands.
      Parameters:
      value - true for with replacement, false for without replacement

    • getRetireCalculatedThisStep

      boolean getRetireCalculatedThisStep()
      Get whether retire has been calculated this step.
      Returns:
      true if retire was calculated, false otherwise

    • setRetireCalculatedThisStep

      void setRetireCalculatedThisStep(boolean calculated)
      Set whether retire has been calculated this step.
      Parameters:
      calculated - true if retire was calculated, false otherwise

    • getRechargeBasePopulation

      Optional<EngineNumber> getRechargeBasePopulation()
      Get the recharge base population for cumulative calculations.
      Returns:
      The base population, or empty if not yet captured this step

    • setRechargeBasePopulation

      void setRechargeBasePopulation(EngineNumber value)
      Set the recharge base population for cumulative calculations.
      Parameters:
      value - The base population value

    • getAppliedRechargeAmount

      Optional<EngineNumber> getAppliedRechargeAmount()
      Get the applied recharge amount for cumulative calculations.
      Returns:
      The total amount already recharged this step in kg

    • setAppliedRechargeAmount

      void setAppliedRechargeAmount(EngineNumber value)
      Set the applied recharge amount for cumulative calculations.
      Parameters:
      value - The total amount recharged this step in kg

    • getPrechargeBasePopulation

      Optional<EngineNumber> getPrechargeBasePopulation()
      Get the precharge base population for cumulative calculations.
      Returns:
      The base population, or empty if not yet captured this year

    • setPrechargeBasePopulation

      void setPrechargeBasePopulation(EngineNumber value)
      Set the precharge base population for cumulative calculations.
      Parameters:
      value - The base population value

    • getAppliedPrechargeAmount

      Optional<EngineNumber> getAppliedPrechargeAmount()
      Get the applied precharge amount for cumulative calculations.
      Returns:
      The total amount already precharged this step in kg

    • setAppliedPrechargeAmount

      void setAppliedPrechargeAmount(EngineNumber value)
      Set the applied precharge amount for cumulative calculations.
      Parameters:
      value - The total amount precharged this step in kg

    • isRecyclingCalculatedThisStep

      boolean isRecyclingCalculatedThisStep()
      Get whether recycling has been calculated this step.
      Returns:
      true if recycling was calculated, false otherwise

    • setRecyclingCalculatedThisStep

      void setRecyclingCalculatedThisStep(boolean calculated)
      Set whether recycling has been calculated this step.
      Parameters:
      calculated - true if recycling was calculated, false otherwise

    • accumulateRecharge

      void accumulateRecharge(EngineNumber population, EngineNumber intensity)
      Accumulate recharge parameters. Sets when not previously set, accumulates otherwise.

      Multiple calls accumulate rates (addition) and intensities (weighted-average). Population rates are added, intensities are weighted-averaged using absolute values for weights to handle negative adjustments correctly.

      Weighted average formula: (|rate1| × intensity1 + |rate2| × intensity2) / (|rate1| + |rate2|)

      Parameters:
      population - The recharge population rate to add
      intensity - The recharge intensity for this rate

    • accumulatePrecharge

      void accumulatePrecharge(EngineNumber population, EngineNumber intensity)
      Accumulate precharge parameters. Sets when not previously set, accumulates otherwise.

      Multiple calls accumulate rates (addition) and intensities (weighted-average). Population rates are added, intensities are weighted-averaged using absolute values for weights to handle negative adjustments correctly.

      Weighted average formula: (|rate1| × intensity1 + |rate2| × intensity2) / (|rate1| + |rate2|)

      Parameters:
      population - The precharge population rate to add
      intensity - The precharge intensity for this rate

    • setLastSpecifiedValue

      void setLastSpecifiedValue(String streamName, EngineNumber value)
      Set the last specified value for a stream.

      This tracks the value and units last used when setting streams to preserve user intent across carry-over years. Percentage-unit values are ignored so they do not impact last recorded values.

      Parameters:
      streamName - The name of the stream
      value - The last specified value with units

    • getLastSpecifiedValue

      EngineNumber getLastSpecifiedValue(String streamName)
      Get the last specified value for a stream.
      Parameters:
      streamName - The name of the stream
      Returns:
      The last specified value with units, or null if not set

    • hasLastSpecifiedValue

      boolean hasLastSpecifiedValue(String streamName)
      Check if a stream has a last specified value.
      Parameters:
      streamName - The name of the stream
      Returns:
      true if the stream has a last specified value, false otherwise

    • markStreamAsEnabled

      void markStreamAsEnabled(String streamName)
      Mark a stream as having been enabled (set to non-zero value).
      Parameters:
      streamName - The name of the stream to mark as enabled

    • hasStreamBeenEnabled

      boolean hasStreamBeenEnabled(String streamName)
      Check if a stream has ever been enabled (set to non-zero value).
      Parameters:
      streamName - The name of the stream to check
      Returns:
      true if the stream has been enabled, false otherwise

    • isSalesIntentFreshlySet

      boolean isSalesIntentFreshlySet()
      Check if sales intent has been freshly set in the current processing cycle.
      Returns:
      true if sales intent was freshly set, false otherwise

    • setSalesIntentFreshlySet

      void setSalesIntentFreshlySet(boolean freshlySet)
      Set the flag indicating whether sales intent has been freshly set.
      Parameters:
      freshlySet - true if sales intent was freshly set, false otherwise

    • resetStateAtTimestep

      void resetStateAtTimestep()
      Reset state at the beginning of a timestep.

      This resets recovery rate to 0% and induction rate to 100% between steps since recycling programs may cease and should not be expected to continue unchanged, but default induction behavior should return to induced demand (100%).

    • clearLastSpecifiedValue

      void clearLastSpecifiedValue(String stream)
      Clear the last specified value in this parameterization.

      The last specified value tracks the user specified target for a stream such that commands changing those values respect user directives like maintaining units-based tracking with implicit recharge. This method clears that directive so that, for example, a set command can override a prior given value. This, for example, allows the user to switch from units-based to volume-based tracking.

      This will clear the stream and those dependent upon it. Therefore, clearing sales will also clear substreams domestic and import. Similarly, clearing domestic will clear sales but not import.

      Parameters:
      stream - The name of the stream like "sales" or "import" in which to clear.

    • freeze

      StreamParameterization freeze()
      Get an immutable snapshot of this instance.

      The snapshot shares immutable EngineNumber-typed values by reference but copies mutable containers (maps/sets) and recursively freezes the nested prior equipment bases, so later mutation of this instance does not affect the snapshot.

      Returns:
      An immutable snapshot backed by FrozenStreamParameterization, or this same instance if it is already frozen