🔋 BESSMAXX — API Diagnostics

1. Simulation Timing & Workflow

The model runs sequentially day-by-day. For each day, it follows this strict order of operations:

1. Data Sorting: Input data is strictly sorted chronologically to ensure accurate rolling windows and SOC tracking.
2. Day-Ahead (DA) Clearing:
   • The model looks at the DA Price Forecast to identify the best hours to sell.
   • It constructs an Offer Curve (10 price legs: L1–L5 charge, L6–L10 discharge) based on your volatility settings.
   • It clears these offers against the Actual DA LMP.
   • Constraint: The total cleared volume is limited by both your DA Discharge Limit (MW) and DA Energy Limit (MWh).
3. Charge Scheduling:
   • After knowing the discharge obligation, the model schedules charging in the cheapest hours (lowest RT Forecast LMP) prior to the discharge.
   • Hurdle Check: Charging is only scheduled if the RT Forecast is lower than the (Daily Avg Charge + Hurdle).
4. Opportunistic Charging:
   • Bid-Curve Based: The model generates an hourly planned charge MW from the charge bid ladder (L1–L5). This planned MW is what you would be willing to charge at various price levels.
   • Intent Flag: Separately, the model marks certain hours as intended charge hours based on the RT price forecast and required charge volume. This does not force clearing; it is a diagnostic so you can see where the optimizer expected to charge.
   • Clearing Rule: Whether planned MW actually clears is determined by the actual RT LMP relative to the RT charge legs for DA support (lower RT LMP → more charge MW clears; higher RT LMP → less or none clears).
   • Why this helps: This avoids bias where “planned hours” automatically clear. The market clears against a bid curve, so we let the RT LMP decide what portion of the ladder clears.
5. Real-Time (RT) Balancing:
   • The model steps through the day in Real-Time to check for Bailout Conditions and Opportunistic Conditions.
   • Start SOC: The model initializes with the user-defined Start SOC.
6. State of Charge (SOC) Update:
   • The battery's energy level is updated hourly based on actual physical flow.

2. Charge Bailout Logic (Risk Management)

The "Bailout" logic protects you from discharging when it is no longer profitable, or when it is cheaper to simply buy back your obligation from the grid.

• Trigger: The model calculates an Expected Charge Cost for the day. If the Actual RT LMP during a discharge hour is lower than (Expected Charge Cost + RT Bail Hurdle), the model "Bails".
• Action: The physical battery does not discharge. Instead, the model settles the financial obligation by buying the power back at the current low RT price.
• Capacity Re-use: Any capacity freed up by a bailout is automatically made available for Ancillary Services.

3. Opportunistic Discharge (RT Inc)

If the Real-Time price spikes unexpectedly high, the model can discharge additional energy on top of its DA schedule.

• Trigger: Two conditions must be met: 1. Actual RT LMP must exceed the generated Offer Curve legs. 2. Actual RT LMP must be greater than (Daily Avg Charge Price + RT Inc Hurdle).
• Constraints: The actual incremental discharge is limited by RT Discharge Limits, remaining SOC (minus Min Reserve), and inverter headroom.

4. State of Charge (SOC) Management

• Tracking: SOC_t = SOC_{t-1} + (Charge_MW * Efficiency) - Discharge_MW.
• Min SOC Enforcement: 1. In RT, the model will reduce DA delivery if Current SOC - Min SOC is insufficient. 2. At EOD, if the SOC falls below Minimum SOC Reserve, it forces "Reserve Charging" to refill the tank.

5. Ancillary Services (AS)

Any capacity not physically used for energy (DA delivery, RT buyback, RT incremental discharge, or RT charging) is assumed to be available to bid into Spinning Reserve and Short Term Reserve (STR).

• Shoulder vs Off-Shoulder: The model allows AS to clear outside the main energy window (outside HE 9 through HE 18) up to 100% of the Power Rating (MW), subject to remaining headroom after any RT charging/discharging that hour.
• Charging Interaction: When the plant is charging, the available headroom for AS can increase (because energy dispatch is in the opposite direction), so you may see additional SPIN/STR MW clear in those hours.
• Pricing: AS revenue is settled using the RT MCP for each service (Spin/STR) for that hour, regardless of whether the battery is charging or discharging.

6. Intended SOC vs Actual SOC

The combined SOC / RT LMP / rolling throughput chart shows two inventory paths. Actual SOC is the realized path after actual DA and RT LMP clearing, actual RT charge clearing, buybacks, and physical DA/RT discharge. Intended SOC is the model's expected inventory path using planned RT charge before actual RT clearing and the DA/RT discharge plan. The gap between these two lines is the clearest visual signal of missed charge, unexpected bailouts, or unintended charge clearing.

7. Equivalent Full Cycles and Throughput Accounting

Equivalent Full Cycles are calculated from discharge throughput only: physical DA/RT discharge plus regulation SOC drift MWh divided by usable energy capacity. This avoids double-counting the same cycle by counting both charge and discharge while still capturing regulation drift as discharge-equivalent wear. Charge throughput and rolling 24-hour throughput are still tracked separately because they matter for operating limits, thermal intensity, and warranty-style throughput monitoring.

• Charge Throughput: actual RT charge MWh.
• Discharge Throughput: physical DA delivery plus RT incremental discharge plus regulation SOC drift MWh.
• Rolling 24h Throughput: charge plus discharge over the trailing 24 hours.
• DA Energy Cycles: physical DA discharge divided by usable energy capacity.
• RT Incremental Cycles: RT incremental discharge divided by usable energy capacity.
• ASM Estimated Cycles: reserved as a separate bucket. In this JavaScript backtest, spin and STR are treated as capacity awards and do not create deployment MWh unless an explicit deployment/drift input is added.

10. Target SOC, Recovery Charging, and SOC Scarcity Premiums

Target SOC Reserve is treated as a preferred inventory target, not as a hard RT dispatch stop. If actual RT LMP clears a submitted discharge leg, the model can dispatch below the target SOC. The separate Hard Minimum SOC is the physical floor used to limit dispatch feasibility.

• Below target: the model creates SOC recovery debt equal to the grid MWh needed to restore SOC to Target SOC plus the recovery buffer.
• RT charge legs: when SOC is below target, the model switches to SOC_RECOVERY charge mode and raises RT charge bid prices by the SOC scarcity premium. Higher charge bid prices make recovery charge more likely to clear.
• RT discharge legs: the same scarcity premium is added to incremental RT discharge offers, making additional depletion more expensive without hard-blocking dispatch.
• Audit fields: tooltips and hourly exports include SOC Target, Hard Min SOC, SOC Shortfall, SOC Scarcity Premium, SOC Recovery Debt, SOC Recovery Charge Planned/Cleared, and RT charge/discharge ladder premiums.

8. Price vs Dispatch Tooltip

The Price vs Dispatch tooltip is intended to be an hourly audit panel. It shows RT charge legs for DA support, DA/RT discharge legs, RT charge legs, DA target offer, RT target offer, bail threshold, incremental threshold, RT charge mode, RT discharge mode, actual dispatch, intended SOC, actual SOC, and any binding constraints. Highlighted leg cells indicate the ladder price pair that cleared or was economically active for that hour.

Naming note: “RT Charge Legs for DA Support” means the model builds real-time charge bid curves during the Day-Ahead bidding pass to support DA discharge obligations. These are not Day-Ahead charge awards. Actual charge still clears later against RT LMP, where a charge bid clears when RT LMP is less than or equal to the submitted charge leg price.

9. Current JS Backtest vs Future MILP Engine

This browser model remains a deterministic walk-forward backtest. It uses ladder-based clearing, inventory-style SOC tracking, deterministic bailout rules, and post-run diagnostics. The future Python solver core can formalize this into the hybrid MILP architecture: DA candidate selection, DA-cleared rebalance, paired-cost bookkeeping, deterministic bail layer, and RT incremental optimization.