CSE User's Manual

California Simulation Engine


BATTERY describes input data for a model of an energy-storage system which is not tied to any specific energy storage technology. The battery model integrates the energy added and removed (accounting for efficiency losses). Note: although we use the term battery, the underlying model is flexible enough to model any energy storage system.

The modeler can set limits and constraints on capacities and flows and the associated efficiencies for this model.


Name of the battery system. Given after the word BATTERY.

UnitsLegal RangeDefaultRequiredVariability
63 characters*noneNoconstant


Name of a METER to which the BATTERY’s charge/discharge energy flows are recorded. Battery energy flows are accumulated to meter end use “BT”. Battery energy flows are seen from the standpoint of a “load” on the electric grid, so charges to the BATTERY system are positive values while discharges from the BATTERY system are negative values.

Note btMeter also determines the source for the probe value loadSeen. See discussion and example under btChgReq (below).

UnitsLegal RangeDefaultRequiredVariability
meter namenoneNoconstant


The charging efficiency of storing electricity into the BATTERY system. A value of 1.0 means that no energy is lost and 100% of charge energy enters and is stored in the battery.

UnitsLegal RangeDefaultRequiredVariability
0 < x \(\le\) 10.975Nohourly


The discharge efficiency for when the BATTERY system is discharging power. A value of 1.0 means that no energy is lost and 100% of discharge energy leaves the system.

UnitsLegal RangeDefaultRequiredVariability
0 < x \(\le\) 10.975Nohourly


This is the maximum amount of energy that can be stored in the BATTERY system in kilowatt-hours. Once the BATTERY has reached its maximum capacity, no additional energy will be stored.

UnitsLegal RangeDefaultRequiredVariability
kWhx \(\ge\) 016Noconstant


The initial state of energy of the BATTERY system as a fraction of the total capacity. If btInitSOE is specified, the battery state-of-energy at the beginning of the actual simulation will be set to the amount specified, regardless of whether there was a warm-up period or not. If btInitSOE is NOT specififed, it will default to 1.0 (i.e., 100%) at the beginning of the warmup period (if any).

UnitsLegal RangeDefaultRequiredVariability
0 \(\le\) x \(\le\) 01.0Noconstant


The number of cycles on the battery at the beginning of the run.

UnitsLegal RangeDefaultRequiredVariability
number of cyclesx \(\ge\) 00Norunly


The maximum rate at which the BATTERY can be charged in kilowatts (i.e., energy flowing into the BATTERY).

UnitsLegal RangeDefaultRequiredVariability
kWx \(\ge\) 04Nohourly


The maximum rate at which the BATTERY can be discharged in kilowatts (i.e., energy flowing out of the BATTERY).

UnitsLegal RangeDefaultRequiredVariability
kWx \(\ge\) 04Nohourly


Selects charge/discharge control algorithm. btChgReq (next) specifies the desired battery charge or discharge rate. btControlAlg allows selection of alternative algorithms for deriving btChgReq.

DEFAULTbtChgReq is used as input or defaulted (see below)
TDVPEAKSAVEbtChgReq input (if any) is ignored. Instead, a California-specific algorithm is used that saves battery charge until peak TDV (Time Dependant Valuation) hours of the day, shifting energy generated on site (e.g. PV) to supply feed the grid during critical periods. The algorithm requires availability of hourly TDV data, see Top.tdvFName.

Note btControlAlg has hourly variability, allowing dynamic algorithm selection. In California compliance applications, TDVPEAKSAVE is typically used only on days with high TDV peaks.

UnitsLegal RangeDefaultRequiredVariability


The power request to charge (or discharge if negative) the battery. If omitted, the default strategy is used (attempt to satisfy all loads and absorb all available excess power). btChgReq and the default strategy requested power are literally requests: that is, more power will not be delivered than is available; more power will not be absorbed than capacity exits to store; and the battery’s power limits will be respected.

btChgReq can be set by an expression to allow complex energy management/dispatch strategies. These approaches typically involve the BATTERY probe value loadSeen, which is the net electricity use (not including the battery) on the meter specified by btMeter (above). When loadSeen is positive, electricity input (e.g. from the grid) is required; when negative, excess electrical energy is available from photovoltaic generation. loadSeen can be used in btChgReq expressions such as –

btChgReq = select(
    $hour>=9 && $hour<=20,-min(@BATTERY[ 1].loadSeen, 0), // hrs 9 - 20: charge when surplus energy
    default -max( @BATTERY[ 1].loadSeen, 0))              // else: discharge when energy is required

The sign conventions here are tricky. min(@BATTERY [ 1].loadSeen, 0) produces a value <=0 that is the negative of the amount of surplus energy available. A positive btChgReq value requests charging, hence “-” (minus sign) in front of the min(). Conversely, max( @BATTERY [ 1].loadSeen, 0) results in a value >= 0 indicating the net energy needed by the building. To request discharge, btChgReq must be negative, so “-” is also needed in the discharge expression. (The @BATTERY [1] references mean “this battery”, assuming there is only one battery being modelled. In multi-battery situations, the current BATTERY’s index or name must be included within the “[ ]”.)

UnitsLegal RangeDefaultRequiredVariability
kWbtMeter net loadNohourly


Former yes/no choice that currently has no effect. Deprecated, will be removed in a future version.


Optionally indicates the end of the BATTERY definition. Alternatively, the end of the definition can be indicated by END or by beginning another object.

UnitsLegal RangeDefaultRequiredVariability

Related Probes: