From 690b478013758459d25a9227cbd223145dde6bc2 Mon Sep 17 00:00:00 2001 From: Philip Eisenlohr Date: Sat, 24 Apr 2021 13:12:44 -0400 Subject: [PATCH 1/2] [skip ci] language polishing --- python/damask/_result.py | 32 ++++++++++++++++---------------- python/damask/_vtk.py | 6 +++--- python/damask/grid_filters.py | 4 ++-- python/damask/solver/__init__.py | 2 +- 4 files changed, 22 insertions(+), 22 deletions(-) diff --git a/python/damask/_result.py b/python/damask/_result.py index bc3d3916d..0ca160922 100644 --- a/python/damask/_result.py +++ b/python/damask/_result.py @@ -59,17 +59,17 @@ class Result: """ Add data to and export data from a DADF5 file. - A DADF5 (DAMASK HDF5) file contain DAMASK results. + A DADF5 (DAMASK HDF5) file contains DAMASK results. Its group/folder structure reflects the layout in material.yaml. - This class provides a customable view on the DADF5 file. + This class provides a customizable view on the DADF5 file. Upon initialization, all attributes are visible. Derived quantities are added to the file and existing data is exported based on the current view. Examples -------- - Open 'my_file.hdf5', which needs to contain deformation gradient 'F' + Open 'my_file.hdf5', which is assumed to contain deformation gradient 'F' and first Piola-Kirchhoff stress 'P', add the Mises equivalent of the Cauchy stress, and export it to VTK (file) and numpy.ndarray (memory). @@ -234,12 +234,12 @@ class Result: def modification_enable(self): """ - Allow to modify existing data. + Allow modification of existing data. Returns ------- modified_view : damask.Result - View where data is not write-protected. + View without write-protection of existing data. """ print(util.warn('Warning: Modification of existing datasets allowed!')) @@ -249,12 +249,12 @@ class Result: def modification_disable(self): """ - Disallow to modify existing data (default case). + Prevent modification of existing data (default case). Returns ------- modified_view : damask.Result - View where data is write-protected. + View with write-protection of existing data. """ dup = self.copy() @@ -328,7 +328,7 @@ class Result: Returns ------- view : damask.Result - View with where selected attributes are visible. + View with only the selected attributes being visible. Examples -------- @@ -338,7 +338,7 @@ class Result: >>> r = damask.Result('my_file.hdf5') >>> r_first = r.view('increment',0) - Get a view that shows all results of in simulation time [10,40]: + Get a view that shows all results between simulation times of 10 to 40: >>> import damask >>> r = damask.Result('my_file.hdf5') @@ -363,7 +363,7 @@ class Result: Returns ------- modified_view : damask.Result - View with more visible attributes. + View with additional visible attributes. Examples -------- @@ -380,7 +380,7 @@ class Result: def view_less(self,what,datasets): """ - Delete from view. + Remove from view. Parameters ---------- @@ -393,11 +393,11 @@ class Result: Returns ------- modified_view : damask.Result - View with less visible attributes. + View with fewer visible attributes. Examples -------- - Get a view that does not show the undeformed configuration: + Get a view that omits the undeformed configuration: >>> import damask >>> r_all = damask.Result('my_file.hdf5') @@ -1396,7 +1396,7 @@ class Result: Parameters ---------- output : (list of) str, optional - Names of the datasets included in the VTK file. + Names of the datasets to export to the VTK file. Defaults to '*', in which case all datasets are exported. mode : {'cell', 'point'} Export in cell format or point format. @@ -1521,7 +1521,7 @@ class Result: in the DADF5 file. Multi-phase data is fused into a single output. - `place` is equivalent to `read` if only one phase/homogenization + `place` is equivalent to `get` if only one phase/homogenization and one constituent is present. Parameters @@ -1537,7 +1537,7 @@ class Result: Remove branches with no data. Defaults to True. constituents : (list of) int, optional Constituents to consider. - Defaults to 'None', in which case all constituents are considered. + Defaults to None, in which case all constituents are considered. fill_float : float Fill value for non-existent entries of floating point type. Defaults to NaN. diff --git a/python/damask/_vtk.py b/python/damask/_vtk.py index 2a6cbd3f2..61f3efd80 100644 --- a/python/damask/_vtk.py +++ b/python/damask/_vtk.py @@ -46,9 +46,9 @@ class VTK: grid : iterable of int, len (3) Number of cells along each dimension. size : iterable of float, len (3) - Physical lengths along each dimension. + Physical length along each dimension. origin : iterable of float, len (3), optional - Spatial origin coordinates. + Coordinates of grid origin. Returns ------- @@ -161,7 +161,7 @@ class VTK: """ if not os.path.isfile(fname): # vtk has a strange error handling - raise FileNotFoundError(f'no such file: {fname}') + raise FileNotFoundError(f'No such file: {fname}') ext = Path(fname).suffix if ext == '.vtk' or dataset_type is not None: reader = vtk.vtkGenericDataObjectReader() diff --git a/python/damask/grid_filters.py b/python/damask/grid_filters.py index bc9194947..7d0bdab64 100644 --- a/python/damask/grid_filters.py +++ b/python/damask/grid_filters.py @@ -493,7 +493,7 @@ def node_to_point(node_data): def coordinates0_valid(coordinates0): """ - Check whether coordinates lie on a regular grid. + Check whether coordinates form a regular grid. Parameters ---------- @@ -503,7 +503,7 @@ def coordinates0_valid(coordinates0): Returns ------- valid : bool - Wheter the coordinates lie on a regular grid. + Whether the coordinates form a regular grid. """ try: diff --git a/python/damask/solver/__init__.py b/python/damask/solver/__init__.py index 01cfeed9b..bd92ee9a8 100644 --- a/python/damask/solver/__init__.py +++ b/python/damask/solver/__init__.py @@ -1,3 +1,3 @@ -"""Run simulations directly from python.""" +"""Run simulations directly from Python.""" from ._marc import Marc # noqa From 0459f17f583458652766c165779190d59f43410a Mon Sep 17 00:00:00 2001 From: Martin Diehl Date: Sun, 25 Apr 2021 07:47:00 +0200 Subject: [PATCH 2/2] improved usability --- PRIVATE | 2 +- python/damask/_config.py | 15 +++++++++++++++ python/damask/_configmaterial.py | 17 ++++++++++++++++- python/damask/_grid.py | 5 +++++ python/damask/_result.py | 17 +++++++++-------- python/damask/_rotation.py | 10 +++++----- python/tests/test_Result.py | 14 +++++++------- 7 files changed, 58 insertions(+), 22 deletions(-) diff --git a/PRIVATE b/PRIVATE index afffa8d04..7f0594060 160000 --- a/PRIVATE +++ b/PRIVATE @@ -1 +1 @@ -Subproject commit afffa8d04e110282e514a4e57d0bad9c76effe01 +Subproject commit 7f0594060779d9a8a4e774d558134309ab77b96e diff --git a/python/damask/_config.py b/python/damask/_config.py index 989f28fcd..627fc88c8 100644 --- a/python/damask/_config.py +++ b/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) diff --git a/python/damask/_configmaterial.py b/python/damask/_configmaterial.py index e927874f3..b5b38a417 100644 --- a/python/damask/_configmaterial.py +++ b/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 diff --git a/python/damask/_grid.py b/python/damask/_grid.py index aebd8f92c..1b58870e4 100644 --- a/python/damask/_grid.py +++ b/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): diff --git a/python/damask/_result.py b/python/damask/_result.py index 0ca160922..f0f944790 100644 --- a/python/damask/_result.py +++ b/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') """ diff --git a/python/damask/_rotation.py b/python/damask/_rotation.py index 6b2869033..3bd84fcb1 100644 --- a/python/damask/_rotation.py +++ b/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. """ diff --git a/python/tests/test_Result.py b/python/tests/test_Result.py index e79e25784..56bc4a00f 100644 --- a/python/tests/test_Result.py +++ b/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_x','#sigma#',unit='x') + default.add_calculation('#sigma#','sigma_y',unit='y') + 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()