Skip to main content
https://github.com/NREL/phygnn/workflows/Documentation/badge.svg https://github.com/NREL/phygnn/workflows/pytests_tf_latest/badge.svg https://github.com/NREL/phygnn/workflows/Lint%20Code%20Base/badge.svg https://img.shields.io/pypi/pyversions/nrel-phygnn.svg https://badge.fury.io/py/NREL-phygnn.svg https://anaconda.org/nrel/nrel-phygnn/badges/version.svg https://anaconda.org/nrel/nrel-phygnn/badges/license.svg https://codecov.io/gh/nrel/phygnn/branch/master/graph/badge.svg?token=ZJFQWAAM1N https://zenodo.org/badge/276492167.svg https://mybinder.org/badge_logo.svg

phygnn (fi-geon |  ˈfi-jən) noun.

  1. a physics-guided neural network

  2. a rare and mythical bird

This implementation of physics-guided neural networks augments a traditional neural network loss function with a generic loss term that can be used to guide the neural network to learn physical or theoretical constraints. phygnn enables scientific software developers and data scientists to easily integrate machine learning models into physics and engineering applications. This framework should help alleviate some challenges that are often encountered when applying purely data-driven machine learning models to scientific applications, such as when machine learning models produce physically inconsistent results or have trouble generalizing to out-of-sample scenarios.

For details on the phygnn class framework see the phygnn class documentation here.

For example notebooks using the phygnn architecture for regression, classification, and even GAN applications, see the example notebooks here. You can also run the examples using a free cloud-hosted jupyter instance via Binder.

At the National Renewable Energy Lab (NREL), we are using the phygnn framework to supplement traditional satellite-based cloud property prediction models. We use phygnn to predict cloud optical properties when the traditional mechanistic models fail and use a full tensor-based radiative transfer model as the physical loss function to transform the predicted cloud properties into phygnn-predicted irradiance data. We then calculate a loss value comparing the phygnn-predicted irradiance to high quality ground measurements. We have seen excellent improvements in the predicted irradiance data in rigorous out-of-sample-validation experiments (Buster et al. 2021).

Engineers and researchers can use the phygnn framework to:

  • Enforce physically-consistent predictions from a deep neural network (see lake temperature reference below)

  • Implement custom regularization (e.g. topological regularization)

  • Use the physics loss function to extend training data, e.g. train against “known” outputs but also train using the downstream application of the predicted variables

  • Use the physics loss function to adjust theoretical models based on empirical observation using respective loss weights

Here are additional examples of similar architectures from the literature which are related to or inspired this work:

  • Buster, Grant, Mike Bannister, Aron Habte, Dylan Hettinger, Galen Maclaurin, Michael Rossol, Manajit Sengupta, and Yu Xie. “Physics-Guided Machine Learning for Improved Accuracy of the National Solar Radiation Database.” Solar Energy 232 (January 15, 2022): 483–92. https://doi.org/10.1016/j.solener.2022.01.004.

  • Jared Willard, Xiaowei Jia, Shaoming Xu, Michael Steinbach, and Vipin Kumar, “Integrating Physics-Based Modeling with Machine Learning: A Survey.” ArXiv abs/2003.04919 (2020).

  • Forssell, U. and P. Lindskog. “Combining Semi-Physical and Neural Network Modeling: An Example ofIts Usefulness.” IFAC Proceedings Volumes 30 (1997): 767-770.

  • Xinyue Hu, Haoji Hu, Saurabh Verma, and Zhi-Li Zhang, “Physics-Guided Deep Neural Networks for PowerFlow Analysis”, arXiv:2002.00097v1 (2020).

  • Anuj Karpatne, William Watkins, Jordan Read, and Vipin Kumar, “Physics-guided Neural Networks (PGNN): An Application in Lake Temperature Modeling”. arXiv:1710.11431v2 (2018).

  • Anuj Karpatne, Gowtham Atluri, James H Faghmous, Michael Steinbach, Arindam Banerjee, Auroop Ganguly, Shashi Shekhar, Nagiza Samatova, and Vipin Kumar. 2017. Theory-guided data science: A new paradigm for scientific discovery from data. IEEE Transactions on knowledge and data engineering 29, 10 (2017), 2318–2331.

  • Justin Sirignano, Jonathan F. MacArt, Jonathan B. Freund, “DPM: A deep learning PDE augmentation method with application to large-eddy simulation”. Journal of Computational Physics, Volume 423, 2020, ISSN 0021-9991, https://doi.org/10.1016/j.jcp.2020.109811.

Suggested Citation

Update with current version and DOI:

Grant Buster, Michael Rossol, Mike Bannister, and Dylan Hettinger. Physics-Guided Neural Networks (phygnn). https://github.com/NREL/phygnn (version v0.0.9), 2021. https://doi.org/10.5281/zenodo.4498541.

Installation

Simple Install

  1. Use conda (anaconda or miniconda) to create a phygnn environment: conda create --name phygnn python=3.9

    1. Note that phygnn is tested with python >= 3.8 via pip install. Users have reported issues installing phygnn using conda install.

  2. Activate your new conda env: conda activate phygnn

  3. Install with pip or conda:

    1. pip install NREL-phygnn

    2. conda install -c nrel nrel-phygnn

Developer Install

  1. Use conda (anaconda or miniconda) to create a phygnn environment: conda create --name phygnn python=3.9

  2. Activate your new conda env: conda activate phygnn

  3. Clone the phygnn repository: git clone git@github.com:NREL/phygnn.git

  4. Navigate to the cloned repo and checkout your desired branch: git checkout main or git checkout <branch>

  5. Navigate to the phygnn directory that contains setup.py and run: pip install -e . (developer install) or pip install . (static install).

  6. Test your installation:

    1. Start ipython and test the following import: from phygnn import PhysicsGuidedNeuralNetwork

    2. Navigate to the tests/ directory and run the command: pytest

Acknowledgements

This work was authored by the National Renewable Energy Laboratory, operated by Alliance for Sustainable Energy, LLC, for the U.S. Department of Energy (DOE) under Contract No. DE-AC36-08GO28308. This material is based upon work supported by the U.S. Department of Energy’s Office of Energy Efficiency and Renewable Energy (EERE) under the Solar Energy Technologies Office (Systems Integration Subprogram) Contract Number 36598. The views expressed in the article do not necessarily represent the views of the DOE or the U.S. Government. The U.S. Government retains and the publisher, by accepting the article for publication, acknowledges that the U.S. Government retains a nonexclusive, paid-up, irrevocable, worldwide license to publish or reproduce the published form of this work, or allow others to do so, for U.S. Government purposes.

Metadata

Release files for NREL-phygnn 0.0.33

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for NREL-phygnn 0.0.33
File Size Uploaded
nrel_phygnn-0.0.33.tar.gz 8.2 MB Details

Built distribution (wheel)

Table of built distributions (wheels) for NREL-phygnn 0.0.33
File Interpreter ABI Platform
nrel_phygnn-0.0.33-py3-none-any.whl Python 3 none any Details

Total release size: 8.3 MB

Release files / nrel_phygnn-0.0.33.tar.gz

Download URL nrel_phygnn-0.0.33.tar.gz
Size 8.2 MB
Tags Source
SHA-256 checksum
How to use checksums
a85cba3ee8bf7fc6d528ea803a6847e78076d9aa09c35462bced835ce9927a88
BLAKE2b-256 checksum
How to use checksums
db1d125abcee73d43c2b74ffd62bd5ffeae0c7e583363c36f09af5565596a26c
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.12.9

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jun 3, 2025.

Transparency log

Release files / nrel_phygnn-0.0.33-py3-none-any.whl

Download URL nrel_phygnn-0.0.33-py3-none-any.whl
Size 60.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
389f42fa1d1488244e48f86285216968357ea553ca8e3f739198807dc66ddf7c
BLAKE2b-256 checksum
How to use checksums
44c34c9a17ca2b2ae1f09f91b4ee2608e185af82ddc751e9dbedaa6949bde644
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.12.9

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jun 3, 2025.

Transparency log
Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page