From 62e88edbe25511e56225a9f1add95144cf3f2743 Mon Sep 17 00:00:00 2001 From: Chang Yu Date: Tue, 19 Apr 2022 21:55:07 +0800 Subject: [PATCH] [Doc] [mesh] Update docstring for ti.Mesh (#4818) * add ti.mesh_local() docstring * add ti.mesh_patch_idx() docstring * add MeshElement.link() docstring * add MeshElement.place() docstring * add MeshElement.place() docstring * add docstring for MeshBuilder.build * add docstring for MeshElement.SOA/AOS * add docstring for ti.Mesh * [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com> --- python/taichi/lang/mesh.py | 71 +++++++++++++++++++++++++++++++++++--- python/taichi/lang/misc.py | 32 +++++++++++++++++ 2 files changed, 99 insertions(+), 4 deletions(-) diff --git a/python/taichi/lang/mesh.py b/python/taichi/lang/mesh.py index 43b9c6e6c58340..62a3154eb5556f 100644 --- a/python/taichi/lang/mesh.py +++ b/python/taichi/lang/mesh.py @@ -196,8 +196,12 @@ def _SOA(self, soa=True): # AOS/SOA def _AOS(self, aos=True): self.layout = Layout.AOS if aos else Layout.SOA - SOA = property(fget=_SOA) - AOS = property(fget=_AOS) + SOA = property(fset=_SOA) + """ Set `True` for SOA (structure of arrays) layout. + """ + AOS = property(fset=_AOS) + """ Set `True` for AOS (array of structures) layout. + """ def place( self, @@ -205,6 +209,20 @@ def place( reorder=False, needs_grad=False, ): + """Declares mesh attributes for the mesh element in current mesh builder. + + Args: + members (Dict[str, Union[PrimitiveType, VectorType, MatrixType]]): \ + names and types for element attributes. + reorder: True if reorders the internal memory for coalesced data access within mesh-for loop. + needs_grad: True if needs to record grad. + + Example:: + >>> vec3 = ti.types.vector(3, ti.f32) + >>> mesh = ti.TriMesh() + >>> mesh.faces.place({'area' : ti.f32}) # declares a mesh attribute `area` for each face element. + >>> mesh.verts.place({'pos' : vec3}, reorder=True) # declares a mesh attribute `pos` for each vertex element, and reorder it in memory. + """ self.builder.elements.add(self._type) for key, dtype in members.items(): if key in {'verts', 'edges', 'faces', 'cells'}: @@ -244,6 +262,16 @@ def build(self, mesh_instance, size, g2r_field): field_dict, g2r_field) def link(self, element): + """Explicitly declares the element-element connectivity for compiler to pre-generate relation data. + + Args: + element (MeshElement): mesh element in the same builder to represent the to-end of connectivity. + + Example:: + >>> mesh = ti.TriMesh() + >>> mesh.faces.link(mesh.verts) # declares F-V connectivity + >>> mesh.verts.link(mesh.verts) # declares V-V connectivity + """ assert isinstance(element, MeshElement) assert element.builder == self.builder self.builder.relations.add(tuple([self._type, element._type])) @@ -390,6 +418,17 @@ def __init__(self, topology): self.relations = set() def build(self, metadata: MeshMetadata): + """Build and instantiate mesh from model meta data + + Use the following external lib to generate meta data: + https://github.com/BillXu2000/meshtaichi_patcher + + Args: + metadata : model meta data. + + Returns: + The mesh instance class. + """ instance = MeshInstance(self) instance.fields = {} @@ -442,15 +481,33 @@ def build(self, metadata: MeshMetadata): # Mesh First Class class Mesh: + """The Mesh type class. + + ti.Mesh offers first-class support for triangular/tetrahedral meshes + and allows efficient computation on these irregular data structures, + only available for backends supporting `ti.extension.mesh`. + + Related to https://github.com/taichi-dev/taichi/issues/3608 + """ def __init__(self): pass @staticmethod def Tet(): + """Create a tetrahedron mesh (a set of vert/edge/face/cell elements, attributes, and connectivity) builder. + + Returns: + An instance of mesh builder. + """ return MeshBuilder(MeshTopology.Tetrahedron) @staticmethod def Tri(): + """Create a triangle mesh (a set of vert/edge/face elements, attributes, and connectivity) builder. + + Returns: + An instance of mesh builder. + """ return MeshBuilder(MeshTopology.Triangle) @staticmethod @@ -465,13 +522,19 @@ def generate_meta(data): def TriMesh(): - """Create a triangle mesh builder. + """Create a triangle mesh (a set of vert/edge/face elements, attributes, and connectivity) builder. + + Returns: + An instance of mesh builder. """ return Mesh.Tri() def TetMesh(): - """Create a tetrahedron mesh builder. + """Create a tetrahedron mesh (a set of vert/edge/face/cell elements, attributes, and connectivity) builder. + + Returns: + An instance of mesh builder. """ return Mesh.Tet() diff --git a/python/taichi/lang/misc.py b/python/taichi/lang/misc.py index 8cd84fea8bbb91..13438ddfd31b8d 100644 --- a/python/taichi/lang/misc.py +++ b/python/taichi/lang/misc.py @@ -492,6 +492,33 @@ def block_local(*args): def mesh_local(*args): + """Hints the compiler to cache the mesh attributes + and to enable the mesh BLS optimization, + only available for backends supporting `ti.extension.mesh` and to use with mesh-for loop. + + Related to https://github.com/taichi-dev/taichi/issues/3608 + + Args: + *args (List[Attribute]): A list of mesh attributes or fields accessed as attributes. + + Examples:: + + # instantiate model + mesh_builder = ti.Mesh.tri() + mesh_builder.verts.place({ + 'x' : ti.f32, + 'y' : ti.f32 + }) + model = mesh_builder.build(meta) + + @ti.kernel + def foo(): + # hint the compiler to cache mesh vertex attribute `x` and `y`. + ti.mesh_local(model.verts.x, model.verts.y) + for v0 in model.verts: # mesh-for loop + for v1 in v0.verts: + v0.x += v1.y + """ for a in args: for v in a._get_field_members(): get_runtime().prog.current_ast_builder().insert_snode_access_flag( @@ -626,6 +653,11 @@ def global_thread_idx(): def mesh_patch_idx(): + """Returns the internal mesh patch id of this running thread, + only available for backends supporting `ti.extension.mesh` and to use within mesh-for loop. + + Related to https://github.com/taichi-dev/taichi/issues/3608 + """ return impl.get_runtime().prog.current_ast_builder().insert_patch_idx_expr( )