Debian Codegraph @

include/deal.II/grid/grid_in.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 1999 - 2025 by the deal.II authors
5 //
6 // This file is part of the deal.II library.
7 //
8 // Part of the source code is dual licensed under Apache-2.0 WITH
9 // LLVM-exception OR LGPL-2.1-or-later. Detailed license information
10 // governing the source code and code contributions can be found in
11 // LICENSE.md and CONTRIBUTING.md at the top level directory of deal.II.
12 //
13 // ------------------------------------------------------------------------
14
15 #ifndef dealii_grid_in_h
16 #define dealii_grid_in_h
17
18
19 #include <deal.II/base/config.h>
20
21 #include <deal.II/base/exceptions.h>
22 #include <deal.II/base/observer_pointer.h>
23 #include <deal.II/base/point.h>
24
25 #include <deal.II/lac/vector.h>
26
27 #include <iostream>
28 #include <map>
29 #include <string>
30 #include <vector>
31
32 DEAL_II_NAMESPACE_OPEN
33
34 // Forward declarations
35 #ifndef DOXYGEN
36 template <int dim, int spacedim>
37 DEAL_II_CXX20_REQUIRES((concepts::is_valid_dim_spacedim<dim, spacedim>))
38 class Triangulation;
39 template <int dim>
40 struct CellData;
41 #endif
42
43 /**
44 * This class implements an input mechanism for mesh data. It allows to read a
45 * mesh structure into a Triangulation object. At present, UCD (unstructured
46 * cell data), DB Mesh, XDA, %Gmsh, Tecplot, UNV, VTK, ASSIMP, and Cubit
47 * are supported as input format for grid data. Any numerical data other than
48 * geometric (vertex locations) and topological (how vertices form cells,
49 * faces, and edges) information is ignored, but the readers for the various
50 * formats generally do read information that associates material ids or
51 * boundary ids to cells or faces (see
52 * @ref GlossMaterialId "this"
53 * and
54 * @ref GlossBoundaryIndicator "this"
55 * glossary entry for more information).
56 *
57 * In practice, the list of formats this class supports is of course limited.
58 * However, other people have written tools to convert mesh files from one
59 * format to another, and if you have a mesh you cannot read with the functions
60 * of this class, you may want to convert it into a format that is in fact
61 * supported. One of these tools you may want to look up is
62 * [meshio](https://github.com/nschloe/meshio).
63 * A separate tool that can convert tetrahedral to hexahedral mesges is tethex,
64 * available [here](https://github.com/martemyev/tethex).
65 *
66 * The mesh you read will form the coarsest level of a @p Triangulation
67 * object. As such, it must not contain hanging nodes or other forms of
68 * adaptive refinement, or strange things will happen if the mesh represented
69 * by the input file does in fact have them. This is due to the fact that most
70 * mesh description formats do not store neighborship information between
71 * cells, so the grid reading functions have to regenerate it. They do so by
72 * checking whether two cells have a common face. If there are hanging nodes
73 * in a triangulation, adjacent cells have no common (complete) face, so the
74 * grid reader concludes that the adjacent cells have no neighbors along these
75 * faces and must therefore be at the boundary. In effect, an internal crack
76 * of the domain is introduced this way. Since such cases are very hard to
77 * detect (how is GridIn supposed to decide whether a place where the faces of
78 * two small cells coincide with the face or a larger cell is in fact a
79 * hanging node associated with local refinement, or is indeed meant to be a
80 * crack in the domain?), the library does not make any attempt to catch such
81 * situations, and you will get a triangulation that probably does not do what
82 * you want. If your goal is to save and later read again a triangulation that
83 * has been adaptively refined, then this class is not your solution; rather
84 * take a look at the PersistentTriangulation class.
85 *
86 * To read grid data, the triangulation to be filled has to be empty.
87 * Upon calling the functions of this class, the input file may
88 * contain only lines in one dimension; lines and quads in two
89 * dimensions; and lines, quads, and hexes in three dimensions. All
90 * other cell types (e.g. triangles in two dimensions, triangles or
91 * tetrahedra in 3d) are rejected. (Here, the "dimension" refers to
92 * the dimensionality of the mesh; it may be embedded in a higher
93 * dimensional space, such as a mesh on the two-dimensional surface of
94 * the sphere embedded in 3d, or a 1d mesh that discretizes a line in
95 * 3d.) The result will be a triangulation that consists of the cells
96 * described in the input file, and to the degree possible with
97 * material indicators and boundary indicators correctly set as
98 * described in the input file.
99 *
100 * @note You can not expect vertex and cell numbers in the triangulation
101 * to match those in the input file. (This is already clear based on the
102 * fact that we number cells and vertices separately, whereas this is not
103 * the case for some input file formats; some formats also do not require
104 * consecutive numbering, or start numbering at indices other than zero.)
105 *
106 *
107 * <h3>Supported input formats</h3>
108 *
109 * At present, the following input formats are supported:
110 * <ul>
111 * <li> @p UCD (unstructured cell data) format: this format is used for grid
112 * input as well as data output. If there are data vectors in the input file,
113 * they are ignored, as we are only interested in the grid in this class. The
114 * UCD format requires the vertices to be in following ordering: in 2d
115 * @verbatim
116 * 3-----2
117 * | |
118 * | |
119 * | |
120 * 0-----1
121 * @endverbatim
122 * and in 3d
123 * @verbatim
124 * 7-------6 7-------6
125 * /| | / /|
126 * / | | / / |
127 * / | | / / |
128 * 3 | | 3-------2 |
129 * | 4-------5 | | 5
130 * | / / | | /
131 * | / / | | /
132 * |/ / | |/
133 * 0-------1 0-------1
134 * @endverbatim
135 * Note, that this ordering is different from the deal.II numbering scheme,
136 * see the Triangulation class. The exact description of the UCD format can
137 * be found in the AVS Explorer manual (see http://www.avs.com). The @p UCD
138 * format can be read by the read_ucd() function.
139 *
140 * <li> <tt>DB mesh</tt> format: this format is used by the @p BAMG mesh
141 * generator (see http://www-rocq.inria.fr/gamma/cdrom/www/bamg/eng.htm. The
142 * documentation of the format in the @p BAMG manual is very incomplete, so we
143 * don't actually parse many of the fields of the output since we don't know
144 * their meaning, but the data that is read is enough to build up the mesh as
145 * intended by the mesh generator. This format can be read by the
146 * read_dbmesh() function.
147 *
148 * <li> @p XDA format: this is a rather simple format used by the MGF code. We
149 * don't have an exact specification of the format, but the reader can read in
150 * several example files. If the reader does not grok your files, it should be
151 * fairly simple to extend it.
152 *
153 * <li> <tt>%Gmsh 1.0 mesh</tt> format: this format is used by the @p %Gmsh mesh
154 * generator (see http://gmsh.info/). The documentation in the @p %Gmsh
155 * manual explains how to generate meshes compatible with the deal.II library
156 * (i.e. quads rather than triangles). In order to use this format, %Gmsh has
157 * to output the file in the old format 1.0. This is done adding the line
158 * "Mesh.MshFileVersion = 1" to the input file.
159 *
160 * <li> <tt>%Gmsh 2.0 mesh</tt> format: this is a variant of the above format.
161 * The read_msh() function automatically determines whether an input file is
162 * version 1 or version 2.
163 *
164 * <li> <tt>Tecplot</tt> format: this format is used by @p TECPLOT and often
165 * serves as a basis for data exchange between different applications. Note,
166 * that currently only the ASCII format is supported, binary data cannot be
167 * read.
168 *
169 * <li> <tt>UNV</tt> format: this format is generated by the Salome mesh
170 * generator, see http://www.salome-platform.org/ . The sections of this format
171 * that the GridIn::read_unv function supports are (only) 2411, 2412 and 2467.
172 * A detailed description of all the sections of the UNV file can be found in
173 * the following links:
174 * <ul>
175 * <li> https://www.ceas3.uc.edu/sdrluff/
176 * <li> https://docs.plm.automation.siemens.com/tdoc/nx/12/nx_help#uid:xid1128419:index_advanced:xid1404601:xid1404604
177 * </ul>
178 *
179 * A Wikipedia page dedicated to Universal File Format is available here:
180 * https://en.wikipedia.org/wiki/Universal_File_Format
181 *
182 * Note that Salome, let's say in 2d, can only make a quad mesh on an object
183 * that has exactly 4 edges (or 4 pieces of the boundary). That means, that if
184 * you have a more complicated object and would like to mesh it with quads,
185 * you will need to decompose the object into >= 2 separate objects. Then 1)
186 * each of these separate objects is meshed, 2) the appropriate groups of
187 * cells and/or faces associated with each of these separate objects are
188 * created, 3) a compound mesh is built up, and 4) all numbers that might be
189 * associated with some of the internal faces of this compound mesh are
190 * removed.
191 *
192 * @note It is essential that __all__ the mesh groups in Salome have purely
193 * integer names for this function to work as expected. For reference, the
194 * user guide of [OpenFCST](http://www.openfcst.mece.ualberta.ca/index.html)
195 * (a project that uses deal.II) has a section on creating deal.II-compatible
196 * meshes on Salome.
197 *
198 * <li> <tt>VTK</tt> format: VTK Unstructured Grid Legacy file reader
199 * generator. The reader can handle only Unstructured Grid format of data at
200 * present for 2d & 3d geometries. The documentation for the general legacy
201 * vtk file, including Unstructured Grid format can be found here:
202 * http://www.cacr.caltech.edu/~slombey/asci/vtk/vtk_formats.simple.html
203 *
204 * The VTK format requires the vertices to be in following ordering: in 2d
205 * @verbatim
206 * 3-----2
207 * | |
208 * | |
209 * | |
210 * 0-----1
211 * @endverbatim
212 * and in 3d
213 * @verbatim
214 * 7-------6 7-------6
215 * /| | / /|
216 * / | | / / |
217 * / | | / / |
218 * 4 | | 4-------5 |
219 * | 3-------2 | | 2
220 * | / / | | /
221 * | / / | | /
222 * |/ / | |/
223 * 0-------1 0-------1
224 * @endverbatim
225 *
226 *
227 * <li> <tt>Cubit</tt> format: deal.II doesn't directly support importing from
228 * Cubit at this time. However, Cubit can export in UCD format using a simple
229 * plug-in, and the resulting UCD file can then be read by this class. The
230 * plug-in script can be found on the deal.II wiki page under
231 * <a href="https://github.com/dealii/dealii/wiki/Mesh-Input-And-Output">Mesh
232 * Input and Output</a>.
233 *
234 * Alternatively, Cubit can generate ABAQUS files that can be read in via the
235 * read_abaqus() function. This may be a better option for geometries with
236 * complex boundary condition surfaces and multiple materials - information
237 * which is currently not easily obtained through Cubit's python interface.
238 *
239 * </ul>
240 *
241 * <h3>Structure of input grid data.</h3>
242 *
243 * It is your duty to use a correct numbering of vertices in the cell list,
244 * i.e. for lines in 1d, you have to first give the vertex with the lower
245 * coordinate value, then that with the higher coordinate value. For
246 * quadrilaterals in two dimensions, the vertex indices in the @p quad list
247 * have to be such that the vertices are numbered in counter-clockwise sense.
248 *
249 * In two dimensions, another difficulty occurs, which has to do with the
250 * sense of a quadrilateral. A quad consists of four lines which have a
251 * direction, which is by definition as follows:
252 * @verbatim
253 * 3-->--2
254 * | |
255 * ^ ^
256 * | |
257 * 0-->--1
258 * @endverbatim
259 * Now, two adjacent cells must have a vertex numbering such that the
260 * direction of the common side is the same. For example, the following two
261 * quads
262 * @verbatim
263 * 3---4---5
264 * | | |
265 * 0---1---2
266 * @endverbatim
267 * may be characterised by the vertex numbers <tt>(0 1 4 3)</tt> and <tt>(1 2
268 * 5 4)</tt>, since the middle line would get the direction <tt>1->4</tt> when
269 * viewed from both cells. The numbering <tt>(0 1 4 3)</tt> and <tt>(5 4 1
270 * 2)</tt> would not be allowed, since the left quad would give the common
271 * line the direction <tt>1->4</tt>, while the right one would want to use
272 * <tt>4->1</tt>, leading to an ambiguity. The Triangulation object is capable
273 * of detecting this special case, which can be eliminated by rotating the
274 * indices of the right quad by two. However, it would not know what to do if
275 * you gave the vertex indices <tt>(4 1 2 5)</tt>, since then it would have to
276 * rotate by one element or three, the decision which to take is not yet
277 * implemented.
278 *
279 * There are more ambiguous cases, where the triangulation may not know what
280 * to do at all without the use of sophisticated algorithms. Furthermore,
281 * similar problems exist in three space dimensions, where faces and lines
282 * have orientations that need to be taken care of.
283 *
284 * For this reason, the <tt>read_*</tt> functions of this class that read in
285 * grids in various input formats call the GridTools::consistently_order_cells()
286 * function to bring the order of vertices that define the cells into an
287 * ordering that satisfies the requirements of the Triangulation class. Be sure
288 * to read the documentation of that class if you experience unexpected problems
289 * when reading grids through this class.
290 *
291 *
292 * <h3>Dealing with distorted mesh cells</h3>
293 *
294 * For each of the mesh reading functions, the last call is always to
295 * Triangulation::create_triangulation(). That function checks whether all the
296 * cells it creates as part of the coarse mesh are distorted or not (where
297 * distortion here means that the Jacobian of the mapping from the reference
298 * cell to the real cell has a non-positive determinant, i.e. the cell is
299 * pinched or twisted; see the entry on
300 * @ref GlossDistorted "distorted cells"
301 * in the glossary). If it finds any such cells, it throws an exception. This
302 * exception is not caught in the grid reader functions of the current class,
303 * and so will propagate through to the function that called it. There, you
304 * can catch and ignore the exception if you are certain that there is no harm
305 * in dealing with such cells. If you were not aware that your mesh had such
306 * cells, your results will likely be of dubious quality at best if you ignore
307 * the exception.
308 *
309 *
310 * @ingroup grid
311 * @ingroup input
312 */
313
314 template <int dim, int spacedim = dim>
315 class GridIn
316 {
317 public:
318 /**
319 * List of possible mesh input formats. These values are used when calling
320 * the function read() in order to determine the actual reader to be called.
321 */
322 enum Format
323 {
324 /// Use GridIn::default_format stored in this object
325 Default,
326 /// Use read_unv()
327 unv,
328 /// Use read_ucd()
329 ucd,
330 /// Use read_abaqus()
331 abaqus,
332 /// Use read_dbmesh()
333 dbmesh,
334 /// Use read_xda()
335 xda,
336 /// Use read_msh()
337 msh,
338 /// Use read_tecplot()
339 tecplot,
340 /// Use read_vtk()
341 vtk,
342 /// Use read_vtu()
343 vtu,
344 /// Use read_assimp()
345 assimp,
346 /// Use read_exodusii()
347 exodusii,
348 };
349
350 /**
351 * Constructor.
352 */
353 GridIn();
354
355 /**
356 * Constructor. Attach this triangulation to be fed with the grid data.
357 */
358 GridIn(Triangulation<dim, spacedim> &tria);
359
360 /**
361 * Attach this triangulation to be fed with the grid data.
362 */
363 void
364 attach_triangulation(Triangulation<dim, spacedim> &tria);
365
366 /**
367 * Read from the given stream. If no format is given,
368 * GridIn::Format::Default is used.
369 */
370 void
371 read(std::istream &in, Format format = Default);
372
373 /**
374 * Open the file given by the string and call the previous function
375 * read() taking a std::istream argument.
376 */
377 void
378 read(const std::string &in, Format format = Default);
379
380 /**
381 * Read grid data from a unstructured vtk file. The vtk file may contain
382 * the following VTK cell types: VTK_HEXAHEDRON (12), VTK_TETRA (10),
383 * VTK_QUAD (9), VTK_TRIANGLE (5), and VTK_LINE (3).
384 *
385 * Depending on the template dimension, only some of the above are accepted.
386 *
387 * In particular, in three dimensions, this function expects the file to
388 * contain
389 *
390 * - VTK_HEXAHEDRON/VTK_TETRA cell types
391 * - VTK_QUAD/VTK_TRIANGLE cell types, to specify optional boundary or
392 * interior quad faces
393 * - VTK_LINE cell types, to specify optional boundary or interior edges
394 *
395 * In two dimensions:
396 *
397 * - VTK_QUAD/VTK_TRIANGLE cell types
398 * - VTK_LINE cell types, to specify optional boundary or interior edges
399 *
400 * In one dimension
401 *
402 * - VTK_LINE cell types
403 *
404 * The input file may specify boundary ids, material ids, and manifold ids
405 * using the CELL_DATA section of the
406 * [VTK file format](http://www.vtk.org/VTK/img/file-formats.pdf).
407 *
408 * This function interprets two types of CELL_DATA contained in the input
409 * file: `SCALARS MaterialID`, used to specify the material_id of the cells,
410 * or the boundary_id of the faces and edges, and `SCALARS ManifoldID`, that
411 * can be used to specify the manifold id of any Triangulation object (cell,
412 * face, or edge).
413 *
414 * The companion GridOut::write_vtk function can be used to write VTK files
415 * compatible with this method.
416 *
417 * Also see
418 * @ref simplex "Simplex support".
419 */
420 void
421 read_vtk(std::istream &in);
422
423 /**
424 * Read grid data from a unstructured vtu file, saved by deal.II using
425 * GridOut::write_vtu(), with the flag
426 * GridOutFlags::Vtu::serialize_triangulation set to true.
427 *
428 * Notice that this function does not support reading in arbitrary vtu files,
429 * but only files that were written by deal.II itself, using the function
430 * GridOut::write_vtu and setting GridOutFlags::Vtu::serialize_triangulation
431 * to true.
432 *
433 * When this flag is set to true, the generated vtu file contains the
434 * triangulation in a xml section which is ignored by general vtu readers.
435 * If this section is absent, an exception is thrown.
436 */
437 void
438 read_vtu(std::istream &in);
439
440
441 /**
442 * Read grid data from an unv file as generated by the Salome mesh
443 * generator. Numerical data is ignored.
444 *
445 * Note the comments on generating this file format in the general
446 * documentation of this class.
447 */
448 void
449 read_unv(std::istream &in);
450
451 /**
452 * Read grid data from an ucd file. Numerical data is ignored.
453 * It is not possible to use a ucd file to set both boundary_id and
454 * manifold_id for the same cell. Yet it is possible to use
455 * the flag apply_all_indicators_to_manifolds to decide if
456 * the indicators in the file refer to manifolds (flag set to true)
457 * or boundaries (flag set to false). If the flag is set, the
458 * indicators are used for cells as manifold id, too.
459 */
460 void
461 read_ucd(std::istream &in,
462 const bool apply_all_indicators_to_manifolds = false);
463
464 /**
465 * Read grid data from an Abaqus file. Numerical and constitutive data is
466 * ignored. As in the case of the ucd file format, it is possible to use
467 * the flag apply_all_indicators_to_manifolds to decide if
468 * the indicators in the file refer to manifolds (flag set to true)
469 * or boundaries (flag set to false).
470 *
471 * @note The current implementation of this mesh reader is suboptimal, and
472 * may therefore be slow for large meshes.
473 *
474 * @note Usage tips for Cubit:
475 * - Multiple material-id's can be defined in the mesh.
476 * This is done by specifying blocksets in the pre-processor.
477 * - Arbitrary surface boundaries can be defined in the mesh.
478 * This is done by specifying sidesets in the pre-processor. In particular,
479 * boundaries are not confined to just surfaces (in 3d) individual element
480 * faces can be added to the sideset as well. This is useful when a boundary
481 * condition is to be applied on a complex shape boundary that is difficult
482 * to define using "surfaces" alone. Similar can be done in 2d.
483 *
484 * @note Compatibility information for this file format is listed below.
485 * - Files generated in Abaqus CAE 6.12 have been verified to be
486 * correctly imported, but older (or newer) versions of Abaqus may also
487 * generate valid input decks.
488 * - Files generated using Cubit 11.x, 12.x, 13.x, 14.x and 15.x are valid,
489 * but only when using a specific set of export steps. These are as follows:
490 * - Go to "Analysis setup mode" by clicking on the disc icon in the
491 * toolbar on the right.
492 * - Select "Export Mesh" under "Operation" by clicking on the
493 * necessary icon in the toolbar on the right.
494 * - Select an output file. In Cubit version 11.0 and 12.0 it might be
495 * necessary to click on the browse button and type it in the dialogue that
496 * pops up.
497 * - Select the dimension to output in.
498 * - Tick the overwrite box.
499 * - If using Cubit v12.0 onwards, uncheck the box "Export using Cubit
500 * ID's". An invalid file will encounter errors if this box is left checked.
501 * - Click apply.
502 */
503 void
504 read_abaqus(std::istream &in,
505 const bool apply_all_indicators_to_manifolds = false);
506
507 /**
508 * Read grid data from a file containing data in the DB mesh format.
509 */
510 void
511 read_dbmesh(std::istream &in);
512
513 /**
514 * Read grid data from a file containing data in the XDA format.
515 */
516 void
517 read_xda(std::istream &in);
518
519 /**
520 * Read grid data from an msh file. The %Gmsh formats are documented at
521 * http://www.gmsh.info/.
522 *
523 * Also see
524 * @ref simplex "Simplex support".
525 */
526 void
527 read_msh(std::istream &in);
528
529 #ifdef DEAL_II_GMSH_WITH_API
530 /**
531 * Read grid data using Gmsh API. Any file supported by Gmsh can be passed as
532 * argument. The format is deduced from the filename extension.
533 *
534 * This function interprets non-named physical ids (gmsh format < 4.0) as
535 * material or boundary ids (similarly to what happens with the other
536 * read_msh() function). If you want to specify non default manifold or
537 * boundary ids, you must group all entities that require a non default
538 * boundary or manifold id into named physical groups, where the name is
539 * interpreted using the function Patterns::Tools::to_value() applied to a
540 * `std::map<std::string, int>`. The keys can be either `MaterialID` (if the
541 * physical group refers to object of dimension `dim`), `BoundaryID` (if the
542 * group refers to objects of dimension < `dim`), or `ManifoldID`.
543 *
544 * From the Gmsh documentation, the formats of the physical tags follows the
545 * following conventions:
546 * @code
547 * \$PhysicalNames // same as MSH version 2
548 * numPhysicalNames(ASCII int)
549 * dimension(ASCII int) physicalTag(ASCII int) "name"(127 characters max)
550 * ...
551 * \$EndPhysicalNames
552 * @endcode
553 *
554 * For example, the following snippet of mesh file
555 * @code
556 * MeshFormat
557 * 4.1 0 8
558 * \$EndMeshFormat
559 * \$PhysicalNames
560 * 4
561 * 1 1 "ManifoldID:0"
562 * 1 2 "BoundaryID: -1, ManifoldID: 1"
563 * 2 3 "ManifoldID: 1"
564 * 2 4 "MaterialID: 2, ManifoldID: 1"
565 * \$EndPhysicalNames
566 * \$Entities
567 * ...
568 * @endcode
569 *
570 * refers to a two dimensional grid where:
571 * - a portion of the boundary of dimension 1 has physical tag 1, and manifold
572 * id 0
573 * - some internal faces (lines of dimension 1) have manifold id 1
574 * - some elements have manifold id 1 (and material id equal to the default
575 * value, i.e., zero)
576 * - some elements have manifold id 1 and material id equal to 2
577 *
578 * If the physical groups are not named, then the behavior is the same as
579 * the other read_msh() function, i.e., the physical tag itself is interpreted
580 * as a boundary or material id. Physical surface numbers created in Gmsh,
581 * which can be seen in the .geo file, become material IDs.
582 *
583 *
584 * Also see
585 * @ref simplex "Simplex support".
586 */
587 void
588 read_msh(const std::string &filename);
589 #endif
590
591 /**
592 * Read grid data from a `.mphtxt` file. `.mphtxt` is one of the file formats
593 * typically generated by COMSOL. The file format is described at
594 * http://victorsndvg.github.io/FEconv/formats/mphtxt.xhtml .
595 *
596 * The reader interprets the "geometric entity indicators" that COMSOL
597 * writes into these files as either boundary indicators (for edges and faces
598 * of cells) or as material ids (for cells). See the glossary for a
599 * description of
600 * @ref GlossBoundaryIndicator "boundary indicators".
601 * and
602 * @ref GlossMaterialId "material indicators"
603 *
604 * COMSOL has a habit of assigning "geometric entity indicators" not only
605 * to edges and faces on the actual boundary, but also to interior faces
606 * and edges. For example, for the following volume mesh generated by
607 * COMSOL,
608 * @image html "comsol-mesh-boundary-volume-mesh.png"
609 * the marked edges and faces are as follows:
610 * @image html "comsol-mesh-marked-lines.png"
611 * @image html "comsol-mesh-marked-triangles.png"
612 * Here, some of the marked lines and faces with explicitly given
613 * geometric entity indicators are in the *interior* of the domain -- an
614 * artifact of the geometry description that was used to describe
615 * the mesh. However, we can of course not assign boundary indicators to
616 * interior edges and faces. As a consequence, this reader function simply
617 * ignores the geometric entity indicator for edges and faces that
618 * are not in fact on the boundary of the domain. The result is then a mesh
619 * in which only the following edges and faces are explicitly assigned
620 * boundary indicators:
621 * @image html "comsol-mesh-boundary-lines.png"
622 * @image html "comsol-mesh-boundary-triangles.png"
623 *
624 * Also see
625 * @ref simplex "Simplex support".
626 */
627 void
628 read_comsol_mphtxt(std::istream &in);
629
630 /**
631 * Read grid data from a file containing tecplot ASCII data. This also works
632 * in the absence of any tecplot installation.
633 */
634 void
635 read_tecplot(std::istream &in);
636
637 /**
638 * Read in a file supported by Assimp, and generate a Triangulation
639 * out of it. If you specify a @p mesh_index, only the mesh with
640 * the given index will be extracted, otherwise all meshes which are
641 * present in the file will be used to generate the Triangulation.
642 *
643 * This function can only be used to read two-dimensional meshes (possibly
644 * embedded in three dimensions). This is the standard for graphical software
645 * such as blender, or 3d studio max, and that is what the original Assimp
646 * library was built for. We "bend" it to deal.II to support complex
647 * co-dimension one meshes and complex two-dimensional meshes.
648 *
649 * If @p remove_duplicates is set to true (the default), then
650 * duplicated vertices will be removed if their distance is lower
651 * than @p tol.
652 *
653 * Only the elements compatible with the given dimension and space dimension
654 * will be extracted from the mesh, and only those elements that are
655 * compatible with deal.II are supported. If you set
656 * `ignore_unsupported_element_types`, all the other element types are simply
657 * ignored by this algorithm. If your mesh contains a mixture of triangles
658 * and quadrilaterals, for example, only the quadrilaterals will be
659 * extracted. The resulting mesh (as represented in the Triangulation object)
660 * may not make any sense if you are mixing compatible and incompatible
661 * element types. If `ignore_unsupported_element_types` is set to `false`,
662 * then an exception is thrown when an unsupported type is encountered.
663 *
664 * @param filename The file to read from
665 * @param mesh_index Index of the mesh within the file
666 * @param remove_duplicates Remove duplicated vertices
667 * @param tol Tolerance to use when removing vertices
668 * @param ignore_unsupported_element_types Don't throw exceptions if we
669 * encounter unsupported types during parsing
670 */
671 void
672 read_assimp(const std::string &filename,
673 const unsigned int mesh_index = numbers::invalid_unsigned_int,
674 const bool remove_duplicates = true,
675 const double tol = 1e-12,
676 const bool ignore_unsupported_element_types = true);
677
678 /**
679 * A structure containing some of the information provided by ExodusII that
680 * doesn't have a direct representation in the Triangulation object.
681 *
682 * @note This struct exists to enable forward compatibility with future
683 * versions of read_exodusii that may provide additional output data, but for
684 * now it has a single field.
685 */
686 struct ExodusIIData
687 {
688 /**
689 * A vector containing a mapping from deal.II boundary ids (or manifold ids)
690 * to the provided ExodusII sideset ids.
691 */
692 std::vector<std::vector<int>> id_to_sideset_ids;
693 };
694
695 /**
696 * Read in a mesh stored in the ExodusII file format.
697 *
698 * ExodusII is a feature-rich file format that supports many more features
699 * (like node sets, finite element fields, quality assurance data, and more)
700 * than most other grid formats supported by this class. Many of these
701 * features do not have equivalent representations in deal.II and are
702 * therefore not supported (for example, deal.II does not assign degrees of
703 * freedom directly to nodes, so data stored in a nodal format is not loaded
704 * by this function). At the current time only the following information is
705 * extracted from the input file:
706 *
707 * <ol>
708 * <li>Block ids: the block id of an element is loaded as its material
709 * id.</li>
710 * <li>Elements and vertices: the core geometric information stored in the
711 * ExodusII file populates the attached Triangulation object. Higher-order
712 * elements are automatically truncated to lower-order elements since
713 * deal.II does not support this feature (e.g., there is no equivalent to
714 * the <code>QUAD9</code> element in deal.II since all quadrilaterals have
715 * four vertices and additional geometric information is either stored in
716 * a Manifold or something like MappingQEulerian).</li>
717 * <li>Sideset ids: these are interpreted as boundary ids or manifold ids
718 * (see the note on the output value below). An error will occur if you
719 * attempt to read an ExodusII file that assigns a sideset id to an
720 * internal face boundary id.</li>
721 * </ol>
722 *
723 * Sideset ids are not translated for Triangulations with nonzero codimension
724 * since those Triangulations do not support the setting of boundary ids.
725 *
726 * @param filename The name of the file to read from.
727 *
728 * @param apply_all_indicators_to_manifolds Boolean determining if the sideset
729 * ids should be interpreted as manifold ids or boundary ids. The default
730 * value is <tt>false</tt>, i.e., treat all sideset ids as boundary ids. If
731 * your mesh sets sideset ids on internal faces then it will be necessary to
732 * set this argument to <code>true</code> and then do some postprocessing to
733 * set the boundary ids correctly.
734 *
735 * @return This function returns a struct containing some extra data stored by
736 * the ExodusII file that cannot be loaded into a Triangulation - see
737 * ExodusIIData for more information.
738 *
739 * A cell face in ExodusII can be in an arbitrary number of sidesets (i.e., it
740 * can have an arbitrary number of sideset ids) - however, a boundary cell
741 * face in deal.II has exactly one boundary id. All boundary faces that are
742 * not in a sideset are given the (default) boundary id of $0$. This function
743 * then groups sidesets together into unique sets and gives each one a
744 * boundary id. For example: Consider a single-quadrilateral mesh whose left
745 * side has no sideset id, right side has sideset ids $0$ and $1$, and whose
746 * bottom and top sides have sideset ids of $0$. The left face will have a
747 * boundary id of $0$, the top and bottom faces boundary ids of $1$, and the
748 * right face a boundary id of $2$. Hence the vector returned by this function
749 * in that case will be $\{\{\}, \{0\}, \{0, 1\}\}$.
750 */
751 ExodusIIData
752 read_exodusii(const std::string &filename,
753 const bool apply_all_indicators_to_manifolds = false);
754
755 /**
756 * Return the standard suffix for a file in this format.
757 */
758 static std::string
759 default_suffix(const Format format);
760
761 /**
762 * Return the enum Format for the format name.
763 */
764 static Format
765 parse_format(const std::string &format_name);
766
767 /**
768 * Return a list of implemented input formats. The different names are
769 * separated by vertical bar signs (<tt>`|'</tt>) as used by the
770 * ParameterHandler classes.
771 */
772 static std::string
773 get_format_names();
774
775 /**
776 * Return a map containing cell data associated with the elements of an
777 * external vtk format mesh imported using read_vtk().
778 * The format of the returned map is as
779 * follows:
780 * - std::string stores the name of the field data (identifier) as specified
781 * in the external mesh
782 * - Vector<double> stores value for the given identifier in each cell.
783 * To access the value, use cell_data[name_field][cell->active_cell_index()].
784 *
785 * For example, if the vtk mesh contains field data "Density" defined on
786 * cells, then `cell_data["Density"][0]` provides the density defined at cell
787 * ID '0', which corresponds to index 0 of the vector. The length of the
788 * vector in `cell_data["Density"]` equals the number of elements in the
789 * coarse mesh.
790 */
791 const std::map<std::string, Vector<double>> &
792 get_cell_data() const;
793
794 /**
795 * Exception
796 */
797 DeclException1(ExcUnknownSectionType,
798 int,
799 << "The section type <" << arg1 << "> in an UNV "
800 << "input file is not implemented.");
801
802 /**
803 * Exception
804 */
805 DeclException1(ExcUnknownElementType,
806 int,
807 << "The element type <" << arg1 << "> in an UNV "
808 << "input file is not implemented.");
809
810 /**
811 * Exception
812 */
813 DeclException1(ExcUnknownIdentifier,
814 std::string,
815 << "The identifier <" << arg1 << "> as name of a "
816 << "part in an UCD input file is unknown or the "
817 << "respective input routine is not implemented."
818 << "(Maybe the space dimension of triangulation and "
819 << "input file do not match?");
820 /**
821 * Exception
822 */
823 DeclExceptionMsg(ExcNoTriangulationSelected,
824 "No Triangulation has been attached to this GridIn object "
825 "so that nothing can be filled during any read function "
826 "calls. Please pass a reference to the Triangulation tria "
827 "to be filled in the constructor GridIn(tria) or attach "
828 "it with the function call GridIn::attach_triangulation().");
829 /**
830 * Exception
831 */
832 DeclException2(
833 ExcInvalidVertexIndex,
834 int,
835 int,
836 << "While creating cell " << arg1
837 << ", you are referencing a vertex with index " << arg2
838 << " but no vertex with this index has been described in the input file.");
839 /**
840 * Exception
841 */
842 DeclException3(
843 ExcInvalidVertexIndexGmsh,
844 int,
845 int,
846 int,
847 << "While creating cell " << arg1 << " (which is numbered as " << arg2
848 << " in the input file), you are referencing a vertex with index " << arg3
849 << " but no vertex with this index has been described in the input file.");
850 /**
851 * Exception
852 */
853 DeclException0(ExcInvalidDBMeshFormat);
854 /**
855 * Exception
856 */
857 DeclException1(ExcInvalidDBMESHInput,
858 std::string,
859 << "The string <" << arg1
860 << "> is not recognized at the present"
861 << " position of a DB Mesh file.");
862
863 /**
864 * Exception
865 */
866 DeclException1(
867 ExcDBMESHWrongDimension,
868 int,
869 << "The specified dimension " << arg1
870 << " is not the same as that of the triangulation to be created.");
871
872 DeclException1(ExcInvalidGMSHInput,
873 std::string,
874 << "The string <" << arg1
875 << "> is not recognized at the present"
876 << " position of a Gmsh Mesh file.");
877
878 DeclException1(ExcGmshUnsupportedGeometry,
879 int,
880 << "The Element Identifier <" << arg1 << "> is not "
881 << "supported in the deal.II library when "
882 << "reading meshes in " << dim << " dimensions.\n"
883 << "Supported elements are: \n"
884 << "ELM-TYPE\n"
885 << "1 Line (2 nodes, 1 edge).\n"
886 << "2 Triangle (3 nodes, 3 edges).\n"
887 << "3 Quadrilateral (4 nodes, 4 edges).\n"
888 << "4 Tetrahedron (4 nodes, 6 edges, 4 faces) when in 3d.\n"
889 << "5 Hexahedron (8 nodes, 12 edges, 6 faces) when in 3d.\n"
890 << "15 Point (1 node, ignored when read).");
891
892
893 DeclException2(
894 ExcGmshNoCellInformation,
895 unsigned int,
896 unsigned int,
897 "While reading a gmsh file, the reader function did not find "
898 "any cells. This sometimes happens if the file only contains a "
899 "surface mesh, but not a volume mesh."
900 "\n\n"
901 "The reader function did find " +
902 std::to_string(arg1) + " lines and " + std::to_string(arg2) +
903 " facets (surface triangles or quadrilaterals).");
904
905 protected:
906 /**
907 * Store address of the triangulation to be fed with the data read in.
908 */
909 ObserverPointer<Triangulation<dim, spacedim>, GridIn<dim, spacedim>> tria;
910
911 /**
912 * This function can write the raw cell data objects created by the
913 * <tt>read_*</tt> functions in Gnuplot format to a stream. This is
914 * sometimes handy if one would like to see what actually was created, if it
915 * is known that the data is not correct in some way, but the Triangulation
916 * class refuses to generate a triangulation because of these errors. In
917 * particular, the output of this class writes out the cell numbers along
918 * with the direction of the faces of each cell. In particular the latter
919 * information is needed to verify whether the cell data objects follow the
920 * requirements of the ordering of cells and their faces, i.e. that all
921 * faces need to have unique directions and specified orientations with
922 * respect to neighboring cells (see the documentations to this class and
923 * the GridTools::consistently_order_cells() function).
924 *
925 * The output of this function consists of vectors for each line bounding
926 * the cells indicating the direction it has with respect to the orientation
927 * of this cell, and the cell number. The whole output is in a form such
928 * that it can be read in by Gnuplot and generate the full plot without
929 * further ado by the user.
930 */
931 static void
932 debug_output_grid(const std::vector<CellData<dim>> &cells,
933 const std::vector<Point<spacedim>> &vertices,
934 std::ostream &out);
935
936 private:
937 /**
938 * Skip empty lines in the input stream, i.e. lines that contain either
939 * nothing or only whitespace.
940 */
941 static void
942 skip_empty_lines(std::istream &in);
943
944 /**
945 * Skip lines of comment that start with the indicated character (e.g.
946 * <tt>#</tt>) following the point where the given input stream presently
947 * is. After the call to this function, the stream is at the start of the
948 * first line after the comment lines, or at the same position as before if
949 * there were no lines of comments.
950 */
951 static void
952 skip_comment_lines(std::istream &in, const char comment_start);
953
954 /**
955 * This function does the nasty work (due to very lax conventions and
956 * different versions of the tecplot format) of extracting the important
957 * parameters from a tecplot header, contained in the string @p header. The
958 * other variables are output variables, their value has no influence on the
959 * function execution..
960 */
961 static void
962 parse_tecplot_header(std::string &header,
963 std::vector<unsigned int> &tecplot2deal,
964 unsigned int &n_vars,
965 unsigned int &n_vertices,
966 unsigned int &n_cells,
967 std::vector<unsigned int> &IJK,
968 bool &structured,
969 bool &blocked);
970
971 /**
972 * Input format used by read() if no format is given.
973 */
974 Format default_format;
975
976 /**
977 * Data member that stores field data defined at the cells of the mesh.
978 * The format is as follows:
979 * - std::string stores the name of the field data (identifier) as specified
980 * in the external mesh
981 * - Vector<double> stores value for the given identifier in each cell id.
982 *
983 * To access the value use cell_data[name_field][cell->active_cell_index()].
984 */
985 std::map<std::string, Vector<double>> cell_data;
986 };
987
988 /* -------------- declaration of explicit specializations ------------- */
989
990 #ifndef DOXYGEN
991
992 template <>
993 void
994 GridIn<2>::debug_output_grid(const std::vector<CellData<2>> &cells,
995 const std::vector<Point<2>> &vertices,
996 std::ostream &out);
997
998
999 template <>
1000 void
1001 GridIn<2, 3>::debug_output_grid(const std::vector<CellData<2>> &cells,
1002 const std::vector<Point<3>> &vertices,
1003 std::ostream &out);
1004 template <>
1005 void
1006 GridIn<3>::debug_output_grid(const std::vector<CellData<3>> &cells,
1007 const std::vector<Point<3>> &vertices,
1008 std::ostream &out);
1009 #endif // DOXYGEN
1010
1011 DEAL_II_NAMESPACE_CLOSE
1012
1013 #endif