Skip to content

Admittance Perturbations

Base Classes

AdmittanceGenerator

Bases: ABC

Abstract base class for applying perturbations to line admittances.

Source code in gridfm_datakit/perturbations/admittance_perturbation.py 
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
class AdmittanceGenerator(ABC):
    """Abstract base class for applying perturbations to line admittances."""

    def __init__(self) -> None:
        """Initialize the admittance generator."""
        pass

    @abstractmethod
    def generate(
        self,
        example_generator: Generator[Network, None, None],
    ) -> Union[Generator[Network, None, None], List[Network]]:
        """Generate admittance perturbations.

        Args:
            example_generator: A generator producing example (load/topology/generation)
                scenarios to which line admittance perturbations are added.

        Yields:
            An admittance-perturbed scenario.
        """
        pass
__init__()

Initialize the admittance generator.

Source code in gridfm_datakit/perturbations/admittance_perturbation.py 
11
12
13
def __init__(self) -> None:
    """Initialize the admittance generator."""
    pass
generate(example_generator) abstractmethod

Generate admittance perturbations.

Parameters:

Name Type Description Default
example_generator Generator[Network, None, None]

A generator producing example (load/topology/generation) scenarios to which line admittance perturbations are added.

 required

Yields:

Type Description
Union[Generator[Network, None, None], List[Network]]

An admittance-perturbed scenario.
Source code in gridfm_datakit/perturbations/admittance_perturbation.py 
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
@abstractmethod
def generate(
    self,
    example_generator: Generator[Network, None, None],
) -> Union[Generator[Network, None, None], List[Network]]:
    """Generate admittance perturbations.

    Args:
        example_generator: A generator producing example (load/topology/generation)
            scenarios to which line admittance perturbations are added.

    Yields:
        An admittance-perturbed scenario.
    """
    pass

Concrete Implementations

NoAdmittancePerturbationGenerator

Bases: AdmittanceGenerator

Generator that yields the original example generator without any perturbations.

Source code in gridfm_datakit/perturbations/admittance_perturbation.py 
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
class NoAdmittancePerturbationGenerator(AdmittanceGenerator):
    """Generator that yields the original example generator without any perturbations."""

    def __init__(self):
        """Initialize the no-perturbation generator"""
        pass

    def generate(
        self,
        example_generator: Generator[Network, None, None],
    ) -> Generator[Network, None, None]:
        """Yield the original examples without any perturbations.

        Args:
            example_generator: A generator producing example (load/topology/generation)
                scenarios to which line admittance perturbations are added.

        Yields:
            The original example produced by the example_generator.
        """
        for example in example_generator:
            yield example
__init__()

Initialize the no-perturbation generator

Source code in gridfm_datakit/perturbations/admittance_perturbation.py 
35
36
37
def __init__(self):
    """Initialize the no-perturbation generator"""
    pass
generate(example_generator)

Yield the original examples without any perturbations.

Parameters:

Name Type Description Default
example_generator Generator[Network, None, None]

A generator producing example (load/topology/generation) scenarios to which line admittance perturbations are added.

 required

Yields:

Type Description
Network

The original example produced by the example_generator.
Source code in gridfm_datakit/perturbations/admittance_perturbation.py 
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
def generate(
    self,
    example_generator: Generator[Network, None, None],
) -> Generator[Network, None, None]:
    """Yield the original examples without any perturbations.

    Args:
        example_generator: A generator producing example (load/topology/generation)
            scenarios to which line admittance perturbations are added.

    Yields:
        The original example produced by the example_generator.
    """
    for example in example_generator:
        yield example

PerturbAdmittanceGenerator

Bases: AdmittanceGenerator

Class for applying perturbations to line admittances.

This class is for generating different line admittance scenarios by applying perturbations to the resistance (R) and reactance (X) values of the lines. Perturbations are applied as a scaling factor sampled from a uniform distribution with a given lower and upper bound.

Source code in gridfm_datakit/perturbations/admittance_perturbation.py 
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
class PerturbAdmittanceGenerator(AdmittanceGenerator):
    """Class for applying perturbations to line admittances.

    This class is for generating different line admittance scenarios
    by applying perturbations to the resistance (R) and reactance (X)
    values of the lines.  Perturbations are applied as a scaling factor
    sampled from a uniform distribution with a given lower and upper
    bound.
    """

    def __init__(self, base_net: Network, sigma: float) -> None:
        """
        Initialize the line admittance perturbation generator.
        TODO: add BR_B

        Args:
            base_net: The base power network.
            sigma: A constant that specifies the range from which to draw
                samples from a uniform distribution to be used as a scaling
                factor for resistance and reactance. The range is
                set as [max([0, 1-sigma]), 1+sigma).
        """
        self.base_net = base_net
        self.r_original = self.base_net.branches[:, BR_R]
        self.x_original = self.base_net.branches[:, BR_X]
        self.lower = np.max([0.0, 1.0 - sigma])
        self.upper = 1.0 + sigma
        self.sample_size = self.base_net.branches.shape[0]

    def generate(
        self,
        example_generator: Generator[Network, None, None],
    ) -> Generator[Network, None, None]:
        """Generate a network with perturbed line admittance values.

        Args:
            example_generator: A generator producing example (load/topology/generation)
                scenarios to which line admittance perturbations are added.

        Yields:
            An example scenario with random perturbations applied to line
            admittances.
        """
        for example in example_generator:
            example.branches[:, BR_R] = np.random.uniform(
                self.lower * self.r_original,
                self.upper * self.r_original,
                self.r_original.shape[0],
            )

            example.branches[:, BR_X] = np.random.uniform(
                self.lower * self.x_original,
                self.upper * self.x_original,
                self.x_original.shape[0],
            )

            yield example
__init__(base_net, sigma)

Initialize the line admittance perturbation generator. TODO: add BR_B

Parameters:

Name Type Description Default
base_net Network

The base power network.

 required
sigma float

A constant that specifies the range from which to draw samples from a uniform distribution to be used as a scaling factor for resistance and reactance. The range is set as [max([0, 1-sigma]), 1+sigma).

 required
Source code in gridfm_datakit/perturbations/admittance_perturbation.py 
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
def __init__(self, base_net: Network, sigma: float) -> None:
    """
    Initialize the line admittance perturbation generator.
    TODO: add BR_B

    Args:
        base_net: The base power network.
        sigma: A constant that specifies the range from which to draw
            samples from a uniform distribution to be used as a scaling
            factor for resistance and reactance. The range is
            set as [max([0, 1-sigma]), 1+sigma).
    """
    self.base_net = base_net
    self.r_original = self.base_net.branches[:, BR_R]
    self.x_original = self.base_net.branches[:, BR_X]
    self.lower = np.max([0.0, 1.0 - sigma])
    self.upper = 1.0 + sigma
    self.sample_size = self.base_net.branches.shape[0]
generate(example_generator)

Generate a network with perturbed line admittance values.

Parameters:

Name Type Description Default
example_generator Generator[Network, None, None]

A generator producing example (load/topology/generation) scenarios to which line admittance perturbations are added.

 required

Yields:

Type Description
Network

An example scenario with random perturbations applied to line
Network

admittances.
Source code in gridfm_datakit/perturbations/admittance_perturbation.py 
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
def generate(
    self,
    example_generator: Generator[Network, None, None],
) -> Generator[Network, None, None]:
    """Generate a network with perturbed line admittance values.

    Args:
        example_generator: A generator producing example (load/topology/generation)
            scenarios to which line admittance perturbations are added.

    Yields:
        An example scenario with random perturbations applied to line
        admittances.
    """
    for example in example_generator:
        example.branches[:, BR_R] = np.random.uniform(
            self.lower * self.r_original,
            self.upper * self.r_original,
            self.r_original.shape[0],
        )

        example.branches[:, BR_X] = np.random.uniform(
            self.lower * self.x_original,
            self.upper * self.x_original,
            self.x_original.shape[0],
        )

        yield example