qtcad.builder package

This package provides the qtcad.builer.Builder class which is the main interface to builder.

Also available are qtcad.builder.Polygon` to create two-dimensional shapes that can be added to layouts contained in instances of qtcad.builder.Mask. Masks can then be used in qtcad.builer.Builder.

The MeshAlgorithm2D and MeshAlgorithm3D enums are used to specify the meshing algorithm in qtcad.builer.Builder.mesh.

class Builder(name: str = 'builder', length_unit_exponent: int = -9, gmsh_log_level: int = 30)

Bases: Builder

Generates three dimensional Gmsh models from two dimensional shapes (see qtcad.builder.masks.Shape, load_layout).

Parameters:

name – The name of the Gmsh model to be generated.
length_unit_exponent – Defines the scaling factor with respect to meter. E.g. -9 for nanometre. This is used to adjust the scaling when importing layouts.
gmsh_log_level – Controls verbosity level for Gmsh output. By default, it is logging.WARN because of the large volume of Gmsh-related output. You may wish to set this higher e.g. when diagnosing issues.

Interface

The basic workflow is inspired by physical fabrication steps. The API uses the builder pattern with methods returning self to allow chaining of method calls. The idea is to sequentially create three dimensional geometries from two-dimensional shapes (selected from a collection stored within the generator), while controlling how the newly created geometries are integrated into the existing model.

The z-coordinate is controlled semi-manually (see set_z, set_z_from_group, save_z and extrude), whereas the x-y coordinates are taken from the two-dimensional shapes. The x-y plane can be changed by using rotate_model and translate_model.

Devicegen does not load or write to the global Gmsh options to ensure reputability.

There are three types of methods.

Modifiers

First, there are methods that modify the behaviour of operations:

set_mesh_size: Set the local mesh size for elements added after this point in units set by the length_unit_exponent (see qtcad.builer.Builder). Note that the mesh size may be chosen smaller due to set_min_elements.
use_all_masks: Select all masks and merge them into one temporary mask.
use_mask: Switch to use another mask as the working one. The mask parameter can be either the ID or name of a mask or a function taking a mask and returning True if the mask is to be selected. A list of the above can also be provided (see qtcad.builder.MaskContainer.get_mask). If multiple masks are selected, they are merged into a temporary mask.
use_shapes: Select shapes in the current mask that will be used for all following operations.
set_z_from_group: Set the current z-coordinate to the top (default) or bottom of the bounding box of the entities in the group named group_name. Optionally, an offset can be provided to shift the z-coordinate up (positive offset) or down (negative offset).
set_z: Set the z-coordinate used as the basis for operations.
set_min_elements: 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.
use_mode: Set the strategy for handling intersecting geometries for the dimensions dim. Currently, this setting is only relevant for dimensions 2 and 3.
fill_mode: When creating new entities, inherit the physical groups where the new entities intersect with the old ones.
displace_mode: 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.
overlay_mode: 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].
inherit_mesh_size: 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.
override_mesh_size: 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.
minimum_mesh_size: 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.
set_group_name: Any entities created after calling this method will be assigned to the physical group with name name.
group_from_mask: Any entities created after calling this method will be assigned to a physical group that is named according to the name of the mask they belong to.
group_from_shape: Any entities created after calling this method will be assigned to a physical group that is named according the name of the shape that the entity is created from.
set_geometry_tolerance: Set the geometry tolerance used by Gmsh when determining whether two points are identical. The default is 1e-8 length units.
set_match_mesh_tolerance: Set the tolerance used when matching mesh nodes to geometry points. The default is 1e-6 length units. This doesn’t seem to have much effect in practice.
number_hull_surfaces: Enable or disable automatic numbering of hull surfaces bounding volumes created during operations such as extrude, grow and pad_volume. If enable is None, the setting is toggled.
differentiate_hull_surfaces: Enable or disable differentiation of hull surfaces created during operations such as extrude, grow and pad_volume. If enable is None, the setting is toggled.

Operations

Second, there are methods that perform constructive or destructive operations on the model:

add_surface: Add surfaces based on the the currently selected shapes to the model at the current z-coordinate.
extrude: 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.
deposit_surface: Add the currently selected shapes as surfaces on top of the model, following the contours of the top surface. If noclip is True, then the surface is not clipped and can extend past the currently selected shapes.
deposit: Deposit the currently selected shape(s) into the model up from the current z coordinate by height length units. This is done by adding new material atop the topmost surfaces of the model. If noclip=True, the new material is deposited on the whole top surface of the model, rather than clipped by the currently selected shapes.
grow: Emulate a physical ‘growth’ operation to add material to the current topmost volumes. In contrast to deposit, this will not only add material to the top of the volumes but also to their sides. The currently active shapes are used to horizontally clip the new volumes unless noclip is True.
pad_volume: Add a padding layer of thickness around the volumes in volume group with name group_name. The newly created padding volume will be named group_name + padding_suffix and clipped horizontally by the currently selected shapes unless noclip is True.
cut: Cut the currently selected shape(s) into the model up from the current z coordinate down by depth length units. If noclip=True, the cutting is performed on the whole model rather than clipped by the selected shapes.
etch: Etch the currently selected shape(s) into the model up from the current z coordinate down by depth length units. This is done by cutting into each top surface. If noclip is True, then the surface is not clipped to the currently selected shapes.
translate_model: Translate the whole model by the vector vec. The z-coordinate is updated by the z-component of vec.
rotate_model: Rotate the model around its centre of mass (or the point specified by around) by a given angle in degrees on a a specified axis . The z-coordinate is updated to the new top of the model.
import_model: Import a Gmsh model from file file_path. The model can be in any format that Gmsh supports (e.g. .iges, .step, .brep).

Utilities

Finally, there are methods that provide utility functions and an interface to Gmsh functionality:

add_mask: Add a mask, which is then available for usage with use_mask. The newly added mask becomes the current mask and all shapes in it are selected (see use_shapes).
load_layout: 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).
copy_mask: Copy current mask to an empty mask named new_name, set the current mask to this newly created one and select all shapes in the new mask.
print_mask_tree: Print a tree of all masks and shapes currently loaded using qtcad.builder.MaskContainer.print_tree. The arguments are passed on to the above-mentioned method.
rename_shape: Copy and rename the currently selected shape and select the newly created shape after adding it to the current mask.
remove_shapes: Remove the currently selected shapes from the current mask. Selects all the shapes left in the current mask.
copy_shape: Copy the currently active shapes (see use_shapes, use_mask), apply transformations (translation, rotation, scaling, …) to them and select the copies. The copies will be added to the current mask or to the mask specified by to_mask (which does not have to exist yet). See also qtcad.builder.masks.MaskContainer.copy_shapes and qtcad.builder.masks.Shape.transform.
get_group: Get the physical group with the specified name or all groups if name is None or not given. The name can also be a list of names or a callable that takes a PhysicalGroup (the group name) and returns True if the group should be returned.
assign_to_group: Assign one or multiple entities tag of dimension dim to group group. If the group does not exist, it will be created. If there already exists a group with this name, but in another dimension, then make the name unique by appending DimSuffix.
rename_group: Rename an existing physical group old to new.
dissolve_physical_group: Dissolve (remove) the physical group(s) with name name (see get_group). The entities in the group are not removed from the model.
merge_groups: Merge multiple physical groups groups into the (potentially new) group new.
save_z: Save the current z-coordinate under name.
get_z: Get the current z-coordinate or the saved z-coordinate with the given name.
get_z_from_group: Get the top z-coordinate of the bounding box of the entities in the group named group_name. If bottom is True, return the bottom z-coordinate instead. The method tries to snap to the z coordinate of an existing point, but falls back to the bounding box value if there aren’t any.
log: Log an logging.INFO level message.
clear_mesh: Clear the mesh from the current model.
mesh: Generate a mesh for the current model.
quick_mesh: Quickly generate a mesh for the current model using the initial mesh algorithms in Gmsh. This is useful for visualisation purposes.
write: Save the model to path using gmsh.write.
set_periodic: Set a periodicity constraint between the entities in groups master and match. The periodicity is defined by an affine transformation that maps entities in master to entities in match consisting of an optional rotation (3x3 matrix) and an optional translation (3-vector). If not provided, no rotation and no translation is assumed.
visualize: View the current model using qtcad.device.Device.view().
view: View the current model in the Gmsh GUI.
view_shapes: View the currently selected shapes in gmsh. All the keyword arguments are passed on to view.
snapshot: Return a clone of the object (including the Gmsh state).
finalize: Stop all underlying Gmsh processes. No further operations can be performed after calling this method. This is mainly useful to clean up memory.
assign_mesh_size: 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.

add_mask(mask: Mask) → Self

[⚡ Utility] Add a mask, which is then available for usage with use_mask. The newly added mask becomes the current mask and all shapes in it are selected (see use_shapes).

Parameters:: mask – The mask to add.

add_surface() → Self: [🏗️ Operation] Add surfaces based on the the currently selected shapes to the model at the current z-coordinate.

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.

assign_to_group(dim: int, tag: list[int] | int, group: str) → Self: [⚡ Utility] Assign one or multiple entities tag of dimension dim to group group. If the group does not exist, it will be created. If there already exists a group with this name, but in another dimension, then make the name unique by appending DimSuffix.

property bbox: Returns: The bounding box of the model.

property canfork: Returns whether forking is supported.

clear_mesh() → Self: [⚡ Utility] Clear the mesh from the current model.

copy_mask(new_name: str, **kwargs) → Self

[⚡ Utility] Copy current mask to an empty mask named new_name, set the current mask to this newly created one and select all shapes in the new mask.

For the keyword arguments see copy_shape. This method is equivalent to use_mask(current_mask).copy_shape(to_mask=new_name, **kwargs).

copy_shape(name: str | None = '__unset', to_mask: int | str | None = None, translate: tuple[float, float] = (0, 0), rotate: float = 0, scale: float = 1, transformer: Callable[[Shape], Shape] | None = None) → Self

[⚡ Utility] Copy the currently active shapes (see use_shapes, use_mask), apply transformations (translation, rotation, scaling, …) to them and select the copies. The copies will be added to the current mask or to the mask specified by to_mask (which does not have to exist yet). See also qtcad.builder.masks.MaskContainer.copy_shapes and qtcad.builder.masks.Shape.transform.

Parameters:

name – The name of the new shape. If "__unset", the name will be copied from the original shape. If None, the new shape will be unnamed. See Shape.named. If multiple shapes are copied, an index is appended to the name. E.g., "my_shape_0". Use transformer to modify the names in a more flexible way.
to_mask – If specified, the copied shapes will be added to the mask with this name or index. Otherwise, they will be added to the current mask. If the specified mask does not exist and str is provided, a new mask will be created with this name.
translate – Translation vector in the x-y plane to apply to the copied shapes. See qtcad.builder.masks.Shape.translate.
rotate – The rotation angle in degrees around the barycenter of the selected shapes. If a tuple (angle, center) is given, the selected shapes are rotated around center (which may be None in which case the shapes are rotated about their individual barycenters). See also Shape.rotated.
scale – Scaling factor to apply to the copied shapes. See qtcad.builder.masks.Shape.scale.
transformer – A callable that takes a shape and returns a modified shape. It is applied after the above transformations. This can be used to apply arbitrary transformations to the copied shapes. See qtcad.builder.masks.Shape.transform. This might be useful to rename the shapes.

copy_shapes(name: str | None = '__unset', to_mask: int | str | None = None, translate: tuple[float, float] = (0, 0), rotate: float = 0, scale: float = 1, transformer: Callable[[Shape], Shape] | None = None) → Self

[⚡ Utility] Copy the currently active shapes (see use_shapes, use_mask), apply transformations (translation, rotation, scaling, …) to them and select the copies. The copies will be added to the current mask or to the mask specified by to_mask (which does not have to exist yet). See also qtcad.builder.masks.MaskContainer.copy_shapes and qtcad.builder.masks.Shape.transform.

Parameters:

name – The name of the new shape. If "__unset", the name will be copied from the original shape. If None, the new shape will be unnamed. See Shape.named. If multiple shapes are copied, an index is appended to the name. E.g., "my_shape_0". Use transformer to modify the names in a more flexible way.
to_mask – If specified, the copied shapes will be added to the mask with this name or index. Otherwise, they will be added to the current mask. If the specified mask does not exist and str is provided, a new mask will be created with this name.
translate – Translation vector in the x-y plane to apply to the copied shapes. See qtcad.builder.masks.Shape.translate.
rotate – The rotation angle in degrees around the barycenter of the selected shapes. If a tuple (angle, center) is given, the selected shapes are rotated around center (which may be None in which case the shapes are rotated about their individual barycenters). See also Shape.rotated.
scale – Scaling factor to apply to the copied shapes. See qtcad.builder.masks.Shape.scale.
transformer – A callable that takes a shape and returns a modified shape. It is applied after the above transformations. This can be used to apply arbitrary transformations to the copied shapes. See qtcad.builder.masks.Shape.transform. This might be useful to rename the shapes.

property current_mask

The currently active mask or the first available mask.

Raises:: ValueError – If no current mask is set and the mask container is empty.

property current_shapes: List of shapes currently selected.

cut(depth: float, noclip: bool = False) → Self

[🏗️ Operation] Cut the currently selected shape(s) into the model up from the current z coordinate down by depth length units. If noclip=True, the cutting is performed on the whole model rather than clipped by the selected shapes.

See also etch which follows the contours of the top surface.

Parameters:

depth – The distance by which to etch the selected shapes down into the model.
noclip – Whether to cut the shape without horizontally clipping to the current shapes.

deposit(height: float, noclip: bool = False) → Self

[🏗️ Operation] Deposit the currently selected shape(s) into the model up from the current z coordinate by height length units. This is done by adding new material atop the topmost surfaces of the model. If noclip=True, the new material is deposited on the whole top surface of the model, rather than clipped by the currently selected shapes.

See also cut, deposit and grow.

Parameters:: depth – The distance by which to etch the selected shapes down into the model. Must be positive.

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.

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.

finalize(kill: bool = False) → Self: [⚡ Utility] Stop all underlying Gmsh processes. No further operations can be performed after calling this method. This is mainly useful to clean up memory.

get_all_entities(dim: int | list[int] | None = None) → list[tuple[int, int]]

Get a list of all entities in the model that are part of a group. See also qtcad.builer.Builder._get_entities_for_group.

Parameters:: dim – Dimension. If set only the entities of that dimension will be returned, otherwise all are returned.

get_group(name: GroupSpecifier | None = None, ret_list: bool = False) → PhysicalGroup | list[PhysicalGroup]

[⚡ Utility] Get the physical group with the specified name or all groups if name is None or not given. The name can also be a list of names or a callable that takes a PhysicalGroup (the group name) and returns True if the group should be returned.

If ret_list is True, always return a list.

Raises:: ValueError – If the group could not be found.

get_groups(dim: int | list[int] | None = None, sync: bool = True) → list[PhysicalGroup]

Get all groups, optionally filtered by their dimension. The result value is a list of PhysicalGroup instances. If no match was found an empty list is returned.

Parameters:

dim – A dimension of the physical groups to be returned. Can also be a collection of dimensions, see DimensionSpecifier. If unset then all dimensions will be considered.
sync – Whether to synchronize the internal Builder representation of groups the physical groups with Gmsh before retrieving them.

Returns:

A list of found groups. An empty list if none were found.

get_z(name: str | None = None) → float: [⚡ Utility] Get the current z-coordinate or the saved z-coordinate with the given name.

get_z_from_group(group_name: str, bottom: bool = False) → float

[⚡ Utility] Get the top z-coordinate of the bounding box of the entities in the group named group_name. If bottom is True, return the bottom z-coordinate instead. The method tries to snap to the z coordinate of an existing point, but falls back to the bounding box value if there aren’t any.

Parameters:

group_name – The name of the group to use.
bottom – If True, return the bottom of the bounding box.

group_from_mask() → Self: [🔧 Modifier] Any entities created after calling this method will be assigned to a physical group that is named according to the name of the mask they belong to.

group_from_shape() → Self: [🔧 Modifier] Any entities created after calling this method will be assigned to a physical group that is named according the name of the shape that the entity is created from.

grow(thickness: float, noclip: bool = False, exact: bool = False, num_tries: int = 10, i_know_what_im_doing: bool = False, polygonize: bool = True) → Self

[🏗️ Operation] Emulate a physical ‘growth’ operation to add material to the current topmost volumes. In contrast to deposit, this will not only add material to the top of the volumes but also to their sides. The currently active shapes are used to horizontally clip the new volumes unless noclip is True.

The resulting surfaces are labelled similar to the extrude command. However, there is some ambiguity as to what surfaces are to be considered to be on top and what surfaces are on the side. Here, we choose surfaces whose (average) normal vector projected on the x-y plane is 10% larger than its projection on the z-axis to be on the “side”. Surfaces can be created/renamed using assign_to_group, add_surface or deposit_surface.

Warning

Due to problems in OpenCASCADE, this operation might fail. If it does it may help to retry with a different thickness or polygonize=False. The warning can be suppressed with i_know_what_im_doing=True.

Parameters:

thickness – The distance by which to grow the selected shapes. Must be positive.
noclip – If True, do not clip the created volumes horizontally.
exact – If exact=True do not try to slightly adjust the growth thickness in case growth fails and crash straightaway.
num_tries – If exact=False, try up to num_tries times to successively slightly reduce the thickness (by 0.1% each time) and retry.
i_know_what_im_doing – If False, a warning will be issued because this operation is known to be somewhat unstable due to problems in OpenCASCADE.
polygonize – If True, the newly created volumes will be recreated from their hull meshes to avoid problems with curved OpenCASCADE solids (default is True).

import_model(file_path: str | Path, format: str = '', translate: Iterable[float] | None = None, scale: float = 1.0, rotate: float = 0.0, rotation_axis: Iterable[float] | str = Direction.z) → Self

[🏗️ Operation] Import a Gmsh model from file file_path. The model can be in any format that Gmsh supports (e.g. .iges, .step, .brep).

Parameters:

file_path – The path to the file to import.
format – The format of the file. If empty (default), the format will be guessed from the file extension. Can be “iges”, “step”, “brep”.
translate – If provided, a 3-vector by which to translate the model after import.
scale – Scaling factor to apply to the model after import.
rotate – Angle in degrees by which to rotate the model around its centre of mass.

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.

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.

log(*args, **kwargs) → Self

[⚡ Utility] Log an logging.INFO level message.

For the arguments see logging.info.

merge_groups(groups: GroupSpecifier, into: str) → Self

[⚡ Utility] Merge multiple physical groups groups into the (potentially new) group new.

Parameters:

groups – Group(s) to merge. See get_group for details.
into – The name of a new or existing group to merge into.

mesh(dimension: int = 3, algorithm2d: int | MeshAlgorithm2D = 2, algorithm3d: int | MeshAlgorithm3D = 1, show_gmsh_output: bool = False, check_connectivity: bool = True, exclude: GroupSpecifier = []) → Self

[⚡ Utility] Generate a mesh for the current model.

Parameters:

dimension – The dimensionality of the objects to be meshed.
save – Optional path(s) under which the meshed model will be saved.
algorithm2d – The ID of the two-dimensional mesh algorithm to use in Gmsh (see https://gmsh.info/doc/texinfo/gmsh.html#Meshing- parameters). Default is automatic. See MeshAlgorithm2D.
algorith3d – The ID of the three-dimensional mesh algorithm to use in Gmsh (see https://gmsh.info/doc/texinfo/gmsh.html#Meshing- parameters). See MeshAlgorithm3D.
show_gmsh_output – If True, show Gmsh output in the terminal.
check_connectivity – If True, run a simple conformity check on the mesh after generation. The check consists of determining whether the mesh is fully connected which is sufficient but not necessary for conformity. (Only for three-dimensional meshes.)
exclude – Physical group(s) to exclude from meshing. Can be a single group name, a list of group names or a callable that takes a PhysicalGroup and returns True if the group should be excluded.

property mesh_size

The current mesh size.

Raises ValueError if no current mesh size is set.

property min_elements: The current minimum number of mesh elements along the narrowest dimension of subsequently created volumes.

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.

property mode

The current mode used for combining intersecting geometries.

See qtcad.builer.Builder.Mode for a description of the different modes.

number_hull_surfaces(enable: None | bool = None) → Self

[🔧 Modifier] Enable or disable automatic numbering of hull surfaces bounding volumes created during operations such as extrude, grow and pad_volume. If enable is None, the setting is toggled.

Default is False. Has no effect if :differentiate_hull_surfaces` is turned off.

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.

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.

pad_volume(group: GroupSpecifier, thickness: float, padding_suffix: str = '_padding', noclip: bool = False, polygonize: bool = True) → Self

[🏗️ Operation] Add a padding layer of thickness around the volumes in volume group with name group_name. The newly created padding volume will be named group_name + padding_suffix and clipped horizontally by the currently selected shapes unless noclip is True.

Parameters:

group – The group(s) to pad. See get_group for details on the allowed types.
thickness – The padding thickness.
padding_suffix – Suffix to append to the group name for the new volume.
noclip – If True, no horizontal clipping will occur. Default is False.
polygonize – If True, the newly created volumes will be recreated from their hull meshes to avoid problems with curved OpenCASCADE solids (default is True).

print_mask_tree(*args, **kwargs) → Self: [⚡ Utility] Print a tree of all masks and shapes currently loaded using qtcad.builder.MaskContainer.print_tree. The arguments are passed on to the above-mentioned method.

quick_mesh(dim: int = 3, mesh_size: float | None = None) → Self

[⚡ Utility] Quickly generate a mesh for the current model using the initial mesh algorithms in Gmsh. This is useful for visualisation purposes.

Parameters:

dim – The dimensionality of the objects to be meshed.
mesh_size – If provided, use this mesh size for all entities being meshed.

remove_shapes() → Self: [⚡ Utility] Remove the currently selected shapes from the current mask. Selects all the shapes left in the current mask.

rename_group(old: str, new: str) → Self

[⚡ Utility] Rename an existing physical group old to new.

Raises:: ValueError – If the group already exists.

rename_shape(name: str) → Self

[⚡ Utility] Copy and rename the currently selected shape and select the newly created shape after adding it to the current mask.

Calls copy_shape.

rotate_model(angle: float, axis: Iterable[float] | str, around: tuple[float, float] | Iterable[float] | Direction | None = None) → Self

[🏗️ Operation] Rotate the model around its centre of mass (or the point specified by around) by a given angle in degrees on a a specified axis . The z-coordinate is updated to the new top of the model.

Parameters:

angle – The angle to rotate by (in degrees).
axis – The direction vector of the axis of rotation. Either “x”, “y” or “z” or a 3-vector.
around – Point to rotate around. If None (default), rotates around the centre of mass. If a string is provided, the centre of rotation will be the centre of mass of the physical group with that name.

save_z(name: str) → Self

[⚡ Utility] Save the current z-coordinate under name.

This name can then be used to restore the z-coordinate with set_z.

set_geometry_tolerance(tolerance: float) → Self: [🔧 Modifier] Set the geometry tolerance used by Gmsh when determining whether two points are identical. The default is 1e-8 length units.

set_group_name(name: str) → Self

[🔧 Modifier] Any entities created after calling this method will be assigned to the physical group with name name.

set_match_mesh_tolerance(tolerance: float) → Self: [🔧 Modifier] Set the tolerance used when matching mesh nodes to geometry points. The default is 1e-6 length units. This doesn’t seem to have much effect in practice.

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 qtcad.builer.Builder). Note that the mesh size may be chosen smaller due to set_min_elements.

Parameters:: size – The new mesh characteristic length.

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.

set_periodic(master: GroupSpecifier, match: GroupSpecifier, translation: Iterable[float] | None = None, rotation: ndarray | None = None) → Self

[⚡ Utility] Set a periodicity constraint between the entities in groups master and match. The periodicity is defined by an affine transformation that maps entities in master to entities in match consisting of an optional rotation (3x3 matrix) and an optional translation (3-vector). If not provided, no rotation and no translation is assumed.

See the Gmsh documentation for more information.

Parameters:

master – The group(s) of the master entities. (See get_group().)
match – The group(s) of the matching entities.
translation – The translation vector of the affine transformation.
rotation – The rotation matrix of the affine transformation.

set_z(z_coordinate: float | str | None = None, offset: float = 0) → Self

[🔧 Modifier] Set the z-coordinate used as the basis for operations.

Either a float or an already defined name can be given. When using a name, it will load the saved z which was previously saved with save_z. If z_coordinate is None, the current z-coordinate will be kept.

The offset can be used to shift the z-coordinate (useful when using a string argument or None for z_coordinate).

set_z_from_group(group_name: str, bottom: bool = False, offset: float = 0) → Self

[🔧 Modifier] Set the current z-coordinate to the top (default) or bottom of the bounding box of the entities in the group named group_name. Optionally, an offset can be provided to shift the z-coordinate up (positive offset) or down (negative offset).

Submodules

qtcad.builder.builder_types module

exception BuilderException

Bases: Exception

An exception originating from qtcad.builder.Builder or its methods.

class Direction(*values)

Bases: StrEnum

Behaviours choosing the group entities are assigned to.

x = 'x'

y = 'y'

z = 'z'

class FragmentationMode(*values)

Bases: Enum

Behaviours for creating new entities that overlap with existing ones.

DISPLACE = 1: See qtcad.builer.Builder.displace_mode

FILL = 3: See qtcad.builer.Builder.fill_mode

OVERLAY = 2: See qtcad.builer.Builder.overlay_mode

class GroupingMode(*values)

Bases: StrEnum

Behaviours choosing the group entities are assigned to.

from_mask = '__from_mask': See qtcad.builer.Builder.group_from_mask()

from_shape = '__from_shape': See qtcad.builer.Builder.group_from_shape()

class MeshSizeMode(*values)

Bases: Enum

Behaviours for choosing which characteristic length or layer number to choose when creating new entities.

inherit = 0

minimum = 2

override = 1

exception NonconformalMesh(msg: str, tmpdir, *args, **kwargs)

Bases: BuilderException

An exception raised when the mesh is found to be non-conformal after performing a heat-conduction check.

outputdir

The directory where the heat-conduction results are stored.

See qtcad.builder.Builder.mesh.

class PhysicalGroup(dim: int, tag: int, name: str, entities: set[int])

Bases: object

Represents a Gmsh physical group and is only used internally.

dim: int: Dimension to which the physical group pertains.

property dimtag: tuple[int, int]

The dimension and tag of the group, represented as a tuple.

qtcad.builder.gmsh_types module

Box = tuple[float, float, float, float, float, float] | numpy.ndarray[tuple[int], numpy.dtype[numpy.float64]]: A bounding box of format (x_min, y_min, z_min, x_max, y_max, z_max).

BoxArray

An array of n bounding boxes, each box having format as specified by Box.

alias of ndarray[tuple[int, int], dtype[float64]]

DimTag

Dimension (int) and tag number (int) of a Gmsh entity.

alias of tuple[int, int]

DimTagArray

Array of dimension and tag pairs (DimTag).