* Add support of pow and divide operation.

* Allow register the value of a scalar field after the field is defined.
* Update the docstring and documentations.

Author: qiauil

.github/workflows/build_docs.yml

@@ -1,35 +1,35 @@
-on:
-  push:
-    branches:
-      - main
-permissions:
-  contents: write
-jobs:
-  deploy:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - name: Configure Git Credentials
-        run: |
-          git config user.name github-actions[bot]
-          git config user.email 41898282+github-actions[bot]@users.noreply.github.com
-      - uses: actions/setup-python@v5
-        with:
-          python-version: 3.x
-      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV 
-
-      - name: Install dependencies
-        run: |
-          python -m pip install --upgrade pip
-          pip install setuptools
-          bash install.sh
-          python -m pip install -r docs/requirements.txt
-
-      - uses: actions/cache@v4
-        with:
-          key: mkdocs-material-${{ env.cache_id }}
-          path: .cache
-          restore-keys: |
-            mkdocs-material-
-      - run: pip install mkdocs-material 
-      - run: mkdocs gh-deploy --force
+on:
+  push:
+    branches:
+      - main
+permissions:
+  contents: write
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Configure Git Credentials
+        run: |
+          git config user.name github-actions[bot]
+          git config user.email 41898282+github-actions[bot]@users.noreply.github.com
+      - uses: actions/setup-python@v5
+        with:
+          python-version: 3.x
+      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV 
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install setuptools
+          bash install.sh
+          python -m pip install -r docs/requirements.txt
+
+      - uses: actions/cache@v4
+        with:
+          key: mkdocs-material-${{ env.cache_id }}
+          path: .cache
+          restore-keys: |
+            mkdocs-material-
+      - run: pip install mkdocs-material 
+      - run: mkdocs gh-deploy --force

ConvDO/operator.py renamed to ConvDO/_operator_deprecated.py

@@ -1,16 +1,18 @@
 #usr/bin/python3
 # -*- coding: UTF-8 -*-
-import os,torch
+import torch
 from . import *
 from .domain import *
 from .obstacles import *
 from .boundaries import *
+from typing import Optional
 
 print("Warning: This is an old version of operator which will be deprecated soon. Please use 'operator_HO' instead.")
 
 class ScalarField(CommutativeValue):
 
-    def __init__(self,value,domain=UnconstrainedDomain()) -> None:
+    def __init__(self,value:torch.Tensor,
+                 domain:Optional[Domain]=UnconstrainedDomain()) -> None:
         self.value=value
         self.domain=domain
 
@@ -55,7 +57,7 @@ def __mul__(self,other):
         else:
             try:
                 return self*other
-            except TypeError:
+            except Exception:
                 return NotImplemented    
 
 class GradY():
@@ -87,7 +89,7 @@ def __mul__(self,other):
         else:
             try:
                 return self*other
-            except TypeError:
+            except Exception:
                 return NotImplemented    
 
 class LaplacianX():
@@ -119,7 +121,7 @@ def __mul__(self,other):
         else:
             try:
                 return self*other
-            except TypeError:
+            except Exception:
                 return NotImplemented     
 
 class LaplacianY():
@@ -151,7 +153,7 @@ def __mul__(self,other):
         else:
             try:
                 return self*other
-            except TypeError:
+            except Exception:
                 return NotImplemented   
 
 class Laplacian():

ConvDO/boundaries.py

@@ -22,94 +22,123 @@ def correct_left(self,padded_face,ori_field,delta):
         pass
 
 class DirichletBoundary(Boundary):
+    '''
+    DirichletBoundary is a boundary condition that the value of the field is fixed at the boundary.
+    '''
 
-    def __init__(self,boundary_value) -> None:
+    def __init__(self,boundary_value: float) -> None:
         super().__init__()
-        self.boundary_value=boundary_value
-        self.face_calculator=DirichletFace(boundary_value)
+        self.boundary_face=DirichletFace(boundary_value)
 
     def correct_top(self,padded_face,ori_field,delta):
-        padded_face[...,0,:]=self.face_calculator.correct_outward_padding(ori_field[...,0,:])
+        padded_face[...,0,:]=self.boundary_face.correct_outward_padding(ori_field[...,0,:])
         return padded_face
 
     def correct_right(self,padded_face,ori_field,delta):
-        padded_face[...,:,-1]=self.face_calculator.correct_outward_padding(ori_field[...,:,-1])  
+        padded_face[...,:,-1]=self.boundary_face.correct_outward_padding(ori_field[...,:,-1])  
         return padded_face
 
     def correct_bottom(self,padded_face,ori_field,delta):
-        padded_face[...,-1,:]=self.face_calculator.correct_inward_padding(ori_field[...,-1,:])  
+        padded_face[...,-1,:]=self.boundary_face.correct_inward_padding(ori_field[...,-1,:])  
         return padded_face
 
     def correct_left(self,padded_face,ori_field,delta):
-        padded_face[...,:,0]=self.face_calculator.correct_inward_padding(ori_field[...,:,0]) 
+        padded_face[...,:,0]=self.boundary_face.correct_inward_padding(ori_field[...,:,0]) 
         return padded_face   
 
     # + ： 
     def __add__(self, other):
         if isinstance(other,DirichletBoundary):
             # Dirichlet+Dirichlet=Dirichlet
-            return DirichletBoundary(self.boundary_value+other.boundary_value)
+            return DirichletBoundary(self.boundary_face.face_value+other.boundary_face.face_value)
         elif isinstance(other,Boundary):
             # Dirichlet+otherboundary=uncontrainedBoundary
             return UnConstrainedBoundary()
         else:
             try:
                 # Dirichlet+number=Dirichlet
-                return DirichletBoundary(self.boundary_value+other)
-            except TypeError:
+                return DirichletBoundary(self.boundary_face.face_value+other)
+            except Exception:
                 return NotImplemented
 
     # *           
     def __mul__(self,other):
         if isinstance(other,DirichletBoundary):
             # Dirichlet*Dirichlet=Dirichlet
-            return DirichletBoundary(self.boundary_value*other.boundary_value)
+            return DirichletBoundary(self.boundary_face.face_value*other.boundary_face.face_value)
         elif isinstance(other,Boundary):
             # Dirichlet*otherboundary=uncontrainedBoundary
             return UnConstrainedBoundary()
         else:
             try:
                 # Dirichlet*number=Dirichlet
-                return DirichletBoundary(self.boundary_value*other)
-            except TypeError:
+                return DirichletBoundary(self.boundary_face.face_value*other)
+            except Exception:
                 return NotImplemented
+            
+    def __truediv__(self, other):
+        if isinstance(other,DirichletBoundary):
+            return DirichletBoundary(self.boundary_face.face_value/other.boundary_face.face_value)
+        elif isinstance(other,Boundary):
+            return UnConstrainedBoundary()
+        else:
+            try:
+                return DirichletBoundary(self.boundary_face.face_value/other)
+            except Exception:
+                return NotImplemented
+        
+    def __rtruediv__(self, other):
+        if isinstance(other,DirichletBoundary):
+            return DirichletBoundary(other.boundary_face.face_value/self.boundary_face.face_value)
+        elif isinstance(other,Boundary):
+            return UnConstrainedBoundary()
+        else:
+            try:
+                return DirichletBoundary(other/self.boundary_face.face_value)
+            except Exception:
+                return NotImplemented
+
+    def __pow__(self, other):
+        return DirichletBoundary(self.boundary_face.face_value**other)
 
 class NeumannBoundary(Boundary):
+    '''
+    NeumannBoundary is a boundary condition that the gradient of the field is fixed at the boundary.
+    '''
 
-    def __init__(self,face_gradient) -> None:
+    def __init__(self,face_gradient: float) -> None:
         super().__init__()
-        self.face_gradient=face_gradient
-        self.face_calculator=NeumannFace(face_gradient)
+        self.boundary_face=NeumannFace(face_gradient)
 
     def correct_top(self,padded_face,ori_field,delta):
-        padded_face[...,0,:]=self.face_calculator.correct_outward_padding(ori_field[...,0,:],delta)
+        padded_face[...,0,:]=self.boundary_face.correct_outward_padding(ori_field[...,0,:],delta)
         return padded_face
 
     def correct_right(self,padded_face,ori_field,delta):
-        padded_face[...,:,-1]=self.face_calculator.correct_outward_padding(ori_field[...,:,-1],delta)  
+        padded_face[...,:,-1]=self.boundary_face.correct_outward_padding(ori_field[...,:,-1],delta)  
         return padded_face
 
     def correct_bottom(self,padded_face,ori_field,delta):
-        padded_face[...,-1,:]=self.face_calculator.correct_inward_padding(ori_field[...,-1,:],delta)  
+        padded_face[...,-1,:]=self.boundary_face.correct_inward_padding(ori_field[...,-1,:],delta)  
         return padded_face
 
     def correct_left(self,padded_face,ori_field,delta):
-        padded_face[...,:,0]=self.face_calculator.correct_inward_padding(ori_field[...,:,0],delta) 
+        padded_face[...,:,0]=self.boundary_face.correct_inward_padding(ori_field[...,:,0],delta) 
         return padded_face    
 
     # + ： 
     def __add__(self, other):
         if isinstance(other,NeumannBoundary):
             # Neumann+Neumann=Dirichlet
-            return NeumannBoundary(self.face_gradient+other.face_gradient)
+            return NeumannBoundary(self.boundary_face.face_gradient+other.boundary_face.face_gradient)
         elif isinstance(other,Boundary):
-            # Dirichlet+otherboundary=uncontrainedBoundary
+            # Neumann+otherboundary=uncontrainedBoundary
             return UnConstrainedBoundary()
         else:
             try:
-                # Neumann+number=NeumannBoundary
-                return NeumannBoundary(self.face_gradient)
-            except TypeError:
+                # Neumann+number=Neumann
+                return NeumannBoundary(self.boundary_face.face_gradient)
+            except Exception:
                 return NotImplemented
 
     # *           
@@ -119,32 +148,58 @@ def __mul__(self,other):
             return UnConstrainedBoundary()
         else:
             try:
-                # Neumann*number=Neumann
-                return DirichletBoundary(self.boundary_value*other)
-            except TypeError:
+                # Neumann*number=Neumann*number
+                return DirichletBoundary(self.boundary_face.face_value*other)
+            except Exception:
                 return NotImplemented
 
+    def __truediv__(self, other):
+        if isinstance(other,Boundary):
+            return UnConstrainedBoundary()
+        else:
+            try:
+                return DirichletBoundary(self.boundary_face.face_value/other)
+            except Exception:
+                return NotImplemented
+
+    def __rtruediv__(self, other):
+        if isinstance(other,Boundary):
+            return UnConstrainedBoundary()
+        else:
+            try:
+                return DirichletBoundary(other/self.boundary_face.face_value)
+            except Exception:
+                return NotImplemented
+
+    def __pow__(self, other):
+        return UnConstrainedBoundary()
+
 
 class UnConstrainedBoundary(Boundary):
+    '''
+    UnConstrainedBoundary is a boundary condition that the value at the boundary is calculated by the value of the neighbour cells.
+    If you are not sure about the boundary condition, you can use UnConstrainedBoundary.
+    The 
+    '''
 
     def __init__(self) -> None:
         super().__init__()
-        self.face_calculator=UnConstrainedFace()
+        self.boundary_face=UnConstrainedFace()
 
     def correct_top(self,padded_face,ori_field,delta):
-        padded_face[...,0,:]=self.face_calculator.correct_outward_padding(ori_field[...,0,:],ori_field[...,1,:],ori_field[...,2,:])
+        padded_face[...,0,:]=self.boundary_face.correct_outward_padding(ori_field[...,0,:],ori_field[...,1,:],ori_field[...,2,:])
         return padded_face
 
     def correct_right(self,padded_face,ori_field,delta):
-        padded_face[...,:,-1]=self.face_calculator.correct_outward_padding(ori_field[...,:,-1],ori_field[...,:,-2],ori_field[...,:,-3])  
+        padded_face[...,:,-1]=self.boundary_face.correct_outward_padding(ori_field[...,:,-1],ori_field[...,:,-2],ori_field[...,:,-3])  
         return padded_face
 
     def correct_bottom(self,padded_face,ori_field,delta):
-        padded_face[...,-1,:]=self.face_calculator.correct_outward_padding(ori_field[...,-1,:],ori_field[...,-2,:],ori_field[...,-3,:])
+        padded_face[...,-1,:]=self.boundary_face.correct_outward_padding(ori_field[...,-1,:],ori_field[...,-2,:],ori_field[...,-3,:])
         return padded_face
 
     def correct_left(self,padded_face,ori_field,delta):
-        padded_face[...,:,0]=self.face_calculator.correct_outward_padding(ori_field[...,:,0],ori_field[...,:,1],ori_field[...,:,2]) 
+        padded_face[...,:,0]=self.boundary_face.correct_outward_padding(ori_field[...,:,0],ori_field[...,:,1],ori_field[...,:,2]) 
         return padded_face    
 
     # + ： 
@@ -153,9 +208,20 @@ def __add__(self, other):
     # *           
     def __mul__(self,other):
         return UnConstrainedBoundary()
+
+    def __pow__(self, other):
+        return UnConstrainedBoundary()
+    
+    def __truediv__(self, other):
+        return UnConstrainedBoundary()
 
+    def __rtruediv__(self, other):
+        return UnConstrainedBoundary()
 
 class PeriodicBoundary(Boundary):
+    '''
+    Periodic boundary conditions.
+    '''
 
     def __init__(self) -> None:
         super().__init__()
@@ -197,3 +263,18 @@ def __mul__(self,other):
             return UnConstrainedBoundary()
         else:
             return PeriodicBoundary()
+        
+    def __pow__(self, other):
+        return PeriodicBoundary()
+    
+    def __truediv__(self, other):
+        if isinstance(other,PeriodicBoundary):
+            return PeriodicBoundary()
+        else:
+            return UnConstrainedBoundary()
+        
+    def __rtruediv__(self, other):
+        if isinstance(other,PeriodicBoundary):
+            return PeriodicBoundary()
+        else:
+            return UnConstrainedBoundary()