Comparison#

spec_to_keyed_dict(spec, source='')#

Convert PfNetworkSpec to diff-friendly dict keyed by canonical IDs.

Parameters:

  • spec -- Normalized power flow spec.

  • source -- Source file name for metadata.

Returns:

Dict with meta + per-model dicts keyed by canonical identifiers.

export_spec_json(spec, source='', *, indent=2, sort_keys=True)#

Export PfNetworkSpec to JSON string.

Parameters:

  • spec -- Normalized power flow spec.

  • source -- Source file name for metadata.

  • indent -- JSON indentation level.

  • sort_keys -- Sort keys for deterministic output.

Returns:

JSON string.

export_spec_file(spec, path, source='')#

Export PfNetworkSpec to JSON file.

Parameters:

  • spec -- Normalized power flow spec.

  • path -- Output file path.

  • source -- Source file name for metadata.

diff_specs(spec_a, spec_b, source_a='A', source_b='B', *, tolerance=1e-06, ignore_meta=True)#

Compare two PfNetworkSpec instances using DeepDiff.

Parameters:

  • spec_a -- First spec (e.g., from RAW).

  • spec_b -- Second spec (e.g., from MATPOWER).

  • source_a -- Label for first spec.

  • source_b -- Label for second spec.

  • tolerance -- Absolute tolerance for numeric comparison. Default 1e-6 is appropriate for per-unit values; use 1e-4 for cases with known format precision differences.

  • ignore_meta -- If True, ignore meta.source and meta.warning_count.

Returns:

SpecDiff with comparison results.

diff_keyed_dicts(dict_a, dict_b, source_a='A', source_b='B', *, tolerance=1e-06, ignore_meta=True)#

Compare two keyed spec dicts directly.

Useful when working with JSON files exported via export_spec_json().

Direction: Returns changes FROM dict_a TO dict_b.

Parameters:

  • dict_a -- First keyed dict (e.g., loaded from JSON).

  • dict_b -- Second keyed dict.

  • source_a -- Label for first dict.

  • source_b -- Label for second dict.

  • tolerance -- Numeric tolerance.

  • ignore_meta -- If True, ignore meta.source and meta.warning_count.

Returns:

SpecDiff with comparison results.

apply_delta(dict_a, diff, *, in_place=False)#

Apply a diff to transform dict_a into dict_b.

Direction: diff_specs(A, B) produces a diff; apply_delta(A, diff) yields B.

Parameters:

  • dict_a -- Source keyed dict (from spec_to_keyed_dict or JSON).

  • diff -- SpecDiff from diff_specs() or diff_keyed_dicts().

  • in_place -- If True, mutate dict_a. If False, return a new dict.

Returns:

Transformed dict (approximating dict_b).

Note

Due to tolerance-based comparison, the result may not exactly match the original dict_b for values within tolerance.

assert_specs_equal(spec_a, spec_b, *, tolerance=1e-06)#

Assert two specs are equivalent within tolerance.

For use in testing.

Parameters:

  • spec_a -- First spec.

  • spec_b -- Second spec.

  • tolerance -- Numeric tolerance.

Raises:

AssertionError -- If specs differ beyond tolerance.

class SpecDiff(source_a, source_b, sbase_a, sbase_b, basfrq_a, basfrq_b, raw_diff, model_counts=<factory>)#

Bases: object

Structured diff result between two PfNetworkSpec instances.

Wraps DeepDiff output with power-flow-specific accessors.

property direction#

Human-readable direction string.

property has_differences#

True if any differences were found.

property is_equivalent#

True if specs are equivalent within tolerance.

model_summary()#

Per-model summary of counts and differences.

Direction: Changes FROM source_a TO source_b.

summary()#

One-line summary of differences.

to_dict()#

Convert to JSON-serializable dict.

to_json(indent=2)#

Convert to JSON string.