v0.1.0

First public release of gridfm-trustlayer: statistically valid error bars on grid-state predictions, without retraining the model.

gridfm-trustlayer wraps the point predictions of a power-system foundation model, such as a GridFM power-flow model, in intervals that contain the true AC value with a probability you choose, for example 90%. It learns how large the model's errors are on scenarios with a known solution, and turns them into bounds on bus voltages and line loadings for new scenarios, including contingencies the model never saw in training. In N-k contingency screening, only the contingencies whose bounds cross a limit need a full AC power flow.

Highlights

• Two conformal methods. Stratified split-conformal prediction (cp_type: element), with a finite-sample coverage guarantee when calibration and test scenarios are exchangeable, and kernel-weighted conformal prediction (cp_type: kernel), which adapts the bounds to each scenario using the model's embeddings, and whose bandwidth can be chosen by cross-validation (n_eff_target: auto).
• Stratification by number of outages, outage type, system load or predicted value, so that bounds widen where the model is less accurate.
• Voltages and line loading: Vm and Va directly, and line_loading derived from the predicted voltages with gridfm-datakit's branch-flow routine.
• Screening against operating limits. Every value is within limits, uncertain or a violation, and every operating scenario secure, uncertain or insecure, next to the point prediction alone. Only uncertain scenarios need an AC power flow.
• Fit, validate, operate: compute fits the layer on a calibration set, calibrate and screen check coverage and screening on a test set with known solutions, and apply gives bounds and statuses for new scenarios without any AC solution.
• Readable reports: a summary.md with tables and figures for each command, CSVs by stratum and element, and partitioned parquet outputs in the layout of gridfm-datakit.
• Python API on plain NumPy arrays, for any model: NaiveIntervalCalibrator, KernelIntervalCalibrator, classify_status, scenario_status.
• A demo notebook on IEEE 14-bus N-1 to N-5 contingencies, with a released GridFM model and the data included. There, the point prediction calls 74 insecure scenarios secure; the 90% intervals call 7, while sending 10% of the scenarios to an AC power flow.

Install

pip install gridfm-trustlayer

Extras: datakit (needed for line_loading) and interactive (a Jupyter form that writes the config):

pip install "gridfm-trustlayer[datakit,interactive]"

Python 3.10 to 3.12, CPU only, no PyTorch dependency.

Get started

• Documentation: https://gridfm.github.io/gridfm-trustlayer/
• Demo notebook: https://github.com/gridfm/gridfm-trustlayer/blob/main/examples/demo/demo.ipynb
• Quick start: https://gridfm.github.io/gridfm-trustlayer/getting-started/quickstart/

This is a pre-1.0 release: the statistical core is tested, but the Python API, configuration keys and artifact formats may still change between minor versions. See the CHANGELOG for the full list of changes.

Citation

If you use gridfm-trustlayer in your research, please cite the paper: A. Alcántara and S. Chatzivasileiadis, Trustworthiness Layer for Foundation Models in Power Systems: Application to N-k Contingency Screening, arXiv:2602.07995 (2026). GitHub's "Cite this repository" button gives the BibTeX.