Note

Go to the end to download the full example code.

Mesh size modes

In this example we explore ways to control the mesh size.

Initializing the Builder

Below, we initialize a new instance of qtcad.builder.Builder and define a couple of simple shapes we are going to use in the following.

from qtcad.builder import Builder, Polygon, Mask, Circle, MeshAlgorithm3D

box = Polygon.box(10, 10).centered()
partially_overlapping = box.translated(6, 0).auto_name()
circle = Circle(radius=2.5).translated(-2, 0)

mask = Mask("shapes", shapes=[box, partially_overlapping, circle])

[15:24:51] INFO     Auto-named Polygon instance to 'box'               masks.py:231
           INFO     Auto-named Polygon instance to                     masks.py:231
                    'partially_overlapping'
           INFO     Auto-named Circle instance to 'circle'             masks.py:231

Next, we define a function that we will use to create the same geometry, but with different mesh size modes.

The geometry consists of two boxes that are partially overlapping and a cylinder completely inside the first box. The cylinder has the finest mesh size, the left box has a medium mesh size, and the right box has the coarsest mesh size.

We use qtcad.builder.Builder.set_mesh_size to set the mesh size for the subsequent extrusions. We also use qtcad.builder.Builder.overlay_mode to be able to easily identify overlapping regions of the geometry later on.

Builder.set_mesh_size(size: float) → Self

[🔧 Modifier] Set the local mesh size for elements added after this point in units set by the length_unit_exponent (see Builder). Note that the mesh size may be chosen smaller due to set_min_elements.

Parameters:

size – The new mesh characteristic length.

def make_geometry(gen: Builder):
    """
    Create a geometry with two boxes that are partially overlapping and a cylinder
    completely inside the first box.

    The cylinder has the finest mesh size, the left box has a medium mesh size, and
    the right box has the coarsest mesh size.
    """
    return (
        gen.add_mask(mask)
        .overlay_mode()
        .use_shape("box")
        .set_mesh_size(1)
        .extrude(10)
        .use_shape("partially_overlapping")
        .set_z(0)
        .set_mesh_size(20)
        .extrude(10)
        .set_z(4)
        .use_shape("circle")
        .set_mesh_size(0.1)
        .extrude(2)
        .mesh(algorithm3d=MeshAlgorithm3D.HXT, check_connectivity=False)
    )

Overriding the mesh size (default)

In override mode, each newly created volume will use the mesh size previously set with qtcad.builder.Builder.set_mesh_size, irrespective of the current fragmentation mode (see Extrusion and fragmentation modes). This is particularly useful when defining regions of finer mesh size using qtcad.builder.Builder.fill_mode.

Builder.override_mesh_size() → Self

[🔧 Modifier] For all subsequently generated entities, use the mesh size set with set_mesh_size and override the mesh size in the intersections with the existing geometry.

builder = Builder().override_mesh_size()
make_geometry(builder).view(
    volume_labels=True,
    save="figs/mesh_override.png",  # caption: The whole mesh.;
)
mesh sizes

Fig. 9 The whole mesh.

           INFO     Selected shapes: [Polygon 0 'box']               builder.py:854
           INFO     Extruding shape 0 from mask 'shapes' with name  builder.py:2794
                    'box' by 10 at z=0
           INFO     Creating new physical group with name           builder.py:2580
                    'box_bottom'
           INFO     Creating new physical group with name           builder.py:2580
                    'box_side'
           INFO     Creating new physical group with name 'box_top' builder.py:2580
           INFO     Creating new physical group with name           builder.py:2580
                    'box_hull'
           INFO     Creating new physical group with name 'box'     builder.py:2580
           INFO     Setting z-coordinate to 10                       builder.py:903
           INFO     Selected shapes: [Polygon 1                      builder.py:854
                    'partially_overlapping']
           INFO     Setting z-coordinate to 0                        builder.py:903
           INFO     Extruding shape 1 from mask 'shapes' with name  builder.py:2794
                    'partially_overlapping' by 10 at z=0
           INFO     Creating new physical group with name           builder.py:2580
                    'partially_overlapping_bottom'
           INFO     Creating new physical group with name           builder.py:2580
                    'partially_overlapping_side'
           INFO     Creating new physical group with name           builder.py:2580
                    'partially_overlapping_top'
           INFO     Creating new physical group with name           builder.py:2580
                    'partially_overlapping_hull'
           INFO     Fragmenting...                                fragmenter.py:218
           INFO     Creating new physical group with name           builder.py:2580
                    'box.partially_overlapping_side'
           INFO     Creating new physical group with name           builder.py:2580
                    'box_side.partially_overlapping_side'
           INFO     Creating new physical group with name           builder.py:2580
                    'box.partially_overlapping'
           INFO     Creating new physical group with name           builder.py:2580
                    'box_side.partially_overlapping'
           INFO     Creating new physical group with name           builder.py:2580
                    'box_top.partially_overlapping_top'
           INFO     Creating new physical group with name           builder.py:2580
                    'box_bottom.partially_overlapping_bottom'
           INFO     Creating new physical group with name           builder.py:2580
                    'partially_overlapping'
           INFO     Setting z-coordinate to 10                       builder.py:903
           INFO     Setting z-coordinate to 4                        builder.py:903
           INFO     Selected shapes: [Circle 2 'circle']             builder.py:854
           INFO     Extruding shape 2 from mask 'shapes' with name  builder.py:2794
                    'circle' by 2 at z=4
           INFO     Creating new physical group with name           builder.py:2580
                    'circle_bottom'
           INFO     Creating new physical group with name           builder.py:2580
                    'circle_side'
           INFO     Creating new physical group with name           builder.py:2580
                    'circle_top'
           INFO     Creating new physical group with name           builder.py:2580
                    'circle_hull'
           INFO     Fragmenting...                                fragmenter.py:218
           INFO     Creating new physical group with name           builder.py:2580
                    'box.circle_top'
           INFO     Creating new physical group with name           builder.py:2580
                    'box.circle_side'
           INFO     Creating new physical group with name           builder.py:2580
                    'box.circle'
           INFO     Creating new physical group with name           builder.py:2580
                    'box.circle_bottom'
           INFO     Setting z-coordinate to 6                        builder.py:903
           INFO     Preparing to mesh                               builder.py:1561
           INFO     Detecting appropriate random factor             builder.py:3681
           INFO     Increased random factor from                    builder.py:3699
                    1.4802974253785605e-08 to 4.425455132591868e-07
[15:24:52] INFO     Random factor is now appropriate                builder.py:3705
           INFO     Meshing                                         builder.py:1577
[15:25:10] INFO     Saving figure                                   builder.py:1926

<qtcad.builder.builder.Builder object at 0x75dd41c3c550>

We see that the right “partially_overlapping” uses the coarse mesh size of the right box, as does the “circle volume”. If we view those two volumes in isolation, this becomes clear:

builder.view(
    groups=["box.partially_overlapping", "box.circle"],
    save="figs/mesh_override_partially_overlapping.png",  # caption: The overlapping parts of the geometry retain their smaller mesh size.;
    angles=(-10, 0, 90),
    volume_labels=True,
)
mesh sizes

Fig. 10 The overlapping parts of the geometry retain their smaller mesh size.

[15:25:11] INFO     Saving figure                                   builder.py:1926

<qtcad.builder.builder.Builder object at 0x75dd41c3c550>

Inheriting the mesh size

On the other hand, in inherit mode, newly created volumes will inherit the mesh size of the volume they intersect with.

Builder.inherit_mesh_size() → Self

[🔧 Modifier] For all subsequently generated entities, inherit the mesh size of the existing intersecting entity of the same dimension with the smallest mesh size. If there are no intersecting elements, the mesh size set with set_mesh_size is used.

builder = Builder().inherit_mesh_size()
make_geometry(builder).view(
    volume_labels=True,
    save="figs/mesh_inherit.png",  # caption: The whole mesh.;
)
mesh sizes

Fig. 11 The whole mesh.

[15:25:12] INFO     Selected shapes: [Polygon 0 'box']               builder.py:854
           INFO     Extruding shape 0 from mask 'shapes' with name  builder.py:2794
                    'box' by 10 at z=0
           INFO     Creating new physical group with name           builder.py:2580
                    'box_bottom'
           INFO     Creating new physical group with name           builder.py:2580
                    'box_side'
           INFO     Creating new physical group with name 'box_top' builder.py:2580
           INFO     Creating new physical group with name           builder.py:2580
                    'box_hull'
           INFO     Creating new physical group with name 'box'     builder.py:2580
           INFO     Setting z-coordinate to 10                       builder.py:903
           INFO     Selected shapes: [Polygon 1                      builder.py:854
                    'partially_overlapping']
           INFO     Setting z-coordinate to 0                        builder.py:903
           INFO     Extruding shape 1 from mask 'shapes' with name  builder.py:2794
                    'partially_overlapping' by 10 at z=0
           INFO     Creating new physical group with name           builder.py:2580
                    'partially_overlapping_bottom'
           INFO     Creating new physical group with name           builder.py:2580
                    'partially_overlapping_side'
           INFO     Creating new physical group with name           builder.py:2580
                    'partially_overlapping_top'
           INFO     Creating new physical group with name           builder.py:2580
                    'partially_overlapping_hull'
           INFO     Fragmenting...                                fragmenter.py:218
           INFO     Creating new physical group with name           builder.py:2580
                    'box.partially_overlapping_side'
           INFO     Creating new physical group with name           builder.py:2580
                    'box_side.partially_overlapping_side'
           INFO     Creating new physical group with name           builder.py:2580
                    'box.partially_overlapping'
           INFO     Creating new physical group with name           builder.py:2580
                    'box_side.partially_overlapping'
           INFO     Creating new physical group with name           builder.py:2580
                    'box_top.partially_overlapping_top'
           INFO     Creating new physical group with name           builder.py:2580
                    'box_bottom.partially_overlapping_bottom'
           INFO     Creating new physical group with name           builder.py:2580
                    'partially_overlapping'
           INFO     Setting z-coordinate to 10                       builder.py:903
           INFO     Setting z-coordinate to 4                        builder.py:903
           INFO     Selected shapes: [Circle 2 'circle']             builder.py:854
           INFO     Extruding shape 2 from mask 'shapes' with name  builder.py:2794
                    'circle' by 2 at z=4
           INFO     Creating new physical group with name           builder.py:2580
                    'circle_bottom'
           INFO     Creating new physical group with name           builder.py:2580
                    'circle_side'
           INFO     Creating new physical group with name           builder.py:2580
                    'circle_top'
           INFO     Creating new physical group with name           builder.py:2580
                    'circle_hull'
           INFO     Fragmenting...                                fragmenter.py:218
           INFO     Creating new physical group with name           builder.py:2580
                    'box.circle_top'
           INFO     Creating new physical group with name           builder.py:2580
                    'box.circle_side'
           INFO     Creating new physical group with name           builder.py:2580
                    'box.circle'
           INFO     Creating new physical group with name           builder.py:2580
                    'box.circle_bottom'
           INFO     Setting z-coordinate to 6                        builder.py:903
           INFO     Preparing to mesh                               builder.py:1561
           INFO     Detecting appropriate random factor             builder.py:3681
           INFO     Random factor is now appropriate                builder.py:3705
           INFO     Meshing                                         builder.py:1577
           INFO     Saving figure                                   builder.py:1926

<qtcad.builder.builder.Builder object at 0x75dd41c3c2d0>

Above we see that in the overlapping regions the mesh size is medium, as the “partially_overlapping” box inherits the mesh size of the “box” volume. The “circle” volume also inherits the mesh size of the left box, so that its mesh becomes coarser compared to the previous case.

builder.view(
    groups=["box.partially_overlapping", "box.circle"],
    save="figs/mesh_inherit_partially_overlapping.png",  # caption: The overlapping parts of the geometry inherit the coarser mesh size.;
    angles=(-10, 0, 90),
    volume_labels=True,
)
mesh sizes

Fig. 12 The overlapping parts of the geometry inherit the coarser mesh size.

[15:25:14] INFO     Saving figure                                   builder.py:1926

<qtcad.builder.builder.Builder object at 0x75dd41c3c2d0>

Note however that boundary surfaces will always inherit the finer mesh size of the two intersecting volumes, irrespective of the mesh size mode. To override this behavior, use qtcad.builder.Builder.assign_mesh_size.

Minimum mesh size

In minimum mode, newly created volumes will inherit the mesh size of the volume they intersect with only if that mesh size is smaller than the currently set size.

Builder.minimum_mesh_size() → Self

[🔧 Modifier] For all subsequently generated entities, use the mesh size set with set_mesh_size and take the minimum of the set mesh size and the existing mesh size in the intersections with the existing geometry.

builder = Builder().minimum_mesh_size()
make_geometry(builder).view(
    volume_labels=True,
    save="figs/mesh_min.png",  # caption: The whole mesh.;
)
mesh sizes

Fig. 13 The whole mesh.

           INFO     Selected shapes: [Polygon 0 'box']               builder.py:854
           INFO     Extruding shape 0 from mask 'shapes' with name  builder.py:2794
                    'box' by 10 at z=0
           INFO     Creating new physical group with name           builder.py:2580
                    'box_bottom'
           INFO     Creating new physical group with name           builder.py:2580
                    'box_side'
           INFO     Creating new physical group with name 'box_top' builder.py:2580
           INFO     Creating new physical group with name           builder.py:2580
                    'box_hull'
           INFO     Creating new physical group with name 'box'     builder.py:2580
           INFO     Setting z-coordinate to 10                       builder.py:903
           INFO     Selected shapes: [Polygon 1                      builder.py:854
                    'partially_overlapping']
           INFO     Setting z-coordinate to 0                        builder.py:903
           INFO     Extruding shape 1 from mask 'shapes' with name  builder.py:2794
                    'partially_overlapping' by 10 at z=0
           INFO     Creating new physical group with name           builder.py:2580
                    'partially_overlapping_bottom'
           INFO     Creating new physical group with name           builder.py:2580
                    'partially_overlapping_side'
           INFO     Creating new physical group with name           builder.py:2580
                    'partially_overlapping_top'
           INFO     Creating new physical group with name           builder.py:2580
                    'partially_overlapping_hull'
           INFO     Fragmenting...                                fragmenter.py:218
           INFO     Creating new physical group with name           builder.py:2580
                    'box.partially_overlapping_side'
           INFO     Creating new physical group with name           builder.py:2580
                    'box_side.partially_overlapping_side'
           INFO     Creating new physical group with name           builder.py:2580
                    'box.partially_overlapping'
           INFO     Creating new physical group with name           builder.py:2580
                    'box_side.partially_overlapping'
           INFO     Creating new physical group with name           builder.py:2580
                    'box_top.partially_overlapping_top'
           INFO     Creating new physical group with name           builder.py:2580
                    'box_bottom.partially_overlapping_bottom'
           INFO     Creating new physical group with name           builder.py:2580
                    'partially_overlapping'
           INFO     Setting z-coordinate to 10                       builder.py:903
           INFO     Setting z-coordinate to 4                        builder.py:903
           INFO     Selected shapes: [Circle 2 'circle']             builder.py:854
           INFO     Extruding shape 2 from mask 'shapes' with name  builder.py:2794
                    'circle' by 2 at z=4
           INFO     Creating new physical group with name           builder.py:2580
                    'circle_bottom'
           INFO     Creating new physical group with name           builder.py:2580
                    'circle_side'
           INFO     Creating new physical group with name           builder.py:2580
                    'circle_top'
           INFO     Creating new physical group with name           builder.py:2580
                    'circle_hull'
           INFO     Fragmenting...                                fragmenter.py:218
[15:25:15] INFO     Creating new physical group with name           builder.py:2580
                    'box.circle_top'
           INFO     Creating new physical group with name           builder.py:2580
                    'box.circle_side'
           INFO     Creating new physical group with name           builder.py:2580
                    'box.circle'
           INFO     Creating new physical group with name           builder.py:2580
                    'box.circle_bottom'
           INFO     Setting z-coordinate to 6                        builder.py:903
           INFO     Preparing to mesh                               builder.py:1561
           INFO     Detecting appropriate random factor             builder.py:3681
           INFO     Random factor is now appropriate                builder.py:3705
           INFO     Meshing                                         builder.py:1577
[15:25:34] INFO     Saving figure                                   builder.py:1926

<qtcad.builder.builder.Builder object at 0x75dd41c3c550>

Above we see that in the overlapping regions the mesh size is now medium instead of coarse, as the “partially_overlapping” box does not inherit the mesh size of the right box. The cylinder retains its very fine mesh.

builder.view(
    groups=["box.partially_overlapping", "box.circle"],
    save="figs/mesh_min_partially_overlapping.png",  # caption: The overlapping parts of the geometry do not inherit the coarser mesh size.;
    angles=(-10, 0, 90),
    volume_labels=True,
)
mesh sizes

Fig. 14 The overlapping parts of the geometry do not inherit the coarser mesh size.

[15:25:35] INFO     Saving figure                                   builder.py:1926

<qtcad.builder.builder.Builder object at 0x75dd41c3c550>

Setting the minimal number of elements

Irrespective of the mesh size mode, we can also set the minimum number of mesh elements along the shortest dimension of a volume using qtcad.builder.Builder.set_min_elements. This allows to automatically create more refined meshes in small structures.

Builder.set_min_elements(min_elements: int | None) → Self

[🔧 Modifier] Ensure that all subsequently created volumes will have at least min_elements mesh elements (triangles, tetrahedra) along their narrowest dimension. If set to None, the mesh size set by set_mesh_size will be used.

Below, we set a very large mesh size, but also set the minimum number of elements to 5. We then extrude a box once by 1 and once by 3, resulting in two volumes with different heights. These different heights will result in different mesh sizes.

builder = (
    Builder()
    .overlay_mode()
    .set_mesh_size(1000)
    .set_min_elements(5)
    .add_mask(mask)
    .use_shape("box")
    .set_group_name("first")
    .extrude(3)
    .set_group_name("second")
    .extrude(1)
    .mesh(2, algorithm3d=MeshAlgorithm3D.HXT)
    .view(
        save="figs/mesh_min_elements.png",  # caption: The whole mesh with a very large mesh size but a minimum of 5 elements along the shortest dimension.;
        orthographic=True,
        angles=(-90, 0, 0),
    )
)
mesh sizes

Fig. 15 The whole mesh with a very large mesh size but a minimum of 5 elements along the shortest dimension.

[15:25:36] INFO     Selected shapes: [Polygon 0 'box']               builder.py:854
           INFO     Extruding shape 0 from mask 'shapes' with name  builder.py:2794
                    'box' by 3 at z=0
           INFO     Creating new physical group with name           builder.py:2580
                    'first_bottom'
           INFO     Creating new physical group with name           builder.py:2580
                    'first_side'
           INFO     Creating new physical group with name           builder.py:2580
                    'first_top'
           INFO     Creating new physical group with name           builder.py:2580
                    'first_hull'
           INFO     Creating new physical group with name 'first'   builder.py:2580
           INFO     Setting z-coordinate to 3                        builder.py:903
           INFO     Extruding shape 0 from mask 'shapes' with name  builder.py:2794
                    'box' by 1 at z=3
           INFO     Creating new physical group with name           builder.py:2580
                    'second_bottom'
           INFO     Creating new physical group with name           builder.py:2580
                    'second_side'
           INFO     Creating new physical group with name           builder.py:2580
                    'second_top'
           INFO     Creating new physical group with name           builder.py:2580
                    'second_hull'
           INFO     Fragmenting...                                fragmenter.py:218
           INFO     Creating new physical group with name           builder.py:2580
                    'first_top.second_bottom'
           INFO     Creating new physical group with name 'second'  builder.py:2580
           INFO     Setting z-coordinate to 4                        builder.py:903
           INFO     Preparing to mesh                               builder.py:1561
           INFO     Detecting appropriate random factor             builder.py:3681
           INFO     Random factor is now appropriate                builder.py:3705
           INFO     Meshing                                         builder.py:1577
           INFO     Saving figure                                   builder.py:1926

Using qtcad.builder.Builder.assign_mesh_size we can override the automatically assigned mesh size.

Builder.assign_mesh_size(group: str, size: float, force: bool = False, force_with_lease: bool = False) → Self

[⚡ Utility] Assign a mesh size size to all entities (and their boundaries) in the physical group named group respecting the mesh size mode (see override_mesh_size and inherit_mesh_size). If force is True, the size will override any existing sizes. If force_with_lease is True, the size will override any existing sizes, but only if the new size is smaller.

Parameters:

  • group – The name of the physical group.

  • size – The mesh size to assign.

  • force – If True, the size will override any existing sizes.

  • force_with_lease – If True, the size will override any existing sizes, but only if the new size is smaller.

builder.clear_mesh().assign_mesh_size("first", 0.1, force=True).mesh(
    2, algorithm3d=MeshAlgorithm3D.HXT
).view(
    save="figs/mesh_assigned.png",  # caption: The same mesh as above, but with the mesh size of the first volume set to 1.;
    orthographic=True,
    angles=(-90, 0, 0),
)
mesh sizes

Fig. 16 The same mesh as above, but with the mesh size of the first volume set to 1.

[15:25:37] INFO     Clearing mesh                                   builder.py:1522
           INFO     Preparing to mesh                               builder.py:1561
           INFO     Detecting appropriate random factor             builder.py:3681
           INFO     Random factor is now appropriate                builder.py:3705
           INFO     Meshing                                         builder.py:1577
[15:25:38] INFO     Saving figure                                   builder.py:1926

<qtcad.builder.builder.Builder object at 0x75dd41c3ca50>

Above we uset the force=True option to completely override the mesh size.

Total running time of the script: (0 minutes 48.298 seconds)

Gallery generated by Sphinx-Gallery