Package org.kigalisim.engine.support

Class LimitExecutor

java.lang.Object
org.kigalisim.engine.support.LimitExecutor
public class LimitExecutor extends Object
Executor for cap and floor limit operations on streams.

  • Constructor Details

    • LimitExecutor

      public LimitExecutor(Engine engine)
      Creates a new LimitExecutor for the given engine.
      Parameters:
      engine - The Engine instance to operate on

  • Method Details

    • executeCap

      public void executeCap(String stream, EngineNumber amount, YearMatcher yearMatcher, String displaceTarget, DisplacementType displacementType)
      Executes a cap operation to limit a stream to a maximum value.

      Cap operations enforce maximum constraints on stream values, reducing the stream if it exceeds the specified limit. This is commonly used for policy scenarios like manufacturing caps, import quotas, and consumption limits.

      For percentage-based caps (e.g., "cap to 85%"), the limit is calculated relative to the lastSpecifiedValue rather than the current calculated value. This enables year-over-year compounding effects. For example, if the user specified "set domestic to 1000 mt" in a previous year, then "cap to 85%" in the current year, the cap will be 850 mt (85% of 1000), not 85% of the current calculated domestic value which may include recharge adjustments.

      If the current stream value exceeds the cap:

      1. The stream is reduced to the cap value via StreamUpdate
      2. If displacement is specified, the reduction is offset through DisplaceExecutor
      Parameters:
      stream - The stream identifier to cap (e.g., "domestic", "import", "sales")
      amount - The maximum value (percentage or absolute)
      yearMatcher - Matcher to determine if the cap applies to current year
      displaceTarget - Optional target for displacement (stream or substance), or null
      displacementType - The type of displacement (EQUIVALENT, BY_VOLUME, or BY_UNITS)

    • executeFloor

      public void executeFloor(String stream, EngineNumber amount, YearMatcher yearMatcher, String displaceTarget, DisplacementType displacementType)
      Executes a floor operation to enforce a minimum value on a stream.

      Floor operations enforce minimum constraints on stream values, increasing the stream if it falls below the specified limit. This is commonly used for policy scenarios like minimum production requirements, guaranteed import levels, and baseline consumption mandates.

      For percentage-based floors (e.g., "floor to 80%"), the limit is calculated relative to the lastSpecifiedValue rather than the current calculated value. This enables year-over-year compounding effects. For example, if the user specified "set domestic to 1000 mt" in a previous year, then "floor to 80%" in the current year, the floor will be 800 mt (80% of 1000), not 80% of the current calculated domestic value which may include recharge adjustments.

      If the current stream value falls below the floor:

      1. The stream is increased to the floor value via StreamUpdate
      2. If displacement is specified, the increase is offset through DisplaceExecutor
      Parameters:
      stream - The stream identifier to floor (e.g., "domestic", "import", "sales")
      amount - The minimum value (percentage or absolute)
      yearMatcher - Matcher to determine if the floor applies to current year
      displaceTarget - Optional target for displacement (stream or substance), or null
      displacementType - The type of displacement (EQUIVALENT, BY_VOLUME, or BY_UNITS)