######
phygnn
######
.. image:: https://github.com/NREL/phygnn/workflows/Documentation/badge.svg
:target: https://nrel.github.io/phygnn/
.. image:: https://github.com/NREL/phygnn/workflows/pytests_tf_latest/badge.svg
:target: https://github.com/NREL/phygnn/actions?query=workflow%3A%22pytests_tf_latest%22
.. image:: https://github.com/NREL/phygnn/workflows/Lint%20Code%20Base/badge.svg
:target: https://github.com/NREL/phygnn/actions?query=workflow%3A%22Lint+Code+Base%22
.. image:: https://img.shields.io/pypi/pyversions/nrel-phygnn.svg
:target: https://pypi.org/project/nrel-phygnn/
.. image:: https://badge.fury.io/py/NREL-phygnn.svg
:target: https://badge.fury.io/py/NREL-phygnn
.. image:: https://anaconda.org/nrel/nrel-phygnn/badges/version.svg
:target: https://anaconda.org/nrel/nrel-phygnn
.. image:: https://anaconda.org/nrel/nrel-phygnn/badges/license.svg
:target: https://anaconda.org/nrel/nrel-phygnn
.. image:: https://codecov.io/gh/nrel/phygnn/branch/master/graph/badge.svg?token=ZJFQWAAM1N
:target: https://codecov.io/gh/nrel/phygnn
.. image:: https://zenodo.org/badge/276492167.svg
:target: https://zenodo.org/badge/latestdoi/276492167
.. image:: https://mybinder.org/badge_logo.svg
:target: https://mybinder.org/v2/gh/NREL/PHYGNN/HEAD
**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. <https://nrel.github.io/phygnn/_autosummary/phygnn.phygnn.PhysicsGuidedNeuralNetwork.html>`_
For example notebooks using the phygnn architecture for regression,
classification, and even GAN applications, see `the example notebooks here
<https://github.com/NREL/phygnn/tree/master/examples>`_.
You can also run the examples using a free cloud-hosted jupyter instance via
`Binder <https://mybinder.org/v2/gh/NREL/PHYGNN/HEAD>`_.
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``
i. 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:
i. ``pip install NREL-phygnn``
ii. ``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:
i. Start ipython and test the following import: ``from phygnn import PhysicsGuidedNeuralNetwork``
ii. 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.
Raw data
{
"_id": null,
"home_page": "https://github.com/NREL/phygnn",
"name": "NREL-phygnn",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "phygnn",
"author": "Grant Buster",
"author_email": "grant.buster@nrel.gov",
"download_url": "https://files.pythonhosted.org/packages/e0/e1/210cc47c19ec8926ef8e2a887e8d01e101dffc2dceb59d2a3bc037019198/NREL-phygnn-0.0.30.tar.gz",
"platform": null,
"description": "######\nphygnn\n######\n\n.. image:: https://github.com/NREL/phygnn/workflows/Documentation/badge.svg\n :target: https://nrel.github.io/phygnn/\n\n.. image:: https://github.com/NREL/phygnn/workflows/pytests_tf_latest/badge.svg\n :target: https://github.com/NREL/phygnn/actions?query=workflow%3A%22pytests_tf_latest%22\n\n.. image:: https://github.com/NREL/phygnn/workflows/Lint%20Code%20Base/badge.svg\n :target: https://github.com/NREL/phygnn/actions?query=workflow%3A%22Lint+Code+Base%22\n\n.. image:: https://img.shields.io/pypi/pyversions/nrel-phygnn.svg\n :target: https://pypi.org/project/nrel-phygnn/\n\n.. image:: https://badge.fury.io/py/NREL-phygnn.svg\n :target: https://badge.fury.io/py/NREL-phygnn\n\n.. image:: https://anaconda.org/nrel/nrel-phygnn/badges/version.svg\n :target: https://anaconda.org/nrel/nrel-phygnn\n\n.. image:: https://anaconda.org/nrel/nrel-phygnn/badges/license.svg\n :target: https://anaconda.org/nrel/nrel-phygnn\n\n.. image:: https://codecov.io/gh/nrel/phygnn/branch/master/graph/badge.svg?token=ZJFQWAAM1N\n :target: https://codecov.io/gh/nrel/phygnn\n\n.. image:: https://zenodo.org/badge/276492167.svg\n :target: https://zenodo.org/badge/latestdoi/276492167\n\n.. image:: https://mybinder.org/badge_logo.svg\n :target: https://mybinder.org/v2/gh/NREL/PHYGNN/HEAD\n\n\n**phygnn** (fi-geon\u00a0| \\\u00a0\u02c8fi-j\u0259n) noun.\n\n 1. a physics-guided neural network\n 2. a rare and mythical bird\n\nThis implementation of physics-guided neural networks augments a traditional\nneural network loss function with a generic loss term that can be used to\nguide the neural network to learn physical or theoretical constraints.\nphygnn enables scientific software developers and data scientists to easily\nintegrate machine learning models into physics and engineering applications.\nThis framework should help alleviate some challenges that are often encountered\nwhen applying purely data-driven machine learning models to scientific\napplications, such as when machine learning models produce physically\ninconsistent results or have trouble generalizing to out-of-sample scenarios.\n\nFor details on the phygnn class framework see `the phygnn class documentation\nhere. <https://nrel.github.io/phygnn/_autosummary/phygnn.phygnn.PhysicsGuidedNeuralNetwork.html>`_\n\nFor example notebooks using the phygnn architecture for regression,\nclassification, and even GAN applications, see `the example notebooks here\n<https://github.com/NREL/phygnn/tree/master/examples>`_.\nYou can also run the examples using a free cloud-hosted jupyter instance via\n`Binder <https://mybinder.org/v2/gh/NREL/PHYGNN/HEAD>`_.\n\nAt the National Renewable Energy Lab (NREL), we are using the phygnn framework\nto supplement traditional satellite-based cloud property prediction models. We\nuse phygnn to predict cloud optical properties when the traditional mechanistic\nmodels fail and use a full tensor-based radiative transfer model as the\nphysical loss function to transform the predicted cloud properties into\nphygnn-predicted irradiance data. We then calculate a loss value comparing the\nphygnn-predicted irradiance to high quality ground measurements. We have seen\nexcellent improvements in the predicted irradiance data in rigorous\nout-of-sample-validation experiments (Buster et al. 2021).\n\nEngineers and researchers can use the phygnn framework to:\n\n * Enforce physically-consistent predictions from a deep neural network (see lake temperature reference below)\n * Implement custom regularization (e.g. topological regularization)\n * 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\n * Use the physics loss function to adjust theoretical models based on empirical observation using respective loss weights\n\nHere are additional examples of similar architectures from the literature which\nare related to or inspired this work:\n\n * Buster, Grant, Mike Bannister, Aron Habte, Dylan Hettinger, Galen Maclaurin, Michael Rossol, Manajit Sengupta, and Yu Xie. \u201cPhysics-Guided Machine Learning for Improved Accuracy of the National Solar Radiation Database.\u201d Solar Energy 232 (January 15, 2022): 483\u201392. https://doi.org/10.1016/j.solener.2022.01.004.\n * Jared Willard, Xiaowei Jia, Shaoming Xu, Michael Steinbach, and Vipin Kumar, \u201cIntegrating Physics-Based Modeling with Machine Learning: A Survey.\u201d ArXiv abs/2003.04919 (2020).\n * Forssell, U. and P. Lindskog. \u201cCombining Semi-Physical and Neural Network Modeling: An Example ofIts Usefulness.\u201d IFAC Proceedings Volumes 30 (1997): 767-770.\n * Xinyue Hu, Haoji Hu, Saurabh Verma, and Zhi-Li Zhang, \u201cPhysics-Guided Deep Neural Networks for PowerFlow Analysis\u201d, arXiv:2002.00097v1 (2020).\n * Anuj Karpatne, William Watkins, Jordan Read, and Vipin Kumar, \"Physics-guided Neural Networks (PGNN): An Application in Lake Temperature Modeling\". arXiv:1710.11431v2 (2018).\n * 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\u20132331.\n * 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.\n\nSuggested Citation\n==================\n\n\nUpdate with current version and DOI:\n\nGrant 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.\n\n\nInstallation\n============\n\n\nSimple Install\n--------------\n\n1. Use conda (anaconda or miniconda) to create a phygnn environment: ``conda create --name phygnn python=3.9``\n\n i. Note that phygnn is tested with python >= 3.8 via pip install. Users have reported issues installing phygnn using conda install.\n\n2. Activate your new conda env: ``conda activate phygnn``\n3. Install with pip or conda:\n\n i. ``pip install NREL-phygnn``\n ii. ``conda install -c nrel nrel-phygnn``\n\n\nDeveloper Install\n-----------------\n\n1. Use conda (anaconda or miniconda) to create a phygnn environment: ``conda create --name phygnn python=3.9``\n2. Activate your new conda env: ``conda activate phygnn``\n3. Clone the phygnn repository: ``git clone git@github.com:NREL/phygnn.git``\n4. Navigate to the cloned repo and checkout your desired branch: ``git checkout main`` or ``git checkout <branch>``\n5. Navigate to the phygnn directory that contains setup.py and run: ``pip install -e .`` (developer install) or ``pip install .`` (static install).\n6. Test your installation:\n\n i. Start ipython and test the following import: ``from phygnn import PhysicsGuidedNeuralNetwork``\n ii. Navigate to the ``tests/`` directory and run the command: ``pytest``\n\n\nAcknowledgements\n================\nThis work was authored by the National Renewable Energy Laboratory, operated by Alliance for Sustainable Energy,\nLLC, for the U.S. Department of Energy (DOE) under Contract No. DE-AC36-08GO28308. This material is based upon\nwork supported by the U.S. Department of Energy\u2019s Office of Energy Efficiency and Renewable Energy (EERE) under\nthe Solar Energy Technologies Office (Systems Integration Subprogram) Contract Number 36598. The views\nexpressed in the article do not necessarily represent the views of the DOE or the U.S. Government. The U.S.\nGovernment retains and the publisher, by accepting the article for publication, acknowledges that the U.S.\nGovernment retains a nonexclusive, paid-up, irrevocable, worldwide license to publish or reproduce the published\nform of this work, or allow others to do so, for U.S. Government purposes.\n\n\n",
"bugtrack_url": null,
"license": "BSD 3-Clause",
"summary": "Physics-Guided Neural Networks (phygnn)",
"version": "0.0.30",
"project_urls": {
"Homepage": "https://github.com/NREL/phygnn"
},
"split_keywords": [
"phygnn"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "2d874a526e853600c1a530664d28650b6c4d1a9dd30b7672e1d1523c47431c56",
"md5": "bb38fba8e2de30cd63207cfe1606ba85",
"sha256": "ec077bd0523b0c782086d2152cc6b0844053d40dded28efbb0f7d11cb6c4e1c0"
},
"downloads": -1,
"filename": "NREL_phygnn-0.0.30-py3-none-any.whl",
"has_sig": false,
"md5_digest": "bb38fba8e2de30cd63207cfe1606ba85",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 55317,
"upload_time": "2024-11-15T21:29:10",
"upload_time_iso_8601": "2024-11-15T21:29:10.498828Z",
"url": "https://files.pythonhosted.org/packages/2d/87/4a526e853600c1a530664d28650b6c4d1a9dd30b7672e1d1523c47431c56/NREL_phygnn-0.0.30-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "e0e1210cc47c19ec8926ef8e2a887e8d01e101dffc2dceb59d2a3bc037019198",
"md5": "1b950b27c8fe52fe3222fbdb3243b8c9",
"sha256": "dc2b0a719178b1958488c1b68a14317e742bba2b6ac07e9b65ff55483f203e6e"
},
"downloads": -1,
"filename": "NREL-phygnn-0.0.30.tar.gz",
"has_sig": false,
"md5_digest": "1b950b27c8fe52fe3222fbdb3243b8c9",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 46484,
"upload_time": "2024-11-15T21:29:13",
"upload_time_iso_8601": "2024-11-15T21:29:13.001754Z",
"url": "https://files.pythonhosted.org/packages/e0/e1/210cc47c19ec8926ef8e2a887e8d01e101dffc2dceb59d2a3bc037019198/NREL-phygnn-0.0.30.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-15 21:29:13",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "NREL",
"github_project": "phygnn",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "nrel-phygnn"
}
JSON
