Distribution Battery#
- pydantic model gdm.distribution.components.DistributionBattery#
Data model for battery system in distribution system models.
Show JSON schema
{ "title": "DistributionBattery", "description": "Data model for battery system in distribution system models.", "type": "object", "properties": { "uuid": { "format": "uuid", "title": "Uuid", "type": "string" }, "name": { "title": "Name", "type": "string" }, "substation": { "anyOf": [ { "$ref": "#/$defs/DistributionSubstation" }, { "type": "null" } ], "default": null, "description": "Name of the substation." }, "feeder": { "anyOf": [ { "$ref": "#/$defs/DistributionFeeder" }, { "type": "null" } ], "default": null, "description": "Name of the feeder." }, "in_service": { "default": true, "description": "Is the component in service?", "title": "In Service", "type": "boolean" }, "bus": { "$ref": "#/$defs/DistributionBus", "description": "Distribution bus to which this battery is connected to." }, "phases": { "description": "List of phases at which this battery is connected to in the same order.", "items": { "$ref": "#/$defs/Phase" }, "title": "Phases", "type": "array" }, "active_power": { "description": "Current active power output of the battery.", "title": "Active Power" }, "reactive_power": { "description": "Current reactive power output of the battery.", "title": "Reactive Power" }, "controller": { "anyOf": [ { "$ref": "#/$defs/InverterController" }, { "type": "null" } ], "default": null, "description": "Controller settings to control output of the inverter" }, "inverter": { "$ref": "#/$defs/InverterEquipment", "description": "Inverter equipment for the distribution battery system." }, "equipment": { "$ref": "#/$defs/BatteryEquipment", "description": "Battery model." } }, "$defs": { "ActivePowerInverterControllerBase": { "additionalProperties": false, "description": "Data model for Inverter controllers that control active power.", "properties": { "uuid": { "format": "uuid", "title": "Uuid", "type": "string" }, "name": { "default": "", "description": "Name of the inverter controller.", "title": "Name", "type": "string" } }, "title": "ActivePowerInverterControllerBase", "type": "object" }, "BatteryEquipment": { "additionalProperties": false, "description": "Data model for Solar Model.", "properties": { "uuid": { "format": "uuid", "title": "Uuid", "type": "string" }, "name": { "title": "Name", "type": "string" }, "rated_energy": { "description": "Rated energy capacity (DC) of the battery.", "title": "Rated Energy", "type": "string" }, "rated_power": { "description": "Rated power of the battery", "title": "Rated Power", "type": "string" }, "charging_efficiency": { "description": "Charging efficiency of the battery.", "maximum": 100.0, "minimum": 0.0, "title": "Charging Efficiency", "type": "number" }, "discharging_efficiency": { "description": "Discharging efficiency of the battery.", "maximum": 100.0, "minimum": 0.0, "title": "Discharging Efficiency", "type": "number" }, "idling_efficiency": { "description": "Idling efficiency of the battery.", "maximum": 100.0, "minimum": 0.0, "title": "Idling Efficiency", "type": "number" }, "rated_voltage": { "description": "Rated voltage for this battery equipment.", "ge": 0, "title": "Rated Voltage" }, "voltage_type": { "$ref": "#/$defs/VoltageTypes", "description": "Rated voltage is line to line or line to neutral." } }, "required": [ "name", "rated_energy", "rated_power", "charging_efficiency", "discharging_efficiency", "idling_efficiency", "rated_voltage", "voltage_type" ], "title": "BatteryEquipment", "type": "object" }, "Curve": { "additionalProperties": false, "description": "An interface for representing a curve using x and y points. e.g for volt-var and volt-watt curves.\n\nExamples\n--------\n\nExample of a Curve (Volt-Var IEEE-1547 standard).\n\n>>> Curve(\n curve_x=[0.5, 0.92, 0.98, 1.02, 1.08, 1.5], curve_y=[1.0, 1.0, 0.0, 0.0, -1.0, -1.0]\n )\n\nExample of a Curve (Volt-Var Volt-Watt IEEE-1547 standard)\n\n>>> Curve(curve_x=[0.5, 1.06, 1.1, 1.5], curve_y=[1.0, 1.0, 0.0, 0.0])", "properties": { "uuid": { "format": "uuid", "title": "Uuid", "type": "string" }, "name": { "default": "", "description": "Name of the curve.", "title": "Name", "type": "string" }, "curve_x": { "anyOf": [ { "items": { "type": "number" }, "type": "array" }, {} ], "description": "The x values of the curve", "title": "Curve X" }, "curve_y": { "anyOf": [ { "items": { "type": "number" }, "type": "array" }, {} ], "description": "The y values of the curve", "title": "Curve Y" } }, "required": [ "curve_x", "curve_y" ], "title": "Curve", "type": "object" }, "DistributionBus": { "additionalProperties": false, "description": "Data model for distribution bus.\n\nExamples:\n >>> from gdm import DistributionBus\n >>> DistributionBus.example()", "properties": { "uuid": { "format": "uuid", "title": "Uuid", "type": "string" }, "name": { "title": "Name", "type": "string" }, "substation": { "anyOf": [ { "$ref": "#/$defs/DistributionSubstation" }, { "type": "null" } ], "default": null, "description": "Name of the substation." }, "feeder": { "anyOf": [ { "$ref": "#/$defs/DistributionFeeder" }, { "type": "null" } ], "default": null, "description": "Name of the feeder." }, "in_service": { "default": true, "description": "Is the component in service?", "title": "In Service", "type": "boolean" }, "voltage_type": { "$ref": "#/$defs/VoltageTypes", "description": "Voltage types for buses." }, "phases": { "description": "List of phases for this bus.", "items": { "$ref": "#/$defs/Phase" }, "title": "Phases", "type": "array" }, "voltagelimits": { "default": [], "description": "List of voltage limit sets for this bus.", "items": { "$ref": "#/$defs/VoltageLimitSet" }, "title": "Voltagelimits", "type": "array" }, "rated_voltage": { "description": "rated voltage for this bus.", "title": "Rated Voltage", "type": "string" }, "coordinate": { "anyOf": [ { "$ref": "#/$defs/Location" }, { "type": "null" } ], "default": null, "description": "Coordinate for the power system bus." } }, "required": [ "name", "voltage_type", "phases", "rated_voltage" ], "title": "DistributionBus", "type": "object" }, "DistributionFeeder": { "additionalProperties": false, "description": "Class interface for distribution feeder.", "properties": { "uuid": { "format": "uuid", "title": "Uuid", "type": "string" }, "name": { "title": "Name", "type": "string" } }, "required": [ "name" ], "title": "DistributionFeeder", "type": "object" }, "DistributionSubstation": { "additionalProperties": false, "description": "Class interface for distribution feeder.", "properties": { "uuid": { "format": "uuid", "title": "Uuid", "type": "string" }, "name": { "title": "Name", "type": "string" }, "feeders": { "description": "List of feeders for this substation.", "items": { "$ref": "#/$defs/DistributionFeeder" }, "title": "Feeders", "type": "array" } }, "required": [ "name", "feeders" ], "title": "DistributionSubstation", "type": "object" }, "InverterController": { "additionalProperties": false, "description": "Inverter contoller represent the complete control settings for a given\nInverterEquipment. This model may be used with an instance of DistributionSolar,\nDistributionBattery or any other model that has an inverter.", "properties": { "uuid": { "format": "uuid", "title": "Uuid", "type": "string" }, "name": { "default": "", "description": "Name of the inverter controller.", "title": "Name", "type": "string" }, "active_power_control": { "anyOf": [ { "$ref": "#/$defs/ActivePowerInverterControllerBase" }, { "type": "null" } ], "default": null, "description": "Controller settings to control active power output of the inverter" }, "reactive_power_control": { "anyOf": [ { "$ref": "#/$defs/ReactivePowerInverterControllerBase" }, { "type": "null" } ], "default": null, "description": "Controller settings to control reactive power output of the inverter" }, "prioritize_active_power": { "description": "If True, the controller tries to prioritize active power.", "title": "Prioritize Active Power", "type": "boolean" }, "night_mode": { "description": "If True, the controller controls reactive power even when there is no active power.", "title": "Night Mode", "type": "boolean" } }, "required": [ "prioritize_active_power", "night_mode" ], "title": "InverterController", "type": "object" }, "InverterEquipment": { "additionalProperties": false, "description": "Data model for inverter equipment.", "properties": { "uuid": { "format": "uuid", "title": "Uuid", "type": "string" }, "name": { "default": "", "description": "Name of the inverter controller.", "title": "Name", "type": "string" }, "rated_apparent_power": { "description": "Apparent power rating for the inverter.", "title": "Rated Apparent Power", "type": "string" }, "rise_limit": { "description": "The rise in power output allowed per unit of time", "title": "Rise Limit", "type": "string" }, "fall_limit": { "description": "The fall in power output allowed per unit of time", "title": "Fall Limit", "type": "string" }, "cutout_percent": { "description": "If the per-unit power drops below this value the PV output is turned off.", "maximum": 100.0, "minimum": 0.0, "title": "Cutout Percent", "type": "number" }, "cutin_percent": { "description": "If the per-unit power rises above this value the PV output is turned on.", "maximum": 100.0, "minimum": 0.0, "title": "Cutin Percent", "type": "number" }, "dc_to_ac_efficiency": { "description": "DC to AC efficiency of the inverter.", "maximum": 100.0, "minimum": 0.0, "title": "Dc To Ac Efficiency", "type": "number" }, "eff_curve": { "anyOf": [ { "$ref": "#/$defs/Curve" }, { "type": "null" } ], "default": null, "description": "Efficency curve for inverter." } }, "required": [ "rated_apparent_power", "rise_limit", "fall_limit", "cutout_percent", "cutin_percent", "dc_to_ac_efficiency" ], "title": "InverterEquipment", "type": "object" }, "LimitType": { "description": "Operational limit types.", "enum": [ "min", "max" ], "title": "LimitType", "type": "string" }, "Location": { "additionalProperties": false, "description": "Specifies geographic location.", "properties": { "uuid": { "format": "uuid", "title": "Uuid", "type": "string" }, "name": { "default": "", "title": "Name", "type": "string" }, "x": { "title": "X", "type": "number" }, "y": { "title": "Y", "type": "number" }, "crs": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Crs" } }, "required": [ "x", "y" ], "title": "Location", "type": "object" }, "Phase": { "description": "This class is used to represent a single phase from a set of possible values.", "enum": [ "A", "B", "C", "N", "S1", "S2" ], "title": "Phase", "type": "string" }, "ReactivePowerInverterControllerBase": { "additionalProperties": false, "description": "Data model for Inverter controllers that control reactive power.", "properties": { "uuid": { "format": "uuid", "title": "Uuid", "type": "string" }, "name": { "default": "", "description": "Name of the inverter controller.", "title": "Name", "type": "string" } }, "title": "ReactivePowerInverterControllerBase", "type": "object" }, "VoltageLimitSet": { "additionalProperties": false, "description": "Data model for voltage limit set.", "properties": { "uuid": { "format": "uuid", "title": "Uuid", "type": "string" }, "name": { "default": "", "description": "Name of the voltage limit set.", "title": "Name", "type": "string" }, "limit_type": { "$ref": "#/$defs/LimitType", "description": "Limit type used." }, "value": { "description": "Voltage threshold.", "title": "Value", "type": "string" } }, "required": [ "limit_type", "value" ], "title": "VoltageLimitSet", "type": "object" }, "VoltageTypes": { "description": "Identifier of voltage types referenced in distribution models.", "enum": [ "line-to-line", "line-to-ground" ], "title": "VoltageTypes", "type": "string" } }, "additionalProperties": false, "required": [ "name", "bus", "phases", "active_power", "reactive_power", "inverter", "equipment" ] }
- Config:
str_strip_whitespace: bool = True
validate_assignment: bool = True
validate_default: bool = True
extra: str = forbid
use_enum_values: bool = False
arbitrary_types_allowed: bool = True
populate_by_name: bool = True
- Fields:
active_power (infrasys.quantities.ActivePower)bus (gdm.distribution.components.distribution_bus.DistributionBus)controller (gdm.distribution.controllers.distribution_inverter_controller.InverterController | None)equipment (gdm.distribution.equipment.battery_equipment.BatteryEquipment)feeder (gdm.distribution.components.distribution_feeder.DistributionFeeder | None)in_service (bool)inverter (gdm.distribution.equipment.inverter_equipment.InverterEquipment)name (str)phases (list[gdm.distribution.enums.Phase])reactive_power (gdm.quantities.ReactivePower)substation (gdm.distribution.components.distribution_substation.DistributionSubstation | None)uuid (uuid.UUID)
- Validators:
validate_controller_types»all fields
- field active_power: Annotated[ActivePower, FieldInfo(annotation=NoneType, required=True, description='Current active power output of the battery.')] [Required]#
Current active power output of the battery.
- Validated by:
validate_controller_types
- field bus: Annotated[DistributionBus, FieldInfo(annotation=NoneType, required=True, description='Distribution bus to which this battery is connected to.')] [Required]#
Distribution bus to which this battery is connected to.
- Validated by:
validate_controller_types
- field controller: Annotated[InverterController | None, FieldInfo(annotation=NoneType, required=False, default=None, description='Controller settings to control output of the inverter')] = None#
Controller settings to control output of the inverter
- Validated by:
validate_controller_types
- field equipment: Annotated[BatteryEquipment, FieldInfo(annotation=NoneType, required=True, description='Battery model.')] [Required]#
Battery model.
- Validated by:
validate_controller_types
- field feeder: Annotated[DistributionFeeder | None, Field(None, description='Name of the feeder.')] = None#
Name of the feeder.
- Validated by:
validate_controller_types
- field in_service: Annotated[bool, Field(True, description='Is the component in service?')] = True#
Is the component in service?
- Validated by:
validate_controller_types
- field inverter: Annotated[InverterEquipment, FieldInfo(annotation=NoneType, required=True, description='Inverter equipment for the distribution battery system.')] [Required]#
Inverter equipment for the distribution battery system.
- Validated by:
validate_controller_types
- field phases: Annotated[list[Phase], FieldInfo(annotation=NoneType, required=True, description='List of phases at which this battery is connected to in the same order.')] [Required]#
List of phases at which this battery is connected to in the same order.
- Validated by:
validate_controller_types
- field reactive_power: Annotated[ReactivePower, FieldInfo(annotation=NoneType, required=True, description='Current reactive power output of the battery.')] [Required]#
Current reactive power output of the battery.
- Validated by:
validate_controller_types
- field substation: Annotated[DistributionSubstation | None, Field(None, description='Name of the substation.')] = None#
Name of the substation.
- Validated by:
validate_controller_types
- classmethod aggregate(instances: list[DistributionBattery], bus: DistributionBus, name: str, split_phase_mapping: dict[str, set[Phase]]) DistributionBattery#
Aggregates multiple DistributionBattery instances into a single instance.
This method combines the properties of multiple DistributionBattery instances connected to the same bus into a single DistributionBattery instance. It calculates the aggregate phases, equipment ratings, and efficiencies based on the provided instances.
- Parameters:
instances (list[DistributionBattery]) – List of DistributionBattery instances to be aggregated.
bus (DistributionBus) – The bus to which the aggregated battery is connected.
name (str) – The name for the aggregated DistributionBattery.
split_phase_mapping (dict[str, set[Phase]]) – Mapping of battery names to their respective split phases.
- Returns:
A new DistributionBattery instance representing the aggregate of the provided instances.
- Return type:
- validator validate_controller_types » all fields#