Package org.kigalisim.engine

Interface Engine

All Known Implementing Classes:
SingleThreadEngine
public interface Engine
Engine entry-point which maintains and updates simulation state.

Coordinator which ensures the state of the simulation as accounted for by SimulationState by performing operations on that state within a current scope, delegating to "Executor" and "Recalc" strategies.

  • Method Details

    • getStartYear

      int getStartYear()
      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.

      Returns:
      The start year like 2025.

    • getEndYear

      int getEndYear()
      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.

      Returns:
      The end year like 2050.

    • getScenarioName

      String getScenarioName()
      Get the scenario name.

      Get the name of the scenario currently being run as defined in the input script or similar. This is used to refer to the set of policy stanzas active within a simluation.

      Returns:
      The name of the scenario being run like business as usual.

    • setScenarioName

      void setScenarioName(String scenarioName)
      Set the scenario name.

      Specify the name of the scenario currently being run as defined in the input script or similar. This is used to refer to the set of policy stanzas active within a simluation.

      Parameters:
      scenarioName - The name of the scenario being run like business as usual.

    • getTrialNumber

      int getTrialNumber()
      Get the trial number.

      Get the Monte Carlo trial number being run. This is typically a one-indexed positive number and, if no Monte Carlo is specified, is one.

      Returns:
      The trial number of the current run like 1.

    • setTrialNumber

      void setTrialNumber(int trialNumber)
      Set the trial number.

      Set the Monte Carlo trial number being run. This is typically a one-indexed positive number and, if no Monte Carlo is specified, is one.

      Parameters:
      trialNumber - The trial number of the current run like 1.

    • setStanza

      void setStanza(String newStanza)
      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.

      Parameters:
      newStanza - The new stanza name such as default for the baseline scenario.

    • setApplication

      void setApplication(String newApplication)
      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.

      Parameters:
      newApplication - The new application name like commercial refrigeration.

    • setSubstance

      void setSubstance(String newSubstance, boolean checkValid)
      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.

      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

      void setSubstance(String newSubstance)
      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.

      Parameters:
      newSubstance - The new substance name like HFC-134a.

    • getScope

      Scope getScope()
      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.

      Returns:
      Scope object describing current location in user script or similar.

    • getStateGetter

      ConverterStateGetter getStateGetter()
      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.

      Returns:
      ConverterStateGetter The state getter which can be used for state-dependent conversions.

    • getUnitConverter

      UnitConverter getUnitConverter()
      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.

      Returns:
      UnitConverter Facade which can perform unit conversions for operations with this Engine.

    • getStreamKeeper

      SimulationState getStreamKeeper()
      Get the simulation state for this engine.
      Returns:
      SimulationState Accounting object which describes the current state of this siulation across all applications and substances.

    • incrementYear

      void incrementYear()
      Increment the engine to simulate the next year.

    • getYear

      int getYear()
      Get the year that the engine is currently simulating.
      Returns:
      Current year being simulated like 2025.

    • getIsDone

      boolean getIsDone()
      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.

      Returns:
      True if reached the end year and false otherwise.

    • executeStreamUpdate

      void executeStreamUpdate(StreamUpdate update)
      Execute a stream update operation using a StreamUpdate object.
      Parameters:
      update - The StreamUpdate describing how to update a stream and which contains all parameters for the operation.

    • setStream

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

    • enable

      void enable(String name, Optional<YearMatcher> yearMatcher)
      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.

      Parameters:
      name - The name of the stream to enable
      yearMatcher - The year matcher object or empty

    • getStream

      EngineNumber getStream(String name, Optional<UseKey> useKey, Optional<String> conversion)
      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.

      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

      EngineNumber getStream(String name)
      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.

      Parameters:
      name - The name of the stream to retrieve like sales.
      Returns:
      The value of the stream in kg.

    • getStreamFor

      EngineNumber getStreamFor(UseKey useKey, String stream)
      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.

      Parameters:
      useKey - 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

      void defineVariable(String name)
      Create a user-defined variable in the current scope.
      Parameters:
      name - The name of the variable to define
      Throws:
      RuntimeException - When trying to define protected variables 'yearsElapsed' or 'yearAbsolute'

    • getVariable

      EngineNumber getVariable(String name)
      Get the value of a user-defined variable in the current scope.
      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

      void setVariable(String name, EngineNumber value)
      Set the value of a variable in the current scope.
      Parameters:
      name - The name of the variable to set
      value - The value to assign to the variable
      Throws:
      RuntimeException - When trying to set protected variables 'yearsElapsed' or 'yearAbsolute'

    • getInitialCharge

      EngineNumber getInitialCharge(String stream)
      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.

      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

      EngineNumber getRawInitialChargeFor(UseKey key, String stream)
      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.

      Parameters:
      key - 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

      void setInitialCharge(EngineNumber value, String stream, YearMatcher yearMatcher)
      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.

      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

      EngineNumber getRechargeVolume()
      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.

      Returns:
      The recharge volume value like percent.

    • getRechargeIntensity

      EngineNumber getRechargeIntensity()
      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.

      Returns:
      The recharge intensity value in kg per unit.

    • recharge

      void recharge(EngineNumber volume, EngineNumber intensity, YearMatcher yearMatcher)
      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.

      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

      void retire(EngineNumber amount, YearMatcher yearMatcher)
      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.

      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

      EngineNumber getRetirementRate()
      Get the retirement rate for the current application and substance.

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

      Returns:
      The retirement rate value like as percentage.

    • recycle

      void recycle(EngineNumber recoveryWithUnits, EngineNumber yieldWithUnits, YearMatcher yearMatcher, RecoverOperation.RecoveryStage stage)
      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.

      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

      void setInductionRate(EngineNumber inductionRate, RecoverOperation.RecoveryStage stage)
      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
      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

      void resetInductionRate(RecoverOperation.RecoveryStage stage)
      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
      Parameters:
      stage - The recovery stage (EOL or RECHARGE) to reset the induction rate for

    • equals

      void equals(EngineNumber amount, YearMatcher yearMatcher)
      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.

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

    • getGhgIntensity

      EngineNumber getGhgIntensity(UseKey useKey)
      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.

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

    • getEqualsGhgIntensity

      EngineNumber getEqualsGhgIntensity()
      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.

      Returns:
      The GHG intensity value with volume normalized GHG in tCO2e per kg.

    • getEqualsGhgIntensityFor

      EngineNumber getEqualsGhgIntensityFor(UseKey useKey)
      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.

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

    • getEqualsEnergyIntensity

      EngineNumber getEqualsEnergyIntensity()
      Retrieve the energy intensity for the current application and substance.
      Returns:
      The energy intensity value, typically in kwh / unit (yearly).

    • getEqualsEnergyIntensityFor

      EngineNumber getEqualsEnergyIntensityFor(UseKey useKey)
      Retrieve the energy intensity for the given UseKey.
      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

      void changeStream(String stream, EngineNumber amount, YearMatcher yearMatcher, UseKey useKey)
      Change a stream value by a delta amount.
      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

    • changeStream

      void changeStream(String stream, EngineNumber amount, YearMatcher yearMatcher)
      Change a stream value by a delta amount with default scope.
      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

    • cap

      void cap(String stream, EngineNumber amount, YearMatcher yearMatcher, String displaceTarget, DisplacementType displacementType)
      Cap a stream at a maximum value.
      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

      void floor(String stream, EngineNumber amount, YearMatcher yearMatcher, String displaceTarget, DisplacementType displacementType)
      Set a minimum floor value for a stream.
      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

      void replace(EngineNumber amountRaw, String stream, String destinationSubstance, YearMatcher yearMatcher)
      Replace an amount from one substance with another.
      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

      List<EngineResult> getResults()
      Get the results for all registered substances.
      Returns:
      List of results for each registered substance

    • getOptimizeRecalcs

      boolean getOptimizeRecalcs()
      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.

      Returns:
      true if optimizations are enabled, false otherwise