GridFM

Train, finetune and interact with a foundation model for the electric power grid.
https://github.com/gridfm/gridfm-graphkit

Category: Energy Systems
Sub Category: Grid Analysis and Planning

Last synced: about 5 hours ago
JSON representation

Repository metadata

Train, finetune and interact with a foundation model for the electric power grid.

Host: GitHub
URL: https://github.com/gridfm/gridfm-graphkit
Owner: gridfm
License: apache-2.0
Created: 2025-06-23T14:51:29.000Z (9 months ago)
Default Branch: main
Last Pushed: 2026-03-21T15:38:07.000Z (10 days ago)
Last Synced: 2026-03-23T13:09:52.071Z (8 days ago)
Language: Python
Homepage: https://gridfm.github.io/gridfm-graphkit/
Size: 144 MB
Stars: 71
Watchers: 0
Forks: 17
Open Issues: 13
Releases: 7
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Support: SUPPORT.md
- Governance: GOVERNANCE.md

README.md

This library is brought to you by the GridFM team to train, finetune and interact with a foundation model for the electric power grid.

Installation

Create and activate a virtual environment (make sure you use the right python version = 3.10, 3.11 or 3.12. I highly recommend 3.12)

python -m venv venv
source venv/bin/activate

Install gridfm-graphkit in editable mode

pip install -e .

Get PyTorch + CUDA version for torch-scatter

TORCH_CUDA_VERSION=$(python -c "import torch; print(torch.__version__ + ('+cpu' if torch.version.cuda is None else ''))")

Install the correct torch-scatter wheel

pip install torch-scatter -f https://data.pyg.org/whl/torch-${TORCH_CUDA_VERSION}.html

For documentation generation and unit testing, install with the optional dev and test extras:

pip install -e .[dev,test]

CLI commands

Interface to train, fine-tune, evaluate, and run inference on GridFM models using YAML configs and MLflow tracking.

gridfm_graphkit <command> [OPTIONS]

Available commands:

train - Train a new model from scratch
finetune – Fine-tune an existing pre-trained model
evaluate – Evaluate model performance on a dataset
predict – Run inference and save predictions

Training Models

gridfm_graphkit train --config path/to/config.yaml

Arguments

Argument	Type	Description	Default
`--config`	`str`	Required. Path to the training configuration YAML file.	`None`
`--exp_name`	`str`	MLflow experiment name.	`timestamp`
`--run_name`	`str`	MLflow run name.	`run`
`--log_dir`	`str`	MLflow tracking/logging directory.	`mlruns`
`--data_path`	`str`	Root dataset directory.	`data`

Examples

Standard Training:

gridfm_graphkit train --config examples/config/case30_ieee_base.yaml --data_path examples/data

Fine-Tuning Models

gridfm_graphkit finetune --config path/to/config.yaml --model_path path/to/model.pt

Arguments

Argument	Type	Description	Default
`--config`	`str`	Required. Fine-tuning configuration file.	`None`
`--model_path`	`str`	Required. Path to a pre-trained model state dict.	`None`
`--exp_name`	`str`	MLflow experiment name.	timestamp
`--run_name`	`str`	MLflow run name.	`run`
`--log_dir`	`str`	MLflow logging directory.	`mlruns`
`--data_path`	`str`	Root dataset directory.	`data`

Evaluating Models

gridfm_graphkit evaluate --config path/to/eval.yaml --model_path path/to/model.pt

Arguments

Argument	Type	Description	Default
`--config`	`str`	Required. Path to evaluation config.	`None`
`--model_path`	`str`	Path to the trained model state dict.	`None`
`--normalizer_stats`	`str`	Path to `normalizer_stats.pt` from a training run. Restores `fit_on_train` normalizers from saved statistics instead of re-fitting on the current data split.	`None`
`--exp_name`	`str`	MLflow experiment name.	timestamp
`--run_name`	`str`	MLflow run name.	`run`
`--log_dir`	`str`	MLflow logging directory.	`mlruns`
`--data_path`	`str`	Dataset directory.	`data`
`--compute_dc_ac_metrics`	`flag`	Compute ground-truth AC/DC power balance metrics on the test split.	`False`
`--save_output`	`flag`	Save predictions as `<grid_name>_predictions.parquet` under MLflow artifacts (`.../artifacts/test`).	`False`

Example with saved normalizer stats

When evaluating a model on a dataset, you can pass the normalizer statistics from the original training run to ensure the same normalization parameters are used:

gridfm_graphkit evaluate \
  --config examples/config/HGNS_PF_datakit_case118.yaml \
  --model_path mlruns/<experiment_id>/<run_id>/artifacts/model/best_model_state_dict.pt \
  --normalizer_stats mlruns/<experiment_id>/<run_id>/artifacts/stats/normalizer_stats.pt \
  --data_path data

Note: The --normalizer_stats flag only affects normalizers with fit_strategy = "fit_on_train" (e.g. HeteroDataMVANormalizer). Per-sample normalizers (HeteroDataPerSampleMVANormalizer) always recompute their statistics from the current dataset regardless of this flag.

Running Predictions

gridfm_graphkit predict --config path/to/config.yaml --model_path path/to/model.pt

Arguments

Argument	Type	Description	Default
`--config`	`str`	Required. Path to prediction config file.	`None`
`--model_path`	`str`	Path to the trained model state dict.	`None`
`--normalizer_stats`	`str`	Path to `normalizer_stats.pt` from a training run. Restores `fit_on_train` normalizers from saved statistics.	`None`
`--exp_name`	`str`	MLflow experiment name.	timestamp
`--run_name`	`str`	MLflow run name.	`run`
`--log_dir`	`str`	MLflow logging directory.	`mlruns`
`--data_path`	`str`	Dataset directory.	`data`
`--output_path`	`str`	Directory where predictions are saved as `<grid_name>_predictions.parquet`.	`data`

Use built-in help for full command details:

gridfm_graphkit --help
gridfm_graphkit <command> --help

Owner metadata

Name: gridfm
Login: gridfm
Email:
Kind: organization
Description:
Website:
Location:
Twitter:
Company:
Icon url: https://avatars.githubusercontent.com/u/12138362?v=4
Repositories: 1
Last ynced at: 2023-03-01T14:30:36.533Z
Profile URL: https://github.com/gridfm

GitHub Events

Total

Release event: 4
Delete event: 11
Member event: 3
Pull request event: 21
Fork event: 4
Issues event: 5
Watch event: 25
Issue comment event: 1
Push event: 83
Pull request review comment event: 4
Pull request review event: 7
Create event: 27

Last Year

Release event: 4
Delete event: 11
Member event: 3
Pull request event: 21
Fork event: 4
Issues event: 5
Watch event: 25
Issue comment event: 1
Push event: 83
Pull request review comment event: 4
Pull request review event: 7
Create event: 27

Committers metadata

Last synced: 3 days ago

Total Commits: 194
Total Committers: 15
Avg Commits per committer: 12.933
Development Distribution Score (DDS): 0.727

Commits in past year: 175
Committers in past year: 12
Avg Commits per committer in past year: 14.583
Development Distribution Score (DDS) in past year: 0.697

Name	Email	Commits
MatteoMazzonelli	m**1@i**m	53
Romeo Kienzler	r**1@i**m	42
Alban Puech	n**p@g**m	21
Mangaliso Mngomomezulu	6****M	20
Matteo Mazzonelli	M**i@i**m	12
Mangaliso Mngomezulu	m**u@M**l	10
Celia Cintas	c**s@i**m	9
Mangaliso Mngomezulu	m**u@m**m	6
Hector Maeso Garcia	h**a@i**m	6
Alban Puech	A**1@i**m	6
“Mangaliso-M”	“**u@g**”	4
Francois Miralles	4****r	2
Jonas Weiss	J**E@z**m	1
Etienne Eben Vos	E**s@i**m	1
Hector Maeso Garcia	H**a@i**m	1

Committer domains:

Issue and Pull Request metadata

Last synced: 3 days ago

Total issues: 3
Total pull requests: 26
Average time to close issues: about 2 months
Average time to close pull requests: 1 day
Total issue authors: 3
Total pull request authors: 9
Average comments per issue: 0.33
Average comments per pull request: 0.12
Merged pull request: 13
Bot issues: 0
Bot pull requests: 0

Past year issues: 3
Past year pull requests: 26
Past year average time to close issues: about 2 months
Past year average time to close pull requests: 1 day
Past year issue authors: 3
Past year pull request authors: 9
Past year average comments per issue: 0.33
Past year average comments per pull request: 0.12
Past year merged pull request: 13
Past year bot issues: 0
Past year bot pull requests: 0

More stats: https://issues.ecosyste.ms/repositories/lookup?url=https://github.com/gridfm/gridfm-graphkit

Top Issue Authors

TavoIREQ (1)
janu000 (1)
mellson (1)

Top Pull Request Authors

MatteoMazzonelli (9)
albanpuech (4)
Mangaliso-M (3)
ttolhurst (3)
naomi-simumba (2)
romeokienzler (2)
mkisuule (1)
celiacintas (1)
Tamaragov (1)

Top Issue Labels

bug (1)

Top Pull Request Labels

enhancement (4)
documentation (2)

Package metadata

Total packages: 1
Total downloads:
- pypi: 89 last-month
Total dependent packages: 0
Total dependent repositories: 0
Total versions: 7
Total maintainers: 1

pypi.org: gridfm-graphkit

Grid Foundation Model

Homepage:
Documentation: https://gridfm-graphkit.readthedocs.io/
Licenses: Apache-2.0
Latest release: 0.0.6 (published 7 months ago)
Last Synced: 2026-03-27T22:00:52.024Z (3 days ago)
Versions: 7
Dependent Packages: 0
Dependent Repositories: 0
Downloads: 89 Last month
Rankings:
- Dependent packages count: 8.944%
- Average: 29.672%
- Dependent repos count: 50.399%
Maintainers (1)
- ccintas

Dependencies

.github/workflows/ci-build.yaml actions

actions/checkout v4 composite
actions/setup-python v4 composite

.github/workflows/deploy_docs.yaml actions

actions/cache v4 composite
actions/checkout v4 composite
actions/setup-python v4 composite

pyproject.toml pypi

mlflow >=3.1.0
nbformat >=5.10.4
networkx >=3.4.2
numpy >=2.2.6
pandas >=2.3.0
plotly >=6.1.2
pyyaml >=6.0.2
torch >=2.7.1
torch-geometric >=2.6.1
torchaudio >=2.7.1
torchvision >=0.22.1

.github/workflows/release.yaml actions

actions/checkout v4 composite
actions/setup-python v4 composite
pypa/gh-action-pypi-publish release/v1 composite

Score: 11.638676670275789

ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Open Sustainable Technology

GridFM

Repository metadata

README.md

Installation

CLI commands

Training Models

Arguments

Examples

Fine-Tuning Models

Arguments

Evaluating Models

Arguments

Example with saved normalizer stats

Running Predictions

Arguments

Owner metadata

GitHub Events

Total

Last Year

Committers metadata

Committer domains:

Issue and Pull Request metadata

Top Issue Authors

Top Pull Request Authors

Top Issue Labels

Top Pull Request Labels

Package metadata

pypi.org: gridfm-graphkit

Dependencies