Components¶
pyconvexity.models.components
¶
Component management operations for PyConvexity.
Provides CRUD operations for energy system components (buses, generators, loads, etc.) with proper validation and error handling.
get_component_type(conn: sqlite3.Connection, component_id: int) -> str
¶
Get component type for a component ID.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
conn
|
Connection
|
Database connection |
required |
component_id
|
int
|
ID of the component |
required |
Returns:
| Type | Description |
|---|---|
str
|
Component type string (e.g., "BUS", "GENERATOR") |
Raises:
| Type | Description |
|---|---|
ComponentNotFound
|
If component doesn't exist |
get_component(conn: sqlite3.Connection, component_id: int) -> Component
¶
Get component by ID (single network per database).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
conn
|
Connection
|
Database connection |
required |
component_id
|
int
|
ID of the component |
required |
Returns:
| Type | Description |
|---|---|
Component
|
Component object with all fields populated |
Raises:
| Type | Description |
|---|---|
ComponentNotFound
|
If component doesn't exist |
list_components_by_type(conn: sqlite3.Connection, component_type: Optional[str] = None) -> List[Component]
¶
List components by type (single network per database).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
conn
|
Connection
|
Database connection |
required |
component_type
|
Optional[str]
|
Optional component type filter (e.g., "BUS", "GENERATOR") |
None
|
Returns:
| Type | Description |
|---|---|
List[Component]
|
List of Component objects |
insert_component(conn: sqlite3.Connection, request: CreateComponentRequest) -> int
¶
Insert a new component (single network per database).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
conn
|
Connection
|
Database connection |
required |
request
|
CreateComponentRequest
|
Component creation request with all necessary fields |
required |
Returns:
| Type | Description |
|---|---|
int
|
ID of the newly created component |
Raises:
| Type | Description |
|---|---|
DatabaseError
|
If insertion fails |
ValidationError
|
If required fields are missing |
create_component(conn: sqlite3.Connection, component_type: str, name: str, description: Optional[str] = None, longitude: Optional[float] = None, latitude: Optional[float] = None, carrier_id: Optional[int] = None, bus_id: Optional[int] = None, bus0_id: Optional[int] = None, bus1_id: Optional[int] = None) -> int
¶
Create a component and return its ID - convenience function (single network per database).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
conn
|
Connection
|
Database connection |
required |
component_type
|
str
|
Type of component (e.g., "BUS", "GENERATOR") |
required |
name
|
str
|
Component name |
required |
description
|
Optional[str]
|
Optional description |
None
|
longitude
|
Optional[float]
|
Optional longitude coordinate |
None
|
latitude
|
Optional[float]
|
Optional latitude coordinate |
None
|
carrier_id
|
Optional[int]
|
Optional carrier ID |
None
|
bus_id
|
Optional[int]
|
Optional bus ID (for single-bus components) |
None
|
bus0_id
|
Optional[int]
|
Optional first bus ID (for two-bus components) |
None
|
bus1_id
|
Optional[int]
|
Optional second bus ID (for two-bus components) |
None
|
Returns:
| Type | Description |
|---|---|
int
|
ID of the newly created component |
update_component(conn: sqlite3.Connection, component_id: int, name: Optional[str] = None, description: Optional[str] = None, longitude: Optional[float] = None, latitude: Optional[float] = None, carrier_id: Optional[int] = None, bus_id: Optional[int] = None, bus0_id: Optional[int] = None, bus1_id: Optional[int] = None) -> None
¶
Update a component.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
conn
|
Connection
|
Database connection |
required |
component_id
|
int
|
ID of component to update |
required |
name
|
Optional[str]
|
New name (optional) |
None
|
description
|
Optional[str]
|
New description (optional) |
None
|
longitude
|
Optional[float]
|
New longitude (optional) |
None
|
latitude
|
Optional[float]
|
New latitude (optional) |
None
|
carrier_id
|
Optional[int]
|
New carrier ID (optional) |
None
|
bus_id
|
Optional[int]
|
New bus ID (optional) |
None
|
bus0_id
|
Optional[int]
|
New first bus ID (optional) |
None
|
bus1_id
|
Optional[int]
|
New second bus ID (optional) |
None
|
Raises:
| Type | Description |
|---|---|
ComponentNotFound
|
If component doesn't exist |
delete_component(conn: sqlite3.Connection, component_id: int) -> None
¶
Delete a component and all its attributes.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
conn
|
Connection
|
Database connection |
required |
component_id
|
int
|
ID of component to delete |
required |
Raises:
| Type | Description |
|---|---|
ComponentNotFound
|
If component doesn't exist |
list_component_attributes(conn: sqlite3.Connection, component_id: int) -> List[str]
¶
List all attribute names for a component.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
conn
|
Connection
|
Database connection |
required |
component_id
|
int
|
Component ID |
required |
Returns:
| Type | Description |
|---|---|
List[str]
|
List of attribute names |
get_component_by_name(conn: sqlite3.Connection, name: str) -> Component
¶
Get a component by name (single network per database).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
conn
|
Connection
|
Database connection |
required |
name
|
str
|
Component name |
required |
Returns:
| Type | Description |
|---|---|
Component
|
Component object |
Raises:
| Type | Description |
|---|---|
ComponentNotFound
|
If component doesn't exist |
get_component_id(conn: sqlite3.Connection, name: str) -> int
¶
Get component ID by name (single network per database).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
conn
|
Connection
|
Database connection |
required |
name
|
str
|
Component name |
required |
Returns:
| Type | Description |
|---|---|
int
|
Component ID |
Raises:
| Type | Description |
|---|---|
ComponentNotFound
|
If component doesn't exist |
component_exists(conn: sqlite3.Connection, name: str) -> bool
¶
Check if a component exists (single network per database).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
conn
|
Connection
|
Database connection |
required |
name
|
str
|
Component name |
required |
Returns:
| Type | Description |
|---|---|
bool
|
True if component exists, False otherwise |
get_component_carrier_map(conn: sqlite3.Connection, component_type: Optional[str] = None) -> Dict[str, str]
¶
Get mapping from component names to carrier names (single network per database).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
conn
|
Connection
|
Database connection |
required |
component_type
|
Optional[str]
|
Optional component type filter |
None
|
Returns:
| Type | Description |
|---|---|
Dict[str, str]
|
Dictionary mapping component names to carrier names |
get_default_carrier_id(conn: sqlite3.Connection, component_type: str) -> int
¶
Get default carrier ID for a component type (single network per database).
ensure_unmet_load_for_bus(conn: sqlite3.Connection, bus_id: int, bus_name: str, unmet_load_active: bool) -> None
¶
Ensure there is exactly one UNMET_LOAD per bus (single network per database).
get_bus_name_to_id_map(conn: sqlite3.Connection) -> Dict[str, int]
¶
Get mapping from bus names to component IDs (single network per database).