Merge pull request #32 from TomF98/main

Update Documentation and DeepONet

CHANGELOG.rst

@@ -1,10 +1,15 @@
 =========
 Changelog
 =========
+All notable changes to this project will be documented in this file.
 
-Version 0.1
+
+Version 1.0
 ===========
+First official release of TorchPhysics on PyPI.
 
-- Feature A added
-- FIX: nasty bug #1729 fixed
-- add your changes here!
+Version 1.0.1
+=============
+    - Updated documentation and error messages
+    - Simplyfied creation/definition of DeepONets
+    - Add more evalution types for the DeepONet

README.rst

@@ -78,20 +78,40 @@ to have a look at the following sections:
 
 Installation
 ============
-TorchPhysics can be installed by using:
+TorchPhysics reqiueres the follwing dependencies to be installed: 
+
+- PyTorch_ >= 1.7.1, < 2.0.0
+- `PyTorch Lightning`_ >= 1.3.4, < 2.0.0
+- Numpy_ >= 1.20.2
+- Matplotlib_ >= 3.0.0
+- Scipy_ >= 1.6.3
+
+Installing TorchPhysics with ``pip``, automatically downloads everything that is needed:
 
 .. code-block:: python
 
-  pip install git+https://github.com/boschresearch/torchphysics
+  pip install torchphysics
+
+Additionally, to use the ``Shapely`` and ``Trimesh`` functionalities, install the library 
+with the option ``all``:
+
+.. code-block:: python
+
+  pip install torchphysics[all]
+
 
-If you want to change or add something to the code. You should first copy the repository and install
-it locally:
+If you want to add functionalities or modify the code. We recommend copying the 
+repository and installing it locally:
 
 .. code-block:: python
 
   git clone https://github.com/boschresearch/torchphysics 
-  pip install .
+  cd path_to_torchphysics_folder
+  pip install .[all]
 
+.. _Numpy: https://numpy.org/
+.. _Matplotlib: https://matplotlib.org/
+.. _Scipy: https://scipy.org/
 
 About
 =====

docs/index.rst

@@ -34,7 +34,7 @@ can be found.
    :maxdepth: 2
 
    Overview <readme>
-   Tutorial <tutorial/tutorial_start>
+   Tutorial <tutorial/main_page>
    Examples <examples>
 
 

docs/tutorial/applied_tutorial_start.rst

@@ -0,0 +1,45 @@
+==============================
+Applied TorchPhysics Tutorials
+==============================
+Here, we explain the library of TorchPhysics along the implementation of different 
+examples. 
+
+To start, we consider a heat equation problem of the form
+
+.. math::
+    \begin{align}
+    \partial_t u(x,t) &= \Delta_x u(x,t) \text{ on } \Omega\times I, \\
+    u(x, t) &= u_0 \text{ on } \Omega\times \{0\},\\
+    u(x,t) &= h(t) \text{ at } \partial\Omega_{heater}\times I, \\
+    \nabla_x u(x, t) \cdot n(x) &= 0 \text{ at } (\partial \Omega \setminus \partial\Omega_{heater}) \times I,
+    \end{align}
+
+
+that we will solve with PINNs. This example is a nice starting point for a new user and can 
+be found here_. The notebook gives a lot of information about TorchPhysics and even repeats the
+basic ideas of PINNs.
+
+.. _here : https://github.com/boschresearch/torchphysics/blob/main/examples/tutorial/Introduction_Tutorial_PINNs.ipynb
+
+A next step would be to make the problem more complicated, such that not a single solution
+should be found, but a whole family of solutions for different functions :math:`h`.
+As long as the different :math:`h` can be defined through some parameters, the solution operator 
+can still be learned through PINNs. This is explained in this notebook_, which is really similar to
+previous one and highlights the small aspects that have to be changed.
+
+.. _notebook : https://github.com/boschresearch/torchphysics/blob/main/examples/tutorial/Tutorial_PINNs_Parameter_Dependency.ipynb
+
+For more complex :math:`h` functions, we end up at the DeepONet. DeepONets can also be learned 
+physics informed, which is demonstrated in this tutorial_.
+
+.. _tutorial : https://github.com/boschresearch/torchphysics/blob/main/examples/tutorial/Introduction_Tutorial_DeepONet.ipynb
+
+Similar examples, with a description of each step, can be found in the two notebooks `PINNs for Poisson`_ 
+and `DRM for Poisson`_. The second notebook 
+also uses the Deep Ritz Method instead of PINNs. 
+
+More applications can be found on the `example page`_.
+
+.. _`PINNs for Poisson`: https://github.com/boschresearch/torchphysics/blob/main/examples/tutorial/solve_pde.ipynb
+.. _`DRM for Poisson`: https://github.com/boschresearch/torchphysics/blob/main/examples/tutorial/solve_pde_drm.ipynb
+.. _`example page`: https://torchphysics.readthedocs.io/en/latest/examples.html

docs/tutorial/main_page.rst

@@ -0,0 +1,48 @@
+=========================
+The TorchPhysics Tutorial
+=========================
+Here one can find all important information and knowledge to get started with the 
+software library TorchPhysics.
+
+In order to make it as easy and user-friendly as possible for all users, 
+both complete novices and professionals in Machine Learning and PDEs, to get started, the tutorial
+starts with some basics regarding differential equations and neural networks. For more
+experienced users, these points can be skipped.
+
+Afterward, we give a rough overview of different Deep Learning approaches for solving 
+differential equations, with a focus on PINNs and DeepONet.
+
+The main and final topic is the use of TorchPhysics. Here we split the tutorial into two parts.
+The first part, guides you along some implementations of different small examples, while showing 
+all the important aspects and steps to solve a differential equation in TorchPhysics. This tutorial
+series is aimed at an audience which is more interested on the direct utilization of the library 
+and for getting a fast and small overview of the possibilities.
+
+To get a deeper understanding of the library, we show in the second part how the library is 
+internally structured. This series is more aimed for users who plan to add or change functionalities.
+
+
+Basics of Deep Learning and Differential Equations
+=====================================================
+Will be added in the future.
+
+
+Overview of Deep Learning Methods for Differential Equations
+============================================================
+Will be added in the future.
+
+
+Usage of TorchPhysics
+=====================
+Like mentioned at the beginning, here we explain the aspects of TorchPhysics in more 
+detail. We split the tutorial into two categories:
+
+1) A more applied tutorial to learn TorchPhysics by implementing some examples.
+   All basics features will be explained. The start can be found here_.
+
+2) A more in depth tutorial that focuses more on the library architecture. This 
+   tutorial begins on this page_.
+
+
+.. _here : applied_tutorial_start.html
+.. _page : tutorial_start.html