Package org.kigalisim.engine.state

Class SimulationState

java.lang.Object
org.kigalisim.engine.state.SimulationState
public class SimulationState extends Object
Manager for the state for a single scenario within a single trial.

State management object for storage and retrieval of substance data, stream values, and associated parameterizations.

  • Field Details

    • ZERO_VOLUME

      public static final EngineNumber ZERO_VOLUME

  • Constructor Details

    • SimulationState

      public SimulationState(OverridingConverterStateGetter stateGetter, UnitConverter unitConverter)
      Create a new SimulationState instance.
      Parameters:
      stateGetter - Structure to retrieve state information
      unitConverter - Converter for handling unit transformations

  • Method Details

    • getRegisteredSubstances

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

    • hasSubstance

      public 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

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

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

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

    • getStream

      public 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

      public 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

      public 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

      public 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

      public 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

      public 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

      public 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

      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.

      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.

      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.
      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.
      Returns:
      The current year

    • setCurrentYear

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

    • incrementYear

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

    • setGhgIntensity

      public 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

      public 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

      public 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

      public 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

      public 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

      public 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

      public 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

      public 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

      public 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

      public 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

      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.

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

    • getRechargeBasePopulation

      public 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

      public 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

      public 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

      public 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

    • isRecyclingCalculatedThisStep

      public 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

      public 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

      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.
      Parameters:
      useKey - The key containing application and substance
      newValue - The new recovery rate value

    • 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.
      Parameters:
      useKey - The key containing application and substance
      newValue - The new recovery rate value
      stage - The recovery stage (EOL or RECHARGE)

    • getRecoveryRate

      public 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

      public 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

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

      Parameters:
      useKey - The key containing application and substance
      newValue - The new yield rate value
      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.

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

    • getYieldRate

      public 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

      public 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

      public 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

      public 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

      public 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

      public 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

      public 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

      public 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

      public 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

      public 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

      public 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

      public 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

      public 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

      public 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

      public 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

      public 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

      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.

      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

      public 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

      public 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

      public 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

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

    • hasStreamBeenEnabled

      public 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

      public 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

      public void clearLastSpecifiedValue(UseKey useKey, String stream)
      Clear the last specified value in the parameterization for the given use key.

      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.