Extrusion and fragmentation modes

This example demonstrates the qtcad.builder.Builder.extrude operation and the different strategies that are available when merging new objects into the existing geometry (see FragmentationMode) on the example of a smiling face.

Initialization

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

Initializing the Builder

Below, we initialize a new instance of qtcad.builer.Builder and load the shapes we’ll later user from an OASIS layout. An overview of the currently registered masks and shapes can be obtained through qtcad.builder.Builder.print_tree. We then select all masks and thus all shapes in all masks and visualize them using qtcad.builder.Builder.view_shapes.

Builder.load_layout(file_path: str | Path, cell_name: str | None = None, name_property: str = 'name') → Self

[⚡ Utility] Read the cell named cell_name (default is the top cell) from a GDS or an OASIS file file_path and parse its structure. Each layer will become a qtcad.builder.Mask appropriately named and the ID from the layout file (provided there are no conflicting IDs) containing polygons for each shape found in the layer. The name of each shape is taken from the user property name_property. The length units in the file are assumed to be 10**length_unit_exponent meters (default is nanometres).

Parameters:

• file_path – The path to the GDS or OASIS file.

• cell_name – The name of the cell that the device is specified in. If None, use the top cell.

• name_property – The user property that contains the name of a shape.

Fig. 15 The photomask layout for the smiling face.

builder = (
    Builder()
    .load_layout("./layouts/smile.oas")
    .print_mask_tree()
    .use_all_masks()
    .view_shapes(
        save="figs/shapes_in_mask.svg",
        font_size=20,
    )
)

Layout
├── Mask 1 "footprint"
│   └── 0  Polygon  "footprint"
└── Mask 2 "smile"
    ├── 0  Polygon  "left_eye"
    ├── 1  Polygon  "right_eye"
    └── 2  Polygon  "mouth"

The shape names are either read from a user property (name by default) or from text labels (as is the case for the right_eye here).

Building the geometry

Next, select the mask "footprint" (the outline of the smiling face) extrude that mask to create a volume. We used qtcad.builder.Builder.set_mesh_size to set the mesh characteristic length and qtcad.builder.Builder.set_mesh_size to tell the Builder not to try and lower the mesh size based on the resulting volume size. We use qtcad.builder.Builder.difference_hull_surfaces with the argument False to make sure all the hull surfaces get the same name.

Builder.extrude(height: float) → Self

[🏗️ Operation] Create a solid extrusion of a plane shape of height height at the current z_coordinate. Also advances the current z_coordinate by height. The resulting surfaces are automatically named using the current naming strategy by appending the suffixes EXTRUSION_SURF_SUFFIXES.

Parameters:

height – The distance by which the shape will be extruded into three dimensional space.

(
    builder.set_mesh_size(10)
    .set_min_elements(1)
    .differentiate_hull_surfaces(False)
    .use_mask("footprint")
    .set_z(-10)
    .extrude(20)
)

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

The above results in a volume named footprint (named after the shape).

builder.view(
    surfaces=False,
    volume_labels=True,
    angles=(-45, 0, 45),
    save="figs/extrusion_foot.svg",
    font_size=20,
    surface_labels=False,
)

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

The extrusion advances the current z-coordinate to the top of the extruded volume.

print(builder.get_z())

10

The surfaces of created by the extrusion operation are automatically added to physical groups named according to the volume:

builder.view(
    surfaces=True,
    volume_labels=False,
    surface_labels=True,
    angles=(-45, 0, 45),
    save="figs/extrusion_foot_surfs.svg",
    font_size=20,
)

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

Displace mode

Next, we insert the left eye using qtcad.builder.Builder.displace_mode (the default mode). Note that we used qtcad.builder.Builder.set_z to set the base coordinate of the extrusion and qtcad.builder.Builder.use_shape to select a specific shape in the mask to extrude. By default selecting a mask also selects all shapes in the masks for subsequent operation (see for example Adding the gate surfaces in the Gated Quantum Dot tutorial). We also use qtcad.builder.Builder.set_mesh_size to set a finer mesh size for subsequently created volumes. We re-enable hull surface differ with the argument True.

Builder.displace_mode(dim: int | list[int] | None = None) → Self

[🔧 Modifier] When creating new entities, override the physical groups where the new entities intersect with the old ones to correspond to the physical group of the new elements.

Parameters:

dim – See use_mode.

(
    builder.set_mesh_size(5)
    .use_mask("smile")
    .set_z(0)
    .displace_mode()
    .differentiate_hull_surfaces(True)
    .use_shape("left_eye")
    .extrude(20)
)

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

The resulting volume intersects with the the footprint. Because we chose the displace mode the resulting fragments are all added to the physical group left_eye (name generated from the shape name, see also qtcad.builder.Builder.name_from_shape, qtcad.builder.Builder.name_from_mask, and qtcad.builder.Builder.name_from_shape).

builder.view(
    surfaces=False,
    volume_labels=True,
    surface_labels=False,
    angles=(-45, 0, 45),
    save="figs/extrusion_left_eye.svg",
    font_size=20,
)

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

Note that the hull surfaces are now differentiated into bottom, side, and top.

builder.view(
    surfaces=False,
    volume_labels=False,
    surface_labels=True,
    groups=["left_eye"],
    angles=(-45, 0, 45),
    font_size=5,
    save="figs/extrusion_left_eye_surfs.svg",
)

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

Fill mode

Next, we will use qtcad.builder.Builder.fill_mode to add the right eye. The fill mode is the conceptual opposite of the displace mode:

Builder.fill_mode(dim: int | list[int] | None = None) → Self

[🔧 Modifier] When creating new entities, inherit the physical groups where the new entities intersect with the old ones.

Parameters:

dim – See use_mode.

We also demonstrate here qtcad.builder.Builder.number_hull_surfaces to number the hull surfaces consecutively according to the direction they are facing in addition of naming them according to their position (bottom, side, top). This is useful, for example, to apply boundary conditions only to select surfaces:

builder.set_z(0).fill_mode().number_hull_surfaces().use_shapes("right_eye").extrude(30)

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

We find, this results in the part of the geometry intersecting with the "footprint" volume inherit the physical group of that volume.

builder.view(
    surfaces=False,
    volume_labels=True,
    surface_labels=False,
    angles=(-45, 0, 45),
    save="figs/extrusion_right_eye.svg",
    font_size=20,
)

builder.view(
    surfaces=False,
    volume_labels=False,
    surface_labels=True,
    groups=["right_eye"],
    angles=(-45, 0, 45),
    font_size=5,
    save="figs/extrusion_right_eye_surfs.svg",
)

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

Overlay mode

Finally, we will use qtcad.builder.Builder.overlay_mode to add the right eye. The overlay mode is a middle ground between displacing and filling.

Builder.overlay_mode(dim: int | list[int] | None = None) → Self

[🔧 Modifier] Like fill_mode, but instead of inheriting the group from the intersecting entities the intersecting elements will be added to physical groups named like [intersecting_group].[new_entity_group].

Parameters:

dim – See use_mode.

(
    builder.set_z(0)
    .differentiate_hull_surfaces(False)
    .overlay_mode()
    .use_shapes("mouth")
    .extrude(30)
)

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

We find, this results in the part of the geometry intersecting with the "footprint" volume to be named ``”footprint.mouth”.

builder.view(
    surfaces=False,
    volume_labels=True,
    surface_labels=False,
    angles=(-45, 0, 45),
    save="figs/extrusion_mouth.svg",
    font_size=20,
)

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

When viewing just the mouth, we can make out how the new volume and surfaces are named.

builder.view(
    surfaces=True,
    volume_labels=False,
    surface_labels=True,
    angles=(-45, 0, 45),
    save="figs/extrusion_mouth_only.svg",
    font_size=10,
    groups=["mouth", "footprint.mouth"],
)

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

The final mesh then becomes:

builder.mesh(algorithm3d=MeshAlgorithm3D.HXT)

builder.view(
    surfaces=False,
    volume_labels=True,
    surface_labels=False,
    angles=(-45, 0, 45),
    save="figs/extrusion_mesh.png",
    font_size=20,
)

nodes:   0%|          | 0/7179 [00:00<?, ?it/s]
nodes:   0%|          | 0/7179 [00:00<?, ?it/s]
nodes: 100%|██████████| 7179/7179 [00:00<00:00, 1852978.98it/s]
nodes: 100%|██████████| 7179/7179 [00:00<00:00, 1790504.16it/s]
nodes: 100%|██████████| 7179/7179 [00:00<00:00, 1752264.22it/s]

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

Filling around the entire model

Fill mode is also usefull to add material around an existing structure. To that end we first create a container shape that is slightly larger than the bounding box of the existing geometry. We then add that shape as a mask and use fill mode to extrude it around the existing geometry.

container = (
    Polygon.from_bbox(*builder.bbox, name="container").scaled(1.2).translated(-2, 0)
)
container_mask = Mask("container")
container_mask.add_shape(container)

(
    builder.clear_mesh()
    .add_mask(container_mask)
    .inherit_mesh_size()
    .fill_mode()
    .set_z(-21)
    .extrude(60)
    .view(
        surfaces=False,
        volume_labels=True,
        surface_labels=False,
        angles=(-45, 0, 45),
        save="figs/extrusion_container.svg",
        font_size=20,
    )
)

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

When we view the just-created volume in isolation, we see that the existing geometry has been “stenciled out”.

(
    builder.view(
        surfaces=False,
        volume_labels=True,
        surface_labels=False,
        angles=(-45, 0, 45),
        save="figs/extrusion_container_only.svg",
        font_size=20,
        groups=["container"],
    )
)

# Local Variables:
# jinx-languages: "en_CA"
# End:

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