Package org.kigalisim.engine.support

Class NewEquipmentToSalesInterpreter

java.lang.Object
org.kigalisim.engine.support.NewEquipmentToSalesInterpreter
public class NewEquipmentToSalesInterpreter extends Object
Handles newEquipment stream operations by converting them into sales operations.

Unlike EquipmentChangeUtil, this class never needs to retire prior stock: newEquipment is a purely marginal (delta) quantity recomputed fresh each year, so every operation bottoms out in a sales change or set rather than a retirement.

  • Constructor Details

    • NewEquipmentToSalesInterpreter

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

  • Method Details

    • handleChange

      public void handleChange(EngineNumber changeAmount)
      Handle changing newEquipment by a delta amount (percent or absolute, any units).

      Caller is responsible for checking year range before calling this method.

      Parameters:
      changeAmount - The change amount (bare "%" or absolute in units/kg/mt/tCO2e)

    • handleSet

      public void handleSet(EngineNumber targetNewEquipment)
      Handle setting newEquipment to a target value (absolute in units/kg/mt/tCO2e, or bare percent).

      Caller is responsible for checking year range before calling this method.

      Unit-based targets ("unit"/"units") are set directly as an absolute sales value in units: the existing implicit-recharge machinery for unit-tracked sales automatically adds recharge and precharge volume on top, so no extra accounting is needed here.

      Mass-based targets (kg/mt/tCO2e) represent only the equipment-forming portion of sales (matching how newEquipment itself is defined as (salesKg - rechargeKg - prechargeKg) / initialCharge). To land sales at a value that reproduces exactly this target after the next population recalc subtracts recharge/precharge again, this method explicitly adds the current recharge and precharge volume (in kg) on top before setting sales in kg.

      Bare percent (decision 3) resolves against this year's already-computed newEquipment value (pre-adjustment), mirroring how EquipmentChangeUtil.handleChange(org.kigalisim.engine.number.EngineNumber) resolves percent against currentEquipment for the equipment stream.

      Parameters:
      targetNewEquipment - The target value: bare "%" or absolute in units/kg/mt/tCO2e

    • handleCap

      public void handleCap(EngineNumber capValue, String displaceTarget, DisplacementType displacementType)
      Handle capping newEquipment to a maximum value (absolute or percent-of-own-history).

      Caller is responsible for checking year range before calling this method (SingleThreadEngine.cap already checks getIsInRange before dispatching, same as it does for the "equipment" case).

      Per decision 2, all four percent forms ("%", "% prior year", "% current year", "% current") resolve against newEquipment's own raw stream history (prior-year or current-year), never against sales's lastSpecifiedValue or UnitConverter's percent machinery -- see resolveLimitTargetUnits(org.kigalisim.engine.number.EngineNumber, org.kigalisim.engine.number.EngineNumber, org.kigalisim.engine.number.UnitConverter). Absolute values are converted to a units delta and applied via changeStream("sales", ...); no explicit recharge/precharge adjustment is needed since a marginal newEquipment delta always equals the same marginal sales delta (recharge/precharge are computed from priorEquipment, fixed for the year, and cancel out of any delta-based comparison).

      Displacement reuses DisplaceExecutor with "sales" as the displaced-stream identifier (not "newEquipment") since the reduction was just applied as a sales change, and passing the derived stream name would be silently clobbered by the destination substance's next population recalc.

      Parameters:
      capValue - The maximum newEquipment level: absolute in units/kg/mt/tCO2e, or one of the four percent forms ("%", "% prior year", "% current year", "% current")
      displaceTarget - Optional substance/stream to displace the excess to (null for no displacement)
      displacementType - The displacement mode (EQUIVALENT, BY_VOLUME, or BY_UNITS)

    • handleFloor

      public void handleFloor(EngineNumber floorValue, String displaceTarget, DisplacementType displacementType)
      Handle flooring newEquipment to a minimum value (absolute or percent-of-own-history).

      Caller is responsible for checking year range before calling this method (SingleThreadEngine.floor already checks getIsInRange before dispatching, same as it does for the "equipment" case).

      Per decision 2, all four percent forms ("%", "% prior year", "% current year", "% current") resolve against newEquipment's own raw stream history (prior-year or current-year), never against sales's lastSpecifiedValue or UnitConverter's percent machinery -- see resolveLimitTargetUnits(org.kigalisim.engine.number.EngineNumber, org.kigalisim.engine.number.EngineNumber, org.kigalisim.engine.number.UnitConverter), shared unchanged with handleCap(org.kigalisim.engine.number.EngineNumber, java.lang.String, org.kigalisim.lang.operation.DisplacementType). Absolute values are converted to a units delta and applied via changeStream("sales", ...); no explicit recharge/precharge adjustment is needed since a marginal newEquipment delta always equals the same marginal sales delta (recharge/precharge are computed from priorEquipment, fixed for the year, and cancel out of any delta-based comparison).

      Displacement reuses DisplaceExecutor with "sales" as the displaced-stream identifier (not "newEquipment"), exactly as handleCap(org.kigalisim.engine.number.EngineNumber, java.lang.String, org.kigalisim.lang.operation.DisplacementType) does, and for the same reason: the raise was just applied as a sales change, and passing the derived stream name would be silently clobbered by the destination substance's next population recalc. Because DisplaceExecutor.execute negates changeAmount before applying it to the displacement target, a positive (raising) deltaUnits here correctly *reduces* the displacement target -- e.g. "floor newEquipment to X displacing SubB" raises this substance and reduces SubB by the same amount, the mirror image of cap's displacement direction.

      Parameters:
      floorValue - The minimum newEquipment level: absolute in units/kg/mt/tCO2e, or one of the four percent forms ("%", "% prior year", "% current year", "% current")
      displaceTarget - Optional substance/stream to displace the deficit from (null for no displacement)
      displacementType - The displacement mode (EQUIVALENT, BY_VOLUME, or BY_UNITS)