Simulated Battery

Configurable battery with realistic physics, efficiency losses, thermal effects, degradation, and optional inverter simulation.

Quick Start with Presets

{
  "Name": "home-battery",
  "DeviceClass": "SimulatedBattery",
  "AssetType": "Battery",
  "SimulatedBattery": {
    "ConfigurationModel": "MediumResidential"
  }
}

See Battery Presets for all available models.

Custom Configuration

{
  "Name": "sim-battery",
  "DeviceClass": "SimulatedBattery",
  "AssetType": "Battery",
  "SimulatedBattery": {
    "ConfigurationModel": "Custom",
    "CapacityWh": 100000.0,
    "InitialSoC": 50.0,
    "InitialSoH": 95.0,
    "MaxPowerW": 100000.0,
    "RoundTripEfficiency": 0.90,
    "Inverter": {
      "Enabled": true,
      "RatedPowerVA": 120000.0,
      "MaxDischargePowerW": 100000.0,
      "MaxChargePowerW": 100000.0
    }
  }
}

Configuration Options

Core Properties

Property	Description	Default
CapacityWh	Battery capacity in watt-hours	100,000 Wh (100 kWh)
InitialSoC	Initial state of charge percentage	50%
InitialSoH	Initial state of health percentage	95%
InitialTemperatureC	Initial temperature in Celsius	25°C
RoundTripEfficiency	Round-trip efficiency as decimal	0.90 (90%)
MaxPowerW	Maximum charge/discharge power in watts	100,000 W (100 kW)
MinVoltage	Minimum voltage at 0% SoC	360 V
MaxVoltage	Maximum voltage at 100% SoC	420 V

Energy Registers & Cycles

Property	Description	Default
InitialImportRegisterWh	Initial import energy register	1,500,000 Wh
InitialExportRegisterWh	Initial export energy register	1,200,000 Wh
InitialCycles	Initial cycle count	120

Chemistry

Property	Description	Default
Chemistry	Battery chemistry type	LiIon

Chemistry options:

• LiIon - Lithium-Ion (NMC/NCA): 360-420V, gradual S-curve with steeper slopes at extremes
• LiFePO4 - Lithium Iron Phosphate: 320-365V, flat voltage plateau between 10-90% SoC
• SodiumIon - Sodium-Ion: 300-380V, more linear curve than Li-Ion

Cooling System

Property	Description	Default
Cooling	Cooling system type	ActiveAir
AmbientTemperatureC	Ambient air temperature	20°C
CoolantTemperatureC	Coolant temperature for liquid cooling	25°C

Cooling options:

Type	Description	Cooling Factor
PassiveAir	Natural convection	0.2× (slowest)
ActiveAir	Forced air circulation	1.0× (baseline)
LiquidCooling	Water/glycol circulation	3.0× (fastest)
Chiller	Active refrigeration cycle	Precise setpoint control

Degradation

Property	Description	Default
DegradationPerCyclePercent	SoH degradation per full cycle	0.1%
MinSoH	Minimum state of health percentage	70%

Pack & Cell Configuration

Property	Description	Default
PackCount	Number of battery packs	1
CellsPerPack	Number of cells per pack	96
CapacityPerPackWh	Capacity per pack in Wh	Calculated
CellVoltageVariationV	Max voltage variation between cells (±V)	0.02 V (±20 mV)
PackTemperatureVariationC	Temperature variation between packs (±°C)	2.0 °C
CellTemperatureVariationC	Temperature variation within a pack (±°C)	1.0 °C
PRateC	Power-to-capacity ratio (1.0 = 1C)	Calculated

Thermal Properties

Property	Description	Default
IdlePowerW	Idle energy consumption for BMS and cooling	50 W
ThermalThresholdW	Power threshold for thermal effects	50,000 W
HeatingRateCPerHour	Temperature rise rate at high power	0.5 °C/hr
CoolingRateCPerHour	Base cooling rate	0.2 °C/hr
MaxTemperatureC	Maximum operating temperature	45°C
ThermalDeratingThresholdC	Temperature for power derating	40°C
ThermalDeratingFactor	Power derating factor at high temp	0.95 (5% reduction)

Inverter Configuration

When enabled, the battery's DC power is converted through the inverter before grid connection.

"Inverter": {
  "Enabled": true,
  "RatedPowerVA": 250000.0,
  "MaxDischargePowerW": 250000.0,
  "MaxChargePowerW": 250000.0,
  "PeakEfficiency": 0.98,
  "NominalACVoltageV": 230.0,
  "StandbyPowerLossW": 400.0,
  "MaxOperatingTemperatureC": 60.0
}

Property	Description	Default
Enabled	Enable inverter simulation	false
RatedPowerVA	Inverter rated power (VA)	250,000 VA
MaxDischargePowerW	Maximum discharge (export) power on AC side	250,000 W
MaxChargePowerW	Maximum charge (import) power on AC side	250,000 W
PeakEfficiency	Peak conversion efficiency (0.0-1.0)	0.98 (98%)
NominalACVoltageV	Nominal AC voltage (line-to-neutral)	230 V
StandbyPowerLossW	Standby power consumption	400 W
MaxOperatingTemperatureC	Maximum operating temperature	60°C

Inverter features:

• Variable efficiency based on load (peak at 30-70% load)
• Separate charge/discharge limits on AC side
• Temperature rises with conversion losses
• Reactive power control (configurable power factor and VAr setpoints)
• AC voltage, current, frequency, and power factor metrics

The system's effective power is limited by both the battery's MaxPowerW (DC side) and the inverter's limits (AC side).

Per-Pack and Per-Cell Tracking

The battery supports detailed per-pack and per-cell voltage and temperature tracking.

Hierarchy

Battery System
├── Pack 0
│   ├── Cell 0
│   ├── Cell 1
│   └── ... (CellsPerPack cells)
├── Pack 1
│   ├── Cell 0
│   └── ...
└── ... (PackCount packs)

Cell Statistics Metrics

Metric	Description
MaxCellVoltage	Highest voltage across all cells
MinCellVoltage	Lowest voltage across all cells
AvgCellVoltage	Average voltage across all cells
MaxCellTemperature	Highest temperature across all cells
MinCellTemperature	Lowest temperature across all cells
AvgCellTemperature	Average temperature across all cells

Implementation Details

• Deterministic initialization: Same asset name produces identical cell values
• Voltage drift: ±2 mV per update simulates natural cell imbalance
• Temperature drift: ±0.05 °C per update for realistic thermal variation

Use Cases

• Health monitoring: Compare MaxCellVoltage and MinCellVoltage to detect cell imbalance (>100 mV indicates degradation)
• Thermal management: Monitor MaxCellTemperature to trigger cooling or power derating (>40°C threshold)
• Pack-level analysis: Iterate through Packs collection to analyze individual pack behavior

Power Setpoint Convention

• Positive = discharge (export to grid)
• Negative = charge (import from grid)

Use GetPowerLimits() to check max charge/discharge based on current SoC and temperature.

Examples

Large Commercial Battery (250 kWh)

{
  "Name": "commercial-battery",
  "DeviceClass": "SimulatedBattery",
  "AssetType": "Battery",
  "SimulatedBattery": {
    "ConfigurationModel": "Custom",
    "CapacityWh": 250000.0,
    "MaxPowerW": 200000.0,
    "InitialSoC": 80.0,
    "RoundTripEfficiency": 0.92,
    "Chemistry": "LiIon",
    "Inverter": {
      "Enabled": true,
      "RatedPowerVA": 250000.0,
      "MaxDischargePowerW": 200000.0,
      "MaxChargePowerW": 200000.0,
      "PeakEfficiency": 0.98
    }
  }
}

Residential LiFePO4 Battery (13.5 kWh)

{
  "Name": "home-battery",
  "DeviceClass": "SimulatedBattery",
  "AssetType": "Battery",
  "SimulatedBattery": {
    "ConfigurationModel": "Custom",
    "CapacityWh": 13500.0,
    "MaxPowerW": 5000.0,
    "InitialSoC": 50.0,
    "MinVoltage": 320.0,
    "MaxVoltage": 365.0,
    "Chemistry": "LiFePO4",
    "Inverter": {
      "Enabled": true,
      "RatedPowerVA": 6000.0,
      "MaxDischargePowerW": 5000.0,
      "MaxChargePowerW": 5000.0
    }
  }
}

Overriding Preset Properties

{
  "Name": "customized-residential",
  "DeviceClass": "SimulatedBattery",
  "AssetType": "Battery",
  "SimulatedBattery": {
    "ConfigurationModel": "LargeResidential",
    "InitialSoC": 80.0,
    "RoundTripEfficiency": 0.92
  }
}