VeraGrid Documentation

The FMU (Functional Mock-up Unit) import infrastructure in VeraGrid is currently under development. It is designed to handle the parsing and execution of FMUs within the VeraGrid ecosystem, specifically focusing on the following capabilities:

• Parsing modelDescription.xml files.
• Detecting whether an FMU is a CoSimulation or ModelExchange type.
• Validating bindings against FMI causality rules.
• Opening and executing FMUs using the FMPy library.

Note: This infrastructure is currently in trunk and the API is considered unstable. Integration with RMS (Root Mean Square) and EMT (Electromagnetic Transient) solvers is still in progress, and coupling between these modes is not yet implemented.

The VeraGrid FMU Export package provides a non-invasive FMI 2.0 Co-Simulation export pipeline for VeraGrid symbolic Block models. It is designed to snapshot and reconstruct models using to_dict() and Block.parse(), flatten them on an isolated copy, and build a deterministic export IR (Intermediate Representation) used for both XML and C generation. The final output is a standalone C runtime template for the resulting FMU.

Note that this package is located under trunk.veragrid_fmu_export to allow it to evolve independently of the core engine package layout.

The VeraGrid AI Knowledge Catalog provides a structured index of documentation, GUI components, and engine logic. Developers and AI agents can use this catalog to locate specific technical information across three main categories:

1. Documentation Assets: High-level guides covering power flow, grid reduction, contingency analysis, optimal power flow, and installation.
2. GUI/Main Assets: Detailed technical documentation for the graphical user interface, including MainWindow, Model subclasses (scenarios, time events, diagrams), Results handling, Scripting, and Server components.
3. VeraGridEngine Assets: Low-level engine logic and implementation details.

This catalog serves as a map for navigating the project's extensive codebase and documentation.

VeraGrid is a power systems planning and simulation software providing a wide range of analysis studies, including:

• Power Flow: AC/DC multi-grid, 3-phase unbalanced, AC/DC Stochastic, and AC Continuation power flow.
• Optimization: AC/DC multi-grid linear optimal power flow, AC linear analysis (PTDF & LODF), and Net Transfer Capacity (NTC) calculations.
• Stability & Contingency: Contingency analysis (Power flow and LODF variants), Sigma analysis (one-shot stability), and RMS/EMT simulations.
• Grid Modeling: Large device collection, Bus-branch schematics, Substation-line maps, and Overhead tower designer.
• Data I/O:
  • Import: PSSe (.raw/.rawx), epc, dgs, matpower, pypsa, json, cim, cgmes.
  • Export: .xlsx, .veragrid, .json, matpower, cgmes, psse (.raw/.rawx).

The VeraGridEngine assets are organized into two main categories for AI knowledge retrieval and system modeling:

1. GUI/Main Assets: Assets primarily used by the graphical user interface.
2. VeraGridEngine Assets: Core engine assets, specifically the CGMES v2.4.15 device definitions used for grid modeling and I/O operations.

Developers building extensions or using the AI agent should refer to the specific devices sub-modules to understand the properties and behaviors of individual grid components like acdc_converter, breaker, or power_transformer.

VeraGrid is licensed under the Mozilla Public License 2.0 (MPLv2).

Key implications for developers:

• Commercial Use: You are permitted to use VeraGrid for commercial work and sell commercial services based on it.
• Distribution: If you distribute VeraGrid, you must also distribute its source code (typically as Python code).
• Non-Propagation: The VeraGrid license does not propagate to your own code, even if you use VeraGrid or parts of it within your project. However, you must retain the individual file licensing for VeraGrid files.

The VeraGrid GUI provides several specialized editors and views for grid construction, editing, and inspection:

• Schematic Editor: The primary tool for visual construction and inspection of the grid.
• Tabular Editor: Used for bulk-editing grid data.
• Time-Series Editor: Manages profile data and time-based events.
• Results & Tabular-Results Views: The primary surfaces for inspecting simulation outputs.
• Console: Provides access to in-GUI scripting and automation capabilities.
• Tooltips: Many GUI controls are documented via tooltips within the interface.

The adjustText library is designed to prevent text labels from overlapping with data points or other labels in matplotlib plots. It works by iteratively adjusting label positions to minimize overlaps.

For best results with minimal tweaking:

1. Make the text slightly smaller than the default matplotlib size.
2. Make the figure size slightly larger.

For highly complex plots, the underlying algorithm is highly configurable.

The cvxoptklu plugin exposes SparseSolver.KLU through the VeraGrid EMT sparse backend interface. It is designed to provide a benchmarkable alternative to the internal SuperLU backend while keeping external packages outside the VeraGrid core.

Current Limitations

This version is an integration-ready first release and has the following limitations:

• Each solve is delegated through the external KLU wrapper.
• It does not yet expose symbolic-analysis reuse.
• It does not yet expose numeric-only refactorization.

A Winding is a terminal element used within multi-winding transformer representations. It serves as a link between terminals or represents a network element between two buses (bus_from and bus_to).

Key characteristics include:

• Connectivity: Connects a bus_from to a bus_to.
• Modeling: Can be used for RMS or EMT dynamic modeling via rms_model/emt_model or FMU templates (rms_fmu_template/emt_fmu_template).
• Impedance: Defines electrical properties such as resistance (R), reactance (X), conductance (G), and susceptance (B) for positive, zero, and negative sequences.