Metadata-Version: 2.4
Name: ddDT-GFM
Version: 0.1.4
Summary: Generalized graph foundation models as versatile data-driven digital twins for complex technological systems.
Author: Benjamin G. Pierce, Raymond J. Wieser, Weiqi Yue, Yangxin Fan, Hein Htet Aung, Thomas G. Ciardi, Yinghui Wu, Pawan K. Tripathi, Roger H. French
Maintainer-email: "Pawan K. Tripathi" <pawan.tripathi@case.edu>, "Roger H. French" <rxf131@case.edu>
License: BSD 2-Clause License
        
        Copyright (c) 2024, CWRU SDLE
        
        Redistribution and use in source and binary forms, with or without
        modification, are permitted provided that the following conditions are met:
        
        1. Redistributions of source code must retain the above copyright notice, this
           list of conditions and the following disclaimer.
        
        2. Redistributions in binary form must reproduce the above copyright notice,
           this list of conditions and the following disclaimer in the documentation
           and/or other materials provided with the distribution.
        
        THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
        AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
        IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
        DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
        FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
        DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
        SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
        CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
        OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
        OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
        
Project-URL: Homepage, https://github.com/cwru-sdle/ddDT-GFM
Project-URL: Repository, https://github.com/cwru-sdle/ddDT-GFM
Project-URL: Documentation, https://dddt-gfm.readthedocs.io
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: <3.12,>=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy<2.0,>=1.24
Requires-Dist: pandas>=2.0
Requires-Dist: scipy>=1.10
Requires-Dist: scikit-learn>=1.2
Requires-Dist: matplotlib>=3.7
Requires-Dist: seaborn>=0.11
Requires-Dist: tqdm>=4.6
Requires-Dist: requests>=2.28
Requires-Dist: setuptools<81
Requires-Dist: torch<2.3,>=2.1
Requires-Dist: torchvision<0.18,>=0.16
Requires-Dist: torch-geometric<2.8,>=2.5
Requires-Dist: torch-spatiotemporal<0.10,>=0.9
Requires-Dist: pytorch-lightning<2.3,>=2.1
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Provides-Extra: docs
Requires-Dist: sphinx>=7; extra == "docs"
Requires-Dist: furo; extra == "docs"
Requires-Dist: sphinx-autodoc-typehints; extra == "docs"
Dynamic: license-file

# ddDT-GFM
## Generalized graph foundation models as versatile data-driven digital twins for complex technological systems

[![PyPI version](https://img.shields.io/pypi/v/ddDT-GFM.svg)](https://pypi.org/project/ddDT-GFM/)
[![Python versions](https://img.shields.io/pypi/pyversions/ddDT-GFM.svg)](https://pypi.org/project/ddDT-GFM/)
[![Documentation Status](https://readthedocs.org/projects/dddt-gfm/badge/?version=latest)](https://dddt-gfm.readthedocs.io/en/latest/)
[![License: BSD-2-Clause](https://img.shields.io/badge/License-BSD--2--Clause-blue.svg)](LICENSE)

## Installation

Always install into an **isolated environment** (a fresh venv or conda env — never a shared base environment). **Linux is required** for the full pipeline; on **Python 3.10**.

`tsl` (torch-spatiotemporal) requires `torch-sparse`/`torch-scatter`, which are distributed as wheels **matched to your torch + CUDA build** from the PyG index (not PyPI). Install torch first, then the matched extensions, then this package:

```bash
python3.10 -m venv .venv && source .venv/bin/activate
# 1) torch (choose your CUDA build; cu121 shown — use .../whl/cpu for CPU-only)
pip install "setuptools<81" "numpy<2" torch==2.1.2 torchvision==0.16.2 \
    --index-url https://download.pytorch.org/whl/cu121
# 2) PyG extensions matched to torch 2.1 + cu121  (this match is what fixes the
#    "libcudart.so.11 / incompatible CUDA" errors seen on mismatched installs)
pip install torch-scatter torch-sparse -f https://data.pyg.org/whl/torch-2.1.0+cu121.html
# 3) the package
pip install ddDT-GFM
```

> **Notes.** `setuptools<81` is required (pytorch-lightning imports `pkg_resources`, removed in setuptools 81). `numpy<2` is required (torch 2.1/2.2 are not ABI-compatible with numpy 2). **macOS has no prebuilt `torch_sparse` wheel** — use Linux or the Docker image below.

### Reproducible environment (exact validated versions)

For a guaranteed-identical setup — the versions used in the paper (Python 3.10, torch 2.1.2 + CUDA 12.1) — use one of:

```bash
# pip + lockfile (GPU); use requirements-lock-cpu.txt for CPU-only
pip install -r requirements-lock-cu121.txt && pip install ddDT-GFM

# conda
conda env create -f environment.yml && conda activate dddt-gfm

# Docker (host needs only an NVIDIA driver >= 525)
docker build -t dddt-gfm:0.2.0 . && docker run --gpus all -it -p 8888:8888 dddt-gfm:0.2.0
```

The demo notebooks in [`notebooks/`](notebooks/) each begin with a pinned **Setup** cell, so they run reproducibly on Colab or a fresh machine without any prior setup.

See the [documentation](https://dddt-gfm.readthedocs.io) for details.

## Abstract
Digital twins are comprised of computational models that mimic the 'as built' characteristics of devices, systems, and networks of systems whose performance in the real world warrants quantitative and critical assessment. 
The literature on constructing digital twins is historically focused around task-specific, physics-based models that seek to understand the device from first principles, thereby constructing an idealized understanding of the system. 
However, these ``empirical digital twins" (eDT) can be quite difficult to construct, as the level of detail required to accurately model the complex physics of many devices is often missing or expensive to obtain, especially for systems with widespread deployment. 
Additionally, eDTs generally assume the device is working as intended; in practice, many systems experience some form of derating or degradation that causes them to operate off-specification. 
As it is often the goal of a digital twin model to quantify these departures from the idealized system, it is quite difficult to separate derated assumptions from the expected model output. 
In contrast, data-driven digital twins (ddDT) seek to model the system as it actually is based on real observations about the device in question. 
Additionally, ddDTs generally utilize a flexible model architecture (typically an artificial neural network) to avoid injecting implicit bias into the system. 
This flexibility also lends itself to another advantage: modularity. 
Digital twins are often utilized to answer multiple different questions about the system. 
With a ddDT, it is possible to train the model in a self-supervised manner via a reconstruction objective in order to obtain an encoder module. 
This module can then be used as a Foundation Model (FM) for different tasks without either constructing a entirely new task-specific eDT or training another ddDT from scratch. 
This work presents a unified pipeline for constructing data-driven Foundation Models for three exemplifying cases: solar photovoltaic fleets, direct ink write additive manufacturing, and laser powder bed fusion. 
Although these three systems are conceptually very different, the presented Foundation Model utilizes the flexibility of spatiotemporal graph neural networks (st-GNNs) to apply the same methodology to each case, allowing scientists to focus on their scientific objectives rather than troubleshooting a overwhelmingly detailed modeling pipeline. 

## Downloading data
You can download the data used in this work from OSF with the `util` module of this package. 
For example, to download a PV site:
```py
from dddt_gfm.util.io import OSF_download
OSF_download(0, 'downloaded_test.csv', './')
```

## Citation

If you use this software, please cite the accompanying paper:

> Pierce, B. G., Aung, H. H., Ciardi, T. G., Hernandez, K. J., Wieser, R. J., Yue, W., Fan, Y., Harding Bradley, A. C., Rajamohan, B. P., Barcelos, E. I., Jimenez, J. C., Spears, B. K., Giera, B., Gao, R. X., Li, M., Davis, K. O., Bruckman, L. S., Wu, Y., Tripathi, P. K., & French, R. H. Generalized graph foundation models as versatile data-driven digital twins for complex technological systems. *Scientific Reports* (2026). DOI: _to be added upon publication_.

```bibtex
@article{pierce2026ddltgfm,
  title   = {Generalized graph foundation models as versatile data-driven digital twins for complex technological systems},
  author  = {Pierce, Benjamin G. and Aung, Hein Htet and Ciardi, Thomas G. and Hernandez, Kristen J. and Wieser, Raymond J. and Yue, Weiqi and Fan, Yangxin and Harding Bradley, Alexander C. and Rajamohan, Balashanmuga Priyan and Barcelos, Erika I. and Jimenez, Jayvic C. and Spears, Brian K. and Giera, Brian and Gao, Robert X. and Li, Mengjie and Davis, Kristopher O. and Bruckman, Laura S. and Wu, Yinghui and Tripathi, Pawan K. and French, Roger H.},
  journal = {Scientific Reports},
  year    = {2026},
  note    = {DOI to be added upon publication}
}
```
