Package org.kigalisim.engine.state

Interface SimulationState

All Known Implementing Classes:
FrozenSimulationState, MutableSimulationState
public interface SimulationState
Interface for the state for a single scenario within a single trial.

Implemented by MutableSimulationState for live, mutable simulation state and by FrozenSimulationState for immutable snapshots captured for prior-year lookups (see getAtPrior(int)).

  • Field Details

    • ZERO_VOLUME

      static final EngineNumber ZERO_VOLUME
      The zero value used to initialize volume-denominated streams (kg).

  • Method Details

    • getRegisteredSubstances

      List<SubstanceInApplicationId> getRegisteredSubstances()
      Get all registered substance-application pairs.
      Returns:
      Array of substance identifiers

    • hasSubstance

      boolean hasSubstance(UseKey useKey)
      Check if a substance exists for a key.
      Parameters:
      useKey - The key containing application and substance
      Returns:
      true if the substance exists for the key

    • ensureSubstance

      void ensureSubstance(UseKey useKey)
      Ensure a substance exists for a key, creating it if needed.
      Parameters:
      useKey - The key containing application and substance

    • update

      void update(SimulationStateUpdate stateUpdate)
      Set a stream using pre-computed stream data.

      This method replaces setStream, setOutcomeStream, and setSalesStream with a unified interface that accepts pre-computed stream values. The SimulationStateUpdate object encapsulates all necessary parameters including distribution logic and recycling behavior.

      This method provides clear architectural separation between calculation instructions (StreamUpdate) and pre-computed results (SimulationStateUpdate).

      Parameters:
      stateUpdate - Pre-computed stream data with all parameters

    • getStream

      EngineNumber getStream(UseKey useKey, String name)
      Get the value of a specific stream using key. Uses current year.
      Parameters:
      useKey - The key containing application and substance
      name - The stream name
      Returns:
      The stream value

    • getStream

      EngineNumber getStream(UseKey useKey, String name, boolean priorYear)
      Get the value of a specific stream using key from this or prior year.
      Parameters:
      useKey - The key containing application and substance
      name - The stream name
      priorYear - If true, returns prior year value if available, returns current year if no prior year exists.
      Returns:
      The stream value

    • isKnownStream

      boolean isKnownStream(UseKey useKey, String name)
      Check if a stream exists for a key.
      Parameters:
      useKey - The key containing application and substance
      name - The stream name
      Returns:
      true if the stream exists

    • getInductionStream

      EngineNumber getInductionStream(UseKey useKey, RecoverOperation.RecoveryStage stage)
      Get the induction stream value for a specific recovery stage. Uses current year.
      Parameters:
      useKey - The key containing application and substance
      stage - The recovery stage (EOL or RECHARGE)
      Returns:
      The induction stream value in kg

    • getInductionStream

      EngineNumber getInductionStream(UseKey useKey, RecoverOperation.RecoveryStage stage, boolean priorYear)
      Get the induction stream value for a specific recovery stage.
      Parameters:
      useKey - The key containing application and substance
      stage - The recovery stage (EOL or RECHARGE)
      priorYear - If true, returns prior year value if available, returns current year if no prior year exists.
      Returns:
      The induction stream value in kg

    • getTotalInductionStream

      EngineNumber getTotalInductionStream(UseKey useKey)
      Get total induction across all stages. Uses current year.
      Parameters:
      useKey - The key containing application and substance
      Returns:
      Total induction in kg

    • getTotalInductionStream

      EngineNumber getTotalInductionStream(UseKey useKey, boolean priorYear)
      Get total induction across all stages.
      Parameters:
      useKey - The key containing application and substance
      priorYear - If true, returns prior year value if available, returns current year if no prior year exists.
      Returns:
      Total induction in kg

    • getDistribution

      SalesStreamDistribution getDistribution(UseKey useKey)
      Get a sales stream distribution for the given substance/application.

      This method centralizes the logic for creating sales distributions by getting the current domestic and import values, determining their enabled status, and building an appropriate distribution using the builder pattern. Exports are excluded for backward compatibility.

      Parameters:
      useKey - The key containing application and substance
      Returns:
      A SalesStreamDistribution with appropriate percentages

    • getDistribution

      SalesStreamDistribution getDistribution(UseKey useKey, boolean includeExports)
      Get a sales stream distribution for the given substance/application.

      This method centralizes the logic for creating sales distributions by getting the current domestic, import, and optionally export values, determining their enabled status, and building an appropriate distribution using the builder pattern.

      Parameters:
      useKey - The key containing application and substance
      includeExports - Whether to include exports in the distribution calculation
      Returns:
      A SalesStreamDistribution with appropriate percentages

    • hasStreamsEnabled

      boolean hasStreamsEnabled(UseKey useKey)
      Check if any sales streams have been enabled for the given substance/application.
      Parameters:
      useKey - The key containing application and substance
      Returns:
      True if any of domestic, import, or export streams are enabled

    • getCurrentYear

      int getCurrentYear()
      Get the current year for this simulation state.
      Returns:
      The current year

    • setCurrentYear

      void setCurrentYear(int year)
      Set the current year for this simulation state.
      Parameters:
      year - The current year

    • getAtPrior

      Optional<SimulationState> getAtPrior(int years)
      Get the simulation state from N years ago.

      Returns Optional.empty() if years is negative. Returns Optional.of(this) if years is 0. Otherwise traverses the linked list of prior states: getAtPrior(1) returns the state from the previous year, getAtPrior(2) returns the state from two years ago, and so on. If the linked list is exhausted before reaching the requested year, returns Optional.empty().

      Parameters:
      years - The number of years to look back
      Returns:
      Optional.of(this) if years is 0, Optional.of(priorState) if years is 1, traversing the linked list for larger values, or Optional.empty() if not available

    • incrementYear

      void incrementYear()
      Increment the year, updating populations and resetting internal params.

      Freezes the current state before modifications to build the linked list of prior states, enabling lookback N years via getAtPrior().

    • setGhgIntensity

      void setGhgIntensity(UseKey useKey, EngineNumber newValue)
      Set the greenhouse gas intensity for a key.
      Parameters:
      useKey - The key containing application and substance
      newValue - The new GHG intensity value

    • setEnergyIntensity

      void setEnergyIntensity(UseKey useKey, EngineNumber newValue)
      Set the energy intensity for a key.
      Parameters:
      useKey - The key containing application and substance
      newValue - The new energy intensity value

    • getGhgIntensity

      EngineNumber getGhgIntensity(UseKey useKey)
      Get the greenhouse gas intensity for a key.
      Parameters:
      useKey - The key containing application and substance
      Returns:
      The GHG intensity value

    • getEnergyIntensity

      EngineNumber getEnergyIntensity(UseKey useKey)
      Get the energy intensity for a key.
      Parameters:
      useKey - The key containing application and substance
      Returns:
      The energy intensity value

    • setInitialCharge

      void setInitialCharge(UseKey useKey, String substream, EngineNumber newValue)
      Set the initial charge for a key's stream.
      Parameters:
      useKey - The key containing application and substance
      substream - The stream identifier ('domestic' or 'import')
      newValue - The new initial charge value

    • getInitialCharge

      EngineNumber getInitialCharge(UseKey useKey, String substream)
      Get the initial charge for a key.
      Parameters:
      useKey - The key containing application and substance
      substream - The substream name
      Returns:
      The initial charge value

    • setRechargePopulation

      void setRechargePopulation(UseKey useKey, EngineNumber newValue)
      Set the recharge population percentage for a key.
      Parameters:
      useKey - The key containing application and substance
      newValue - The new recharge population value

    • getRechargePopulation

      EngineNumber getRechargePopulation(UseKey useKey)
      Get the recharge population percentage for a key.
      Parameters:
      useKey - The key containing application and substance
      Returns:
      The current recharge population value

    • setRechargeIntensity

      void setRechargeIntensity(UseKey useKey, EngineNumber newValue)
      Set the recharge intensity for a key.
      Parameters:
      useKey - The key containing application and substance
      newValue - The new recharge intensity value

    • getRechargeIntensity

      EngineNumber getRechargeIntensity(UseKey useKey)
      Get the recharge intensity for a key.
      Parameters:
      useKey - The key containing application and substance
      Returns:
      The current recharge intensity value

    • accumulateRecharge

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

      Multiple calls accumulate rates (addition) and intensities (weighted-average). Rates add linearly and intensities use weighted-average with absolute value weights to handle negative adjustments correctly.

      Parameters:
      useKey - The key containing application and substance
      population - The recharge population rate to add
      intensity - The recharge intensity for this rate

    • getRechargeBasePopulation

      Optional<EngineNumber> getRechargeBasePopulation(UseKey useKey)
      Get the recharge base population for cumulative calculations.
      Parameters:
      useKey - The key containing application and substance
      Returns:
      The base population, or null if not yet captured this year

    • setRechargeBasePopulation

      void setRechargeBasePopulation(UseKey useKey, EngineNumber value)
      Set the recharge base population for cumulative calculations.
      Parameters:
      useKey - The key containing application and substance
      value - The base population value

    • getAppliedRechargeAmount

      Optional<EngineNumber> getAppliedRechargeAmount(UseKey useKey)
      Get the applied recharge amount for cumulative calculations.
      Parameters:
      useKey - The key containing application and substance
      Returns:
      The total amount already recharged this year in kg

    • setAppliedRechargeAmount

      void setAppliedRechargeAmount(UseKey useKey, EngineNumber value)
      Set the applied recharge amount for cumulative calculations.
      Parameters:
      useKey - The key containing application and substance
      value - The total amount recharged this year in kg

    • setPrechargePopulation

      void setPrechargePopulation(UseKey useKey, EngineNumber newValue)
      Set the precharge population percentage for a key.
      Parameters:
      useKey - The key containing application and substance
      newValue - The new precharge population value

    • getPrechargePopulation

      EngineNumber getPrechargePopulation(UseKey useKey)
      Get the precharge population percentage for a key.
      Parameters:
      useKey - The key containing application and substance
      Returns:
      The current precharge population value

    • setPrechargeIntensity

      void setPrechargeIntensity(UseKey useKey, EngineNumber newValue)
      Set the precharge intensity for a key.
      Parameters:
      useKey - The key containing application and substance
      newValue - The new precharge intensity value

    • getPrechargeIntensity

      EngineNumber getPrechargeIntensity(UseKey useKey)
      Get the precharge intensity for a key.
      Parameters:
      useKey - The key containing application and substance
      Returns:
      The current precharge intensity value

    • accumulatePrecharge

      void accumulatePrecharge(UseKey useKey, EngineNumber population, EngineNumber intensity)
      Accumulate precharge parameters. Sets when not previously set, accumulates otherwise.
      Parameters:
      useKey - The key containing application and substance
      population - The precharge population rate to add
      intensity - The precharge intensity for this rate

    • getPrechargeBasePopulation

      Optional<EngineNumber> getPrechargeBasePopulation(UseKey useKey)
      Get the precharge base population for cumulative calculations.
      Parameters:
      useKey - The key containing application and substance
      Returns:
      The base population, or null if not yet captured this year

    • setPrechargeBasePopulation

      void setPrechargeBasePopulation(UseKey useKey, EngineNumber value)
      Set the precharge base population for cumulative calculations.
      Parameters:
      useKey - The key containing application and substance
      value - The base population value

    • getAppliedPrechargeAmount

      Optional<EngineNumber> getAppliedPrechargeAmount(UseKey useKey)
      Get the applied precharge amount for cumulative calculations.
      Parameters:
      useKey - The key containing application and substance
      Returns:
      The total amount already precharged this year in kg

    • setAppliedPrechargeAmount

      void setAppliedPrechargeAmount(UseKey useKey, EngineNumber value)
      Set the applied precharge amount for cumulative calculations.
      Parameters:
      useKey - The key containing application and substance
      value - The total amount precharged this year in kg

    • isRecyclingCalculatedThisStep

      boolean isRecyclingCalculatedThisStep(UseKey useKey)
      Get whether recycling has been calculated this step.
      Parameters:
      useKey - The key containing application and substance
      Returns:
      true if recycling was calculated, false otherwise

    • setRecyclingCalculatedThisStep

      void setRecyclingCalculatedThisStep(UseKey useKey, boolean calculated)
      Set whether recycling has been calculated this step.
      Parameters:
      useKey - The key containing application and substance
      calculated - true if recycling was calculated, false otherwise

    • setRecoveryRate

      void setRecoveryRate(UseKey useKey, EngineNumber newValue)
      Set the recovery rate percentage for a key.
      If a recovery rate is already set, this method implements additive recycling:
      • Recovery rates are added together.
      • Both rates are converted to percentage units before addition.
      • The combined rate is stored as a percentage.
      Parameters:
      useKey - The key containing application and substance
      newValue - The new recovery rate value

    • setRecoveryRate

      void setRecoveryRate(UseKey useKey, EngineNumber newValue, RecoverOperation.RecoveryStage stage)
      Set the recovery rate percentage for a key with a specific stage.
      Implements additive behavior for multiple recovery commands on the same stage:
      • When a recovery rate is already set for this stage, the new rate is added to the existing one.
      • The first recovery rate for a timestep is set directly without addition.
      Parameters:
      useKey - The key containing application and substance
      newValue - The new recovery rate value
      stage - The recovery stage (EOL or RECHARGE)

    • getRecoveryRate

      EngineNumber getRecoveryRate(UseKey useKey)
      Get the recovery rate percentage for a key.
      Parameters:
      useKey - The key containing application and substance
      Returns:
      The current recovery rate value

    • getRecoveryRate

      EngineNumber getRecoveryRate(UseKey useKey, RecoverOperation.RecoveryStage stage)
      Get the recovery rate percentage for a key with a specific stage.
      Parameters:
      useKey - The key containing application and substance
      stage - The recovery stage (EOL or RECHARGE)
      Returns:
      The current recovery rate value

    • setYieldRate

      void setYieldRate(UseKey useKey, EngineNumber newValue)
      Set the yield rate percentage for recycling for a key.

      Convenience method that sets the yield rate for the RECHARGE recovery stage. Delegates to setYieldRate(UseKey, EngineNumber, RecoveryStage) with RecoveryStage.RECHARGE.

      Parameters:
      useKey - The key containing application and substance
      newValue - The new yield rate value
      See Also:

    • setYieldRate

      void setYieldRate(UseKey useKey, EngineNumber newValue, RecoverOperation.RecoveryStage stage)
      Set the yield rate percentage for recycling for a key with a specific stage.

      When an existing yield rate is set for this stage, combines them using a weighted average approach that uses equal weighting, which is a reasonable approximation for efficiency rates.

      Parameters:
      useKey - The key containing application and substance
      newValue - The new yield rate value
      stage - The recovery stage (EOL or RECHARGE)

    • getYieldRate

      EngineNumber getYieldRate(UseKey useKey)
      Get the yield rate percentage for recycling for a key.
      Parameters:
      useKey - The key containing application and substance
      Returns:
      The current yield rate value

    • getYieldRate

      EngineNumber getYieldRate(UseKey useKey, RecoverOperation.RecoveryStage stage)
      Get the yield rate percentage for recycling for a key with a specific stage.
      Parameters:
      useKey - The key containing application and substance
      stage - The recovery stage (EOL or RECHARGE)
      Returns:
      The current yield rate value

    • setInductionRate

      void setInductionRate(UseKey useKey, EngineNumber newValue)
      Set the induction rate percentage for recycling for a key.
      Parameters:
      useKey - The key containing application and substance
      newValue - The new induction rate value

    • setInductionRate

      void setInductionRate(UseKey useKey, EngineNumber newValue, RecoverOperation.RecoveryStage stage)
      Set the induction rate percentage for recycling for a key with a specific stage.
      Parameters:
      useKey - The key containing application and substance
      newValue - The new induction rate value
      stage - The recovery stage (EOL or RECHARGE)

    • getInductionRate

      EngineNumber getInductionRate(UseKey useKey)
      Get the induction rate percentage for recycling for a key.
      Parameters:
      useKey - The key containing application and substance
      Returns:
      The current induction rate value

    • getInductionRate

      EngineNumber getInductionRate(UseKey useKey, RecoverOperation.RecoveryStage stage)
      Get the induction rate percentage for recycling for a key with a specific stage.
      Parameters:
      useKey - The key containing application and substance
      stage - The recovery stage (EOL or RECHARGE)
      Returns:
      The current induction rate value

    • setRetirementRate

      void setRetirementRate(UseKey useKey, EngineNumber newValue)
      Set the retirement rate percentage for a key.
      Parameters:
      useKey - The key containing application and substance
      newValue - The new retirement rate value

    • getRetirementRate

      EngineNumber getRetirementRate(UseKey useKey)
      Get the retirement rate percentage for a key.
      Parameters:
      useKey - The key containing application and substance
      Returns:
      The current retirement rate value

    • getRetirementBasePopulation

      Optional<EngineNumber> getRetirementBasePopulation(UseKey useKey)
      Get the retirement base population for cumulative calculations.
      Parameters:
      useKey - The key containing application and substance
      Returns:
      The base population, or null if not yet captured

    • setRetirementBasePopulation

      void setRetirementBasePopulation(UseKey useKey, EngineNumber value)
      Set the retirement base population for cumulative calculations.
      Parameters:
      useKey - The key containing application and substance
      value - The base population value

    • getAppliedRetirementAmount

      Optional<EngineNumber> getAppliedRetirementAmount(UseKey useKey)
      Get the applied retirement amount for cumulative calculations.
      Parameters:
      useKey - The key containing application and substance
      Returns:
      The total amount already retired this year

    • setAppliedRetirementAmount

      void setAppliedRetirementAmount(UseKey useKey, EngineNumber value)
      Set the applied retirement amount for cumulative calculations.
      Parameters:
      useKey - The key containing application and substance
      value - The total amount retired this year

    • getHasReplacementThisStep

      boolean getHasReplacementThisStep(UseKey useKey)
      Get the replacement mode for retire commands this step.
      Parameters:
      useKey - The key containing application and substance
      Returns:
      null if no retire yet, true if with replacement, false if without replacement

    • setHasReplacementThisStep

      void setHasReplacementThisStep(UseKey useKey, boolean value)
      Set the replacement mode for retire commands this step.
      Parameters:
      useKey - The key containing application and substance
      value - true for with replacement, false for without replacement

    • getRetireCalculatedThisStep

      boolean getRetireCalculatedThisStep(UseKey useKey)
      Get whether retire has been calculated this step.
      Parameters:
      useKey - The key containing application and substance
      Returns:
      true if retire was calculated, false otherwise

    • setRetireCalculatedThisStep

      void setRetireCalculatedThisStep(UseKey useKey, boolean calculated)
      Set whether retire has been calculated this step.
      Parameters:
      useKey - The key containing application and substance
      calculated - true if retire was calculated, false otherwise

    • setLastSpecifiedValue

      void setLastSpecifiedValue(UseKey useKey, String streamName, EngineNumber value)
      Tracks the last specified value for sales-related streams.

      This method preserves user intent across carry-over years by storing the units and values that were explicitly specified by the user. This is essential for maintaining correct behavior when sales values carry over to subsequent years, particularly for unit-based specifications where recharge calculations need to be applied consistently.

      Parameters:
      useKey - The key containing application and substance
      streamName - The name of the stream (e.g., "sales", "domestic", "import")
      value - The value being specified with its units

    • getLastSpecifiedValue

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

    • hasLastSpecifiedValue

      boolean hasLastSpecifiedValue(UseKey useKey, String streamName)
      Check if a stream has a last specified value.
      Parameters:
      useKey - The key containing application and substance
      streamName - The name of the stream
      Returns:
      true if the stream has a last specified value, false otherwise

    • isSalesIntentFreshlySet

      boolean isSalesIntentFreshlySet(UseKey useKey)
      Check if sales intent has been freshly set for the given scope.
      Parameters:
      useKey - The key containing application and substance
      Returns:
      true if sales intent was freshly set, false otherwise

    • resetSalesIntentFlag

      void resetSalesIntentFlag(UseKey useKey)
      Reset the sales intent flag for the given scope.
      Parameters:
      useKey - The key containing application and substance

    • hasStreamBeenEnabled

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

    • markStreamAsEnabled

      void markStreamAsEnabled(UseKey useKey, String streamName)
      Mark a stream as having been enabled (set to non-zero value).
      Parameters:
      useKey - The key containing application and substance
      streamName - The name of the stream to mark as enabled

    • clearLastSpecifiedValue

      void clearLastSpecifiedValue(UseKey useKey, 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.

      Parameters:
      useKey - The substance / application pair in which to clear last specified value.
      stream - The name of the stream like "sales" or "import" in which to clear.

    • freeze

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

      Container fields (maps) are copied so the mutable original can keep mutating its own containers independently. Immutable values (EngineNumber) are shared by reference. Each substance's StreamParameterization is frozen recursively, and priorState is captured by reference (the prior chain is already frozen, so sharing is safe and O(1) per year).

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