Package org.kigalisim.engine.state

Class FrozenSimulationState

java.lang.Object
org.kigalisim.engine.state.FrozenSimulationState
All Implemented Interfaces:
SimulationState
public class FrozenSimulationState extends Object implements SimulationState
Immutable snapshot of SimulationState.

Holds only final fields populated at construction (each substance's StreamParameterization already frozen, and priorState captured by reference since the prior chain is already frozen) and throws UnsupportedOperationException from every mutator, so a snapshot captured for a prior-year lookup can never be silently corrupted.

  • Constructor Details

    • FrozenSimulationState

      public FrozenSimulationState(Map<String,StreamParameterization> substances, Map<String,EngineNumber> streams, Optional<SimulationState> priorState, OverridingConverterStateGetter stateGetter, UnitConverter unitConverter, int currentYear)
      Create a new immutable snapshot with the specified field values.
      Parameters:
      substances - The frozen per-substance parameterizations, keyed by application/substance
      streams - The stream values at the time of the snapshot
      priorState - The (already frozen) prior year's state, if any
      stateGetter - Structure to retrieve state information, shared with the live state
      unitConverter - Converter for handling unit transformations, shared with the live state
      currentYear - The year this snapshot was captured at

  • Method Details

    • getRegisteredSubstances

      public List<SubstanceInApplicationId> getRegisteredSubstances()
      Get all registered substance-application pairs.
      Specified by:
      getRegisteredSubstances in interface SimulationState
      Returns:
      Array of substance identifiers

    • hasSubstance

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

    • ensureSubstance

      public void ensureSubstance(UseKey useKey)
      Ensure a substance exists for a key, creating it if needed.
      Specified by:
      ensureSubstance in interface SimulationState
      Parameters:
      useKey - The key containing application and substance
      Throws:
      UnsupportedOperationException - always, since this instance is frozen

    • update

      public 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).

      Specified by:
      update in interface SimulationState
      Parameters:
      stateUpdate - Pre-computed stream data with all parameters
      Throws:
      UnsupportedOperationException - always, since this instance is frozen

    • getStream

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

    • getStream

      public EngineNumber getStream(UseKey useKey, String name, boolean priorYear)
      Get the value of a specific stream using key from this or prior year.
      Specified by:
      getStream in interface SimulationState
      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

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

    • getInductionStream

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

    • getInductionStream

      public EngineNumber getInductionStream(UseKey useKey, RecoverOperation.RecoveryStage stage, boolean priorYear)
      Get the induction stream value for a specific recovery stage.
      Specified by:
      getInductionStream in interface SimulationState
      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

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

    • getTotalInductionStream

      public EngineNumber getTotalInductionStream(UseKey useKey, boolean priorYear)
      Get total induction across all stages.
      Specified by:
      getTotalInductionStream in interface SimulationState
      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

      public 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.

      Specified by:
      getDistribution in interface SimulationState
      Parameters:
      useKey - The key containing application and substance
      Returns:
      A SalesStreamDistribution with appropriate percentages

    • getDistribution

      public 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.

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

    • hasStreamsEnabled

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

    • getCurrentYear

      public int getCurrentYear()
      Get the current year for this simulation state.
      Specified by:
      getCurrentYear in interface SimulationState
      Returns:
      The current year

    • setCurrentYear

      public void setCurrentYear(int year)
      Set the current year for this simulation state.
      Specified by:
      setCurrentYear in interface SimulationState
      Parameters:
      year - The current year
      Throws:
      UnsupportedOperationException - always, since this instance is frozen

    • getAtPrior

      public 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().

      Specified by:
      getAtPrior in interface SimulationState
      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

      public 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().

      Specified by:
      incrementYear in interface SimulationState
      Throws:
      UnsupportedOperationException - always, since this instance is frozen

    • setGhgIntensity

      public void setGhgIntensity(UseKey useKey, EngineNumber newValue)
      Set the greenhouse gas intensity for a key.
      Specified by:
      setGhgIntensity in interface SimulationState
      Parameters:
      useKey - The key containing application and substance
      newValue - The new GHG intensity value
      Throws:
      UnsupportedOperationException - always, since this instance is frozen

    • setEnergyIntensity

      public void setEnergyIntensity(UseKey useKey, EngineNumber newValue)
      Set the energy intensity for a key.
      Specified by:
      setEnergyIntensity in interface SimulationState
      Parameters:
      useKey - The key containing application and substance
      newValue - The new energy intensity value
      Throws:
      UnsupportedOperationException - always, since this instance is frozen

    • getGhgIntensity

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

    • getEnergyIntensity

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

    • setInitialCharge

      public void setInitialCharge(UseKey useKey, String substream, EngineNumber newValue)
      Set the initial charge for a key's stream.
      Specified by:
      setInitialCharge in interface SimulationState
      Parameters:
      useKey - The key containing application and substance
      substream - The stream identifier ('domestic' or 'import')
      newValue - The new initial charge value
      Throws:
      UnsupportedOperationException - always, since this instance is frozen

    • getInitialCharge

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

    • setRechargePopulation

      public void setRechargePopulation(UseKey useKey, EngineNumber newValue)
      Set the recharge population percentage for a key.
      Specified by:
      setRechargePopulation in interface SimulationState
      Parameters:
      useKey - The key containing application and substance
      newValue - The new recharge population value
      Throws:
      UnsupportedOperationException - always, since this instance is frozen

    • getRechargePopulation

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

    • setRechargeIntensity

      public void setRechargeIntensity(UseKey useKey, EngineNumber newValue)
      Set the recharge intensity for a key.
      Specified by:
      setRechargeIntensity in interface SimulationState
      Parameters:
      useKey - The key containing application and substance
      newValue - The new recharge intensity value
      Throws:
      UnsupportedOperationException - always, since this instance is frozen

    • getRechargeIntensity

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

    • accumulateRecharge

      public 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.

      Specified by:
      accumulateRecharge in interface SimulationState
      Parameters:
      useKey - The key containing application and substance
      population - The recharge population rate to add
      intensity - The recharge intensity for this rate
      Throws:
      UnsupportedOperationException - always, since this instance is frozen

    • getRechargeBasePopulation

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

    • setRechargeBasePopulation

      public void setRechargeBasePopulation(UseKey useKey, EngineNumber value)
      Set the recharge base population for cumulative calculations.
      Specified by:
      setRechargeBasePopulation in interface SimulationState
      Parameters:
      useKey - The key containing application and substance
      value - The base population value
      Throws:
      UnsupportedOperationException - always, since this instance is frozen

    • getAppliedRechargeAmount

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

    • setAppliedRechargeAmount

      public void setAppliedRechargeAmount(UseKey useKey, EngineNumber value)
      Set the applied recharge amount for cumulative calculations.
      Specified by:
      setAppliedRechargeAmount in interface SimulationState
      Parameters:
      useKey - The key containing application and substance
      value - The total amount recharged this year in kg
      Throws:
      UnsupportedOperationException - always, since this instance is frozen

    • setPrechargePopulation

      public void setPrechargePopulation(UseKey useKey, EngineNumber newValue)
      Set the precharge population percentage for a key.
      Specified by:
      setPrechargePopulation in interface SimulationState
      Parameters:
      useKey - The key containing application and substance
      newValue - The new precharge population value
      Throws:
      UnsupportedOperationException - always, since this instance is frozen

    • getPrechargePopulation

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

    • setPrechargeIntensity

      public void setPrechargeIntensity(UseKey useKey, EngineNumber newValue)
      Set the precharge intensity for a key.
      Specified by:
      setPrechargeIntensity in interface SimulationState
      Parameters:
      useKey - The key containing application and substance
      newValue - The new precharge intensity value
      Throws:
      UnsupportedOperationException - always, since this instance is frozen

    • getPrechargeIntensity

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

    • accumulatePrecharge

      public void accumulatePrecharge(UseKey useKey, EngineNumber population, EngineNumber intensity)
      Accumulate precharge parameters. Sets when not previously set, accumulates otherwise.
      Specified by:
      accumulatePrecharge in interface SimulationState
      Parameters:
      useKey - The key containing application and substance
      population - The precharge population rate to add
      intensity - The precharge intensity for this rate
      Throws:
      UnsupportedOperationException - always, since this instance is frozen

    • getPrechargeBasePopulation

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

    • setPrechargeBasePopulation

      public void setPrechargeBasePopulation(UseKey useKey, EngineNumber value)
      Set the precharge base population for cumulative calculations.
      Specified by:
      setPrechargeBasePopulation in interface SimulationState
      Parameters:
      useKey - The key containing application and substance
      value - The base population value
      Throws:
      UnsupportedOperationException - always, since this instance is frozen

    • getAppliedPrechargeAmount

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

    • setAppliedPrechargeAmount

      public void setAppliedPrechargeAmount(UseKey useKey, EngineNumber value)
      Set the applied precharge amount for cumulative calculations.
      Specified by:
      setAppliedPrechargeAmount in interface SimulationState
      Parameters:
      useKey - The key containing application and substance
      value - The total amount precharged this year in kg
      Throws:
      UnsupportedOperationException - always, since this instance is frozen

    • isRecyclingCalculatedThisStep

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

    • setRecyclingCalculatedThisStep

      public void setRecyclingCalculatedThisStep(UseKey useKey, boolean calculated)
      Set whether recycling has been calculated this step.
      Specified by:
      setRecyclingCalculatedThisStep in interface SimulationState
      Parameters:
      useKey - The key containing application and substance
      calculated - true if recycling was calculated, false otherwise
      Throws:
      UnsupportedOperationException - always, since this instance is frozen

    • setRecoveryRate

      public 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.
      Specified by:
      setRecoveryRate in interface SimulationState
      Parameters:
      useKey - The key containing application and substance
      newValue - The new recovery rate value
      Throws:
      UnsupportedOperationException - always, since this instance is frozen

    • setRecoveryRate

      public 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.
      Specified by:
      setRecoveryRate in interface SimulationState
      Parameters:
      useKey - The key containing application and substance
      newValue - The new recovery rate value
      stage - The recovery stage (EOL or RECHARGE)
      Throws:
      UnsupportedOperationException - always, since this instance is frozen

    • getRecoveryRate

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

    • getRecoveryRate

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

    • setYieldRate

      public 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 SimulationState.setYieldRate(UseKey, EngineNumber, RecoveryStage) with RecoveryStage.RECHARGE.

      Specified by:
      setYieldRate in interface SimulationState
      Parameters:
      useKey - The key containing application and substance
      newValue - The new yield rate value
      Throws:
      UnsupportedOperationException - always, since this instance is frozen
      See Also:

    • setYieldRate

      public 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.

      Specified by:
      setYieldRate in interface SimulationState
      Parameters:
      useKey - The key containing application and substance
      newValue - The new yield rate value
      stage - The recovery stage (EOL or RECHARGE)
      Throws:
      UnsupportedOperationException - always, since this instance is frozen

    • getYieldRate

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

    • getYieldRate

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

    • setInductionRate

      public void setInductionRate(UseKey useKey, EngineNumber newValue)
      Set the induction rate percentage for recycling for a key.
      Specified by:
      setInductionRate in interface SimulationState
      Parameters:
      useKey - The key containing application and substance
      newValue - The new induction rate value
      Throws:
      UnsupportedOperationException - always, since this instance is frozen

    • setInductionRate

      public void setInductionRate(UseKey useKey, EngineNumber newValue, RecoverOperation.RecoveryStage stage)
      Set the induction rate percentage for recycling for a key with a specific stage.
      Specified by:
      setInductionRate in interface SimulationState
      Parameters:
      useKey - The key containing application and substance
      newValue - The new induction rate value
      stage - The recovery stage (EOL or RECHARGE)
      Throws:
      UnsupportedOperationException - always, since this instance is frozen

    • getInductionRate

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

    • getInductionRate

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

    • setRetirementRate

      public void setRetirementRate(UseKey useKey, EngineNumber newValue)
      Set the retirement rate percentage for a key.
      Specified by:
      setRetirementRate in interface SimulationState
      Parameters:
      useKey - The key containing application and substance
      newValue - The new retirement rate value
      Throws:
      UnsupportedOperationException - always, since this instance is frozen

    • getRetirementRate

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

    • getRetirementBasePopulation

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

    • setRetirementBasePopulation

      public void setRetirementBasePopulation(UseKey useKey, EngineNumber value)
      Set the retirement base population for cumulative calculations.
      Specified by:
      setRetirementBasePopulation in interface SimulationState
      Parameters:
      useKey - The key containing application and substance
      value - The base population value
      Throws:
      UnsupportedOperationException - always, since this instance is frozen

    • getAppliedRetirementAmount

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

    • setAppliedRetirementAmount

      public void setAppliedRetirementAmount(UseKey useKey, EngineNumber value)
      Set the applied retirement amount for cumulative calculations.
      Specified by:
      setAppliedRetirementAmount in interface SimulationState
      Parameters:
      useKey - The key containing application and substance
      value - The total amount retired this year
      Throws:
      UnsupportedOperationException - always, since this instance is frozen

    • getHasReplacementThisStep

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

    • setHasReplacementThisStep

      public void setHasReplacementThisStep(UseKey useKey, boolean value)
      Set the replacement mode for retire commands this step.
      Specified by:
      setHasReplacementThisStep in interface SimulationState
      Parameters:
      useKey - The key containing application and substance
      value - true for with replacement, false for without replacement
      Throws:
      UnsupportedOperationException - always, since this instance is frozen

    • getRetireCalculatedThisStep

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

    • setRetireCalculatedThisStep

      public void setRetireCalculatedThisStep(UseKey useKey, boolean calculated)
      Set whether retire has been calculated this step.
      Specified by:
      setRetireCalculatedThisStep in interface SimulationState
      Parameters:
      useKey - The key containing application and substance
      calculated - true if retire was calculated, false otherwise
      Throws:
      UnsupportedOperationException - always, since this instance is frozen

    • setLastSpecifiedValue

      public 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.

      Specified by:
      setLastSpecifiedValue in interface SimulationState
      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
      Throws:
      UnsupportedOperationException - always, since this instance is frozen

    • getLastSpecifiedValue

      public EngineNumber getLastSpecifiedValue(UseKey useKey, String streamName)
      Get the last specified value for a stream.
      Specified by:
      getLastSpecifiedValue in interface SimulationState
      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

      public boolean hasLastSpecifiedValue(UseKey useKey, String streamName)
      Check if a stream has a last specified value.
      Specified by:
      hasLastSpecifiedValue in interface SimulationState
      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

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

    • resetSalesIntentFlag

      public void resetSalesIntentFlag(UseKey useKey)
      Reset the sales intent flag for the given scope.
      Specified by:
      resetSalesIntentFlag in interface SimulationState
      Parameters:
      useKey - The key containing application and substance
      Throws:
      UnsupportedOperationException - always, since this instance is frozen

    • hasStreamBeenEnabled

      public boolean hasStreamBeenEnabled(UseKey useKey, String streamName)
      Check if a stream has ever been enabled (set to non-zero value).
      Specified by:
      hasStreamBeenEnabled in interface SimulationState
      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

      public void markStreamAsEnabled(UseKey useKey, String streamName)
      Mark a stream as having been enabled (set to non-zero value).
      Specified by:
      markStreamAsEnabled in interface SimulationState
      Parameters:
      useKey - The key containing application and substance
      streamName - The name of the stream to mark as enabled
      Throws:
      UnsupportedOperationException - always, since this instance is frozen

    • clearLastSpecifiedValue

      public 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.

      Specified by:
      clearLastSpecifiedValue in interface SimulationState
      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.
      Throws:
      UnsupportedOperationException - always, since this instance is frozen

    • freeze

      public 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).

      Specified by:
      freeze in interface SimulationState
      Returns:
      this same instance, since it is already frozen