h2integrate.storage.battery.pysam_battery

Classes

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

class h2integrate.storage.battery.pysam_battery.PySAMBatteryPerformanceModelConfig(*, min_soc_fraction, max_soc_fraction, demand_profile, max_capacity, max_charge_rate, chemistry, init_soc_fraction, control_variable='input_power', ref_module_capacity=400, ref_module_surface_area=30, Cp=900, battery_h=20, resistance=0.001)

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:

• min_soc_fraction (float)

• max_soc_fraction (float)

• demand_profile (int | float | list)

• max_capacity (float)

• max_charge_rate (float)

• chemistry (str)

• init_soc_fraction (float)

• control_variable (str)

• ref_module_capacity (int | float)

• ref_module_surface_area (int | float)

• Cp (int | float)

• battery_h (int | float)

• resistance (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

demand_profile

Demand values for each timestep, in the same units as commodity_rate_units. May be a scalar for constant demand or a list/array for time-varying demand.

Type:

int | float | list

chemistry

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

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

Type:

str

min_soc_fraction

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

Type:

float

max_soc_fraction

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

Type:

float

init_soc_fraction

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

Type:

float

control_variable

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

Type:

str

ref_module_capacity

Reference module capacity in kWh. Defaults to 400.

Type:

int | float, optional

ref_module_surface_area

Reference module surface area in m². Defaults to 30.

Type:

int | float, optional

Cp

Battery specific heat capacity [J/kg*K]. Defaults to 900.

Type:

int | float, optional

battery_h

Heat transfer between battery and environment [W/m2*K]. Defaults to 20.

Type:

int | float, optional

resistance

Battery internal resistance [Ohm]. Defaults to 0.001.

Type:

int | float, optional

max_capacity: float

max_charge_rate: float

chemistry: str

init_soc_fraction: float

control_variable: str

ref_module_capacity: int | float

ref_module_surface_area: int | float

Cp: int | float

battery_h: int | float

resistance: int | float

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

OpenMDAO component wrapping the PySAM Battery Performance model.

This class integrates the NLR 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.

system_model

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

Type:

BatteryStateful

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.

_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).

_time_step_bounds = (3600, 3600)

initialize()

Perform any one-time initialization run at instantiation.

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.

simulate(storage_dispatch_commands, charge_rate, discharge_rate, storage_capacity, 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 or discharge limits derived from:

1. Rated power (config.max_charge_rate)

2. PySAM internal estimates (P_chargeable and P_dischargeable)

3. Remaining energy headroom vs. SOC bounds

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.

• control_variable – 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).

• charge_rate (float)

• discharge_rate (float)

• storage_capacity (float)

Returns:

tuple[np.ndarray, np.ndarray] – Battery power (kW) and SOC (%) per timestep.

Notes

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

_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”.