Package org.kigalisim.engine

Class SingleThreadEngine

java.lang.Object
org.kigalisim.engine.SingleThreadEngine
All Implemented Interfaces:
Engine
public class SingleThreadEngine extends Object implements Engine
Single-threaded implementation of the Engine interface.

At this time the only implementation of Engine which does not guarantee thread safety within a single scenario. However, note that Engine only evaluates one scenario at a time so Kigali Sim still achieves concurency by having multiple Engines and evaluating scenarios or Monte Carlo trials in parallel.

  • Constructor Details

    • SingleThreadEngine

      public SingleThreadEngine(int startYear, int endYear)
      Create a new SingleThreadEngine instance.
      Parameters:
      startYear - The starting year of the simulation
      endYear - The ending year of the simulation

  • Method Details

    • getStartYear

      public int getStartYear()
      Description copied from interface: Engine
      Get the starting year of the simulation.

      Get the starting year of the simulation as defined in the simulation stanza or similar. Actual execution will start at this value and increment one timestep (year) at a time until end year such that commands outside this range will not run.

      Specified by:
      getStartYear in interface Engine
      Returns:
      The start year like 2025.

    • getEndYear

      public int getEndYear()
      Description copied from interface: Engine
      Get the ending year of the simulation.

      Get the starting year of the simulation as defined in the simulation stanza or similar. Actual execution will end at this value, incrementing one timestep (year) at a time until end year such that commands outside this range will not run.

      Specified by:
      getEndYear in interface Engine
      Returns:
      The end year like 2050.

    • getScenarioName

      public String getScenarioName()
      Get the scenario name.
      Specified by:
      getScenarioName in interface Engine
      Returns:
      The name of the scenario being run

    • setScenarioName

      public void setScenarioName(String scenarioName)
      Set the scenario name.
      Specified by:
      setScenarioName in interface Engine
      Parameters:
      scenarioName - The name of the scenario being run

    • getTrialNumber

      public int getTrialNumber()
      Get the trial number.
      Specified by:
      getTrialNumber in interface Engine
      Returns:
      The trial number of the current run

    • setTrialNumber

      public void setTrialNumber(int trialNumber)
      Set the trial number.
      Specified by:
      setTrialNumber in interface Engine
      Parameters:
      trialNumber - The trial number of the current run

    • setStanza

      public void setStanza(String newStanza)
      Description copied from interface: Engine
      Set the stanza for the engine current scope.

      Specify the stanza in which the engine is currently running and which can be used to describe the current variable scope. Note that this may be used in some error reporting and should match the input script or similar.

      Specified by:
      setStanza in interface Engine
      Parameters:
      newStanza - The new stanza name such as default for the baseline scenario.

    • setApplication

      public void setApplication(String newApplication)
      Description copied from interface: Engine
      Set the application for the engine current scope.

      Specify the name of the application which is currently being evaluated as indicated in the input script or similar. Note that this may be used in some error reporting and should match the user specified name.

      Specified by:
      setApplication in interface Engine
      Parameters:
      newApplication - The new application name like commercial refrigeration.

    • setSubstance

      public void setSubstance(String newSubstance, boolean checkValid)
      Description copied from interface: Engine
      Set the substance for the engine current scope.

      Specify the substance that is currently being evaluated by the engine where a substance may appear in multiple applications. Note that this is used in some error reporting and should match the user specified name.

      Specified by:
      setSubstance in interface Engine
      Parameters:
      newSubstance - The new substance name like HFC-134a.
      checkValid - True if an error should be thrown if the app/substance is not previously registered or false if it should be registered if not found. Defaults to false.

    • setSubstance

      public void setSubstance(String newSubstance)
      Description copied from interface: Engine
      Set the substance for the engine current scope with default validation behavior.

      Specify the substance that is currently being evaluated by the engine where a substance may appear in multiple applications. Note that this is used in some error reporting and should match the user specified name.

      Specified by:
      setSubstance in interface Engine
      Parameters:
      newSubstance - The new substance name like HFC-134a.

    • getScope

      public Scope getScope()
      Description copied from interface: Engine
      Get the engine's current scope.

      Get information about the current "location" in which the Engine is performing calculations. This specifically refers to the set of variables in scope where scope may indicate, for example, which application the Engine is evaluating in order to determine the correct initial charge to use.

      Specified by:
      getScope in interface Engine
      Returns:
      Scope object describing current location in user script or similar.

    • getStateGetter

      public ConverterStateGetter getStateGetter()
      Description copied from interface: Engine
      Get the state getter for converter operations.

      QubecTalk numbers have both a numeric value and a type such as kilograms. Many values require conversion to alternative units like metric tonnes and some of those conversions such as from number of units of equipment to tCO2e require information about equipment like charge levels. This retrieves an instance which supports querying of information needed to perform conversions specific to equipment, substance, or stream.

      Specified by:
      getStateGetter in interface Engine
      Returns:
      ConverterStateGetter The state getter which can be used for state-dependent conversions.

    • getUnitConverter

      public UnitConverter getUnitConverter()
      Description copied from interface: Engine
      Get the unit converter for this engine.

      QubecTalk numbers have both a numeric value and a type such as kilograms. Many values require conversion to alternative units like metric tonnes. This retrieves an object which can be used with this Engine for those conversions.

      Specified by:
      getUnitConverter in interface Engine
      Returns:
      UnitConverter Facade which can perform unit conversions for operations with this Engine.

    • getStreamKeeper

      public SimulationState getStreamKeeper()
      Description copied from interface: Engine
      Get the simulation state for this engine.
      Specified by:
      getStreamKeeper in interface Engine
      Returns:
      SimulationState Accounting object which describes the current state of this siulation across all applications and substances.

    • incrementYear

      public void incrementYear()
      Description copied from interface: Engine
      Increment the engine to simulate the next year.
      Specified by:
      incrementYear in interface Engine

    • getYear

      public int getYear()
      Description copied from interface: Engine
      Get the year that the engine is currently simulating.
      Specified by:
      getYear in interface Engine
      Returns:
      Current year being simulated like 2025.

    • getIsDone

      public boolean getIsDone()
      Description copied from interface: Engine
      Determine if the engine has reached its final year.

      The simulation goes through one timestep (year) at a time from start year to end year and is considered finished when reaching end year. This evaluates if that terminal state has been reached.

      Specified by:
      getIsDone in interface Engine
      Returns:
      True if reached the end year and false otherwise.

    • executeStreamUpdate

      public void executeStreamUpdate(StreamUpdate update)
      Description copied from interface: Engine
      Execute a stream update operation using a StreamUpdate object.
      Specified by:
      executeStreamUpdate in interface Engine
      Parameters:
      update - The StreamUpdate describing how to update a stream and which contains all parameters for the operation.

    • setStream

      public void setStream(String name, EngineNumber value, Optional<YearMatcher> yearMatcher)
      Description copied from interface: Engine
      Set a stream for explicit user operations (applies user-level processing like SetExecutor).
      Specified by:
      setStream in interface Engine
      Parameters:
      name - The stream name
      value - The value to set for the stream
      yearMatcher - Optional year matcher for conditional setting

    • enable

      public void enable(String name, Optional<YearMatcher> yearMatcher)
      Description copied from interface: Engine
      Enable a stream without setting its value.

      This method marks a stream as enabled, allowing it to be included in distribution calculations for operations like recharge, retire, and recover without having to set an actual value to the stream.

      Specified by:
      enable in interface Engine
      Parameters:
      name - The name of the stream to enable
      yearMatcher - The year matcher object or empty

    • getStream

      public EngineNumber getStream(String name, Optional<UseKey> useKey, Optional<String> conversion)
      Description copied from interface: Engine
      Get the stream value for a given application and substance key.

      Get the current value of a stream where a stream is a type of stock in the stock and flow model such as sales or equipment.

      Specified by:
      getStream in interface Engine
      Parameters:
      name - The name of the stream to retrieve like sales.
      useKey - The key containing application and substance information.
      conversion - The conversion specification for units (like mt), or empty for no conversion.
      Returns:
      The value of the stream, possibly converted like to kg.

    • getStream

      public EngineNumber getStream(String name)
      Description copied from interface: Engine
      Get the stream value with default scope and no conversion.

      Get the current value of a stream where a stream is a type of stock in the stock and flow model such as sales or equipment. This gets the value of the stream automatically converted to kilograms in the current Engine scope.

      Specified by:
      getStream in interface Engine
      Parameters:
      name - The name of the stream to retrieve like sales.
      Returns:
      The value of the stream in kg.

    • getStreamFor

      public EngineNumber getStreamFor(UseKey key, String stream)
      Description copied from interface: Engine
      Get the stream value without any conversion.

      Get the current value of a stream where a stream is a type of stock in the stock and flow model such as sales or equipment.

      Specified by:
      getStreamFor in interface Engine
      Parameters:
      key - The application and substance name for which the stream should be returned.
      stream - The name of the stream to get like recycle.
      Returns:
      The value of the given combination without conversion (as last saved).

    • defineVariable

      public void defineVariable(String name)
      Description copied from interface: Engine
      Create a user-defined variable in the current scope.
      Specified by:
      defineVariable in interface Engine
      Parameters:
      name - The name of the variable to define

    • getVariable

      public EngineNumber getVariable(String name)
      Description copied from interface: Engine
      Get the value of a user-defined variable in the current scope.
      Specified by:
      getVariable in interface Engine
      Parameters:
      name - The name of the variable to retrieve
      Returns:
      The value of the variable, or special values for 'yearsElapsed' and 'yearAbsolute' in years.

    • setVariable

      public void setVariable(String name, EngineNumber value)
      Description copied from interface: Engine
      Set the value of a variable in the current scope.
      Specified by:
      setVariable in interface Engine
      Parameters:
      name - The name of the variable to set
      value - The value to assign to the variable

    • getInitialCharge

      public EngineNumber getInitialCharge(String stream)
      Description copied from interface: Engine
      Get the initial charge value for a given stream.

      Get the current initial charge in the current state for a given stream, typically a sales stream like sales, import, export, domestic. This is looked up in the current scope.

      Specified by:
      getInitialCharge in interface Engine
      Parameters:
      stream - The stream identifier to get the initial charge for like sales.
      Returns:
      The initial charge value for the stream like in kg / unit.

    • getRawInitialChargeFor

      public EngineNumber getRawInitialChargeFor(UseKey useKey, String stream)
      Description copied from interface: Engine
      Get the initial charge for a specific application and substance.

      Get the current initial charge in the current state for a given stream, typically a sales stream like sales, import, export, domestic.

      Specified by:
      getRawInitialChargeFor in interface Engine
      Parameters:
      useKey - Application and substance for which initial charge is requested
      stream - The stream in which the initial charge is requested and must be realized
      Returns:
      The initial charge for the stream in the given application and substance like in kg / unit.

    • setInitialCharge

      public void setInitialCharge(EngineNumber value, String stream, YearMatcher yearMatcher)
      Description copied from interface: Engine
      Set the initial charge for a stream.

      Set the initial charge to use for a stream in the current scope. This is typically a sales stream like sales, import, export, domestic. This operation will only be applied if the year matcher passes, otherwise a no-op.

      Specified by:
      setInitialCharge in interface Engine
      Parameters:
      value - The initial charge value to set like 5 kg / unit.
      stream - The stream identifier to set the initial charge for like sales.
      yearMatcher - Matcher to determine if the change applies to current year. If not matching the current year, will be a no-op.

    • getRechargeVolume

      public EngineNumber getRechargeVolume()
      Description copied from interface: Engine
      Get the recharge volume for the current application and substance.

      Get the servicing volume (across all recharge commands) within the current scope in the units last saved.

      Specified by:
      getRechargeVolume in interface Engine
      Returns:
      The recharge volume value like percent.

    • getRechargeIntensity

      public EngineNumber getRechargeIntensity()
      Description copied from interface: Engine
      Get the recharge intensity for the current application and substance.

      Get the servicing intensity (across all recharge commands) within the current scope in the units last saved.

      Specified by:
      getRechargeIntensity in interface Engine
      Returns:
      The recharge intensity value in kg per unit.

    • recharge

      public void recharge(EngineNumber volume, EngineNumber intensity, YearMatcher yearMatcher)
      Description copied from interface: Engine
      Set recharge parameters for the current application and substance.

      Recharge represents the substance needed to service existing equipment due to leakage, maintenance, or repair. This method configures both the percentage of equipment requiring recharge (volume) and the amount of substance needed per unit (intensity).

      Note that, when users specify sales in equipment units (e.g., "800 units"), they indicate how many new equipment units should be sold. This recharge method must calculate substance needed for exiting equipment and add it on top. For example, if a user specifies "set import to 800 units during year 2025" and provides no specification for 2026, the carry over mechanism will automatically continue 800 new units in 2026, while recalculating and adding the appropriate recharge volume based on the growing equipment population.

      Specified by:
      recharge in interface Engine
      Parameters:
      volume - The recharge volume to set (percentage of equipment requiring recharge)
      intensity - The recharge intensity to set (substance amount per unit recharged)
      yearMatcher - Matcher to determine if the change applies to current year

    • retire

      public void retire(EngineNumber amount, YearMatcher yearMatcher)
      Description copied from interface: Engine
      Set retirement rate for the current application and substance.

      Set the retirement (also called) scrap rate within the current scope. This is the hazard rate rate to use for retirement and can be specified in any units but are typically given in percentages (probability). Note that these may also be the result of a stateful formula like for users which have an age-dependent hazard for their survival analysis.

      Specified by:
      retire in interface Engine
      Parameters:
      amount - The retirement rate to set in the current scope.
      yearMatcher - Matcher to determine if the change applies to current year and, if not matching the current year, this is a no-op.

    • getRetirementRate

      public EngineNumber getRetirementRate()
      Description copied from interface: Engine
      Get the retirement rate for the current application and substance.

      Get the current hazard rate for equipment retirment (also called scrap in some communities).

      Specified by:
      getRetirementRate in interface Engine
      Returns:
      The retirement rate value like as percentage.

    • recycle

      public void recycle(EngineNumber recoveryWithUnits, EngineNumber yieldWithUnits, YearMatcher yearMatcher, RecoverOperation.RecoveryStage stage)
      Description copied from interface: Engine
      Set recycling parameters for the current application and substance.

      Recycling allows for recovery of some amount of substance to be reused, potentially in place of virgin material. However, this is controlled through an induction (induced demand) parameter. Note that some may use recycling with 0% yield to model destruction in which substance is prevented from emitting but is not salvaged for reuse.

      Specified by:
      recycle in interface Engine
      Parameters:
      recoveryWithUnits - The recovery rate, typically in percentage or probability.
      yieldWithUnits - The yield rate indicating how much recovered is actually reused.
      yearMatcher - Matcher to determine if the change applies to current year and, if not matching the current year, turns this into a no-op.
      stage - The recovery stage (EOL for end of life or RECHARGE for servicing) at which the substance is captured.

    • setInductionRate

      public void setInductionRate(EngineNumber inductionRate, RecoverOperation.RecoveryStage stage)
      Description copied from interface: Engine
      Set the induction rate for recycling operations.

      This parameter allows for modeling induced demand, an economic effect in which increased supply (in our case through recycling / secondary production) actually causes demand to also increase such that one kg of secondary material does not fully reduce or offset one kg of virgin production.

      Induction rate determines how recycled material affects virgin production:
      • 100% induction (default): Recycled material does not displace virgin material, adding to total supply (induced demand behavior)
      • 0% induction: Recycled material fully displaces virgin material, maintaining steady population (displacement behavior)
      • Partial induction: Mixed behavior with proportional effects
      Specified by:
      setInductionRate in interface Engine
      Parameters:
      inductionRate - The induction rate as an EngineNumber with percentage units, or null for default behavior (100% induced demand).
      stage - The recovery stage (EOL or RECHARGE) for which to set the induction rate.

    • resetInductionRate

      public void resetInductionRate(RecoverOperation.RecoveryStage stage)
      Description copied from interface: Engine
      Reset the induction rate to default behavior for recycling operations.

      This method sets the induction rate to 100%, which represents default induced demand behavior where recycled material adds to total supply rather than displacing virgin material. This is the recommended setting when users are uncertain about induction effects.

      Induction rate determines how recycled material affects virgin production:
      • 100% induction (default): Recycled material does not displace virgin material, adding to total supply (induced demand behavior)
      • 0% induction: Recycled material fully displaces virgin material, maintaining steady population (displacement behavior)
      • Partial induction: Mixed behavior with proportional effects
      Specified by:
      resetInductionRate in interface Engine
      Parameters:
      stage - The recovery stage (EOL or RECHARGE) to reset the induction rate for

    • equals

      public void equals(EngineNumber amount, YearMatcher yearMatcher)
      Description copied from interface: Engine
      Set GHG equivalency (GWP - Global Warming Potential) for the current application and substance.

      Set GHG equivalency (GWP - Global Warming Potential) for the current application and substance as defined by the current scope. Will only execute if the year matcher matches the current year. Otherwise, this is a no-op.

      Note that this is intended only for direct emissions though useres may calculate indirect or secondary emissions through energy mix outside of Kigali Sim.

      Specified by:
      equals in interface Engine
      Parameters:
      amount - The GHG intensity value to set (typically in kgCO2e / kg).
      yearMatcher - Matcher to determine if the change applies to current year.

    • getGhgIntensity

      public EngineNumber getGhgIntensity(UseKey useKey)
      Description copied from interface: Engine
      Get the GHG intensity (GWP - Global Warming Potential) associated with a substance.

      Set GHG equivalency (GWP - Global Warming Potential) for the specified application and substance (regradless of current scope). Will only execute if the year matcher matches the current year. Otherwise, this is a no-op.

      Note that this is intended only for direct emissions though useres may calculate indirect or secondary emissions through energy mix outside of Kigali Sim.

      Specified by:
      getGhgIntensity in interface Engine
      Parameters:
      useKey - The UseKey containing application and substance information
      Returns:
      The GHG intensity value associated with the given combination in tCO2e per kg.

    • getEqualsGhgIntensity

      public EngineNumber getEqualsGhgIntensity()
      Description copied from interface: Engine
      Retrieve the tCO2e intensity (GWP - Global Warming Potential) for the current application and substance.

      Retrieve the primary GHG intensity (GWP) for the current application and substance where this value is not expected to cover secondary or indirect emissions. That said, users may calculate those additional emissions through energy mix data from outside Kigali Sim.

      Specified by:
      getEqualsGhgIntensity in interface Engine
      Returns:
      The GHG intensity value with volume normalized GHG in tCO2e per kg.

    • getEqualsGhgIntensityFor

      public EngineNumber getEqualsGhgIntensityFor(UseKey useKey)
      Description copied from interface: Engine
      Retrieve the tCO2e intensity (GWP - Global Warming Potential) for the given UseKey.

      Retrieve the primary GHG intensity (GWP) for the given application and substance where this value is not expected to cover secondary or indirect emissions. That said, users may calculate those additional emissions through energy mix data from outside Kigali Sim.

      Specified by:
      getEqualsGhgIntensityFor in interface Engine
      Parameters:
      useKey - The UseKey containing application and substance information
      Returns:
      The GHG intensity value with volume normalized GHG in tCO2e per kg.

    • getEqualsEnergyIntensity

      public EngineNumber getEqualsEnergyIntensity()
      Description copied from interface: Engine
      Retrieve the energy intensity for the current application and substance.
      Specified by:
      getEqualsEnergyIntensity in interface Engine
      Returns:
      The energy intensity value, typically in kwh / unit (yearly).

    • getEqualsEnergyIntensityFor

      public EngineNumber getEqualsEnergyIntensityFor(UseKey useKey)
      Description copied from interface: Engine
      Retrieve the energy intensity for the given UseKey.
      Specified by:
      getEqualsEnergyIntensityFor in interface Engine
      Parameters:
      useKey - The UseKey containing application and substance information for the application and substance pair for which energy intensity is to be returned.
      Returns:
      The energy intensity value, typically in kwh / unit (yearly).

    • changeStream

      public void changeStream(String stream, EngineNumber amount, YearMatcher yearMatcher)
      Description copied from interface: Engine
      Change a stream value by a delta amount with default scope.
      Specified by:
      changeStream in interface Engine
      Parameters:
      stream - The stream identifier to modify
      amount - The amount to change the stream by
      yearMatcher - Matcher to determine if the change applies to current year

    • changeStream

      public void changeStream(String stream, EngineNumber amount, YearMatcher yearMatcher, UseKey useKey)
      Description copied from interface: Engine
      Change a stream value by a delta amount.
      Specified by:
      changeStream in interface Engine
      Parameters:
      stream - The stream identifier to modify
      amount - The amount to change the stream by
      yearMatcher - Matcher to determine if the change applies to current year
      useKey - The key containing application and substance information

    • cap

      public void cap(String stream, EngineNumber amount, YearMatcher yearMatcher, String displaceTarget, DisplacementType displacementType)
      Description copied from interface: Engine
      Cap a stream at a maximum value.
      Specified by:
      cap in interface Engine
      Parameters:
      stream - The stream identifier to cap
      amount - The maximum value to cap at
      yearMatcher - Matcher to determine if the change applies to current year
      displaceTarget - Optional target for displaced amount
      displacementType - The type of displacement (EQUIVALENT, BY_VOLUME, or BY_UNITS)

    • floor

      public void floor(String stream, EngineNumber amount, YearMatcher yearMatcher, String displaceTarget, DisplacementType displacementType)
      Description copied from interface: Engine
      Set a minimum floor value for a stream.
      Specified by:
      floor in interface Engine
      Parameters:
      stream - The stream identifier to set floor for
      amount - The minimum value to set as floor
      yearMatcher - Matcher to determine if the change applies to current year
      displaceTarget - Optional target for displaced amount
      displacementType - The type of displacement (EQUIVALENT, BY_VOLUME, or BY_UNITS)

    • replace

      public void replace(EngineNumber amountRaw, String stream, String destinationSubstance, YearMatcher yearMatcher)
      Description copied from interface: Engine
      Replace an amount from one substance with another.
      Specified by:
      replace in interface Engine
      Parameters:
      amountRaw - The amount to replace
      stream - The stream identifier to modify
      destinationSubstance - The substance to replace with
      yearMatcher - Matcher to determine if the change applies to current year

    • getResults

      public List<EngineResult> getResults()
      Description copied from interface: Engine
      Get the results for all registered substances.
      Specified by:
      getResults in interface Engine
      Returns:
      List of results for each registered substance

    • getOptimizeRecalcs

      public boolean getOptimizeRecalcs()
      Description copied from interface: Engine
      Gets whether recalc optimizations are enabled.

      When true, certain redundant recalculation steps are skipped for performance. When false, all recalc operations are performed for maximum accuracy verification.

      Specified by:
      getOptimizeRecalcs in interface Engine
      Returns:
      true if optimizations are enabled, false otherwise