From b0d3615d6798b31da3a9bf705629eb88ebbe6370 Mon Sep 17 00:00:00 2001 From: Martin Diehl Date: Tue, 3 Sep 2019 15:29:41 -0700 Subject: [PATCH] more detailed documentation --- python/damask/geom.py | 134 +++++++++++++++++++++++++++++++++++++++--- 1 file changed, 125 insertions(+), 9 deletions(-) diff --git a/python/damask/geom.py b/python/damask/geom.py index 7f9a9d33a..a4a1628c1 100644 --- a/python/damask/geom.py +++ b/python/damask/geom.py @@ -10,10 +10,27 @@ from . import version class Geom(): - """Geometry definition for grid solvers""" + """Geometry definition for grid solvers.""" def __init__(self,microstructure,size,origin=[0.0,0.0,0.0],homogenization=1,comments=[]): - """New geometry definition from array of microstructures and size""" + """ + New geometry definition from array of microstructures and size. + + Parameters + ---------- + microstructure : numpy.ndarray + microstructure array (3D) + size : list or numpy.ndarray + physical size of the microstructure in meter. + origin : list or numpy.ndarray, optional + physical origin of the microstructure in meter. + homogenization : integer, optional + homogenization index. + comments : list of str, optional + comments lines. + + """ + self.__transforms__ = \ self.set_microstructure(microstructure) self.set_size(size) self.set_origin(origin) @@ -22,7 +39,7 @@ class Geom(): def __repr__(self): - """Basic information on geometry definition""" + """Basic information on geometry definition.""" return util.srepr([ 'grid a b c: {}'.format(' x '.join(map(str,self.get_grid ()))), 'size x y z: {}'.format(' x '.join(map(str,self.get_size ()))), @@ -33,7 +50,21 @@ class Geom(): ]) def update(self,microstructure=None,size=None,origin=None,rescale=False): - """Updates microstructure and size""" + """ + Updates microstructure and size. + + Parameters + ---------- + microstructure : numpy.ndarray, optional + microstructure array (3D). + size : list or numpy.ndarray, optional + physical size of the microstructure in meter. + origin : list or numpy.ndarray, optional + physical origin of the microstructure in meter. + rescale : bool, optional + ignore size parameter and rescale according to change of grid points. + + """ grid_old = self.get_grid() size_old = self.get_size() origin_old = self.get_origin() @@ -77,13 +108,40 @@ class Geom(): return util.return_message(message) def set_comments(self,comments): + """ + Replaces all existing comments. + + Parameters + ---------- + comments : list of str + new comments. + + """ self.comments = [] self.add_comments(comments) def add_comments(self,comments): + """ + Appends comments to existing comments. + + Parameters + ---------- + comments : list of str + new comments. + + """ self.comments += [str(c) for c in comments] if isinstance(comments,list) else [str(comments)] def set_microstructure(self,microstructure): + """ + Replaces the existing microstructure representation. + + Parameters + ---------- + microstructure : numpy.ndarray + microstructure array (3D). + + """ if microstructure is not None: if len(microstructure.shape) != 3: raise ValueError('Invalid microstructure shape {}'.format(*microstructure.shape)) @@ -93,6 +151,15 @@ class Geom(): self.microstructure = np.copy(microstructure) def set_size(self,size): + """ + Replaces the existing size information. + + Parameters + ---------- + size : list or numpy.ndarray + physical size of the microstructure in meter. + + """ if size is None: grid = np.asarray(self.microstructure.shape) self.size = grid/np.max(grid) @@ -103,6 +170,15 @@ class Geom(): self.size = np.array(size) def set_origin(self,origin): + """ + Replaces the existing origin information. + + Parameters + ---------- + origin : list or numpy.ndarray + physical origin of the microstructure in meter + + """ if origin is not None: if len(origin) != 3: raise ValueError('Invalid origin {}'.format(*origin)) @@ -110,6 +186,15 @@ class Geom(): self.origin = np.array(origin) def set_homogenization(self,homogenization): + """ + Replaces the existing homogenization index. + + Parameters + ---------- + homogenization : integer + homogenization index + + """ if homogenization is not None: if not isinstance(homogenization,int) or homogenization < 1: raise TypeError('Invalid homogenization {}'.format(homogenization)) @@ -118,24 +203,31 @@ class Geom(): def get_microstructure(self): + """Return the microstructure representation.""" return np.copy(self.microstructure) def get_size(self): + """Return the physical size in meter.""" return np.copy(self.size) def get_origin(self): + """Return the origin in meter.""" return np.copy(self.origin) def get_grid(self): + """Return the grid discretization.""" return np.array(self.microstructure.shape) def get_homogenization(self): + """Return the homogenization index.""" return self.homogenization def get_comments(self): + """Return the comments.""" return self.comments[:] def get_header(self): + """Return the full header (grid, size, origin, homogenization, comments).""" header = ['{} header'.format(len(self.comments)+4)] + self.comments header.append('grid a {} b {} c {}'.format(*self.get_grid())) header.append('size x {} y {} z {}'.format(*self.get_size())) @@ -145,7 +237,15 @@ class Geom(): @classmethod def from_file(cls,fname): - """Reads a geom file""" + """ + Reads a geom file. + + Parameters + ---------- + fname : str or file handle + geometry file to read. + + """ with (open(fname) if isinstance(fname,str) else fname) as f: f.seek(0) header_length,keyword = f.readline().split()[:2] @@ -190,13 +290,21 @@ class Geom(): raise TypeError('Invalid file: expected {} entries,found {}'.format(grid.prod(),i)) microstructure = microstructure.reshape(grid,order='F') - if not np.any(np.mod(microstructure.flatten(),1) != 0.0): # no float present + if not np.any(np.mod(microstructure.flatten(),1) != 0.0): # no float present microstructure = microstructure.astype('int') return cls(microstructure.reshape(grid),size,origin,homogenization,comments) def to_file(self,fname): - """Writes to file""" + """ + Writes a geom file. + + Parameters + ---------- + fname : str or file handle + geometry file to write. + + """ header = self.get_header() grid = self.get_grid() format_string = '%{}i'.format(1+int(np.floor(np.log10(np.nanmax(self.microstructure))))) if self.microstructure.dtype == int \ @@ -208,7 +316,15 @@ class Geom(): def to_vtk(self,fname=None): - """Generates vtk file. If file name is given, stored in file otherwise returned as string""" + """ + Generates vtk file. + + Parameters + ---------- + fname : str, optional + vtk file to write. If no file is given, a string is returned. + + """ grid = self.get_grid() + np.ones(3,dtype=int) size = self.get_size() origin = self.get_origin() @@ -262,7 +378,7 @@ class Geom(): def show(self): - """Show raw content (as in file)""" + """Show raw content (as in file).""" f=StringIO() self.to_file(f) f.seek(0)