From d364b8908408e6a7136618ed3a88b7fd4d8faaf6 Mon Sep 17 00:00:00 2001 From: Kapil Duwadi <62037219+KapilDuwadi@users.noreply.github.com> Date: Mon, 5 Aug 2024 14:24:22 -0500 Subject: [PATCH] added docs for distribution bus and distribution load (#37) * added docs for distribution bus and distribution load * added examples for distribution transformer * first stable release * upgraded actions_python_ruff from 1.0.0 to 1.0.1 * added check src in ruff lint --- .github/workflows/pull_request_tests.yml | 7 +- docs/api/distribution_component.md | 8 - .../distribution_transformer_equipment.md | 9 - docs/index.md | 8 + docs/usage/components/distribution_branch.md | 9 + docs/usage/components/distribution_bus.md | 91 ++++ docs/usage/components/distribution_load.md | 213 ++++++++ .../components/distribution_regulator.md | 169 ++++++ .../components/distribution_transformer.md | 499 ++++++++++++++++++ docs/usage/index.md | 11 + pyproject.toml | 2 +- src/gdm/__init__.py | 2 + .../components/matrix_impedance_branch.py | 3 +- src/gdm/distribution/distribution_common.py | 17 - src/gdm/version.py | 2 +- tests/get_sample_system.py | 15 +- 16 files changed, 1017 insertions(+), 48 deletions(-) delete mode 100644 docs/api/distribution_component.md create mode 100644 docs/usage/components/distribution_branch.md create mode 100644 docs/usage/components/distribution_bus.md create mode 100644 docs/usage/components/distribution_load.md create mode 100644 docs/usage/components/distribution_regulator.md create mode 100644 docs/usage/components/distribution_transformer.md create mode 100644 docs/usage/index.md delete mode 100644 src/gdm/distribution/distribution_common.py diff --git a/.github/workflows/pull_request_tests.yml b/.github/workflows/pull_request_tests.yml index c8267e6..4df91e4 100644 --- a/.github/workflows/pull_request_tests.yml +++ b/.github/workflows/pull_request_tests.yml @@ -22,6 +22,9 @@ jobs: - name: Run pytest run: | pytest -v --cov --cov-report=xml + cd docs + pytest --doctest-glob="*.md" + cd .. - name: Upload coverage reports to Codecov uses: codecov/codecov-action@v4.0.1 with: @@ -33,8 +36,8 @@ jobs: runs-on: ubuntu-latest name: "ruff" steps: - - uses: davidslusser/actions_python_ruff@v1.0.0 + - uses: davidslusser/actions_python_ruff@v1.0.1 with: - src: "src" + src: "check src" pip_install_command: "pip install -e .[dev]" python_version: "3.11" diff --git a/docs/api/distribution_component.md b/docs/api/distribution_component.md deleted file mode 100644 index fe2ff35..0000000 --- a/docs/api/distribution_component.md +++ /dev/null @@ -1,8 +0,0 @@ -# Distribution Component - -```{eval-rst} -.. autopydantic_model:: gdm.DistributionComponent - :members: __init__ - :inherited-members: Component - :exclude-members: example, validate_fields -``` \ No newline at end of file diff --git a/docs/api/equipment/distribution_transformer_equipment.md b/docs/api/equipment/distribution_transformer_equipment.md index 05b132f..539f063 100644 --- a/docs/api/equipment/distribution_transformer_equipment.md +++ b/docs/api/equipment/distribution_transformer_equipment.md @@ -9,15 +9,6 @@ :exclude-members: example, validate_fields ``` - -```{eval-rst} -.. autopydantic_model:: gdm.TapWindingEquipment - :members: __init__ - :inherited-members: Component - :exclude-members: example, validate_fields -``` - - ```{eval-rst} .. autopydantic_model:: gdm.DistributionTransformerEquipment :members: __init__ diff --git a/docs/index.md b/docs/index.md index 7f90792..f6adabb 100644 --- a/docs/index.md +++ b/docs/index.md @@ -48,3 +48,11 @@ api/index cim/index ``` + + +```{toctree} +:caption: Usage +:hidden: true + +usage/index +``` diff --git a/docs/usage/components/distribution_branch.md b/docs/usage/components/distribution_branch.md new file mode 100644 index 0000000..2227efd --- /dev/null +++ b/docs/usage/components/distribution_branch.md @@ -0,0 +1,9 @@ +# Distributio Branch + +_under development_ + +## Matrix Impedance Branch + +## Geometry Branch + +## Sequence Impedance Branch \ No newline at end of file diff --git a/docs/usage/components/distribution_bus.md b/docs/usage/components/distribution_bus.md new file mode 100644 index 0000000..42083d3 --- /dev/null +++ b/docs/usage/components/distribution_bus.md @@ -0,0 +1,91 @@ +# Distribution Bus + +Single phase bus. + +```python +>>> from gdm import ( +... DistributionBus, +... PositiveVoltage, +... VoltageTypes, +... Phase +... ) +>>> DistributionBus( +... name="Bus-1", +... nominal_voltage=PositiveVoltage(7.62, "kilovolts"), +... voltage_type=VoltageTypes.LINE_TO_GROUND, +... phases=[Phase.A] +... ) +DistributionBus(name='Bus-1', +substation=None, +feeder=None, +voltage_type=, +phases=[], +voltagelimits=[], +nominal_voltage=, +coordinate=None) + +``` + +Three phase bus. + +```python +>>> DistributionBus( +... name="Bus-1", +... nominal_voltage=PositiveVoltage(7.62, "kilovolts"), +... voltage_type=VoltageTypes.LINE_TO_GROUND, +... phases=[Phase.A, Phase.B, Phase.C] +... ) +DistributionBus(name='Bus-1', +substation=None, +feeder=None, +voltage_type=, +phases=[, , ], +voltagelimits=[], +nominal_voltage=, +coordinate=None) + +``` + +A bus with cartesian coordinates. + +```python +>>> from gdm import Location +>>> DistributionBus( +... name="Bus-1", +... nominal_voltage=PositiveVoltage(7.62, "kilovolts"), +... voltage_type=VoltageTypes.LINE_TO_GROUND, +... phases=[Phase.A, Phase.B, Phase.C], +... coordinate=Location(x=10.0, y=20.0) +... ) +DistributionBus(name='Bus-1', +substation=None, +feeder=None, +voltage_type=, +phases=[, , ], +voltagelimits=[], +nominal_voltage=, +coordinate=Location(name='', x=10.0, y=20.0, crs=None)) + +``` + +A bus with coordinate reference system. + +```python +>>> from gdm import Location +>>> DistributionBus( +... name="Bus-1", +... nominal_voltage=PositiveVoltage(7.62, "kilovolts"), +... voltage_type=VoltageTypes.LINE_TO_GROUND, +... phases=[Phase.A, Phase.B, Phase.C], +... coordinate=Location(x=10.0, y=20.0, crs='epsg:4326') +... ) +DistributionBus(name='Bus-1', +substation=None, +feeder=None, +voltage_type=, +phases=[, , ], +voltagelimits=[], +nominal_voltage=, +coordinate=Location(name='', x=10.0, y=20.0, crs='epsg:4326')) + +``` \ No newline at end of file diff --git a/docs/usage/components/distribution_load.md b/docs/usage/components/distribution_load.md new file mode 100644 index 0000000..dd9b23a --- /dev/null +++ b/docs/usage/components/distribution_load.md @@ -0,0 +1,213 @@ +# Distribution Load + +## Single Phase Constant Power Load + +Creating a single-phase constant power load connected to a bus. A constant power load means that the power (both real and reactive) remains constant irrespective of voltage variations. The parameters p_real and p_imag are set to 1.0, indicating that the load is a constant power type. + +```python +>>> from gdm import ( +... DistributionBus, +... DistributionLoad, +... LoadEquipment, +... PositiveVoltage, +... VoltageTypes, +... PhaseLoadEquipment, +... Phase, +... ActivePower, +... ReactivePower +... ) +>>> bus1 = DistributionBus( +... name="Bus-1", +... nominal_voltage=PositiveVoltage(7.62, "kilovolts"), +... voltage_type=VoltageTypes.LINE_TO_GROUND, +... phases=[Phase.A] +... ) +>>> phase_load_equipment = PhaseLoadEquipment( +... name="Phase-Load-1", +... real_power=ActivePower(3.5, "kilowatt"), +... reactive_power=ReactivePower(0, "kilovar"), +... z_real=0, +... z_imag=0, +... i_real=0, +... i_imag=0, +... p_real=1.0, +... p_imag=1.0 +... ) +>>> load_equipment = LoadEquipment( +... name="LoadEquipment-1", +... phase_loads=[phase_load_equipment] +... ) +>>> DistributionLoad( +... name="Load-1", +... bus=bus1, +... phases=[Phase.A], +... equipment=load_equipment +... ).pprint() +DistributionLoad( + name='Load-1', + substation=None, + feeder=None, + bus=DistributionBus( + name='Bus-1', + substation=None, + feeder=None, + voltage_type=, + phases=[], + voltagelimits=[], + nominal_voltage=, + coordinate=None + ), + phases=[], + equipment=LoadEquipment( + name='LoadEquipment-1', + phase_loads=[ + PhaseLoadEquipment( + name='Phase-Load-1', + real_power=, + reactive_power=, + z_real=0.0, + z_imag=0.0, + i_real=0.0, + i_imag=0.0, + p_real=1.0, + p_imag=1.0, + num_customers=None + ) + ], + connection_type= + ) +) + +``` + +## Three Phase Delta Connected Constant Power Load + + +For the three-phase delta-connected constant power load, we need to define the load for all three phases (A, B, and C) and set the connection type to delta. In a delta connection, the load is connected between phases rather than from phase to neutral (as in a star connection). + + + +```python +>>> from gdm import ( +... DistributionBus, +... DistributionLoad, +... LoadEquipment, +... PositiveVoltage, +... VoltageTypes, +... PhaseLoadEquipment, +... Phase, +... ActivePower, +... ReactivePower, +... ConnectionType +... ) +>>> bus2 = DistributionBus( +... name="Bus-2", +... nominal_voltage=PositiveVoltage(13.8, "kilovolts"), +... voltage_type=VoltageTypes.LINE_TO_LINE, +... phases=[Phase.A, Phase.B, Phase.C] +... ) +>>> phase_load_equipment_a = PhaseLoadEquipment( +... name="Phase-Load-A", +... real_power=ActivePower(5.0, "kilowatt"), +... reactive_power=ReactivePower(2.0, "kilovar"), +... z_real=0, +... z_imag=0, +... i_real=0, +... i_imag=0, +... p_real=1.0, +... p_imag=1.0 +... ) +>>> phase_load_equipment_b = PhaseLoadEquipment( +... name="Phase-Load-B", +... real_power=ActivePower(5.0, "kilowatt"), +... reactive_power=ReactivePower(2.0, "kilovar"), +... z_real=0, +... z_imag=0, +... i_real=0, +... i_imag=0, +... p_real=1.0, +... p_imag=1.0 +... ) +>>> phase_load_equipment_c = PhaseLoadEquipment( +... name="Phase-Load-C", +... real_power=ActivePower(5.0, "kilowatt"), +... reactive_power=ReactivePower(2.0, "kilovar"), +... z_real=0, +... z_imag=0, +... i_real=0, +... i_imag=0, +... p_real=1.0, +... p_imag=1.0 +... ) +>>> load_equipment_delta = LoadEquipment( +... name="LoadEquipment-Delta", +... phase_loads=[phase_load_equipment_a, phase_load_equipment_b, phase_load_equipment_c], +... connection_type=ConnectionType.DELTA +... ) +>>> distribution_load_delta = DistributionLoad( +... name="Load-Delta", +... bus=bus2, +... phases=[Phase.A, Phase.B, Phase.C], +... equipment=load_equipment_delta +... ) +>>> distribution_load_delta.pprint() +DistributionLoad( + name='Load-Delta', + substation=None, + feeder=None, + bus=DistributionBus( + name='Bus-2', + substation=None, + feeder=None, + voltage_type=, + phases=[, , ], + voltagelimits=[], + nominal_voltage=, + coordinate=None + ), + phases=[, , ], + equipment=LoadEquipment( + name='LoadEquipment-Delta', + phase_loads=[ + PhaseLoadEquipment( + name='Phase-Load-A', + real_power=, + reactive_power=, + z_real=0.0, + z_imag=0.0, + i_real=0.0, + i_imag=0.0, + p_real=1.0, + p_imag=1.0, + num_customers=None + ), + PhaseLoadEquipment( + name='Phase-Load-B', + real_power=, + reactive_power=, + z_real=0.0, + z_imag=0.0, + i_real=0.0, + i_imag=0.0, + p_real=1.0, + p_imag=1.0, + num_customers=None + ), + PhaseLoadEquipment( + name='Phase-Load-C', + real_power=, + reactive_power=, + z_real=0.0, + z_imag=0.0, + i_real=0.0, + i_imag=0.0, + p_real=1.0, + p_imag=1.0, + num_customers=None + ) + ], + connection_type= + ) +) + +``` \ No newline at end of file diff --git a/docs/usage/components/distribution_regulator.md b/docs/usage/components/distribution_regulator.md new file mode 100644 index 0000000..099f1ee --- /dev/null +++ b/docs/usage/components/distribution_regulator.md @@ -0,0 +1,169 @@ +# Distribution Regulator + +## Single Phase Regulator + +```python +>>> from gdm import ( +... DistributionBus, +... DistributionSubstation, +... DistributionFeeder, +... DistributionRegulator, +... DistributionTransformerEquipment, +... WindingEquipment, +... SequencePair, +... RegulatorController, +... PositiveVoltage, +... VoltageTypes, +... Phase, +... ConnectionType, +... Time, +... PositiveApparentPower +... ) +>>> bus_1 = DistributionBus( +... name="Bus-1", +... nominal_voltage=PositiveVoltage(12.47, "kilovolts"), +... phases=[Phase.A], +... voltage_type=VoltageTypes.LINE_TO_GROUND, +... ) + +>>> bus_2 = DistributionBus( +... name="Bus-2", +... nominal_voltage=PositiveVoltage(12.47, "kilovolts"), +... phases=[Phase.A], +... voltage_type=VoltageTypes.LINE_TO_GROUND, +... ) + +>>> regulator_equipment = DistributionTransformerEquipment( +... name="SinglePhase-Regulator-1", +... pct_full_load_loss=0.1, +... pct_no_load_loss=0.002, +... windings=[ +... WindingEquipment( +... resistance=1.0, +... is_grounded=False, +... nominal_voltage=PositiveVoltage(12.47, "kilovolts"), +... rated_power=PositiveApparentPower(25, "kilova"), +... num_phases=1, +... tap_positions=[1.0], +... connection_type=ConnectionType.STAR, +... voltage_type=VoltageTypes.LINE_TO_GROUND, +... ), +... WindingEquipment( +... resistance=1.0, +... is_grounded=False, +... nominal_voltage=PositiveVoltage(12.47, "kilovolts"), +... rated_power=PositiveApparentPower(25, "kilova"), +... num_phases=1, +... tap_positions=[1.0], +... connection_type=ConnectionType.STAR, +... voltage_type=VoltageTypes.LINE_TO_GROUND, +... ), +... ], +... coupling_sequences=[SequencePair(from_index=0, to_index=1)], +... winding_reactances=[2.3], +... is_center_tapped=False, +... ) + +>>> regulator_controller = RegulatorController( +... name="RegulatorController-1", +... delay=Time(10, "seconds"), # seconds +... vsetpoint=120, # volts +... pt_ratio=60.0, +... ldc_R=None, +... ldc_X=None, +... ct_primary=None, +... max_step=16, +... bandwidth=3, # volts +... ) + +>>> regulator_1 = DistributionRegulator( +... name="Regulator-1", +... buses=[bus_1, bus_2], +... winding_phases=[[Phase.A], [Phase.A]], +... equipment=regulator_equipment, +... controllers=[regulator_controller], +... ) +>>> regulator_1.pprint() +DistributionRegulator( + name='Regulator-1', + substation=None, + feeder=None, + buses=[ + DistributionBus( + name='Bus-1', + substation=None, + feeder=None, + voltage_type=, + phases=[], + voltagelimits=[], + nominal_voltage=, + coordinate=None + ), + DistributionBus( + name='Bus-2', + substation=None, + feeder=None, + voltage_type=, + phases=[], + voltagelimits=[], + nominal_voltage=, + coordinate=None + ) + ], + winding_phases=[[], []], + equipment=DistributionTransformerEquipment( + name='SinglePhase-Regulator-1', + pct_no_load_loss=0.002, + pct_full_load_loss=0.1, + windings=[ + WindingEquipment( + name='', + resistance=1.0, + is_grounded=False, + nominal_voltage=, + voltage_type=, + rated_power=, + num_phases=1, + connection_type=, + tap_positions=[1.0], + total_taps=32, + min_tap_pu=0.9, + max_tap_pu=1.1 + ), + WindingEquipment( + name='', + resistance=1.0, + is_grounded=False, + nominal_voltage=, + voltage_type=, + rated_power=, + num_phases=1, + connection_type=, + tap_positions=[1.0], + total_taps=32, + min_tap_pu=0.9, + max_tap_pu=1.1 + ) + ], + coupling_sequences=[SequencePair(from_index=0, to_index=1)], + winding_reactances=[2.3], + is_center_tapped=False + ), + controllers=[ + RegulatorController( + name='RegulatorController-1', + delay=, + vsetpoint=, + pt_ratio=60.0, + ldc_R=None, + ldc_X=None, + ct_primary=None, + max_step=16, + bandwidth= + ) + ] +) + +""" + +``` diff --git a/docs/usage/components/distribution_transformer.md b/docs/usage/components/distribution_transformer.md new file mode 100644 index 0000000..f60f267 --- /dev/null +++ b/docs/usage/components/distribution_transformer.md @@ -0,0 +1,499 @@ +# Distribution Transformer + +## Single Phase Transformer + +A single-phase transformer with star (wye) connection. This example demonstrates creating a single-phase transformer with primary and secondary buses, winding equipment, and transformer configuration. + +```python +>>> from gdm import ( +... DistributionBus, +... DistributionLoad, +... LoadEquipment, +... PositiveVoltage, +... VoltageTypes, +... PhaseLoadEquipment, +... Phase, +... ActivePower, +... ReactivePower, +... ConnectionType, +... DistributionTransformer, +... DistributionSubstation, +... DistributionFeeder, +... DistributionTransformerEquipment, +... WindingEquipment, +... SequencePair, +... PositiveApparentPower +... ) +>>> substation = DistributionSubstation(name='Test Substation', feeders=[DistributionFeeder(name='Test Feeder')]) +>>> feeder = DistributionFeeder(name='Test Feeder') +>>> primary_bus = DistributionBus( +... name='PrimaryBus', +... substation=substation, +... feeder=feeder, +... voltage_type=VoltageTypes.LINE_TO_GROUND, +... phases=[Phase.A], +... nominal_voltage=PositiveVoltage(7.62, "kilovolts") +... ) +>>> secondary_bus = DistributionBus( +... name='SecondaryBus', +... substation=substation, +... feeder=feeder, +... voltage_type=VoltageTypes.LINE_TO_GROUND, +... phases=[Phase.A], +... nominal_voltage=PositiveVoltage(0.24, "kilovolts") +... ) +>>> primary_winding = WindingEquipment( +... name='PrimaryWinding', +... resistance=1.0, +... is_grounded=True, +... nominal_voltage=PositiveVoltage(7.62, "kilovolts"), +... voltage_type=VoltageTypes.LINE_TO_GROUND, +... rated_power=PositiveApparentPower(56, "kilova"), +... num_phases=1, +... connection_type=ConnectionType.STAR, +... tap_positions=[1.0], +... total_taps=32, +... min_tap_pu=0.9, +... max_tap_pu=1.1 +... ) +>>> secondary_winding = WindingEquipment( +... name='SecondaryWinding', +... resistance=1.0, +... is_grounded=True, +... nominal_voltage=PositiveVoltage(0.24, "kilovolts"), +... voltage_type=VoltageTypes.LINE_TO_GROUND, +... rated_power=PositiveApparentPower(56, "kilova"), +... num_phases=1, +... connection_type=ConnectionType.STAR, +... tap_positions=[1.0], +... total_taps=32, +... min_tap_pu=0.9, +... max_tap_pu=1.1 +... ) +>>> transformer_equipment = DistributionTransformerEquipment( +... name='SinglePhaseTransformer', +... pct_no_load_loss=0.1, +... pct_full_load_loss=1.0, +... windings=[primary_winding, secondary_winding], +... coupling_sequences=[SequencePair(from_index=0, to_index=1)], +... winding_reactances=[2.3], +... is_center_tapped=False +... ) +>>> single_phase_transformer = DistributionTransformer( +... name='SinglePhaseTransformer1', +... substation=substation, +... feeder=feeder, +... buses=[primary_bus, secondary_bus], +... winding_phases=[[Phase.A], [Phase.A]], +... equipment=transformer_equipment +... ) +>>> single_phase_transformer.pprint() +DistributionTransformer( + name='SinglePhaseTransformer1', + substation=DistributionSubstation( + name='Test Substation', + feeders=[DistributionFeeder(name='Test Feeder')] + ), + feeder=DistributionFeeder(name='Test Feeder'), + buses=[ + DistributionBus( + name='PrimaryBus', + substation=DistributionSubstation( + name='Test Substation', + feeders=[DistributionFeeder(name='Test Feeder')] + ), + feeder=DistributionFeeder(name='Test Feeder'), + voltage_type=, + phases=[], + voltagelimits=[], + nominal_voltage=, + coordinate=None + ), + DistributionBus( + name='SecondaryBus', + substation=DistributionSubstation( + name='Test Substation', + feeders=[DistributionFeeder(name='Test Feeder')] + ), + feeder=DistributionFeeder(name='Test Feeder'), + voltage_type=, + phases=[], + voltagelimits=[], + nominal_voltage=, + coordinate=None + ) + ], + winding_phases=[[], []], + equipment=DistributionTransformerEquipment( + name='SinglePhaseTransformer', + pct_no_load_loss=0.1, + pct_full_load_loss=1.0, + windings=[ + WindingEquipment( + name='PrimaryWinding', + resistance=1.0, + is_grounded=True, + nominal_voltage=, + voltage_type=, + rated_power=, + num_phases=1, + connection_type=, + tap_positions=[1.0], + total_taps=32, + min_tap_pu=0.9, + max_tap_pu=1.1 + ), + WindingEquipment( + name='SecondaryWinding', + resistance=1.0, + is_grounded=True, + nominal_voltage=, + voltage_type=, + rated_power=, + num_phases=1, + connection_type=, + tap_positions=[1.0], + total_taps=32, + min_tap_pu=0.9, + max_tap_pu=1.1 + ) + ], + coupling_sequences=[SequencePair(from_index=0, to_index=1)], + winding_reactances=[2.3], + is_center_tapped=False + ) +) + +``` + +## Three Phase Star Connected Transformer + +A three-phase transformer with star (wye) connection. This example demonstrates creating a three-phase transformer with primary and secondary buses, winding equipment, and transformer configuration. + +```python +>>> substation = DistributionSubstation(name='Test Substation', feeders=[DistributionFeeder(name='Test Feeder')]) +>>> feeder = DistributionFeeder(name='Test Feeder') +>>> primary_bus_3p = DistributionBus( +... name='PrimaryBus-3P', +... substation=substation, +... feeder=feeder, +... voltage_type=VoltageTypes.LINE_TO_LINE, +... phases=[Phase.A, Phase.B, Phase.C], +... nominal_voltage=PositiveVoltage(12.47, "kilovolts") +... ) +>>> secondary_bus_3p = DistributionBus( +... name='SecondaryBus-3P', +... substation=substation, +... feeder=feeder, +... voltage_type=VoltageTypes.LINE_TO_LINE, +... phases=[Phase.A, Phase.B, Phase.C], +... nominal_voltage=PositiveVoltage(0.4, "kilovolts") +... ) +>>> primary_winding_3p = WindingEquipment( +... name='PrimaryWinding-3P', +... resistance=1.0, +... is_grounded=False, +... nominal_voltage=PositiveVoltage(12.47, "kilovolts"), +... voltage_type=VoltageTypes.LINE_TO_LINE, +... rated_power=PositiveApparentPower(56, "kilova"), +... num_phases=3, +... connection_type=ConnectionType.STAR, +... tap_positions=[1.0, 1.0, 1.0], +... total_taps=32, +... min_tap_pu=0.9, +... max_tap_pu=1.1 +... ) +>>> secondary_winding_3p = WindingEquipment( +... name='SecondaryWinding-3P', +... resistance=1.0, +... is_grounded=False, +... nominal_voltage=PositiveVoltage(0.4, "kilovolts"), +... voltage_type=VoltageTypes.LINE_TO_LINE, +... rated_power=PositiveApparentPower(56, "kilova"), +... num_phases=3, +... connection_type=ConnectionType.STAR, +... tap_positions=[1.0, 1.0, 1.0], +... total_taps=32, +... min_tap_pu=0.9, +... max_tap_pu=1.1 +... ) +>>> transformer_equipment_3p = DistributionTransformerEquipment( +... name='ThreePhaseTransformer', +... pct_no_load_loss=0.1, +... pct_full_load_loss=1.0, +... windings=[primary_winding_3p, secondary_winding_3p], +... coupling_sequences=[SequencePair(from_index=0, to_index=1)], +... winding_reactances=[2.3], +... is_center_tapped=False +... ) +>>> three_phase_transformer = DistributionTransformer( +... name='ThreePhaseTransformer1', +... substation=substation, +... feeder=feeder, +... buses=[primary_bus_3p, secondary_bus_3p], +... winding_phases=[[Phase.A, Phase.B, Phase.C], [Phase.A, Phase.B,Phase.C]], +... equipment=transformer_equipment_3p +... ) +>>> three_phase_transformer.pprint() +DistributionTransformer( + name='ThreePhaseTransformer1', + substation=DistributionSubstation( + name='Test Substation', + feeders=[DistributionFeeder(name='Test Feeder')] + ), + feeder=DistributionFeeder(name='Test Feeder'), + buses=[ + DistributionBus( + name='PrimaryBus-3P', + substation=DistributionSubstation( + name='Test Substation', + feeders=[DistributionFeeder(name='Test Feeder')] + ), + feeder=DistributionFeeder(name='Test Feeder'), + voltage_type=, + phases=[, , ], + voltagelimits=[], + nominal_voltage=, + coordinate=None + ), + DistributionBus( + name='SecondaryBus-3P', + substation=DistributionSubstation( + name='Test Substation', + feeders=[DistributionFeeder(name='Test Feeder')] + ), + feeder=DistributionFeeder(name='Test Feeder'), + voltage_type=, + phases=[, , ], + voltagelimits=[], + nominal_voltage=, + coordinate=None + ) + ], + winding_phases=[ + [, , ], + [, , ] + ], + equipment=DistributionTransformerEquipment( + name='ThreePhaseTransformer', + pct_no_load_loss=0.1, + pct_full_load_loss=1.0, + windings=[ + WindingEquipment( + name='PrimaryWinding-3P', + resistance=1.0, + is_grounded=False, + nominal_voltage=, + voltage_type=, + rated_power=, + num_phases=3, + connection_type=, + tap_positions=[1.0, 1.0, 1.0], + total_taps=32, + min_tap_pu=0.9, + max_tap_pu=1.1 + ), + WindingEquipment( + name='SecondaryWinding-3P', + resistance=1.0, + is_grounded=False, + nominal_voltage=, + voltage_type=, + rated_power=, + num_phases=3, + connection_type=, + tap_positions=[1.0, 1.0, 1.0], + total_taps=32, + min_tap_pu=0.9, + max_tap_pu=1.1 + ) + ], + coupling_sequences=[SequencePair(from_index=0, to_index=1)], + winding_reactances=[2.3], + is_center_tapped=False + ) +) + +``` + +## Split Phase Transformer + +Primary delta connected split phase transformer. + +```python +>>> bus_1 = DistributionBus( +... name="Bus-1", +... nominal_voltage=PositiveVoltage(12.47, "kilovolts"), +... phases=[Phase.A, Phase.B, Phase.C], +... voltage_type=VoltageTypes.LINE_TO_LINE, +... ) + +>>> bus_2 = DistributionBus( +... name="Bus-2", +... nominal_voltage=PositiveVoltage(0.24, "kilovolts"), +... phases=[Phase.S1, Phase.N, Phase.S2], +... voltage_type=VoltageTypes.LINE_TO_LINE, +... ) + +>>> bus_3 = DistributionBus( +... name="Bus-3", +... nominal_voltage=PositiveVoltage(0.24, "kilovolts"), +... phases=[Phase.S1, Phase.S2, Phase.N], +... voltage_type=VoltageTypes.LINE_TO_LINE, +... ) + +>>> transformer_equipment = DistributionTransformerEquipment( +... name="SplitPhase-Transformer-1", +... pct_full_load_loss=0.2, +... pct_no_load_loss=0.002, +... windings=[ +... WindingEquipment( +... resistance=0.02, +... is_grounded=False, +... nominal_voltage=PositiveVoltage(12.47, "kilovolts"), +... rated_power=PositiveApparentPower(25, "kilova"), +... num_phases=1, +... tap_positions=[1.0], +... connection_type=ConnectionType.DELTA, +... voltage_type=VoltageTypes.LINE_TO_LINE, +... ), +... WindingEquipment( +... resistance=0.02, +... is_grounded=False, +... nominal_voltage=PositiveVoltage(0.24, "kilovolts"), +... rated_power=PositiveApparentPower(25, "kilova"), +... num_phases=1, +... tap_positions=[1.0], +... connection_type=ConnectionType.DELTA, +... voltage_type=VoltageTypes.LINE_TO_LINE, +... ), +... WindingEquipment( +... resistance=0.02, +... is_grounded=False, +... nominal_voltage=PositiveVoltage(0.24, "kilovolts"), +... rated_power=PositiveApparentPower(25, "kilova"), +... num_phases=1, +... tap_positions=[1.0], +... connection_type=ConnectionType.DELTA, +... voltage_type=VoltageTypes.LINE_TO_LINE, +... ), +... ], +... coupling_sequences=[ +... SequencePair(from_index=0, to_index=1), +... SequencePair(from_index=1, to_index=2), +... SequencePair(from_index=2, to_index=0), +... ], +... winding_reactances=[0.2, 0.2, 0.2], +... is_center_tapped=True, +... ) + +>>> transformer_1 = DistributionTransformer( +... name="Transformer-1", +... buses=[bus_1, bus_2, bus_3], +... winding_phases=[[Phase.A, Phase.B], [Phase.S1, Phase.N], [Phase.N, Phase.S2]], +... equipment=transformer_equipment, +... ) + +>>> transformer_1.pprint() +DistributionTransformer( + name='Transformer-1', + substation=None, + feeder=None, + buses=[ + DistributionBus( + name='Bus-1', + substation=None, + feeder=None, + voltage_type=, + phases=[, , ], + voltagelimits=[], + nominal_voltage=, + coordinate=None + ), + DistributionBus( + name='Bus-2', + substation=None, + feeder=None, + voltage_type=, + phases=[, , ], + voltagelimits=[], + nominal_voltage=, + coordinate=None + ), + DistributionBus( + name='Bus-3', + substation=None, + feeder=None, + voltage_type=, + phases=[, , ], + voltagelimits=[], + nominal_voltage=, + coordinate=None + ) + ], + winding_phases=[ + [, ], + [, ], + [, ] + ], + equipment=DistributionTransformerEquipment( + name='SplitPhase-Transformer-1', + pct_no_load_loss=0.002, + pct_full_load_loss=0.2, + windings=[ + WindingEquipment( + name='', + resistance=0.02, + is_grounded=False, + nominal_voltage=, + voltage_type=, + rated_power=, + num_phases=1, + connection_type=, + tap_positions=[1.0], + total_taps=32, + min_tap_pu=0.9, + max_tap_pu=1.1 + ), + WindingEquipment( + name='', + resistance=0.02, + is_grounded=False, + nominal_voltage=, + voltage_type=, + rated_power=, + num_phases=1, + connection_type=, + tap_positions=[1.0], + total_taps=32, + min_tap_pu=0.9, + max_tap_pu=1.1 + ), + WindingEquipment( + name='', + resistance=0.02, + is_grounded=False, + nominal_voltage=, + voltage_type=, + rated_power=, + num_phases=1, + connection_type=, + tap_positions=[1.0], + total_taps=32, + min_tap_pu=0.9, + max_tap_pu=1.1 + ) + ], + coupling_sequences=[ + SequencePair(from_index=0, to_index=1), + SequencePair(from_index=1, to_index=2), + SequencePair(from_index=2, to_index=0) + ], + winding_reactances=[0.2, 0.2, 0.2], + is_center_tapped=True + ) +) + +``` + + diff --git a/docs/usage/index.md b/docs/usage/index.md new file mode 100644 index 0000000..f7ee758 --- /dev/null +++ b/docs/usage/index.md @@ -0,0 +1,11 @@ +# Usage + +```{toctree} +:caption: Distribution Components +:hidden: true + +components/distribution_bus +components/distribution_load +components/distribution_transformer.md +components/distribution_regulator.md +``` \ No newline at end of file diff --git a/pyproject.toml b/pyproject.toml index 1472ae1..6f65445 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -28,7 +28,7 @@ dependencies = [ ] [project.optional-dependencies] -dev = ["pre-commit", "pytest", "pytest-cov", "ruff"] +dev = ["pre-commit", "pytest", "pytest-cov", "pytest-doctestplus", "ruff"] doc = [ "sphinx", "pydata-sphinx-theme", diff --git a/src/gdm/__init__.py b/src/gdm/__init__.py index d4c2f42..f0060dc 100644 --- a/src/gdm/__init__.py +++ b/src/gdm/__init__.py @@ -9,6 +9,7 @@ Time, Resistance, ) +from infrasys import Location from gdm.quantities import ( PositiveResistance, ResistancePULength, @@ -122,6 +123,7 @@ ) from gdm.distribution.equipment.solar_equipment import SolarEquipment from gdm.distribution.equipment.voltagesource_equipment import VoltageSourceEquipment +from gdm.distribution.equipment.phase_voltagesource_equipment import PhaseVoltageSourceEquipment from gdm.distribution.controllers.base.capacitor_controller_base import CapacitorControllerBase diff --git a/src/gdm/distribution/components/matrix_impedance_branch.py b/src/gdm/distribution/components/matrix_impedance_branch.py index 72ee341..3ef6256 100644 --- a/src/gdm/distribution/components/matrix_impedance_branch.py +++ b/src/gdm/distribution/components/matrix_impedance_branch.py @@ -31,7 +31,8 @@ def validate_fields(self) -> "MatrixImpedanceBranch": self.equipment.x_matrix, self.equipment.c_matrix, ]: - if set(mat.shape) != {len(self.phases)}: + ph_wo_neutral = set(self.phases) - set(Phase.N) + if set(mat.shape) != {len(ph_wo_neutral)}: msg = f"Length of matrix {mat=} did not match number of phases {self.phases=}" raise ValueError(msg) diff --git a/src/gdm/distribution/distribution_common.py b/src/gdm/distribution/distribution_common.py deleted file mode 100644 index 25ef055..0000000 --- a/src/gdm/distribution/distribution_common.py +++ /dev/null @@ -1,17 +0,0 @@ -"""This module has contains all common models used in -distribution subpackage.""" - -from typing import Annotated, Optional - -from pydantic import Field - -from gdm.distribution.components.base.distribution_component_base import DistributionComponent - - -BELONG_TO_TYPE = Annotated[ - Optional[DistributionComponent], - Field( - None, - description="Provides info about substation and feeder. ", - ), -] diff --git a/src/gdm/version.py b/src/gdm/version.py index 6a093bd..417a008 100644 --- a/src/gdm/version.py +++ b/src/gdm/version.py @@ -3,7 +3,7 @@ import platform import sys -VERSION = "0.3.0" +VERSION = "1.0.0" def is_git_repo(dir: Path) -> bool: diff --git a/tests/get_sample_system.py b/tests/get_sample_system.py index 711d8dc..e0c8607 100644 --- a/tests/get_sample_system.py +++ b/tests/get_sample_system.py @@ -113,25 +113,22 @@ def get_three_bus_system(): name="matrix-impedance-branch-1", r_matrix=PositiveResistancePULength( [ - [0.08820, 0.0312137, 0.0306264], - [0.0312137, 0.0901946, 0.0316143], - [0.0306264, 0.0316143, 0.0889665], + [0.08820, 0.0312137], + [0.0312137, 0.0901946], ], "ohm/mi", ), x_matrix=ReactancePULength( [ - [0.20744, 0.0935314, 0.0760312], - [0.0935314, 0.200783, 0.0855879], - [0.0760312, 0.0855879, 0.204877], + [0.20744, 0.0935314], + [0.0935314, 0.200783], ], "ohm/mi", ), c_matrix=CapacitancePULength( [ - [2.90301, -0.679335, -0.22313], - [-0.679335, 3.15896, -0.481416], - [-0.22313, -0.481416, 2.8965], + [2.90301, -0.679335], + [-0.679335, 3.15896], ], "nanofarad/mi", ),