From 24046ef6830e2fea4751efe3c4059d477853986c Mon Sep 17 00:00:00 2001 From: Martin Diehl Date: Sat, 24 Apr 2021 18:00:57 +0200 Subject: [PATCH] support the user --- PRIVATE | 2 +- python/damask/__init__.py | 12 ++--- python/damask/_colormap.py | 15 ++++++ python/damask/grid_filters.py | 8 +-- python/damask/seeds.py | 12 ++--- python/damask/util.py | 91 ++++++++++++++++++++++++++++++++--- 6 files changed, 113 insertions(+), 27 deletions(-) diff --git a/PRIVATE b/PRIVATE index 156831f79..afffa8d04 160000 --- a/PRIVATE +++ b/PRIVATE @@ -1 +1 @@ -Subproject commit 156831f7962a1eb965023331a900121c5aee5e55 +Subproject commit afffa8d04e110282e514a4e57d0bad9c76effe01 diff --git a/python/damask/__init__.py b/python/damask/__init__.py index af9933954..ad46d454f 100644 --- a/python/damask/__init__.py +++ b/python/damask/__init__.py @@ -1,11 +1,4 @@ -""" -Tools for pre and post processing of DAMASK simulations. - -Modules that contain only one class (of the same name), -are prefixed by a '_'. For example, '_colormap' contains -a class called 'Colormap' which is imported as 'damask.Colormap'. - -""" +"""Tools for managing DAMASK simulations.""" from pathlib import Path as _Path import re as _re @@ -15,7 +8,6 @@ with open(_Path(__file__).parent/_Path('VERSION')) as _f: version = _re.sub(r'^v','',_f.readline().strip()) __version__ = version -# make classes directly accessible as damask.Class from . import util # noqa from . import seeds # noqa from . import tensor # noqa @@ -23,6 +15,8 @@ from . import mechanics # noqa from . import solver # noqa from . import grid_filters # noqa from . import lattice # noqa +#Modules that contain only one class (of the same name), are prefixed by a '_'. +#For example, '_colormap' containsa class called 'Colormap' which is imported as 'damask.Colormap'. from ._rotation import Rotation # noqa from ._orientation import Orientation # noqa from ._table import Table # noqa diff --git a/python/damask/_colormap.py b/python/damask/_colormap.py index 0d36c1ee6..02e2b922c 100644 --- a/python/damask/_colormap.py +++ b/python/damask/_colormap.py @@ -96,6 +96,11 @@ class Colormap(mpl.colors.ListedColormap): new : damask.Colormap Colormap within given bounds. + Examples + -------- + >>> import damask + >>> damask.Colormap.from_range((0,0,1),(0,0,0),'blue_to_black') + """ low_high = np.vstack((low,high)) if model.lower() == 'rgb': @@ -160,6 +165,11 @@ class Colormap(mpl.colors.ListedColormap): new : damask.Colormap Predefined colormap. + Examples + -------- + >>> import damask + >>> damask.Colormap.from_predefined('strain') + """ # matplotlib presets try: @@ -230,6 +240,11 @@ class Colormap(mpl.colors.ListedColormap): damask.Colormap The reversed colormap. + Examples + -------- + >>> import damask + >>> damask.Colormap.from_predefined('stress').reversed() + """ rev = super(Colormap,self).reversed(name) return Colormap(np.array(rev.colors),rev.name[:-4] if rev.name.endswith('_r_r') else rev.name) diff --git a/python/damask/grid_filters.py b/python/damask/grid_filters.py index fe5e290c6..bc9194947 100644 --- a/python/damask/grid_filters.py +++ b/python/damask/grid_filters.py @@ -263,8 +263,8 @@ def cellsSizeOrigin_coordinates0_point(coordinates0,ordered=True): Returns ------- - DNA : tuple with 3 numpy.ndarray of shape (3) - Information to reconstruct grid: cells, size, origin. + cells, size, origin : Three numpy.ndarray, each of shape (3) + Information to reconstruct grid. """ coords = [_np.unique(coordinates0[:,i]) for i in range(3)] @@ -420,8 +420,8 @@ def cellsSizeOrigin_coordinates0_node(coordinates0,ordered=True): Returns ------- - DNA : tuple with 3 numpy.ndarray of shape (3) - Information to reconstruct grid: cells, size, origin. + cells, size, origin : Three numpy.ndarray, each of shape (3) + Information to reconstruct grid. """ coords = [_np.unique(coordinates0[:,i]) for i in range(3)] diff --git a/python/damask/seeds.py b/python/damask/seeds.py index 74d15f1ef..aeab2e64a 100644 --- a/python/damask/seeds.py +++ b/python/damask/seeds.py @@ -26,8 +26,8 @@ def from_random(size,N_seeds,cells=None,rng_seed=None): Returns ------- - new : numpy.ndarray of shape (N_seeds,3) - Coordinates in 3D space. + coords : numpy.ndarray of shape (N_seeds,3) + Seed coordinates in 3D space. """ rng = _np.random.default_rng(rng_seed) @@ -63,8 +63,8 @@ def from_Poisson_disc(size,N_seeds,N_candidates,distance,periodic=True,rng_seed= Returns ------- - new : numpy.ndarray of shape (N_seeds,3) - Coordinates in 3D space. + coords : numpy.ndarray of shape (N_seeds,3) + Seed coordinates in 3D space. """ rng = _np.random.default_rng(rng_seed) @@ -106,8 +106,8 @@ def from_grid(grid,selection=None,invert=False,average=False,periodic=True): Returns ------- - new : numpy.ndarray of shape (...,3) - Coordinates in 3D space. + coords, materials : numpy.ndarray of shape (:,3), numpy.ndarray of shape (:) + Seed coordinates in 3D space, material IDs. """ material = grid.material.reshape((-1,1),order='F') diff --git a/python/damask/util.py b/python/damask/util.py index b519fb15e..fcf41c251 100644 --- a/python/damask/util.py +++ b/python/damask/util.py @@ -49,7 +49,7 @@ _colors = { #################################################################################################### def srepr(arg,glue = '\n'): r""" - Join arguments with glue string. + Join items with glue string. Parameters ---------- @@ -58,6 +58,11 @@ def srepr(arg,glue = '\n'): glue : str, optional Glue used for joining operation. Defaults to \n. + Returns + ------- + joined : str + String representation of the joined items. + """ if (not hasattr(arg, 'strip') and (hasattr(arg, '__getitem__') or @@ -68,19 +73,71 @@ def srepr(arg,glue = '\n'): def emph(what): - """Formats string with emphasis.""" + """ + Format with emphasis. + + Parameters + ---------- + what : object with __repr__ or iterable of objects with __repr__. + Message to format. + + Returns + ------- + formatted : str + Formatted string representation of the joined items. + + """ return _colors['bold']+srepr(what)+_colors['end_color'] def deemph(what): - """Formats string with deemphasis.""" + """ + Format with deemphasis. + + Parameters + ---------- + what : object with __repr__ or iterable of objects with __repr__. + Message to format. + + Returns + ------- + formatted : str + Formatted string representation of the joined items. + + """ return _colors['dim']+srepr(what)+_colors['end_color'] def warn(what): - """Formats string for warning.""" + """ + Format for warning. + + Parameters + ---------- + what : object with __repr__ or iterable of objects with __repr__. + Message to format. + + Returns + ------- + formatted : str + Formatted string representation of the joined items. + + """ return _colors['warning']+emph(what)+_colors['end_color'] def strikeout(what): - """Formats string as strikeout.""" + """ + Format as strikeout. + + Parameters + ---------- + what : object with __repr__ or iterable of objects with __repr__. + Message to format. + + Returns + ------- + formatted : str + Formatted string representation of the joined items. + + """ return _colors['crossout']+srepr(what)+_colors['end_color'] @@ -97,6 +154,11 @@ def execute(cmd,wd='./',env=None): env : dict, optional Environment for execution. + Returns + ------- + stdout, stderr : str + Output of the executed command. + """ print(f"executing '{cmd}' in '{wd}'") process = subprocess.run(shlex.split(cmd), @@ -157,6 +219,11 @@ def scale_to_coprime(v): v : numpy.ndarray of shape (:) Vector to scale. + Returns + ------- + m : numpy.ndarray of shape (:) + Vector scaled to co-prime numbers. + """ MAX_DENOMINATOR = 1000000 @@ -371,9 +438,14 @@ def DREAM3D_base_group(fname): Parameters ---------- - fname : str + fname : str or pathlib.Path Filename of the DREAM.3D (HDF5) file. + Returns + ------- + path : str + Path to the base group. + """ with h5py.File(fname,'r') as f: base_group = f.visit(lambda path: path.rsplit('/',2)[0] if '_SIMPL_GEOMETRY/SPACING' in path else None) @@ -393,9 +465,14 @@ def DREAM3D_cell_data_group(fname): Parameters ---------- - fname : str + fname : str or pathlib.Path Filename of the DREAM.3D (HDF5) file. + Returns + ------- + path : str + Path to the cell data group. + """ base_group = DREAM3D_base_group(fname) with h5py.File(fname,'r') as f: