Diagnostic Function

A power flow calculation on a pandapower network can fail to converge for a vast variety of reasons, which often makes debugging difficult, annoying and time consuming. To help with that, a range of diagnostic functions can automatically check pandapower networks for the most common issues leading to errors.

For convienience a function is provided that creates the Diagnostic object and runs the diagnostic.

pandapower.diagnostic.diagnostic_helpers.diagnostic(net, report_style='detailed', warnings_only=False, return_result_dict=True, overload_scaling_factor=0.001, lines_min_length_km=0., lines_min_z_ohm=0., nom_voltage_tolerance=0.3, **kwargs)

Tool for diagnosis of pandapower networks. Identifies possible reasons for non converging loadflows.

Parameters:

net (pandapowerNet) – A pandapower network
report_style (Literal['compact', 'detailed'] | None) – style of the report, that gets ouput in the console ‘detailed’: full report with high level of additional descriptions ‘compact’ : more compact report, containing essential information only ‘None’ : no report
warnings_only (bool) – Filters logging output for warnings True: logging output for errors only False: logging output for all checks, regardless if errors were found or not
return_result_dict (bool) – returns a dictionary containing all check results True: returns dict with all check results False: no result dict
overload_scaling_factor (float) – downscaling factor for loads and generation for overload check
lines_min_length_km (float) – minimum length_km allowed for lines
lines_min_z_ohm (float) – minimum z_ohm allowed for lines
nom_voltage_tolerance** (float, 0.3) – highest allowed relative deviation between nominal voltages and bus voltages
nom_voltage_tolerance (float)

Keyword Arguments:

Any – Keyword arguments for the power flow function to use during tests. If “run” is in kwargs the default call to runpp() is replaced by the function kwargs[“run”]

Returns:

dict that contains the indices of all elements where errors were found: Format: {‘check_name’: check_results}

Example

>>> from pandapower.diagnostic.diagnostic_helpers import diagnostic
>>> diagnostic(net, report_style='compact', warnings_only=True)

Diagnostic Class

A class provides automated execution and a reporting functionality for ease of use.

class pandapower.diagnostic.Diagnostic(add_default_functions=True)

A Diagnostic Tool Class for diagnosing and reporting on issues in a ADict subclassed network

default Diagnostic Functions are for networks of type pandapowerNet

Parameters:: add_default_functions (bool) – Should the default DiagnosticFunctions for pandapower networks be added.

Example

>>> from pandapower.diagnostic import Diagnostic
>>> from pandapower.networks.mv_oberrhein import mv_oberrhein
>>>
>>> net = mv_oberrhein()
>>> diag = Diagnostic()
>>> result = diag.diagnose_network(net, report_style="detailed")

pandapower.diagnostic.Diagnostic.register_function(self, diagnostic_function, argument_names, name)

register a diagnostic function to run when running network diagnostics and the associated report function.

Parameters:

diagnostic_function (DiagnosticFunction) – instance of class implementing the DiagnosticFunction Base Class
argument_names (list[str] | None) – the kwargs that should be passed to the diagnostic function. If None is provided all kwargs will be passed.
name (str | None) – name to use for results dict and reports, if None will use name of the class

Example

>>> from pandapower.diagnostic import Diagnostic
>>> from pandapower.diagnostic.diagnostic_functions import DeviationFromStdType
>>>
>>> diag = Diagnostic(add_default_functions=False)
>>> diag.register_function(DeviationFromStdType(), None)
>>> diag.register_function(DeviationFromStdType(), None, "dev_from_std_twice")

pandapower.diagnostic.Diagnostic.diagnose_network(self, net, report_style='detailed', warnings_only=False, return_result_dict=True, **kwargs)

Tool for diagnosis of pandapower networks. Identifies possible reasons for non converging loadflows.

Parameters:

net (ADict) – the network to run the registerd diagnostic functions on
report_style (Literal['compact', 'detailed'] | None) – style of the report, that gets ouput in the console - ‘detailled’: full report with high level of additional descriptions - ‘compact’ : more compact report, containing essential information only - ‘None’ : no report
warnings_only (bool) – Filters logging output for warnings True: logging output for errors only False: logging output for all checks, regardless if errors were found or not
return_result_dict (bool) – returns a dictionary containing all check results True: returns dict with all check results False: no result dict
overload_scaling_factor – downscaling factor for loads and generation for overload check
lines_min_length_km – minimum length_km allowed for lines
lines_min_z_ohm – minimum z_ohm allowed for lines
nom_voltage_tolerance – highest allowed relative deviation between nominal voltages and bus voltages

Keyword Arguments:

any – for the power flow function to use during tests. If “run” is in kwargs the default call to runpp() is replaced by the function kwargs[“run”]

Returns:

A dict that contains the the result of each diagnostic function, can be passed to its report function for interpretation.

Return type:

dict[str, Any] | None

Example

>>> from pandapower.diagnostic import Diagnostic
>>> d = Diagnostic()
>>> results = d.diagnose_network(net, report_style='compact', warnings_only=True)
>>> d.compact_report()
>>> d.detailed_report()

pandapower.diagnostic.Diagnostic.compact_report(self, warnings_only=False)

Generate the compact diagnostic report.

Parameters:: warnings_only (bool) – If True only warnings are printed
Raises:: RuntimeError – When called and no diagnostic results are available.

pandapower.diagnostic.Diagnostic.detailed_report(self, warnings_only=False)

Generate the detailed diagnostic report.

Parameters:: warnings_only (bool) – If True only warnings are printed
Raises:: RuntimeError – When called and no diagnostic results are available.

pandapower.diagnostic.diagnostic.Diagnostic.report(self, compact_report=True, warnings_only=False)

Generate a diagnostic report.

Parameters:

compact_report (bool) – diagnostic report should be compact or detailed
warnings_only (bool) – diagnostic report should be only warnings or all info

Raises:

RuntimeError – When called and no diagnostic results are available.

Return type:

None

Usage ist very simple: Just call the function and pass the net you want to diagnose as an argument. Optionally you can specify if you want detailed logging output or summaries only and if the diagnostic should log all checks performed vs. errors only.

Default Diagnostic functions

The DiagnosticFunction implementing classes included with pandapower. These will be added to Diagnostic instances by default.

class pandapower.diagnostic.diagnostic_functions.DeviationFromStdType: Checks, if element parameters match the values in the standard type library.

class pandapower.diagnostic.diagnostic_functions.DifferentVoltageLevelsConnected: Checks if there are lines or switches that connect different voltage levels.

class pandapower.diagnostic.diagnostic_functions.DisconnectedElements: Checks, if there are network sections without a connection to an ext_grid. Returns all network elements in these sections, that are in service. Elements belonging to the same disconnected networks section are grouped in lists (e.g. disconnected lines: [[1, 2, 3], [4, 5]] means, that lines 1, 2 and 3 are in one disconnected section but are connected to each other. The same stands for lines 4, 5.)

class pandapower.diagnostic.diagnostic_functions.ImplausibleImpedanceValues: Checks, if there are lines, xwards or impedances with an impedance value close to zero.

class pandapower.diagnostic.diagnostic_functions.InvalidValues: Applies type check functions to find violations of input type restrictions.

class pandapower.diagnostic.diagnostic_functions.MissingBusIndices: Checks for missing bus indices.

class pandapower.diagnostic.diagnostic_functions.MultipleVoltageControllingElementsPerBus: Checks, if there are buses with more than one generator and/or more than one external grid.

class pandapower.diagnostic.diagnostic_functions.NoExtGrid: Checks, if at least one external grid exists.

class pandapower.diagnostic.diagnostic_functions.NominalVoltagesMismatch

Checks, if there are components whose nominal voltages differ from the nominal voltages of the buses they’re connected to. At the moment, only trafos and trafo3w are checked. Also checks for trafos with swapped hv and lv connectors.

class pandapower.diagnostic.diagnostic_functions.NumbaComparison: Compares the results of loadflows with numba=True vs. numba=False.

class pandapower.diagnostic.diagnostic_functions.OptimisticPowerflow

Checks, if powerflow converges, if a set of ‘optimistic’ tests is performed.

class pandapower.diagnostic.diagnostic_functions.Overload

Checks, if a loadflow calculation converges. If not, checks, if an overload is the reason for that by scaling down the loads, gens and sgens to 0.1%.

class pandapower.diagnostic.diagnostic_functions.ParallelSwitches: Checks for parallel switches.

class pandapower.diagnostic.diagnostic_functions.SlackGenPlacement

Checks, if powerflow converges/losses are minimized, if a different gen is used as slack

class pandapower.diagnostic.diagnostic_functions.SubNetProblemTest

Checks, if subnets are converging. This is done using the zone attribute.

class pandapower.diagnostic.diagnostic_functions.TestContinuousBusIndices: Checks, if powerflow works, when a continuous bus index is used.

class pandapower.diagnostic.diagnostic_functions.WrongLineCapacitance

Checks, if a loadflow calculation converges. If not, checks, if line capacitance is too high, by scaling it to 1%.

class pandapower.diagnostic.diagnostic_functions.WrongReferenceSystem

Checks usage of wrong reference system for loads, sgens and gens.

class pandapower.diagnostic.diagnostic_functions.WrongSwitchConfiguration: Checks, if a loadflow calculation converges. If not, checks, if the switch configuration is the reason for that by closing all switches

Logging Output

Here are a few examples of what logging output looks like:

detailed_report = True/False

Both reports show the same result, but on the left hand picture with detailed information, on the right hand picture summary only.

warnings_only = True/False

Result Dictionary

Additionally all check results are returned in a dict to allow simple access to the indices of all element where errors were found.

Custom Diagnostic Functions

Create a class that implements the DiagnosticFunction mete class.

class pandapower.diagnostic.DiagnosticFunction: A meta class for creating custom Diagnostic Functions that can be executed with the pandapower Diagnostic API.

pandapower.diagnostic.DiagnosticFunction.diagnostic(self, net, **kwargs)

A diagnostic method that should be run on the network.

Parameters:

net (N) – the network to run it on
kwargs – any kwargs passed to diagnose_network

Returns:

the diagnostic result or None if successful

Return type:

T | None

pandapower.diagnostic.DiagnosticFunction.report(self, error, results)

A method to generate a report for the result of diagnostic.

Parameters:

error (Exception | None) – when the diagnostic encountered an error it will be passed here
results (T | None) – when the diagnostic produced an output it will be passed here

Return type:

None

The first lines should always check if an error occurred or there are no results

>>> # error and success checks
>>> if error is not None:
>>>     self.out.warning("Check for < > failed due to the following error:")
>>>     self.out.warning(error)
>>>     return
>>> if results is None:
>>>     self.out.info("PASSED: < > successful.")
>>>     return
>>> # message header
>>> ...
>>> # message body
>>> ...
>>> # message summary

There are additional levels defined for the self.out logger.

>>> self.out.detailed

and

>>> self.out.compact

These will only print in the resepctive reports. Use info if the message should only show when warnings_only is False. Use warning if the message should always be shown.