h2integrate.storage.battery.pysam_battery

Functions

dummy_function()

Classes

BatteryOutputs(n_timesteps, n_control_window)
PySAMBatteryPerformanceModel(**kwargs)	OpenMDAO component wrapping the PySAM Battery Performance model.
PySAMBatteryPerformanceModelConfig(*, ...[, ...])	Configuration class for battery performance models.

class h2integrate.storage.battery.pysam_battery.BatteryOutputs(n_timesteps, n_control_window)

I: Sequence

P: Sequence

Q: Sequence

SOC: Sequence

T_batt: Sequence

gen: Sequence

n_cycles: Sequence

P_chargeable: Sequence

P_dischargeable: Sequence

unmet_demand: list[float]

unused_commodity: list[float]

Container for simulated outputs from the BatteryStateful and H2I dispatch models.

I

Battery current [A] per timestep.

Type:

Sequence

P

Battery power [kW] per timestep.

Type:

Sequence

Q

Battery capacity [Ah] per timestep.

Type:

Sequence

SOC

State of charge [%] per timestep.

Type:

Sequence

T_batt

Battery temperature [°C] per timestep.

Type:

Sequence

gen

Generated power [kW] per timestep.

Type:

Sequence

n_cycles

Cumulative rainflow cycles since start of simulation [1].

Type:

Sequence

P_chargeable

Maximum estimated chargeable power [kW] per timestep.

Type:

Sequence

P_dischargeable

Maximum estimated dischargeable power [kW] per timestep.

Type:

Sequence

unmet_demand

Unmet demand [kW] per timestep.

Type:

list[float]

unused_commodity

Unused available commodity [kW] per timestep.

Type:

list[float]

export()

class h2integrate.storage.battery.pysam_battery.PySAMBatteryPerformanceModelConfig(*, max_capacity, max_charge_rate, system_model_source, chemistry, min_charge_percent, max_charge_percent, init_charge_percent, n_control_window=24, n_horizon_window=48, control_variable='input_power', ref_module_capacity=400, ref_module_surface_area=30)

Configuration class for battery performance models.

This class defines configuration parameters for simulating battery performance in PySAM system models. It includes specifications such as capacity, chemistry, state-of-charge limits, and reference module characteristics.

Parameters:

• max_capacity (float)

• max_charge_rate (float)

• system_model_source (str)

• chemistry (str)

• min_charge_percent (float)

• max_charge_percent (float)

• init_charge_percent (float)

• n_control_window (int)

• n_horizon_window (int)

• control_variable (str)

• ref_module_capacity (int | float)

• ref_module_surface_area (int | float)

max_capacity

Maximum battery energy capacity in kilowatt-hours (kWh). Must be greater than zero.

Type:

float

max_charge_rate

Rated power capacity of the battery in kilowatts (kW). Must be greater than zero.

Type:

float

system_model_source

Source software for the system model. "hopp" source has not been brought over from HOPP yet. Options are:

• "pysam"

Type:

str

chemistry

Battery chemistry option. "LDES" has not been brought over from HOPP yet. Supported values include:

• PySAM: "LFPGraphite", "LMOLTO", "LeadAcid", "NMCGraphite"

Type:

str

min_charge_percent

Minimum allowable state of charge as a fraction (0 to 1).

Type:

float

max_charge_percent

Maximum allowable state of charge as a fraction (0 to 1).

Type:

float

init_charge_percent

Initial state of charge as a fraction (0 to 1).

Type:

float

n_control_window

Number of timesteps in the control window. Defaults to 24.

Type:

int, optional

n_horizon_window

Number of timesteps in the horizon window. Defaults to 48.

Type:

int, optional

control_variable

Control mode for the PySAM battery, either "input_power" or "input_current".

Type:

str

ref_module_capacity

Reference module capacity in kilowatt-hours (kWh). Defaults to 400.

Type:

int | float, optional

ref_module_surface_area

Reference module surface area in square meters (m²). Defaults to 30.

Type:

int | float, optional

max_capacity: float

max_charge_rate: float

system_model_source: str

chemistry: str

min_charge_percent: float

max_charge_percent: float

init_charge_percent: float

n_control_window: int

n_horizon_window: int

control_variable: str

ref_module_capacity: int | float

ref_module_surface_area: int | float

class h2integrate.storage.battery.pysam_battery.PySAMBatteryPerformanceModel(**kwargs)

OpenMDAO component wrapping the PySAM Battery Performance model.

This class integrates the NREL PySAM BatteryStateful model into an OpenMDAO component. It provides inputs and outputs for battery capacity, charge/discharge power, state of charge, and unmet or unused demand.

The PySAM battery simulation does not always respect max and min charge bounds set by the user. It may exceed the bounds by up to 5% SOC.

config

Configuration parameters for the battery performance model.

Type:

PySAMBatteryPerformanceModelConfig

system_model

Instance of the PySAM BatteryStateful model, initialized with the selected chemistry and configuration parameters.

Type:

BatteryStateful

outputs

Container for simulation outputs such as SOC, chargeable/dischargeable power, unmet demand, and unused commodities.

Type:

BatteryOutputs

unmet_demand

Tracks unmet demand during simulation (kW).

Type:

float

unused_commodity

Tracks unused commodity during simulation (kW).

Type:

float

Inputs:

max_charge_rate (float):

Battery charge rate in kilowatts per hour (kW).

storage_capacity (float):

Total energy storage capacity in kilowatt-hours (kWh).

electricity_demand (ndarray):

Power demand time series (kW).

electricity_in (ndarray):

Commanded input electricity (kW), typically from dispatch.

Outputs:

P_chargeable (ndarray):

Maximum chargeable power (kW).

P_dischargeable (ndarray):

Maximum dischargeable power (kW).

unmet_demand_out (ndarray):

Remaining unmet demand after discharge (kW).

unused_commodity_out (ndarray):

Unused energy not absorbed by the battery (kW).

electricity_out (ndarray):

Dispatched electricity to meet demand (kW), including electricity from electricity_in that was never used to charge the battery and battery_electricity_discharge.

SOC (ndarray):

Battery state of charge (%).

battery_electricity_discharge (ndarray):

Electricity output from the battery model (kW).

setup()

Defines model inputs, outputs, configuration, and connections to plant-level dispatch (if applicable).

compute(inputs, outputs, discrete_inputs, discrete_outputs)

Runs the PySAM BatteryStateful model for a simulation timestep, updating outputs such as SOC, charge/discharge limits, unmet demand, and unused commodities.

simulate(electricity_in, electricity_demand, time_step_duration, control_variable,

sim_start_index=0): Simulates the battery behavior across timesteps using either input power or input current as control. This method is similar to what is provided in typical compute methods in H2Integrate for running models, but needs to be a separate method here to allow the dispatch function to call and manage the performance model.

_set_control_mode(control_mode=1.0, input_power=0.0, input_current=0.0,

control_variable="input_power"): Sets the battery control mode (power or current).

Notes

• Default timestep is 1 hour (dt=1.0).

• State of charge (SOC) bounds are set using the configuration's min_charge_percent and max_charge_percent.

• If a Pyomo dispatch solver is provided, the battery will simulate dispatch decisions using solver inputs.

setup()

Set up the PySAM Battery Performance model in OpenMDAO.

Initializes the configuration, defines inputs/outputs for OpenMDAO, and creates a BatteryStateful instance with the selected chemistry. If dispatch connections are specified, it also sets up a discrete input for Pyomo solver integration.

compute(inputs, outputs, discrete_inputs=[], discrete_outputs=[])

Run the PySAM Battery model for one simulation step.

Configures the battery stateful model parameters (SOC limits, timestep, thermal properties, etc.), executes the simulation, and stores the results in OpenMDAO outputs.

Parameters:

• inputs (dict) -- Continuous input values (e.g., electricity_in, electricity_demand).

• outputs (dict) -- Dictionary where model outputs (SOC, P_chargeable, unmet demand, etc.) are written.

• discrete_inputs (dict) -- Discrete inputs such as control mode or Pyomo solver.

• discrete_outputs (dict) -- Discrete outputs (unused in this component).

simulate(storage_dispatch_commands, time_step_duration, control_variable, sim_start_index=0)

Run the PySAM BatteryStateful model over a control window.

Applies a sequence of dispatch commands (positive = discharge, negative = charge) one timestep at a time. Each command is clipped to allowable instantaneous charge / discharge limits derived from:

1. Rated power (config.max_charge_rate)

2. PySAM internal estimates (P_chargeable / P_dischargeable)

3. Remaining energy headroom vs. SOC bounds

The method updates internal rolling arrays in self.outputs in-place using sim_start_index as an offset (enabling sliding / receding horizon logic).

The simulate method is much of what would normally be in the compute() method of a component, but is separated into its own function here to allow the dispatch() method to manage calls to the performance model.

Parameters:

• storage_dispatch_commands (list) -- Sequence[float] Commanded power per timestep (kW). Negative = charge, positive = discharge. Length should be = config.n_control_window.

• time_step_duration (list) -- float | Sequence[float] Timestep duration in hours. Scalar applied uniformly or sequence matching len(storage_dispatch_commands).

• control_variable (str) -- str PySAM control input to set each step ("input_power" or "input_current").

• sim_start_index (int) -- int, optional Starting index for writing into persistent output arrays (default 0).

Returns:

tuple[np.ndarray, np.ndarray]

(battery_power_kW, soc_percent) battery_power_kW : array of PySAM P values (kW) per timestep

(positive = discharge, negative = charge).

soc_percent : array of SOC values (%) per timestep.

Notes

• SOC bounds may still be exceeded slightly due to PySAM internal dynamics.

• self.outputs.stateful_attributes are updated only if the attribute exists

in StatePack or StateCell. - self.outputs.component_attributes (e.g., unmet_demand) are not modified here; they are populated in compute(), unless an external dispatcher manages them.

_set_control_mode(control_mode=1.0, input_power=0.0, input_current=0.0, control_variable='input_power')

Set the control mode for the PySAM BatteryStateful model.

Configures whether the battery operates in power-control or current-control mode and initializes input values.

Parameters:

• control_mode (float, optional) -- Mode flag: 1.0 for power control, 0.0 for current control. Defaults to 1.0.

• input_power (float, optional) -- Initial power input (kW). Defaults to 0.0.

• input_current (float, optional) -- Initial current input (A). Defaults to 0.0.

• control_variable (str, optional) -- Control variable name, either "input_power" or "input_current". Defaults to "input_power".

h2integrate.storage.battery.pysam_battery.dummy_function()