|
4 | 4 | //! |
5 | 5 | //! ## Creating a grid with `ndgrid` |
6 | 6 | //! |
7 | | -//! To explain the library we use the following example of a grid consisting of two triangles that together form the unit rectangle. |
8 | | -//! To that effect we introduce the following boundary vertices. |
| 7 | +//! To demonstrate the library, we use an example grid consisting of two triangles that together form the unit square. |
| 8 | +//! We introduce the following points. As we will make a grid of second oder elements, we include points at the midpoint |
| 9 | +//! of each edge as well as at the vertices of the square |
9 | 10 | //! - Point 0: (0, 0) |
10 | 11 | //! - Point 1: (1, 0) |
11 | 12 | //! - Point 2: (0, 1) |
12 | 13 | //! - Point 3: (1, 1) |
13 | | -//! |
14 | | -//! To make matters more interesting we will define a grid of second order elements. |
15 | | -//! This means that each edge of the triangle also has a middle point. The corresponding points are |
16 | | -//! given as follows: |
17 | | -//! |
18 | 14 | //! - Point 4: (0.5, 0.5) |
19 | 15 | //! - Point 5: (0.0, 0.5) |
20 | 16 | //! - Point 6: (0.5, 0.0) |
21 | 17 | //! - Point 7: (0.5, 1.0) |
22 | 18 | //! - Point 8: (1.0, 0.5) |
23 | 19 | //! |
24 | | -//! The order of points for each element is the same as the one on [defelement.org](https://defelement.org). |
| 20 | +//! The order of points for each cell follows the point ordering of the |
| 21 | +//! [Lagrange element on DefElement](https://defelement.org/elements/lagrange.html). |
25 | 22 | //! For second order triangles we use |
26 | 23 | //! [this ordering](https://defelement.org/elements/examples/triangle-lagrange-equispaced-2.html). |
| 24 | +//! Following this ordering, the two cells of our example grid are: |
27 | 25 | //! |
28 | | -//! `ndgrid` does an important distinction between points and topological vertices. The boundary points |
29 | | -//! of the triangle are called vertices and determine the connectivity relationship of this triangle with other |
30 | | -//! triangles. Topologically, the two triangles are defined through the points 0, 1, 2 for the first triangle |
31 | | -//! and 1, 3, 2 for the second triangle. However, the full cell definition is |
32 | 26 | //! - Cell 1: 0, 1, 2, 4, 5, 6 |
33 | 27 | //! - Cell 2: 1, 3, 2, 7, 4, 8 |
34 | 28 | //! |
35 | | -//! in terms of the points. |
36 | | -//! |
37 | | -//! Let us generate the corresponding data structures. |
38 | | -//! |
| 29 | +//! In order to create our grid using ndgrid, we first create a grid builder. |
39 | 30 | //! ``` |
40 | 31 | //! use ndgrid::traits::Builder; |
41 | 32 | //! use ndelement::types::ReferenceCellType; |
|
46 | 37 | //! (ReferenceCellType::Triangle, 2), |
47 | 38 | //! ); |
48 | 39 | //! ``` |
49 | | -//! The [SingleElementGridBuilder] is for grids that |
50 | | -//! only use a single element type. The first parameter is the geometric dimension. Here we choose 2, |
51 | | -//! meaning the grid lives in two-dimensionals pace. The next parameter is the number of points, 9 in this case, |
52 | | -//! and the third parameter is the number of cells, which is also 2 here. |
53 | | -//! The element type is [ReferenceCellType::Triangle](ndelement::types::ReferenceCellType::Triangle). |
54 | | -//! The order of the triangles is 2. |
55 | | -//! |
56 | | -//! We now add the definitions of the points and cells. |
| 40 | +//! |
| 41 | +//! The [SingleElementGridBuilder] is for grids that only use a single element type. The parameters passed when |
| 42 | +//! initialising the build are: |
| 43 | +//! |
| 44 | +//! - The geometric dimension: our example grid lives in two-dimensional space, so we use 2. |
| 45 | +//! - The number of points: 9 for our example grid. |
| 46 | +//! - The number of cells: 2 for our example grid. |
| 47 | +//! - The cell type and element degree: for our example, this is ([ReferenceCellType::Triangle](ndelement::types::ReferenceCellType::Triangle), 2) |
| 48 | +//! as our geometry cells are triangles and we use quadratic geometry for each triangle. |
| 49 | +//! |
| 50 | +//! If we did not know the number of points and cells that we will include in out grid when creating ths builder, |
| 51 | +//! we could instead use the function [SingleElementGridBuilder::new] when initialising the grid. |
| 52 | +//! |
| 53 | +//! Now that we have created a grid builder, we can add the points and cells: |
| 54 | +//! |
57 | 55 | //! ``` |
58 | 56 | //! # use ndgrid::traits::Builder; |
59 | 57 | //! # use ndelement::types::ReferenceCellType; |
|
73 | 71 | //! builder.add_point(7, &[0.5, 1.0]); |
74 | 72 | //! builder.add_point(8, &[1.0, 0.5]); |
75 | 73 | //! |
76 | | -//! builder.add_cell(0, &[0, 1, 2, 4, 5, 6]); |
77 | | -//! builder.add_cell(1, &[1, 3, 2, 7, 4, 8]); |
| 74 | +//! builder.add_cell(1, &[0, 1, 2, 4, 5, 6]); |
| 75 | +//! builder.add_cell(2, &[1, 3, 2, 7, 4, 8]); |
78 | 76 | //! ``` |
79 | 77 | //! Finally, we generate the grid. |
80 | 78 | //! ``` |
|
95 | 93 | //! # builder.add_point(6, &[0.5, 0.0]); |
96 | 94 | //! # builder.add_point(7, &[0.5, 1.0]); |
97 | 95 | //! # builder.add_point(8, &[1.0, 0.5]); |
98 | | -//! |
99 | | -//! # builder.add_cell(0, &[0, 1, 2, 4, 5, 6]); |
100 | | -//! # builder.add_cell(1, &[1, 3, 2, 7, 4, 8]); |
| 96 | +//! # |
| 97 | +//! # builder.add_cell(1, &[0, 1, 2, 4, 5, 6]); |
| 98 | +//! # builder.add_cell(2, &[1, 3, 2, 7, 4, 8]); |
101 | 99 | //! let grid = builder.create_grid(); |
102 | 100 | //! ``` |
| 101 | +//! |
103 | 102 | //! ## Querying the grid |
104 | 103 | //! |
105 | | -//! A grid is a hierarchy of entities. The highest dimension entities are the cells. Each cell consists of subentities, |
106 | | -//! which are faces, edges, etc. For each entity there are two types of information, the topology information and the |
107 | | -//! geometry information. The topology describes how entities are connected. The geometry describes how entities related |
108 | | -//! to their associated physical points. Each entity is associated with an `index`. Indices are unique within the class |
109 | | -//! of entities, that is there is a point with index 0 and a cell with index 0 but no two points with index 0. Points and |
110 | | -//! cells also have an associated `id`. `ids` are the indices provided by the user with the `add_point` or `add_cell` |
111 | | -//! methods in the grid builder. These ids will usually be different from the internal indices of entities. |
| 104 | +//! A grid is a hierarchy of entities. We follow the standard name conventions for entities of a given topological dimension: |
| 105 | +//! 0-, 1-, 2- and 3-dimensional entities and called vertices, edges, faces and volumes (respectively). |
| 106 | +//! The highest dimensional entities are called cells. If $d$ the (topological) dimension of the cells, |
| 107 | +//! then $d-1$-, $d-2$- and $d-3$-dimensional entities are called facets, ridges and peaks (respectively). |
| 108 | +//! |
| 109 | +//! For each entity there are two types of information: the topology and the geometry. |
| 110 | +//! The topology describes how entities are connected. The geometry describes how entities are positioned in physical space. |
| 111 | +//! As the topology is only concerned with the connectivity between entities, it only includes the cell's points that are at |
| 112 | +//! the vertices of a cell (eg for the triangle cells in our grid, the topology onle includes the first three points for each cell). |
| 113 | +//! In the geometry, all the points that define the cell are stored. |
112 | 114 | //! |
113 | | -//! The following code extracts all topological vertices for each cell and prints the corresponding physical coordinates. |
| 115 | +//! Each entity has an associated `index`. Indices are unique within entities of a given type: |
| 116 | +//! there is a vertex with index 0 and a cell with index 0 but there cannot be two vertices with index 0. Points and |
| 117 | +//! cells may also have an associated `id`: these are the values provided by the user when using the `add_point` or `add_cell` |
| 118 | +//! methods in the grid builder. These ids are not guaranteed to be equal to the indices of the entities. |
| 119 | +//! |
| 120 | +//! The following code extracts the vertices of each cell and prints their corresponding physical coordinates. |
114 | 121 | //! ``` |
115 | 122 | //! # use ndgrid::traits::Builder; |
| 123 | +//! use ndgrid::traits::{Grid, Entity, Topology, Geometry, Point}; |
116 | 124 | //! # use ndelement::types::ReferenceCellType; |
117 | 125 | //! # let mut builder = ndgrid::SingleElementGridBuilder::<f64>::new_with_capacity( |
118 | 126 | //! # 2, |
|
129 | 137 | //! # builder.add_point(6, &[0.5, 0.0]); |
130 | 138 | //! # builder.add_point(7, &[0.5, 1.0]); |
131 | 139 | //! # builder.add_point(8, &[1.0, 0.5]); |
132 | | -//! |
133 | | -//! # builder.add_cell(0, &[0, 1, 2, 4, 5, 6]); |
134 | | -//! # builder.add_cell(1, &[1, 3, 2, 7, 4, 8]); |
| 140 | +//! # |
| 141 | +//! # builder.add_cell(1, &[0, 1, 2, 4, 5, 6]); |
| 142 | +//! # builder.add_cell(2, &[1, 3, 2, 7, 4, 8]); |
135 | 143 | //! # let grid = builder.create_grid(); |
136 | | -//! use ndgrid::traits::{Grid, Entity, Topology, Geometry, Point}; |
| 144 | +//! |
137 | 145 | //! for cell in grid.entity_iter(ReferenceCellType::Triangle) { |
138 | 146 | //! for vertex in cell.topology().sub_entity_iter(ReferenceCellType::Point) { |
139 | 147 | //! let vertex = grid.entity(ReferenceCellType::Point, vertex).unwrap(); |
|
154 | 162 | //! } |
155 | 163 | //! } |
156 | 164 | //! ``` |
157 | | -//! Let us dissect what is going on here. First, we iteratre through the cells of the grid. |
158 | | -//! For this we use the [Grid::entity_iter](crate::traits::Grid::entity_iter) function. |
159 | | -//! For each cell we then access the topology information via [Entity::topology](crate::traits::Entity::topology) |
160 | | -//! and iterate through the point subentities via [Topology::sub_entity_iter](crate::traits::Topology::sub_entity_iter). |
161 | | -//! This gives us the vertices of the triangles. The topology information only considers the points that define the topology. |
162 | | -//! So the middle points on each edge which are necessary for the order of the triangle, are not returned. Also, the iterator |
163 | | -//! returns integer indices of entities. To convert an entity index to an actual entity use the |
164 | | -//! [Grid::entity](crate::traits::Grid::entity) function. We now want to get the actual physical coordinate of a vertex. |
165 | | -//! Since the geometric dimension is 2 we instantiate an array `[f64; 2]` for this. We now call on the vertex the |
166 | | -//! [Entity::geometry](crate::traits::Entity::geometry) function to obtain its geometry information. We then |
167 | | -//! call [Geometry::points](crate::traits::Geometry::points) to get an iterator to all physical points |
168 | | -//! associated with the vertex. Since a vertex only has one associated physical point (namely the vertex itself) we just |
169 | | -//! call `next` once on this iterator to get the actual point. Finally, we call [Point::coords](crate::traits::Point::coords) |
170 | | -//! to get the values of the physical coordinate. |
171 | | -//! |
172 | | -//! |
173 | | -//! |
174 | | -//! |
175 | | -//! |
176 | 165 | //! |
| 166 | +//! This snippets starts by using [Grid::entity_iter](crate::traits::Grid::entity_iter) to iterate through each |
| 167 | +//! cell (ie each entity that is a triangle). |
| 168 | +//! For each cell, we then access the topology information via [Entity::topology](crate::traits::Entity::topology) |
| 169 | +//! and iterate through the vertices (ie the subentities that are points) using [Topology::sub_entity_iter](crate::traits::Topology::sub_entity_iter). |
| 170 | +//! This iterators gives us the index of each vertex: to convert an entity index to an entity, we use [Grid::entity](crate::traits::Grid::entity). |
| 171 | +//! We now want to get the actual physical coordinate of a vertex. |
| 172 | +//! Since the geometric dimension is 2 we instantiate an array `[f64; 2]` for this. We use |
| 173 | +//! [Entity::geometry](crate::traits::Entity::geometry) to obtain the geometry for the vertex, then use |
| 174 | +//! [Geometry::points](crate::traits::Geometry::points) to get an iterator over the physical points |
| 175 | +//! associated with the vertex. Since a vertex has only one associated physical point, we |
| 176 | +//! call `next` once on this iterator to get the point. Finally, we call [Point::coords](crate::traits::Point::coords) |
| 177 | +//! to get the values of the physical coordinate. |
177 | 178 |
|
178 | 179 | #![cfg_attr(feature = "strict", deny(warnings), deny(unused_crate_dependencies))] |
179 | 180 | #![warn(missing_docs)] |
|
0 commit comments