{"id":13471894,"url":"https://github.com/NVIDIA/physicsnemo","last_synced_at":"2025-03-26T15:30:53.546Z","repository":{"id":152283418,"uuid":"593782352","full_name":"NVIDIA/modulus","owner":"NVIDIA","description":"Open-source deep-learning framework for building, training, and fine-tuning deep learning models using state-of-the-art Physics-ML methods","archived":false,"fork":false,"pushed_at":"2024-10-23T17:39:50.000Z","size":92079,"stargazers_count":984,"open_issues_count":78,"forks_count":234,"subscribers_count":37,"default_branch":"main","last_synced_at":"2024-10-24T01:41:30.246Z","etag":null,"topics":["deep-learning","machine-learning","nvidia-gpu","physics","pytorch"],"latest_commit_sha":null,"homepage":"https://developer.nvidia.com/modulus","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/NVIDIA.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-01-26T20:34:45.000Z","updated_at":"2024-10-23T17:39:55.000Z","dependencies_parsed_at":"2024-08-29T23:19:03.970Z","dependency_job_id":"60985db0-a2eb-46ca-b161-2ff8e3c554ce","html_url":"https://github.com/NVIDIA/modulus","commit_stats":null,"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NVIDIA%2Fmodulus","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NVIDIA%2Fmodulus/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NVIDIA%2Fmodulus/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NVIDIA%2Fmodulus/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/NVIDIA","download_url":"https://codeload.github.com/NVIDIA/modulus/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":222090791,"owners_count":16929471,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["deep-learning","machine-learning","nvidia-gpu","physics","pytorch"],"created_at":"2024-07-31T16:00:50.123Z","updated_at":"2025-03-26T15:30:43.531Z","avatar_url":"https://github.com/NVIDIA.png","language":"Python","funding_links":[],"categories":["Python","AI/ML for Simulation","⚗️ Scientific Machine Learning"],"sub_categories":["Verified vs declared","Physics-Informed Neural Networks"],"readme":"# NVIDIA Modulus\n\n\u003c!-- markdownlint-disable --\u003e\n[![Project Status: Active - The project has reached a stable, usable state and is being actively developed.](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/#active)\n[![GitHub](https://img.shields.io/github/license/NVIDIA/modulus)](https://github.com/NVIDIA/modulus/blob/master/LICENSE.txt)\n[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)\n\u003c!-- markdownlint-enable --\u003e\n[**Getting Started**](#getting-started)\n| [**Install guide**](#installation)\n| [**Contributing Guidelines**](#contributing-to-modulus)\n| [**Resources**](#resources)\n| [**Communication**](#communication)\n\n## What is Modulus?\n\nNVIDIA Modulus is an open-source deep-learning framework for building, training, and fine-tuning\ndeep learning models using state-of-the-art SciML methods for AI4science and engineering.\n\nModulus provides utilities and optimized pipelines to develop AI models that combine\nphysics knowledge with data, enabling real-time predictions.\n\nWhether you are exploring the use of Neural operators, GNNs, or transformers or are\ninterested in Physics-informed Neural Networks or a hybrid approach in between, Modulus\nprovides you with an optimized stack that will enable you to train your models at scale.\n\n\u003c!-- markdownlint-disable --\u003e\n\u003cp align=\"center\"\u003e\n  \u003cimg src=https://raw.githubusercontent.com/NVIDIA/modulus/main/docs/img/value_prop/Knowledge_guided_models.gif alt=\"Modulus\"/\u003e\n\u003c/p\u003e\n\u003c!-- markdownlint-enable --\u003e\n\n\u003c!-- toc --\u003e\n\n- [More About Modulus](#more-about-modulus)\n  - [Scalable GPU-optimized training Library](#scalable-gpu-optimized-training-library)\n  - [A suite of Physics-Informed ML Models](#a-suite-of-physics-informed-ml-models)\n  - [Seamless PyTorch Integration](#seamless-pytorch-integration)\n  - [Easy Customization and Extension](#easy-customization-and-extension)\n  - [AI4Science Library](#ai4science-library)\n    - [Domain Specific Packages](#domain-specific-packages)\n- [Who is contributing to Modulus](#who-is-using-and-contributing-to-modulus)\n- [Why use Modulus](#why-are-they-using-modulus)\n- [Getting Started](#getting-started)\n- [Resources](#resources)\n- [Installation](#installation)\n- [Contributing](#contributing-to-modulus)\n- [Communication](#communication)\n- [License](#license)\n  \n\u003c!-- tocstop --\u003e\n\n## More About Modulus\n\nAt a granular level, Modulus provides a library of a few key components:\n\n\u003c!-- markdownlint-disable --\u003e\nComponent | Description |\n---- | --- |\n[**modules.models**](https://docs.nvidia.com/deeplearning/modulus/modulus-core/api/modulus.models.html) | A collection of optimized, customizable, and easy-to-use models such as Fourier Neural Operators, Graph Neural Networks, and many more|\n[**modulus.datapipes**](https://docs.nvidia.com/deeplearning/modulus/modulus-core/api/modulus.datapipes.html) | A data pipeline and data loader library, including benchmark datapipes, weather daptapipes, and graph datapipes|\n[**modulus.distributed**](https://docs.nvidia.com/deeplearning/modulus/modulus-core/api/modulus.distributed.html) | A distributed computing library build on top of `torch.distributed` to enable parallel training with just a few steps|\n[**modulus.sym.geometry**](https://docs.nvidia.com/deeplearning/modulus/modulus-sym/user_guide/features/csg_and_tessellated_module.html) | A library to handle geometry for DL training using the Constructive Solid Geometry modeling and CAD files in STL format.|\n[**modulus.sym.eq**](https://docs.nvidia.com/deeplearning/modulus/modulus-sym/user_guide/features/nodes.html) | A library to use PDEs in your DL training with several implementations of commonly observed equations and easy ways for customization.|\n\u003c!-- markdownlint-enable --\u003e\n\nFor a complete list, refer to the Modulus API documentation for\n[Modulus Core](https://docs.nvidia.com/deeplearning/modulus/modulus-core/index.html) and\n[Modulus Sym](https://docs.nvidia.com/deeplearning/modulus/modulus-sym/api/api_index.html).\n\nUsually, Modulus is used either as:\n\n- A complementary tool to Pytorch when exploring AI for SciML and AI4Science applications.\n- A deep learning research platform that provides scale and optimal performance on\nNVIDIA GPUs.\n\nElaborating Further:\n\n### Scalable GPU-optimized training Library\n\nModulus provides a highly optimized and scalable training library for maximizing the\npower of NVIDIA GPUs.\n[Distributed computing](https://docs.nvidia.com/deeplearning/modulus/modulus-core/api/modulus.distributed.html)\nutilities allow for efficient scaling from a single GPU to multi-node GPU clusters with\na few lines of code, ensuring that large-scale.\nphysics-informed machine learning (ML) models can be trained quickly and effectively.\nThe framework includes support for advanced.\n[optimization utilities](https://docs.nvidia.com/deeplearning/modulus/modulus-core/api/modulus.utils.html#module-modulus.utils.capture),\n[tailor made datapipes](https://docs.nvidia.com/deeplearning/modulus/modulus-core/api/modulus.datapipes.html),\n[validation utilities](https://github.com/NVIDIA/modulus-sym/tree/main/modulus/sym/eq)\nto enhance the end to end training speed.\n\n### A suite of Physics Informed ML Models\n\nModulus offers a comprehensive library of state-of-the-art models specifically designed\nfor physics-ML applications.\nThe [Model Zoo](https://docs.nvidia.com/deeplearning/modulus/modulus-core/api/modulus.models.html#model-zoo)\nincludes generalizable model architectures such as\n[Fourier Neural Operators (FNOs)](modulus/models/fno),\n[DeepONet](https://docs.nvidia.com/deeplearning/modulus/modulus-sym/user_guide/neural_operators/deeponet.html),\n[Physics-Informed Neural Networks (PINNs)](https://docs.nvidia.com/deeplearning/modulus/modulus-sym/user_guide/foundational/1d_wave_equation.html),\n[Graph Neural Networks (GNNs)](modulus/models/gnn_layers),\nand generative AI models like [Diffusion Models](modulus/models/diffusion)\nas well as domain-specific models such as [Deep Learning Weather Prediction (DLWP)](modulus/models/dlwp)\nand [Super Resolution Network (SrNN)](modulus/models/srrn) among others.\nThese models are optimized for various physics domains, such as computational fluid\ndynamics, structural mechanics, and electromagnetics. Users can download, customize, and\nbuild upon these models to suit their specific needs, significantly reducing the time\nrequired to develop high-fidelity simulations.\n\n### Seamless PyTorch Integration\n\nModulus is built on top of PyTorch, providing a familiar and user-friendly experience\nfor those already proficient with PyTorch.\nThis includes a simple Python interface and modular design, making it easy to use\nModulus with existing PyTorch workflows.\nUsers can leverage the extensive PyTorch ecosystem, including its libraries and tools\nwhile benefiting from Modulus's specialized capabilities for physics-ML. This seamless\nintegration ensures users can quickly adopt Modulus without a steep learning curve.\n\nFor more information, refer [Converting PyTorch Models to Modulus Models](https://docs.nvidia.com/deeplearning/modulus/modulus-core/api/modulus.models.html#converting-pytorch-models-to-modulus-models)\n\n### Easy Customization and Extension\n\nModulus is designed to be highly extensible, allowing users to add new functionality\nwith minimal effort. The framework provides Pythonic APIs for\ndefining new physics models, geometries, and constraints, making it easy to extend its\ncapabilities to new use cases.\nThe adaptability of Modulus is further enhanced by key features such as\n[ONNX support](https://docs.nvidia.com/deeplearning/modulus/modulus-core/api/modulus.deploy.html)\nfor flexible model deployment,\nrobust [logging utilities](https://docs.nvidia.com/deeplearning/modulus/modulus-core/api/modulus.launch.logging.html)\nfor streamlined error handling,\nand efficient\n[checkpointing](https://docs.nvidia.com/deeplearning/modulus/modulus-core/api/modulus.launch.utils.html#module-modulus.launch.utils.checkpoint)\nto simplify model loading and saving.\n\nThis extensibility ensures that Modulus can adapt to the evolving needs of researchers\nand engineers, facilitating the development of innovative solutions in the field of physics-ML.\n\nDetailed information on features and capabilities can be found in the [Modulus documentation](https://docs.nvidia.com/modulus/index.html#core).\n\n[Reference samples](examples/README.md) cover a broad spectrum of physics-constrained\nand data-driven\nworkflows to suit the diversity of use cases in the science and engineering disciplines.\n\n\u003e [!TIP]\n\u003e Have questions about how Modulus can assist you? Try our [Experimental] chatbot,\n\u003e [Modulus Guide](https://chatgpt.com/g/g-PXrBv20SC-modulus-guide), for answers.\n\n### Hello world\n\nYou can start using Modulus in your PyTorch code as simple as shown here:\n\n```python\npython\n\u003e\u003e\u003e import torch\n\u003e\u003e\u003e from modulus.models.mlp.fully_connected import FullyConnected\n\u003e\u003e\u003e model = FullyConnected(in_features=32, out_features=64)\n\u003e\u003e\u003e input = torch.randn(128, 32)\n\u003e\u003e\u003e output = model(input)\n\u003e\u003e\u003e output.shape\ntorch.Size([128, 64])\n```\n\n### AI4Science Library\n\n- [Modulus Symbolic](https://github.com/NVIDIA/modulus-sym): This repository of\n  algorithms and utilities allows SciML researchers and developers to physics inform model\n  training and model validation. It also provides a higher level abstraction\n  for domain experts that is native to science and engineering.\n\n#### Domain Specific Packages\n\nThe following are packages dedicated for domain experts of specific communities catering\nto their unique exploration needs.\n\n- [Earth-2 Studio](https://github.com/NVIDIA/earth2studio): Open source project\n  to enable climate researchers and scientists to explore and experiment with\n  AI models for weather and climate.\n\n#### Research packages\n\nThe following are research packages that get packaged into Modulus once they are stable.\n\n- [Modulus Makani](https://github.com/NVIDIA/modulus-makani): Experimental library\n  designed to enable the research and development of machine-learning based weather and\n  climate models.\n- [Earth2 Grid](https://github.com/NVlabs/earth2grid): Experimental library with\n  utilities for working geographic data defined on various grids.\n- [Earth-2 MIP](https://github.com/NVIDIA/earth2mip): Experimental library with\n  utilities for model intercomparison for weather and climate models.\n\n## Who is using and contributing to Modulus\n\nModulus is an open source project and gets contributions from researchers in the SciML and\nAI4science fields. While Modulus team works on optimizing the underlying SW stack, the\ncommunity collaborates and contributes model architectures, datasets, and reference\napplications so we can innovate in the pursuit of developing generalizable model\narchitectures and algorithms.\n\nSome latest examples of community contributors are [HP Labs 3D Printing team](https://developer.nvidia.com/blog/spotlight-hp-3d-printing-and-nvidia-modulus-collaborate-on-open-source-manufacturing-digital-twin/),\n[Stanford Cardiovascular research team](https://developer.nvidia.com/blog/enabling-greater-patient-specific-cardiovascular-care-with-ai-surrogates/),\n[UIUC team](https://github.com/NVIDIA/modulus/tree/main/examples/cfd/mhd_pino),\n[CMU team](https://github.com/NVIDIA/modulus/tree/main/examples/generative/diffusion) etc.\n\nLatest examples of research teams using Modulus are\n[ORNL team](https://arxiv.org/abs/2404.05768),\n[TU Munich CFD team](https://www.nvidia.com/en-us/on-demand/session/gtc24-s62237/) etc.\n\nPlease navigate to this page for a complete list of research work leveraging Modulus.\nFor a list of enterprises using Modulus refer [here](https://developer.nvidia.com/modulus).\n\nUsing Modulus and interested in showcasing your work on\n[NVIDIA Blogs](https://developer.nvidia.com/blog/category/simulation-modeling-design/)?\nFill out this [proposal form](https://forms.gle/XsBdWp3ji67yZAUF7) and we will get back\nto you!\n\n## Why are they using Modulus\n\nHere are some of the key benefits of Modulus for SciML model development:\n\n\u003c!-- markdownlint-disable --\u003e\n\u003cimg src=\"docs/img/value_prop/benchmarking.svg\" width=\"100\"\u003e | \u003cimg src=\"docs/img/value_prop/recipe.svg\" width=\"100\"\u003e | \u003cimg src=\"docs/img/value_prop/performance.svg\" width=\"100\"\u003e\n---|---|---|\n|SciML Benchmarking and validation|Ease of using generalized SciML recipes with heterogenous datasets |Out of the box performance and scalability\n|Modulus enables researchers to benchmark their AI model against proven architectures for standard benchmark problems with detailed domain-specific validation criteria.|Modulus enables researchers to pick from SOTA SciML architectures and use built-in data pipelines for their use case.| Modulus provides out-of-the-box performant training pipelines including optimized ETL pipelines for heterogrneous engineering and scientific datasets and out of the box scaling across multi-GPU and multi-node GPUs.\n\u003c!-- markdownlint-enable --\u003e\n\nSee what your peer SciML researchers are saying about Modulus (Coming soon).\n\n## Getting started\n\nThe following resources will help you in learning how to use Modulus. The best way is to\nstart with a reference sample and then update it for your own use case.\n\n- [Using Modulus with your PyTorch model](https://docs.nvidia.com/deeplearning/modulus/modulus-core/tutorials/simple_training_example.html#using-custom-models-in-modulus)\n- [Using Modulus built-in models](https://docs.nvidia.com/deeplearning/modulus/modulus-core/tutorials/simple_training_example.html#using-built-in-models)\n- [Getting started Guide](https://docs.nvidia.com/deeplearning/modulus/getting-started/index.html)\n- [Reference Samples](https://github.com/NVIDIA/modulus/blob/main/examples/README.md)\n- [User guide Documentation](https://docs.nvidia.com/deeplearning/modulus/modulus-core/index.html)\n\n## Resources\n\n- [Getting started Webinar](https://www.nvidia.com/en-us/on-demand/session/gtc24-dlit61460/?playlistId=playList-bd07f4dc-1397-4783-a959-65cec79aa985)\n- [AI4Science Modulus Bootcamp](https://github.com/openhackathons-org/End-to-End-AI-for-Science)\n- [Modulus Pretrained models](https://catalog.ngc.nvidia.com/models?filters=\u0026orderBy=scoreDESC\u0026query=Modulus\u0026page=\u0026pageSize=)\n- [Modulus Datasets and Supplementary materials](https://catalog.ngc.nvidia.com/resources?filters=\u0026orderBy=scoreDESC\u0026query=Modulus\u0026page=\u0026pageSize=)\n- [Self-paced Modulus DLI training](https://learn.nvidia.com/courses/course-detail?course_id=course-v1:DLI+S-OV-04+V1)\n- [Deep Learnning for Science and Engineering Lecture Series with Modulus](https://www.nvidia.com/en-us/on-demand/deep-learning-for-science-and-engineering/)\n  - [Modulus: purpose and usage](https://www.nvidia.com/en-us/on-demand/session/dliteachingkit-setk5002/)\n- [Video Tutorials](https://www.nvidia.com/en-us/on-demand/search/?facet.mimetype[]=event%20session\u0026layout=list\u0026page=1\u0026q=modulus\u0026sort=relevance\u0026sortDir=desc)\n  \n## Installation\n\n### PyPi\n\nThe recommended method for installing the latest version of Modulus is using PyPi:\n\n```Bash\npip install nvidia-modulus\n```\n\nThe installation can be verified by running the hello world example as demonstrated [here](#hello-world).\n\n#### Optional dependencies\n\nModulus has many optional dependencies that are used in specific components.\nWhen using pip, all dependencies used in Modulus can be installed with\n`pip install nvidia-modulus[all]`. If you are developing Modulus, developer dependencies\ncan be installed using `pip install nvidia-modulus[dev]`. Otherwise, additional dependencies\ncan be installed on a case by case basis. Detailed information on installing the\noptional dependencies can be found in the\n[Getting Started Guide](https://docs.nvidia.com/deeplearning/modulus/getting-started/index.html).\n\n### NVCR Container\n\nThe recommended Modulus docker image can be pulled from the\n[NVIDIA Container Registry](https://catalog.ngc.nvidia.com/orgs/nvidia/teams/modulus/containers/modulus)\n(refer to the NGC registry for the latest tag):\n\n```Bash\ndocker pull nvcr.io/nvidia/modulus/modulus:24.09\n```\n\nInside the container, you can clone the Modulus git repositories and get started with the\nexamples. The below command shows the instructions to launch the modulus container and run\nexamples from this repo.\n\n```bash\ndocker run --shm-size=1g --ulimit memlock=-1 --ulimit stack=67108864 --runtime nvidia \\\n--rm -it nvcr.io/nvidia/modulus/modulus:24.09 bash\ngit clone https://github.com/NVIDIA/modulus.git\ncd modulus/examples/cfd/darcy_fno/\npip install warp-lang # install NVIDIA Warp to run the darcy example\npython train_fno_darcy.py\n```\n\nFor enterprise supported NVAIE container, refer [Modulus Secured Feature Branch](https://catalog.ngc.nvidia.com/orgs/nvidia/teams/modulus/containers/modulus-sfb)\n\n## From Source\n\n### Package\n\nFor a local build of the Modulus Python package from source use:\n\n```Bash\ngit clone git@github.com:NVIDIA/modulus.git \u0026\u0026 cd modulus\n\npip install --upgrade pip\npip install .\n```\n\n### Source Container\n\nTo build Modulus docker image:\n\n```bash\ndocker build -t modulus:deploy \\\n    --build-arg TARGETPLATFORM=linux/amd64 --target deploy -f Dockerfile .\n```\n\nAlternatively, you can run `make container-deploy`\n\nTo build CI image:\n\n```bash\ndocker build -t modulus:ci \\\n    --build-arg TARGETPLATFORM=linux/amd64 --target ci -f Dockerfile .\n```\n\nAlternatively, you can run `make container-ci`.\n\nCurrently, only `linux/amd64` and `linux/arm64` platforms are supported. If using\n`linux/arm64`, some dependencies like `warp-lang` might not install correctly.\n\n## Contributing to Modulus\n\nModulus is an open source collaboration and its success is rooted in community\ncontribution to further the field of Physics-ML. Thank you for contributing to the\nproject so others can build on top of your contribution.\n\nFor guidance on contributing to Modulus, please refer to the\n[contributing guidelines](CONTRIBUTING.md).\n\n## Cite Modulus\n\nIf Modulus helped your research and you would like to cite it, please refer to the [guidelines](https://github.com/NVIDIA/modulus/blob/main/CITATION.cff)\n\n## Communication\n\n- Github Discussions: Discuss new architectures, implementations, Physics-ML research, etc.\n- GitHub Issues: Bug reports, feature requests, install issues, etc.\n- Modulus Forum: The [Modulus Forum](https://forums.developer.nvidia.com/c/physics-simulation/modulus-physics-ml-model-framework)\nhosts an audience of new to moderate-level users and developers for general chat, online\ndiscussions, collaboration, etc.\n\n## Feedback\n\nWant to suggest some improvements to Modulus? Use our feedback form\n[here](https://docs.google.com/forms/d/e/1FAIpQLSfX4zZ0Lp7MMxzi3xqvzX4IQDdWbkNh5H_a_clzIhclE2oSBQ/viewform?usp=sf_link).\n\n## License\n\nModulus is provided under the Apache License 2.0, please see [LICENSE.txt](./LICENSE.txt)\nfor full license text.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FNVIDIA%2Fphysicsnemo","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FNVIDIA%2Fphysicsnemo","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FNVIDIA%2Fphysicsnemo/lists"}