improved usability

PRIVATE

@@ -1 +1 @@
-Subproject commit afffa8d04e110282e514a4e57d0bad9c76effe01
+Subproject commit 7f0594060779d9a8a4e774d558134309ab77b96e

python/damask/_config.py

@@ -61,6 +61,11 @@ class Config(dict):
         other : damask.Config or dict
             Key-value pairs that update self.
 
+        Returns
+        -------
+        updated : damask.Config
+            Updated configuration.
+
         """
         duplicate = self.copy()
         duplicate.update(other)
@@ -81,6 +86,11 @@ class Config(dict):
         keys : iterable or scalar
             Label of the key(s) to remove.
 
+        Returns
+        -------
+        updated : damask.Config
+            Updated configuration.
+
         """
         duplicate = self.copy()
         for k in keys if isinstance(keys, Iterable) and not isinstance(keys, str) else [keys]:
@@ -98,6 +108,11 @@ class Config(dict):
         fname : file, str, or pathlib.Path
             Filename or file for writing.
 
+        Returns
+        -------
+        loaded : damask.Config
+            Configuration from file.
+
         """
         try:
             fhandle = open(fname)

python/damask/_configmaterial.py

@@ -54,7 +54,12 @@ class ConfigMaterial(Config):
         Parameters
         ----------
         fname : file, str, or pathlib.Path, optional
-            Filename or file for writing. Defaults to 'material.yaml'.
+            Filename or file to read from. Defaults to 'material.yaml'.
+
+        Returns
+        -------
+        loaded : damask.ConfigMaterial
+            Material configuration from file.
 
         """
         return super(ConfigMaterial,cls).load(fname)
@@ -103,6 +108,11 @@ class ConfigMaterial(Config):
             and grain- or cell-wise data. Defaults to None, in which case
             it is set as the path that contains _SIMPL_GEOMETRY/SPACING.
 
+        Returns
+        -------
+        loaded : damask.ConfigMaterial
+            Material configuration from file.
+
         """
         b = util.DREAM3D_base_group(fname) if base_group is None else base_group
         c = util.DREAM3D_cell_data_group(fname) if cell_data is None else cell_data
@@ -146,6 +156,11 @@ class ConfigMaterial(Config):
             Keyword arguments where the key is the name and the value specifies
             the label of the data column in the table.
 
+        Returns
+        -------
+        new : damask.ConfigMaterial
+            Material configuration from values in table.
+
         Examples
         --------
         >>> import damask

python/damask/_grid.py

@@ -1012,6 +1012,11 @@ class Grid:
             Direction(s) along which the boundaries are determined.
             Valid entries are 'x', 'y', 'z'. Defaults to 'xyz'.
 
+        Returns
+        -------
+        grain_boundaries : damask.VTK
+            VTK-based geometry of grain boundary network.
+
         """
         valid = ['x','y','z']
         if not set(directions).issubset(valid):

python/damask/_result.py

@@ -585,16 +585,17 @@ class Result:
                           'creator':     'add_calculation'
                           }
                  }
-    def add_calculation(self,name,formula,unit='n/a',description=None):
+    def add_calculation(self,formula,name,unit='n/a',description=None):
         """
         Add result of a general formula.
 
         Parameters
         ----------
-        name : str
-          Name of resulting dataset.
         formula : str
-            Formula to calculate resulting dataset. Existing datasets are referenced by '#TheirName#'.
+            Formula to calculate resulting dataset.
+            Existing datasets are referenced by '#TheirName#'.
+        name : str
+            Name of resulting dataset.
         unit : str, optional
             Physical unit of the result.
         description : str, optional
@@ -608,11 +609,11 @@ class Result:
 
         >>> import damask
         >>> r = damask.Result('my_file.hdf5')
-        >>> r.add_calculation('rho_mob_total','np.sum(#rho_mob#,axis=1)',
+        >>> r.add_calculation('np.sum(#rho_mob#,axis=1)','rho_mob_total',
         ...                    '1/m²','total mobile dislocation density')
-        >>> r.add_calculation('rho_dip_total','np.sum(#rho_dip#,axis=1)',
+        >>> r.add_calculation(''np.sum(#rho_dip#,axis=1)',rho_dip_total',
         ...                    '1/m²','total dislocation dipole density')
-        >>> r.add_calculation('rho_total','#rho_dip_total#+#rho_mob_total',
+        >>> r.add_calculation('#rho_dip_total#+#rho_mob_total','rho_total',
         ...                    '1/m²','total dislocation density')
 
         Add Mises equivalent of the Cauchy stress without storage of
@@ -624,7 +625,7 @@ class Result:
         ...     return damask.mechanics.equivalent_stress_Mises(sigma)
         >>> r = damask.Result('my_file.hdf5')
         >>> r.enable_user_function(equivalent_stress)
-        >>> r.add_calculation('sigma_vM','equivalent_stress(#F#,#P#)','Pa',
+        >>> r.add_calculation('equivalent_stress(#F#,#P#)','sigma_vM','Pa',
         ...                   'Mises equivalent of the Cauchy stress')
 
         """

python/damask/_rotation.py

@@ -357,7 +357,7 @@ class Rotation:
 
         Parameters
         ----------
-            other : damask.Rotation
+        other : damask.Rotation
 
         """
         return self.copy(rotation=np.vstack(tuple(map(lambda x:x.quaternion,
@@ -370,7 +370,7 @@ class Rotation:
 
         Returns
         -------
-            flattened : damask.Rotation
+        flattened : damask.Rotation
             Rotation flattened to single dimension.
 
         """
@@ -383,7 +383,7 @@ class Rotation:
 
         Returns
         -------
-            reshaped : damask.Rotation
+        reshaped : damask.Rotation
             Rotation of given shape.
 
         """
@@ -405,7 +405,7 @@ class Rotation:
 
         Returns
         -------
-            broadcasted : damask.Rotation
+        broadcasted : damask.Rotation
             Rotation broadcasted to given shape.
 
         """
@@ -464,7 +464,7 @@ class Rotation:
 
         Returns
         -------
-            g : damask.Rotation
+        g : damask.Rotation
             Misorientation.
 
         """

python/tests/test_Result.py

@@ -110,14 +110,14 @@ class TestResult:
     def test_add_calculation(self,default,tmp_path,mode):
 
         if mode == 'direct':
-            default.add_calculation('x','2.0*np.abs(#F#)-1.0','-','my notes')
+            default.add_calculation('2.0*np.abs(#F#)-1.0','x','-','my notes')
         else:
             with open(tmp_path/'f.py','w') as f:
                 f.write("import numpy as np\ndef my_func(field):\n  return 2.0*np.abs(field)-1.0\n")
             sys.path.insert(0,str(tmp_path))
             import f
             default.enable_user_function(f.my_func)
-            default.add_calculation('x','my_func(#F#)','-','my notes')
+            default.add_calculation('my_func(#F#)','x','-','my notes')
 
         in_memory = 2.0*np.abs(default.place('F'))-1.0
         in_file   = default.place('x')
@@ -193,14 +193,14 @@ class TestResult:
 
     def test_add_Mises_invalid(self,default):
         default.add_stress_Cauchy('P','F')
-        default.add_calculation('sigma_y','#sigma#',unit='y')
+        default.add_calculation('#sigma#','sigma_y',unit='y')
         default.add_equivalent_Mises('sigma_y')
         assert default.get('sigma_y_vM') is None
 
     def test_add_Mises_stress_strain(self,default):
         default.add_stress_Cauchy('P','F')
-        default.add_calculation('sigma_y','#sigma#',unit='y')
+        default.add_calculation('#sigma#','sigma_y',unit='y')
-        default.add_calculation('sigma_x','#sigma#',unit='x')
+        default.add_calculation('#sigma#','sigma_x',unit='x')
         default.add_equivalent_Mises('sigma_y',kind='strain')
         default.add_equivalent_Mises('sigma_x',kind='stress')
         assert not np.allclose(default.place('sigma_y_vM'),default.place('sigma_x_vM'))
@@ -285,7 +285,7 @@ class TestResult:
 
         time.sleep(2.)
         try:
-            last.add_calculation('sigma','#sigma#*0.0+311.','not the Cauchy stress')
+            last.add_calculation('#sigma#*0.0+311.','sigma','not the Cauchy stress')
         except ValueError:
             pass
 
@@ -362,7 +362,7 @@ class TestResult:
     def test_XDMF(self,tmp_path,single_phase,update,ref_path):
         for shape in [('scalar',()),('vector',(3,)),('tensor',(3,3)),('matrix',(12,))]:
             for dtype in ['f4','f8','i1','i2','i4','i8','u1','u2','u4','u8']:
-                 single_phase.add_calculation(f'{shape[0]}_{dtype}',f"np.ones(np.shape(#F#)[0:1]+{shape[1]},'{dtype}')")
+                 single_phase.add_calculation(f"np.ones(np.shape(#F#)[0:1]+{shape[1]},'{dtype}')",f'{shape[0]}_{dtype}')
         fname = os.path.splitext(os.path.basename(single_phase.fname))[0]+'.xdmf'
         os.chdir(tmp_path)
         single_phase.save_XDMF()