VeraGridEngine.IO.ucte package

Subpackages

• VeraGridEngine.IO.ucte.devices package
  • Submodules
  • VeraGridEngine.IO.ucte.devices.ucte_base module
    • coalesce_number()
    • is_defined_number()
    • sub_float()
    • sub_int()
    • sub_optional_float()
    • sub_optional_int()
    • sub_optional_str()
    • sub_str()
    • try_float()
    • try_int()
    • try_optional_float()
    • try_optional_int()
    • ucte_split()
  • VeraGridEngine.IO.ucte.devices.ucte_circuit module
    • UcteCircuit
      • UcteCircuit.check_file_extension()
      • UcteCircuit.fuse_comments()
      • UcteCircuit.get_transformer_regulation()
      • UcteCircuit.get_transformers_tap_table()
      • UcteCircuit.normalize()
      • UcteCircuit.parse_file()
      • UcteCircuit.summary()
  • VeraGridEngine.IO.ucte.devices.ucte_comment module
    • UcteComment
      • UcteComment.parse()
  • VeraGridEngine.IO.ucte.devices.ucte_exchange_power module
    • UcteExchangePower
      • UcteExchangePower.parse()
  • VeraGridEngine.IO.ucte.devices.ucte_line module
    • UcteLine
      • UcteLine.is_active_and_reducible()
      • UcteLine.parse()
  • VeraGridEngine.IO.ucte.devices.ucte_node module
    • UcteNode
      • UcteNode.has_gen()
      • UcteNode.has_load()
      • UcteNode.is_generator()
      • UcteNode.is_regulating_voltage()
      • UcteNode.normalize()
      • UcteNode.parse()
    • get_default_power_limit()
    • try_parse_voltage()
  • VeraGridEngine.IO.ucte.devices.ucte_transformer module
    • UcteTransformer
      • UcteTransformer.get_primary_key()
      • UcteTransformer.is_active_and_reducible()
      • UcteTransformer.parse()
  • VeraGridEngine.IO.ucte.devices.ucte_transformer_regulation module
    • UcteTransformerRegulation
      • UcteTransformerRegulation.get_primary_key()
      • UcteTransformerRegulation.has_angle_regulation()
      • UcteTransformerRegulation.has_phase_regulation()
      • UcteTransformerRegulation.normalize()
      • UcteTransformerRegulation.parse()
  • VeraGridEngine.IO.ucte.devices.ucte_transformer_tap_table module
    • UcteTransformerTapTable
      • UcteTransformerTapTable.get_primary_key()
      • UcteTransformerTapTable.parse()
  • Module contents

Submodules

VeraGridEngine.IO.ucte.ucte_to_veragrid module

VeraGridEngine.IO.ucte.ucte_to_veragrid.add_fixed_shunt_from_ucte_line(grid: MultiCircuit, ucte_elm, bus: Bus)

VeraGridEngine.IO.ucte.ucte_to_veragrid.add_standard_line(grid: MultiCircuit, ucte_elm, bus_f: Bus, bus_t: Bus, active: bool, reducible: bool, logger: Logger)

VeraGridEngine.IO.ucte.ucte_to_veragrid.add_switch(grid: MultiCircuit, code: str, name: str, current_limit: float | None, bus_f: Bus, bus_t: Bus, active: bool, reducible: bool)

VeraGridEngine.IO.ucte.ucte_to_veragrid.add_switch_from_line(grid: MultiCircuit, ucte_elm, bus_f: Bus, bus_t: Bus, active: bool, reducible: bool)

VeraGridEngine.IO.ucte.ucte_to_veragrid.add_switch_from_transformer(grid: MultiCircuit, ucte_elm, bus_f: Bus, bus_t: Bus, active: bool, reducible: bool)

VeraGridEngine.IO.ucte.ucte_to_veragrid.add_transformer_from_mismatch_line(grid: MultiCircuit, ucte_elm, bus_f: Bus, bus_t: Bus)

VeraGridEngine.IO.ucte.ucte_to_veragrid.apply_tap_table(elm: Transformer2W, ucte_elm, tap_tables, low_tap_position: int, current_tap_number: int, logger: Logger)

VeraGridEngine.IO.ucte.ucte_to_veragrid.build_current_tap_state(regulator, tap_type: TapChangerTypes) → tuple[float, float]

VeraGridEngine.IO.ucte.ucte_to_veragrid.build_tap_changer_type(regulator) → TapChangerTypes

VeraGridEngine.IO.ucte.ucte_to_veragrid.build_technologies(grid: MultiCircuit) → dict[str, Technology]

VeraGridEngine.IO.ucte.ucte_to_veragrid.build_transformer_tap_data(ucte_elm, regulator, tap_tables, bus_f: Bus, bus_t: Bus, invert_fixed_tap: bool, logger: Logger)

VeraGridEngine.IO.ucte.ucte_to_veragrid.build_xnode_active_line_counts(ucte_grid: UcteCircuit, logger: Logger) → dict[str, int]

VeraGridEngine.IO.ucte.ucte_to_veragrid.choose_tap_number(regulator) → int

VeraGridEngine.IO.ucte.ucte_to_veragrid.compute_switch_rate(bus_f: Bus, bus_t: Bus, current_limit: float | None) → float

VeraGridEngine.IO.ucte.ucte_to_veragrid.compute_tap_span(regulator, tap_tables) → tuple[int, int]

VeraGridEngine.IO.ucte.ucte_to_veragrid.convert_ucte_to_veragrid(ucte_grid: UcteCircuit, logger: Logger) → MultiCircuit

Convert UCTE grid to VeraGrid.

VeraGridEngine.IO.ucte.ucte_to_veragrid.discover_nominal_voltages(ucte_grid: UcteCircuit) → Dict[str, float]

Attempt to discover the nominal voltage for each level character.

VeraGridEngine.IO.ucte.ucte_to_veragrid.get_current_limit_a(current_limit: float | None) → float

VeraGridEngine.IO.ucte.ucte_to_veragrid.get_current_limit_ka(current_limit: float | None) → float

VeraGridEngine.IO.ucte.ucte_to_veragrid.get_default_power_limit() → float

VeraGridEngine.IO.ucte.ucte_to_veragrid.has_zero_transformer_impedance(ucte_elm, tol: float = 1e-09) → bool

VeraGridEngine.IO.ucte.ucte_to_veragrid.is_canonical_ucte_node_code(node_code: str) → bool

VeraGridEngine.IO.ucte.ucte_to_veragrid.is_fictitious_shunt_code(node_code: str) → bool

VeraGridEngine.IO.ucte.ucte_to_veragrid.is_fictitious_shunt_line(ucte_elm, tol: float = 1e-09) → bool

VeraGridEngine.IO.ucte.ucte_to_veragrid.is_fictitious_shunt_node(ucte_node) → bool

VeraGridEngine.IO.ucte.ucte_to_veragrid.is_standard_ucte_country_code(country_code: str) → bool

VeraGridEngine.IO.ucte.ucte_to_veragrid.is_xnode_code(node_code: str) → bool

VeraGridEngine.IO.ucte.ucte_to_veragrid.parse_exchange_power(ucte_grid: UcteCircuit, grid: MultiCircuit, bus_dict: Dict[str, Bus], logger: Logger)

Exchange powers are currently ignored by the VeraGrid UCTE importer.

VeraGridEngine.IO.ucte.ucte_to_veragrid.parse_lines(ucte_grid: UcteCircuit, grid: MultiCircuit, bus_dict: Dict[str, Bus], logger: Logger)

Parse UCTE lines and couplers.

VeraGridEngine.IO.ucte.ucte_to_veragrid.parse_nodes(ucte_grid: UcteCircuit, grid: MultiCircuit, logger: Logger) → Dict[str, Bus]

Create buses and their injections.

VeraGridEngine.IO.ucte.ucte_to_veragrid.parse_transformer(ucte_grid: UcteCircuit, grid: MultiCircuit, bus_dict: Dict[str, Bus], logger: Logger)

Parse UCTE transformers.

VeraGridEngine.IO.ucte.ucte_to_veragrid.repair_nominal_voltages_from_references(ucte_grid: UcteCircuit, logger: Logger)

Fix clearly inconsistent nominal voltages in non-canonical UCTE variants.

If Vref/Vnom is outside a realistic range for steady-state operation, infer Vnom from Vref directly using a conservative nominal-level palette.

VeraGridEngine.IO.ucte.ucte_to_veragrid.same_nominal_voltage(bus_f: Bus, bus_t: Bus, tol: float = 1e-06) → bool

VeraGridEngine.IO.ucte.ucte_to_veragrid.should_import_mismatch_line_as_transformer(ucte_elm, bus_f: Bus, bus_t: Bus) → bool

VeraGridEngine.IO.ucte.ucte_to_veragrid.snap_nominal_voltage_from_reference(voltage_reference: float) → float

VeraGridEngine.IO.ucte.ucte_to_veragrid.use_legacy_ucte_transformer_orientation(ucte_elm, bus_node1: Bus, bus_node2: Bus) → bool

VeraGridEngine.IO.ucte.veragrid_to_ucte module

class VeraGridEngine.IO.ucte.veragrid_to_ucte.UcteBranchCounter

Bases: object

Assign one-character UCTE order codes per branch endpoint pair.

get_next_code(node_1: str, node_2: str, logger: Logger) → str

Get the next order code for one endpoint pair.

Parameters:

• node_1 – First node code.

• node_2 – Second node code.

• logger – Export logger.

Returns:

One-character UCTE order code.

class VeraGridEngine.IO.ucte.veragrid_to_ucte.UcteBusAggregate

Bases: object

Store the bus-level values required by one exported UCTE node.

active_gen_mw: float

active_load_mw: float

has_generation_limits: bool

has_generation_record: bool

max_gen_mvar: float

max_gen_mw: float

min_gen_mvar: float

min_gen_mw: float

node_type: int

plant_type: str

reactive_gen_mvar: float

reactive_load_mvar: float

shunt_b_mvar: float

status: int

voltage_reference_kv: float

VeraGridEngine.IO.ucte.veragrid_to_ucte.add_generator_like_device(aggregate: UcteBusAggregate, device: Generator | Battery | StaticGenerator, t_idx: int | None) → None

Add one generator-like device to the bus aggregate using UCTE sign semantics.

Parameters:

• aggregate – Target bus aggregate.

• device – Generator-like device.

• t_idx – Optional profile index.

Returns:

None.

VeraGridEngine.IO.ucte.veragrid_to_ucte.add_load_like_device(aggregate: UcteBusAggregate, device: Load | ExternalGrid, t_idx: int | None, logger: Logger) → None

Add one load-like device to the bus aggregate.

Parameters:

• aggregate – Target bus aggregate.

• device – Load or load-mode external grid.

• t_idx – Optional profile index.

• logger – Export logger.

Returns:

None.

VeraGridEngine.IO.ucte.veragrid_to_ucte.build_bus_aggregate(circuit: MultiCircuit, bus: Bus, bus_injections: Dict[Bus, Dict[object, List[object]]], t_idx: int | None, logger: Logger) → UcteBusAggregate

Aggregate all supported VeraGrid injections attached to one bus.

Parameters:

• circuit – Circuit to export.

• bus – Bus to aggregate.

• bus_injections – Bus-grouped injection lookup.

• t_idx – Optional profile index.

• logger – Export logger.

Returns:

Filled node aggregate.

VeraGridEngine.IO.ucte.veragrid_to_ucte.build_bus_node_code_map(circuit: MultiCircuit, logger: Logger) → Dict[Bus, str]

Build one deterministic UCTE node-code map for every exported bus.

Parameters:

• circuit – Circuit to export.

• logger – Export logger.

Returns:

Bus-to-node-code mapping.

VeraGridEngine.IO.ucte.veragrid_to_ucte.build_shunt_node_code(bus_code: str) → str

Build the fictitious-shunt node code paired to one exported bus code.

Parameters:

bus_code – Main bus node code.

Returns:

Fictitious-shunt node code.

VeraGridEngine.IO.ucte.veragrid_to_ucte.format_line_row(node_1: str, node_2: str, order_code: str, status: int, resistance_ohm: float, reactance_ohm: float, susceptance_us: float, current_limit_a: float, name: str) → str

Format one UCTE line record.

Parameters:

• node_1 – First node code.

• node_2 – Second node code.

• order_code – One-character order code.

• status – UCTE status code.

• resistance_ohm – Series resistance in ohm.

• reactance_ohm – Series reactance in ohm.

• susceptance_us – Total shunt susceptance in uS.

• current_limit_a – Current limit in A.

• name – Device name.

Returns:

Line row text.

VeraGridEngine.IO.ucte.veragrid_to_ucte.format_node_row(node_code: str, bus: Bus, aggregate: UcteBusAggregate) → str

Format one UCTE node record.

Parameters:

• node_code – Exported node code.

• bus – Source bus.

• aggregate – Aggregated node state.

Returns:

Node row text.

VeraGridEngine.IO.ucte.veragrid_to_ucte.format_optional_float(value: float, decimals: int) → str

Format one optional float for tolerant UCTE text output.

Parameters:

• value – Numeric value.

• decimals – Number of decimal places.

Returns:

Formatted text or an empty string.

VeraGridEngine.IO.ucte.veragrid_to_ucte.format_optional_float_width(value: float, width: int, decimals: int) → str

Format one optional float using one strict fixed-width UCTE field.

Parameters:

• value – Numeric value.

• width – Field width.

• decimals – Number of decimal places.

Returns:

Fixed-width text or blanks.

VeraGridEngine.IO.ucte.veragrid_to_ucte.format_transformer_row(node_1: str, node_2: str, order_code: str, status: int, rated_voltage_1_kv: float, rated_voltage_2_kv: float, nominal_power_mva: float, resistance_ohm: float, reactance_ohm: float, susceptance_us: float, conductance_us: float, current_limit_a: float, name: str) → str

Format one UCTE transformer record.

Parameters:

• node_1 – Non-regulated winding node code.

• node_2 – Regulated winding node code.

• order_code – One-character order code.

• status – UCTE status code.

• rated_voltage_1_kv – Rated voltage on node1 side.

• rated_voltage_2_kv – Rated voltage on node2 side.

• nominal_power_mva – Nominal power in MVA.

• resistance_ohm – Series resistance in ohm.

• reactance_ohm – Series reactance in ohm.

• susceptance_us – Total shunt susceptance in uS.

• conductance_us – Total shunt conductance in uS.

• current_limit_a – Current limit in A.

• name – Device name.

Returns:

Transformer row text.

VeraGridEngine.IO.ucte.veragrid_to_ucte.get_bus_voltage_reference(bus: Bus) → float

Convert the VeraGrid bus voltage seed to the UCTE Uref value.

Parameters:

bus – VeraGrid bus.

Returns:

Voltage reference in kV.

VeraGridEngine.IO.ucte.veragrid_to_ucte.get_country_code(bus: Bus) → str

Get the UCTE country code to use for one bus block.

Parameters:

bus – VeraGrid bus.

Returns:

Two-letter country code or XX.

VeraGridEngine.IO.ucte.veragrid_to_ucte.get_line_current_limit_a(line: Line, vnom_kv: float, t_idx: int | None) → float

Convert one VeraGrid line rate to a UCTE current limit.

Parameters:

• line – VeraGrid line.

• vnom_kv – Nominal voltage in kV.

• t_idx – Optional profile index.

Returns:

Current limit in A or nan.

VeraGridEngine.IO.ucte.veragrid_to_ucte.get_line_ucte_impedance(line: Line, circuit: MultiCircuit) → tuple[float, float, float]

Convert one VeraGrid line impedance to UCTE units.

Parameters:

• line – VeraGrid line.

• circuit – Circuit base values.

Returns:

Resistance in ohm, reactance in ohm, susceptance in uS.

VeraGridEngine.IO.ucte.veragrid_to_ucte.get_snapshot_datetime(circuit: MultiCircuit, t_idx: int | None) → datetime

Get the export timestamp represented by one UCTE file.

Parameters:

• circuit – Circuit to export.

• t_idx – Optional profile index.

Returns:

Snapshot datetime.

VeraGridEngine.IO.ucte.veragrid_to_ucte.get_transformer_current_limit_a(transformer: Transformer2W, t_idx: int | None) → float

Convert one VeraGrid transformer rate to a UCTE current limit.

Parameters:

• transformer – VeraGrid transformer.

• t_idx – Optional profile index.

Returns:

Current limit in A or nan.

VeraGridEngine.IO.ucte.veragrid_to_ucte.get_transformer_ucte_impedance(transformer: Transformer2W, circuit: MultiCircuit, rated_voltage_1_kv: float) → tuple[float, float, float, float]

Convert one VeraGrid transformer impedance to UCTE units.

Parameters:

• transformer – VeraGrid transformer.

• circuit – Circuit base values.

• rated_voltage_1_kv – UCTE rated voltage on node1 side.

Returns:

Resistance in ohm, reactance in ohm, susceptance in uS, conductance in uS.

VeraGridEngine.IO.ucte.veragrid_to_ucte.get_ucte_voltage_code(voltage_kv: float) → str

Map one nominal voltage value to the closest standard UCTE voltage code.

Parameters:

voltage_kv – Nominal voltage in kV.

Returns:

One-character voltage code.

VeraGridEngine.IO.ucte.veragrid_to_ucte.is_standard_ucte_country_code(country_code: str) → bool

Check if one country code matches the standard UCTE two-letter form.

Parameters:

country_code – Country code to inspect.

Returns:

True when the code is standard.

VeraGridEngine.IO.ucte.veragrid_to_ucte.is_usable_ucte_bus_code(node_code: str, bus: Bus) → bool

Check if one bus code can be reused directly as a canonical UCTE node code.

Parameters:

• node_code – Candidate node code.

• bus – VeraGrid bus.

Returns:

True when the code is already UCTE-safe.

VeraGridEngine.IO.ucte.veragrid_to_ucte.normalize_reusable_noncanonical_ucte_bus_code(node_code: str) → str | None

Normalize one existing non-canonical node code for roundtrip preservation.

This keeps non-canonical UCTE identifiers from imported synthetic datasets so that the importer can continue applying its nominal-voltage repair heuristics on roundtrip.

Parameters:

node_code – Candidate node code.

Returns:

Normalized 8-character code or None.

VeraGridEngine.IO.ucte.veragrid_to_ucte.update_aggregate_from_external_grid(aggregate: UcteBusAggregate, bus: Bus, external_grid: ExternalGrid, t_idx: int | None, logger: Logger) → None

Apply one external-grid device to the UCTE node aggregate.

Parameters:

• aggregate – Target bus aggregate.

• bus – Parent bus.

• external_grid – External-grid device.

• t_idx – Optional profile index.

• logger – Export logger.

Returns:

None.

VeraGridEngine.IO.ucte.veragrid_to_ucte.update_aggregate_voltage_control_from_generator(aggregate: UcteBusAggregate, bus: Bus, generator: Generator | Battery, t_idx: int | None) → None

Apply one generator voltage-control mode to the aggregate node state.

Parameters:

• aggregate – Target bus aggregate.

• bus – Parent bus.

• generator – Generator or battery.

• t_idx – Optional profile index.

Returns:

None.

VeraGridEngine.IO.ucte.veragrid_to_ucte.update_generation_limits_from_generator(aggregate: UcteBusAggregate, generator: Generator | Battery) → None

Accumulate UCTE generation limits from one VeraGrid generator-like device.

Parameters:

• aggregate – Target bus aggregate.

• generator – Generator or battery device.

Returns:

None.

VeraGridEngine.IO.ucte.veragrid_to_ucte.use_legacy_transformer_orientation(bus_from: Bus, bus_to: Bus) → bool

Select the transformer orientation expected by the UCTE importer.

Standard country-coded UCTE data uses the legacy regulated/non-regulated winding convention, while IEEE-like synthetic files use the direct node1 -> node2 orientation.

Parameters:

• bus_from – VeraGrid transformer bus_from side.

• bus_to – VeraGrid transformer bus_to side.

Returns:

True when the legacy UCTE orientation must be exported.

VeraGridEngine.IO.ucte.veragrid_to_ucte.write_comment_block(circuit: MultiCircuit, t_idx: int | None, file_pointer: TextIO) → None

Write the UCTE comment block.

Parameters:

• circuit – Circuit to export.

• t_idx – Optional profile index.

• file_pointer – Open output file.

Returns:

None.

VeraGridEngine.IO.ucte.veragrid_to_ucte.write_empty_regulation_blocks(file_pointer: TextIO) → None

Write the optional UCTE blocks that are not populated yet.

Parameters:

file_pointer – Open output file.

Returns:

None.

VeraGridEngine.IO.ucte.veragrid_to_ucte.write_line_block(circuit: MultiCircuit, bus_code_map: Dict[Bus, str], aggregate_by_bus: Dict[Bus, UcteBusAggregate], t_idx: int | None, logger: Logger, file_pointer: TextIO) → None

Write the UCTE line block, including switch couplers and fictitious shunts.

Parameters:

• circuit – Circuit to export.

• bus_code_map – Bus-to-node-code mapping.

• aggregate_by_bus – Precomputed bus aggregates.

• t_idx – Optional profile index.

• logger – Export logger.

• file_pointer – Open output file.

Returns:

None.

VeraGridEngine.IO.ucte.veragrid_to_ucte.write_node_blocks_from_aggregates(circuit: MultiCircuit, bus_code_map: Dict[Bus, str], aggregate_by_bus: Dict[Bus, UcteBusAggregate], file_pointer: TextIO) → None

Write the UCTE node sections grouped by country block.

Parameters:

• circuit – Circuit to export.

• bus_code_map – Bus-to-node-code mapping.

• aggregate_by_bus – Precomputed bus aggregates.

• file_pointer – Open output file.

Returns:

None.

VeraGridEngine.IO.ucte.veragrid_to_ucte.write_transformer_block(circuit: MultiCircuit, bus_code_map: Dict[Bus, str], t_idx: int | None, logger: Logger, file_pointer: TextIO) → None

Write the UCTE transformer block.

Parameters:

• circuit – Circuit to export.

• bus_code_map – Bus-to-node-code mapping.

• t_idx – Optional profile index.

• logger – Export logger.

• file_pointer – Open output file.

Returns:

None.

VeraGridEngine.IO.ucte.veragrid_to_ucte.write_ucte(file_name: str, circuit: MultiCircuit, t_idx: int | None = None, logger: Logger | None = None) → Logger

Write one VeraGrid circuit as one UCTE text file.

Parameters:

• file_name – Target file path.

• circuit – Circuit to export.

• t_idx – Optional profile index. None means snapshot export.

• logger – Optional logger.

Returns:

Logger with export messages.

Module contents