G2ELin

Getting started

  • Getting started (no coding needed)
    • 1. Install Python (once)
    • 2. Download G2ELin
    • 3. Start it
    • While it is running
    • Where to go first
    • If it does not start
  • Installation and setup
    • What you need
    • The short way
    • From the command line
      • Which extras to install
      • Build the manual
      • Run the web interface
      • Run the tests
      • Use it from Python or a notebook
    • Keeping it up to date
    • If something goes wrong
    • Publishing the documentation
    • Running it on a server

Validation

  • Cross-validation against independent references
    • Summary
    • 1. Component linearisation, against the MATLAB toolbox
      • What the reference is
      • Method
      • Result
      • What this does and does not prove
      • A detail worth recording
    • 2. Electromechanical modes, against ANDES
      • What the reference is
      • Most of the work was making the two cases the same case
      • Result
      • Reading the intermediate steps
      • What remains unexplained
    • 3. A side result: the reduction validated independently
    • Limitations
    • What to do next
    • Reproducing

Design notes

  • Excitation, stabiliser and governor models — a proposal
    • 1. Recommendation in one table
    • 2. What G2ELin has today
      • 2.1 The governor as implemented
      • 2.2 The PSS as implemented
      • 2.3 The exciter as implemented
      • 2.4 What is missing, across all three
    • 3. Your question: GENROU and GENCLS
      • 3.1 What they are
      • 3.2 How they differ from the model you have
      • 3.3 The mapping
    • 4. The proposed models
      • 4.1 EXST1 / ST1A — static (thyristor) exciter · 4 states
      • 4.2 SEXS — simplified excitation system · 2 states
      • 4.3 EXDC2 / IEEET1 — DC commutator exciter · 4 states
      • 4.4 PSS1A — single-input stabiliser · 5 states
      • 4.5 IEEEST — generalised single-input stabiliser · 7 states
      • 4.6 TGOV1 — steam governor + turbine · 2 states
      • 4.7 IEEEG1 — detailed steam governor · 6 states
      • 4.8 HYGOV — hydro governor with penstock · 4 states
      • 4.9 GAST — gas turbine · 3 states
    • 5. Decisions to make before implementing
      • 5.1 Limits, gates and dead-bands — the central question
      • 5.2 The reduction catalogue becomes model-dependent
      • 5.3 A block architecture
      • 5.4 Schema, API and UI
      • 5.5 Validation
    • 6. Suggested phasing
    • 7. Open questions for you
    • 8. What the first two models settled
      • 8.0 Fitted, not just tuned
      • 8.1 How the architecture came out
      • 8.2 Two things the models showed that the plan had wrong
      • 8.3 One thing to fix, unrelated to these models

Architecture

  • network — schema and presets
    • Schema
      • Transformers: two roles, one element
      • Bus shunts
      • Each bus’s capacitance
    • Presets
      • Kundur two-area
    • Topology layout
    • Validation
    • Reference
      • BusType
      • UnitType
      • GfmController
      • ExciterModel
      • PssModel
      • GovernorModel
      • Bus
      • Line
      • Transformer
      • Load
      • Shunt
      • StateMode
      • ModelOptions
      • DerUnit
      • Network
      • wscc9_3sm()
      • wscc9_2sm_1gfl()
      • wscc9_1sm_2gfl()
      • wscc9_1sm_1gfm_1gfl()
      • wscc9_1sm_2gfm()
      • wscc9_2sm_1gfm()
      • wscc9_1gfm_2gfl()
      • wscc9_3gfm()
      • cigre_islanded_1sm_1gfm_1gfl()
      • cigre_islanded_1sm_2gfm_1gfl()
      • cigre_islanded_1sm_3gfm_1gfl()
      • cigre_islanded_2sm_2gfm_2gfl()
      • sm_smib()
      • gfm_smib()
      • gfl_smib()
      • sm_smsm()
      • gfm_smsm()
      • gfl_smsm()
      • cigre_interconnected_1sm_1gfm_1gfl()
      • kundur_machine_params()
      • kundur_two_area()
      • kundur_two_area_classic()
      • ieee14()
      • ieee39()
      • ieee118()
      • BusNode
      • TopologyEdge
      • NetworkTopology
      • compute_topology_layout()
      • NetworkIssue
      • validate_network()
  • powerflow — static power flow
    • Build → solve → read back
    • Physics: the AC power-flow problem
    • Reference
      • build_pandapower_net()
      • PowerFlowResult
      • run_power_flow()
  • pu_base and operating_point
    • pu_base — amplitude-invariant per-unit bases
    • operating_point — from PowerFlowResult to per-component operating points
    • Physics
      • Per-unit bases
      • Default synchronous-machine parameters
      • GFM/GFL loop-tuning: rise-time pole placement
      • From a solved power flow to a DER’s own operating point
    • Per-unit rebasing: DerUnit.sn_mva
    • Reference
      • PuBase
      • pu_base()
      • sm_params()
      • gfm_outer_tuning()
      • gfm_retuned()
      • gfm_params()
      • gfl_params()
      • overridable_param_keys()
      • unit_keys()
      • unit_transformer_rx()
      • unit_params()
      • rebase_params()
      • apply_param_overrides()
      • NetworkOperatingPoint
      • compute_operating_point()
  • components — symbolic nonlinear-then-linearized models
    • The shared machinery (components.base)
    • Per-component modules
    • Physics: the full nonlinear equations
      • Synchronous machine (sm.py)
      • Grid-forming converter (gfm.py)
      • Grid-following converter (gfl.py)
      • Infinite bus (ib.py)
      • Transmission line (line.py)
      • Network node (node.py)
      • Constant-impedance load (load.py)
      • Linearization, in one place
    • Reference
      • LinearComponent
      • NonlinearFuncs
      • NonlinearJacobians
      • ComponentDAE
      • build_dae()
      • eq_symbol()
      • mode_key()
      • apply_reduction()
      • equilibrium_subs()
      • RebuiltWithParams
      • ExciterKind
      • PssKind
      • GovernorKind
      • sm_dae()
      • sm_nonlinear_funcs()
      • sm_nonlinear_jacobians()
      • SmOperatingPoint
      • EXCITER_SYMBOLS
      • EXCITER_GAIN_KEY
      • EXCITER_PARAM_NAMES
      • linearize_sm()
      • sm_nonlinear_point()
      • GfmControlKind
      • OUTER_SYMBOLS
      • gfm_dae()
      • gfm_nonlinear_funcs()
      • gfm_nonlinear_jacobians()
      • GfmOperatingPoint
      • linearize_gfm()
      • gfm_nonlinear_point()
      • gfl_dae()
      • gfl_nonlinear_funcs()
      • gfl_nonlinear_jacobians()
      • GflOperatingPoint
      • linearize_gfl()
      • gfl_nonlinear_point()
      • ib_dae()
      • linearize_ib()
      • ib_nonlinear_funcs()
      • ib_nonlinear_jacobians()
      • ib_nonlinear_point()
      • frame_dae()
      • frame_nonlinear_funcs()
      • frame_nonlinear_jacobians()
      • linearize_frame()
      • frame_nonlinear_point()
      • line_dae()
      • line_nonlinear_funcs()
      • line_nonlinear_jacobians()
      • linearize_line()
      • line_nonlinear_point()
      • node_dae()
      • node_nonlinear_funcs()
      • node_nonlinear_jacobians()
      • linearize_node()
      • node_nonlinear_point()
      • load_dae()
      • load_nonlinear_funcs()
      • load_nonlinear_jacobians()
      • linearize_load()
      • load_nonlinear_point()
  • interconnect — wiring components into one closed-loop system
    • Block / Wiring / Topology
    • From wiring rules to a closed-loop state-space
    • Physics: closed-loop elimination
    • Reference
      • PortSpec
      • Block
      • AssembledSystem
      • Wiring
      • Topology
      • compute_topology()
      • assemble()
      • AssemblyParts
      • assembly_parts()
      • PerturbationProjector
      • build_blocks_and_wiring()
      • assemble_network()
  • pipeline and modal — linear small-signal analysis end to end
    • linearize_network()
    • modal.analyze()
    • modal.toolbox — the rest of modal_analysis.m
    • Physics: modal analysis
      • modal.toolbox — sensitivity, mode shape, free/step response
    • Reference
      • linearize_network()
      • linear_components()
      • ModalAnalysisResult
      • reference_angle_modes()
      • unregulated_frequency_mode()
      • analyze()
      • SensitivityEntry
      • SensitivityResult
      • eigenvalue_sensitivity()
      • ModeShapeResult
      • mode_shape()
      • free_response()
      • step_response()
  • reduction — model order, and what a time-domain run means
    • The one idea
    • Two reductions, not one
    • The catalogue
      • Network
      • The catalogue is per unit, not per type
      • Synchronous machine
      • Grid-forming converter
      • Grid-following converter
    • What the choice makes the simulation
    • Pairing rules
    • The same categories classify modes
    • Is it safe? The adequacy check
    • Where the settings live
    • Performance
    • Further reading
      • ElementModel
      • StateGroup
      • element()
      • resolve_modes()
      • level_ids()
      • group_ids()
      • describe()
      • category_of_state()
      • group_of_state()
      • split_state_name()
      • sm_element()
      • gfm_element()
      • StateRisk
      • ModePair
      • AdequacyReport
      • check_adequacy()
  • timeseries — multi-scenario load flow, no dynamics
    • Reference
      • Snapshot
      • apply_snapshot()
      • scale_loads()
      • dispatch_sweep()
      • TimeSeriesResult
      • run_time_series()
  • timedomain — EMT (nonlinear) time-domain simulation
    • Why a single global Newton solve, not one per component
    • NonlinearBlockComp and NonlinearNetworkModel
    • Recovering inputs and outputs after the fact
    • Physics: the coupled nonlinear DAE
    • Choosing a solver
      • The Jacobian, first
      • Method
      • Tolerance
      • Fixed stepping
    • Reference
      • NonlinearBlockComp
      • nonlinear_sm_block()
      • nonlinear_gfm_block()
      • nonlinear_gfl_block()
      • nonlinear_ib_block()
      • nonlinear_frame_block()
      • nonlinear_line_block()
      • nonlinear_node_block()
      • nonlinear_load_block()
      • NonlinearNetworkModel
      • build_nonlinear_network()
      • EmtSimulationResult
      • find_state_index()
      • simulate()
      • simulate_fixed_step()
      • EmtStep
      • simulate_steps()
  • g2elin_api and the web UI
    • Endpoints → pages
    • /api/network/* — arbitrary networks, not just presets
    • Mount layout
    • The web UI itself
    • Reference
      • list_presets()
      • get_preset_network()
      • get_topology()
      • list_powerflow_algorithms()
      • list_solvers()
      • list_model_levels()
      • unit_defaults()
      • unit_retune()
      • run_powerflow()
      • run_powerflow_batch()
      • run_modal()
      • run_modal_sensitivity()
      • run_modal_mode_shape()
      • run_modal_free_response()
      • run_modal_step_response()
      • run_timeseries()
      • list_states()
      • run_emt()
      • run_emt_live()
      • bus_rows()
      • powerflow_tables()
      • topology_response()
      • validate_network_response()
      • energized_or_422()
      • runpp_kwargs()
      • solve_powerflow_or_422()
      • powerflow_response()
      • batch_powerflow_response()
      • build_modal_from_network()
      • named_index_or_422()
      • mode_or_422()
      • modal_response()
      • modal_sensitivity_response()
      • modal_parameter_sensitivity_response()
      • modal_mode_shape_response()
      • modal_free_response_response()
      • modal_step_response_response()
      • timeseries_response()
      • build_nonlinear_model_from_network()
      • find_state_or_422()
      • states_response()
      • measurement_set()
      • linear_overlay()
      • solvers_response()
      • emt_response()
      • prepare_emt_live()
      • emt_live_stream()
      • model_levels_response()
      • model_summary_response()
      • adequacy_response()
      • network_validate()
      • network_model()
      • network_model_adequacy()
      • network_topology()
      • network_powerflow()
      • network_powerflow_batch()
      • network_modal()
      • network_modal_sensitivity()
      • network_modal_parameter_sensitivity()
      • network_modal_mode_shape()
      • network_modal_free_response()
      • network_modal_step_response()
      • network_timeseries()
      • network_states()
      • network_emt()
      • network_emt_live()
      • network_modal_sweep()
      • PresetInfo
      • get_preset()
      • BusRow
      • PowerFlowOptions
      • PowerFlowRequest
      • PowerFlowResponse
      • ModeCategoryInfo
      • ModeRow
      • ModalResponse
      • SensitivityRequest
      • SensitivityEntryRow
      • SensitivityResponse
      • ParameterSensitivityRequest
      • ParameterEffectRow
      • EntryParametersRow
      • ParameterSensitivityResponse
      • ModeShapeRequest
      • ModeShapeResponse
      • FreeResponseRequest
      • FreeResponseResponse
      • StepResponseRequest
      • StepResponseResponse
      • TimeSeriesSnapshot
      • TimeSeriesResponse
      • BatchPowerFlowRequest
      • BatchSnapshot
      • BatchPowerFlowResponse
      • MeasurementInfo
      • StatesResponse
      • BusNodeRow
      • TopologyEdgeRow
      • TopologyResponse
      • NetworkEventSpec
      • EmtRequest
      • SolverInfo
      • SolversResponse
      • LinearOverlay
      • EmtResponse
      • PresetSummary
      • ErrorResponse
      • NetworkRequest
      • NetworkPowerFlowRequest
      • NetworkBatchPowerFlowRequest
      • NetworkParameterSensitivityRequest
      • NetworkSensitivityRequest
      • NetworkModeShapeRequest
      • NetworkFreeResponseRequest
      • NetworkStepResponseRequest
      • NetworkEmtRequest
      • SweepTarget
      • SweepExtra
      • SweepRequest
      • NetworkSweepRequest
      • UnitDefaultsRequest
      • UnitRetuneRequest
      • UnitRetuneResponse
      • UnitDefaultsResponse
      • NetworkIssueRow
      • IslandRow
      • ServiceInfo
      • ValidateResponse
      • StateGroupInfo
      • ModelLevelInfo
      • RegulatorOptionInfo
      • RegulatorSlotInfo
      • ElementModelInfo
      • ModelLevelsResponse
      • UnitModelRow
      • ModelSummaryResponse
      • StateRiskRow
      • ModePairRow
      • AdequacyRequest
      • AdequacyResponse
    • Zooming a plot
  • Worked example: CIGRE islanded, 1 SM + 1 GFM + 1 GFL
    • 1. The network
    • 2. Power flow
    • 3. Operating point
    • 4. Components, in isolation
    • 5. Interconnection
    • 6. Modal analysis — reading the eigenvalue map correctly
    • 7. Linear prediction vs. the actual nonlinear transient
    • 8. Time-series load sweep
    • Summary
  • CIGRE islanded 1 SM + 1 GFM + 1 GFL — a complete worked example
    • Run-time toggles
    • 1. Network definition
    • 2. Topology
    • 3. Power flow
    • 4. Per-unit bases
    • 5. Operating point
    • 6. Components — each unit’s own isolated dynamics
    • 7. Interconnection + the closed-loop system
    • 8. Modal analysis
    • 9. The rest of the modal toolbox
    • 10. Nonlinear EMT simulation: does the linear prediction hold?
      • 10a. Perturbing a state
      • 10b. Perturbing an input, via u_exo_fn
    • 11. Time-series load sweep
    • Summary
  • Building a random network from scratch — a tour of Network’s conventions
    • Run-time toggles
    • 1. The convention a network builder has to respect
    • 2. Build one, and look at it
    • 3. validate_network() — the cheap pre-flight check
    • 4. Topology, power flow, modal analysis
    • 5. modal.toolbox — every option
    • 6. Nonlinear EMT simulation — every option
      • 6a. Perturbing a state — traced live, step by step
      • 6b. Perturbing an input, via u_exo_fn
    • 7. Layer 1 — what pydantic rejects outright
    • 8. Layer 2 — what validate_network() catches
    • 9. Robustness across many random networks
    • Good practices to take away
G2ELin
  • Search

© Copyright 2026, Fadi Kelada.

Built with Sphinx using a theme provided by Read the Docs.