Vision converter

The Vision Excel converter converts the Excel exports from Vision to PGM data format. As mentioned in Converters, Vision Excel converter is an implementation of the tabular converter. The default mapping of all attributes is stored in the vision_en.yaml and vision_nl.yaml files in config directory. Custom mapping files are supported via passing the file directory to the constructor of the converter.

Load rate of elements

Certain elements in Vision, i.e., appliances like transformer loads and induction motor have a result parameter of load rate. In Vision, load rates are calculated without considering the simultaneity factors of connected nodes. So we may observe a variation in power inflow/outflow result (i.e., P, Q and S) due to different simultaneity factors. But the load rate always corresponds to simultaneity of loads=1.

When we make conversion to PGM, the input data attributes of PGM for loads like p_specified and q_specified are modified as per simultaneity. The resulting loading then takes simultaneity into account. Hence, the loading of such elements may not correspond to the load rate obtained in Vision

Transformer load modeling

power-grid-model-io converts the transformer load into a individual transformer and a load for usage in power-grid-model. To the best of our knowledge, Vision modeles a transformer load differently than an individual transformer plus load. There is a minor difference in both the reactive power consumed and generated. This might correspond to a minor voltage deviation in the results.

Tip

To avoid this issue, it is recommended to split the transformer load into individual components in Vision beforehand. This can be done by first selecting the transformer loads: [Start | Select | Object -> Element -> Check Transformer load -> Ok], then split it into individual components: [Start | Edit | Topological | Split]

Voltage angle of buses in symmetric power-flow

Note that in symmetrical calculations, Vision does not include clock angles of transformers in the result of voltage angles. power-grid-model, however, does consider them. Therefore when doing a direct comparison of angle results, this needs to be taken into consideration.

Modeling differences or unsupported attributes

Some components are yet to be modeled for conversions because they might not have a straightforward mapping in power-grid-model. Those are listed here.

• power-grid-model currently does not support PV(Active Power-Voltage) bus and related corresponding features.

• Currently, the efficiency type of PVs(Photovoltaics) element is also unsupported for all types except the 100% type. For the efficiency type: 0, 1 pu: 93 %; 1 pu: 97 %, the generation power is multiplied by 97% as a closest approximation.

• The conversions for load behaviors of industry, residential and business are not yet modeled. The load behaviors usually do not create a significant difference in power-flow results for most grids when the voltage at bus is close to 1 pu. Hence, the conversion of the mentioned load behaviors is approximated to be of Constant Power type for the time being.

• The source bus in power-grid-model is mapped with a source impedance. Sk"nom, R/X and Z0/Z1 are the attributes used in modeling source impedance. In Vision, these attributes are used only for short circuit calculations

• The load rate for transformer is calculated in Vision by current i.e., load_rate = max(u1 * I1, u2 * I2) * sqrt(3) / Snom * 100. Whereas in power-grid-model, loading is calculated by power, i.e., loading = max(s1,s2)/sn. (Note: The attribute names are as per relevant notation in Vision and PGM respectively). This gives a slight difference in load rate of transformer.

• A minor difference in results is expected since Vision uses a power mismatch in p.u. as convergence criteria whereas power-grid-model uses voltage mismatch.

• The Voltage Control option in vision is modelled by transformer_tap_regulator in PGM. Currently, PGM only supports line drop compensation on both loading and generating direction. So this is equivalent to unchecking of Also in backw. direction. Neither Load Dependent compensation or a master-slave configuration for control under the State section is supported.

Accomdation of UUID-based id system since Vision 9.7

Vision introduced UUID based identifier system since version 9.7. It is implemented following the Microsoft naming scheme by replacing all the original identifier fields (i.e., ‘*Number’, ‘*Subnumber’, ‘*Nummber’ and ‘*Subnummer’) to GUID. This change brings the many benefits of UUIDs in general while on the other hand adds certain work on the conversion side. Since computations in PGM alone do not benefit from a string based identifier, we hence made the descision to perform UUID to integer conversion while maintaining the ‘GUID’ information in the extra_info field. Note that existing mapping files can still be used without significant changes, apart from adding GUID to the extra fields of interest.

An examplery usage can be found in the example notebook as well as in the test cases.

Optional extra columns

When working with Vision Excel exports, some metadata columns (like GUID or StationID) may not always be present, especially in partial exports. The optional_extra feature allows you to specify columns that should be included in extra_info if present, but won’t cause conversion failure if missing.

Syntax:

grid:
  Transformers:
    transformer:
      id:
        auto_id:
          key: Number
      # ... other fields ...
      extra:
        - ID            # Required - fails if missing
        - Name          # Required - fails if missing
        - optional_extra:
            - GUID      # Optional - skipped if missing
            - StationID # Optional - skipped if missing

Behavior:

• Required columns (listed directly under extra) will cause a KeyError if missing

• Optional columns (nested under optional_extra) are silently skipped if not found

• If some optional columns are present and others missing, only the present ones are included in extra_info

• This feature is particularly useful for handling different Vision export configurations or versions

Duplicate handling: When a column appears in both the regular extra list and within optional_extra, the regular extra entry takes precedence and duplicates are automatically eliminated from optional_extra:

extra:
  - ID              # Regular column - always processed
  - Name            # Regular column - always processed  
  - optional_extra:
      - ID          # Duplicate - automatically removed
      - GUID        # Unique optional - processed if present
      - StationID   # Unique optional - processed if present

In this example, ID will only be processed once (from the regular extra list), while GUID and StationID are processed as optional columns. This prevents duplicate data in the resulting extra_info and ensures consistent behavior regardless of column ordering.

Common/Known issues related to Vision

So far we have the following issue known to us related to Vision exported spread sheets. We provide a solution from user perspective to the best of our knowledge.

Duplicated P columns

Vision can export sheets with duplicated P columns, one of which being unitless additional information. This field is of no actual purpose within PGM calculation. In case of duplicate column names, PGM-IO renames them to, e.g., P, P_2 and so on. However the change in mapping to the duplicate name should be done manually by the user in a custom mapping file.

Tip: We advice users to uncheck the specifics when exporting from Vision and an extra P column would not appear.

Different names for columns

In different versions of exports, user can sometimes find different names for columns. For example, the column name N1 might be represented as Grounding1 in some exports. To address this, the VisionExcelConverter’s terms_changed argument can be used.

Sheets being ignored

In different versions of exports, user can find different names for the spreadsheets. All sheets not specified in the mapping file are ignored for conversion. Hence if the mapping has an incorrect sheet name, they would not be considered in conversion and no error shall be given out. The user should use the adequate mapping file for different vision versions. And if the default mapping is modified, it is advised to verify if all required sheets are being converted.

Security Considerations

Safe XML parsing is used to process Excel-based inputs, ensuring secure handling of mapping and tabular data. See security considerations of the tabular_converter