Skip to content

Geometry

_FEGeometryMixin

Bases: ABC

_addElementToGroup(tags, tagGroup, dim, physicalName='') staticmethod

Add entities to a GMSH physical group.

Parameters:

Name Type Description Default
tags List[myInt64]

List of entity tags to add to the group.

 required
tagGroup myInt64

Physical group tag to assign.

 required
dim Dim

Spatial dimension of the entities.

 required
physicalName str

Optional name to assign to the physical group.

 ''

addArc(tagStart, tagMid, tagEnd, tag=-1, group=False, tagGroup=-1, nb=10)

Create a circular arc through three existing points.

Parameters:

Name Type Description Default
tagStart int

GMSH entity tag of the arc start point.

 required
tagMid int

GMSH entity tag of a point on the arc (used to define the circle; does not need to be the midpoint).

 required
tagEnd int

GMSH entity tag of the arc end point.

 required
tag int

Desired GMSH entity tag for the curve. -1 lets GMSH choose.

 -1
group bool

If True, add the arc to a physical group.

 False
tagGroup int

Physical group tag. Used only when group is True.

 -1
nb int

Number of mesh elements along the arc. The transfinite algorithm places nb + 1 nodes on the curve. Default is 10.

 10

Returns:

Type Description
int

The GMSH entity tag of the created arc curve.

addFrame(tagStart, tagEnd, tag=-1, group=False, tagGroup=-1, nb=1, groupForRename=False, transfiniteCurve=True)

Create a 1D straight frame element between two existing points.

Parameters:

Name Type Description Default
tagStart int

GMSH entity tag of the start point (node).

 required
tagEnd int

GMSH entity tag of the end point (node).

 required
tag int

Desired GMSH entity tag for the curve. -1 lets GMSH choose.

 -1
group bool

If True, add the curve to a physical group.

 False
tagGroup int

Physical group tag. Used only when group is True.

 -1
nb int

Number of mesh elements along the frame. The transfinite algorithm places nb + 1 nodes on the curve.

 1
groupForRename bool

If True, record the mapping between the mesh element tag and tagGroup in the internal rename table. Only meaningful when nb = 1 (single-element frame).

 False
transfiniteCurve bool

If True, apply a structured (transfinite) meshing algorithm and immediately generate the 1D mesh.

 True

Returns:

Type Description
int

The GMSH entity tag of the created curve.

addFramesToGroup(tags, tagGroup, physicalName='')

Add one or more 1D macro-elements (curves) to a physical group.

A macro element is a geometric object (a GMSH entity) that typically corresponds to one or more mesh elements after meshing. The physical name is also recorded per mesh frame element so it can be retrieved later via :meth:getPhysicalNamesForFrame.

Parameters:

Name Type Description Default
tags List[myInt64] | int

A single macro-element tag (int) or a list of them.

 required
tagGroup myInt64

Physical group tag to assign.

 required
physicalName str

Optional name to assign to the physical group.

 ''

addNode(x=None, y=None, z=None, point=None, tag=-1, group=False, tagGroup=-1, groupForRename=False, meshSize=0.0)

Create a 0D geometric point (node) and optionally add it to a physical group.

Parameters:

Name Type Description Default
x Union[int, float] | None

X coordinate.

 None
y Union[int, float] | None

Y coordinate.

 None
z Union[int, float] | None

Z coordinate.

 None
point Point3d | None

Alternative way to assign coordinate

 None
tag int

Desired GMSH entity tag. -1 lets GMSH choose automatically.

 -1
group bool

If True, add the point to a physical group.

 False
tagGroup int

Physical group tag. Used only when group is True.

 -1
groupForRename bool

If True, record the mapping between the mesh element tag and tagGroup in the internal rename table. Useful when the model is pre-meshed and tags need to be resolved back to user-defined ids.

 False
meshSize float

Target mesh element size at this point. 0.0 inherits from the global mesh size setting.

 0.0

Returns:

Type Description
int

The GMSH entity tag of the created point.

addNodesToGroup(tags, tagGroup, physicalName='')

Add 0D (point) entities to a physical group.

Parameters:

Name Type Description Default
tags List[myInt64]

List of 0D entity tags to add to the group.

 required
tagGroup myInt64

Physical group tag to assign.

 required
physicalName str

Optional name to assign to the physical group.

 ''

addNodesToPlate(tags, tagMacro) staticmethod

Embed existing nodes inside a plate surface and regenerate its mesh.

Embedded nodes are forced to appear as vertices in the resulting triangulation, enabling mesh refinement around interior points. The plate must have been created with transfiniteSurface=False to allow an unstructured mesh that can accommodate interior nodes.

Parameters:

Name Type Description Default
tags list[int]

List of 0D entity (point) tags to embed in the surface.

 required
tagMacro int

GMSH surface entity tag of the target plate.

 required

addPlate(tagLine_1=None, tagLine_2=None, tagLine_3=None, tagLine_4=None, tag=-1, group=False, tagGroup=-1, groupForRename=False, elType=Elem.ELEM_QUAD, transfiniteSurface=True, nodes=None, lines=None, nb=None)

Create a planar surface bounded by 3 or 4 curves and generate its mesh.

The boundary can be specified in three mutually exclusive ways:

Positional line args — pass 3 or 4 pre-existing curve tags directly::

plate = am.addPlate(f1, f2, f3, f4)
plate = am.addPlate(f1, f2, f3)

Line list (keyword lines) — same as above but as a single list::

plate = am.addPlate(lines=[f1, f2, f3, f4])
plate = am.addPlate(lines=[f1, f2, f3])

In both line modes, mesh density and transfinite settings are controlled by the nb/transfiniteCurve parameters used when those curves were created with addFrame. Setting nb=1 on every boundary curve yields exactly one element covering the whole surface::

f1 = am.addFrame(n1, n2, nb=1, transfiniteCurve=True)
...
plate = am.addPlate(lines=[f1, f2, f3, f4])

Node list (keyword nodes) — pass 3 or 4 node tags; boundary curves are created internally as plain lines. Use this when the boundary curves do not need to be referenced independently::

plate = am.addPlate(nodes=[n1, n2, n3, n4])
plate = am.addPlate(nodes=[n1, n2, n3])

To force a single-element mesh in node mode, combine with nb=1 and transfiniteSurface=True. nb sets the number of elements per boundary edge (same convention as addFrame: nb+1 nodes per edge via setTransfiniteCurve), so nb=1 places only the two endpoint nodes on each edge::

plate = am.addPlate(nodes=[n1, n2, n3, n4], nb=1)
plate = am.addPlate(nodes=[n1, n2, n3], nb=1, elType=Elem.ELEM_TRIA)

Parameters:

Name Type Description Default
tagLine_1 int | None

Tag of the first boundary curve (positional line mode).

 None
tagLine_2 int | None

Tag of the second boundary curve (positional line mode).

 None
tagLine_3 int | None

Tag of the third boundary curve (positional line mode).

 None
tagLine_4 int | None

Tag of the fourth boundary curve (positional line mode), or None for a triangular surface.

 None
tag int

Gmsh tag to assign to the surface. -1 lets gmsh choose.

 -1
group bool

If True, add the surface to a physical group.

 False
tagGroup int

Physical group tag. Used only when group=True.

 -1
groupForRename bool

If True, will be add tag to special maps that link model tag to mesh tag. This is usefull when you have to build a model that is already meshed.

 False
elType Elem

Element type for the surface mesh. ELEM_QUAD triggers setRecombine so triangles are merged into quads; ELEM_TRIA leaves the triangulation unchanged.

 ELEM_QUAD
transfiniteSurface bool

If True, apply setTransfiniteSurface for a structured mesh. Set to False for an unstructured Delaunay mesh (required when embedding interior nodes via addNodesToPlate).

 True
nodes list[int] | None

List of 3 or 4 node tags (node mode).

 None
lines list[int] | None

List of 3 or 4 line tags (line list mode).

 None
nb int | None

Number of elements per boundary edge, applied only in node mode (ignored for line modes). Follows the same convention as addFrame: gmsh receives nb+1 nodes per edge via setTransfiniteCurve. Use nb=1 to force a single-element mesh. When None (default) no transfinite setting is applied to the boundary curves.

 None

Returns:

Type Description
int

The gmsh surface tag of the created plate.

Raises:

Type Description
ValueError

If the supplied list has a count other than 3 or 4, or if no boundary input is provided.

addPlatesToGroup(tags, tagGroup, physicalName='')

Add one or more 2D macro-elements (surfaces) to a physical group.

A macro element is a geometric object (a GMSH entity) that typically corresponds to one or more mesh elements after meshing. The physical name is also recorded per mesh plate element so it can be retrieved later via :meth:getPhysicalNamesForPlate.

Parameters:

Name Type Description Default
tags List[myInt64] | int

A single macro-element tag (int) or a list of them.

 required
tagGroup myInt64

Physical group tag to assign.

 required
physicalName str

Optional name to assign to the physical group.

 ''

assignGroupTreeToPhysical(treePath, physicalName)

Map a hierarchical group-tree path to an existing physical group name.

The tree path is a list of string labels representing hierarchy levels (e.g. ["Structure", "Columns", None]). None entries are allowed only as trailing placeholders and are ignored when building the path key. None values must not appear before non-None values.

Parameters:

Name Type Description Default
treePath List[str | None]

Non-empty list of path labels. The first element must not be None. Any trailing None values are stripped.

 required
physicalName str

An existing physical group name (must be already registered in the model).

 required

Raises:

Type Description
ValueError

If treePath is empty, starts with None, if physicalName is empty, if physicalName is not a registered physical group, or if None entries appear before non-None entries.

getCustomIdForTag(tag, elem_type)

Return the custom physical-group id mapped to a mesh element tag.

This lookup uses the internal tagToGroupForRename table, which is populated when elements are added with groupForRename=True. It allows the caller to map a mesh-space tag back to a user-defined physical group id.

Parameters:

Name Type Description Default
tag int

Mesh element tag to look up.

 required
elem_type Elem

Element type (ELEM_POINT, ELEM_LINE, ELEM_TRIA, or ELEM_QUAD).

 required

Returns:

Type Description
int | None

The physical group id if a mapping exists, otherwise None.

getGroupTreeToPhysical()

Return the group-tree to physical-name mapping.

Returns:

Type Description
Dict[str, str]

A dict mapping each slash-delimited tree path string to the
Dict[str, str]

corresponding physical group name.

getMacroElementFrame()

Return a deep copy of the macro-element frame dictionary.

A macro element is a geometric object (a GMSH entity) that typically corresponds to one or more underlying mesh entities after meshing.

Returns:

Type Description
dict[int, tuple[int, int]]

A dict mapping each frame macro-tag to the tuple
dict[int, tuple[int, int]]

(start_node_tag, end_node_tag).

getMacroElementNode()

Return a deep copy of the macro-element node dictionary.

A macro element is a geometric object (a GMSH entity) that typically corresponds to one or more underlying mesh entities after meshing.

Returns:

Type Description
dict[int, Point3d]

A dict mapping each node macro-tag to its Point3d coordinates.

getMacroElementPlate()

Return a deep copy of the macro-element plate dictionary.

A macro element is a geometric object (a GMSH entity) that typically corresponds to one or more underlying mesh entities after meshing.

Returns:

Type Description
dict[int, tuple[int, int, int, int] | tuple[int, int, int]]

A dict mapping each plate macro-tag to the tuple of corner node
dict[int, tuple[int, int, int, int] | tuple[int, int, int]]

tags (3 values for triangles, 4 for quads).

getPhysicalNamesForFrame(tag)

Return the physical group names associated with a mesh frame element.

Parameters:

Name Type Description Default
tag myInt64

Mesh frame element tag.

 required

Returns:

Type Description
List[str] | None

List of physical group name strings the element belongs to,
List[str] | None

or None if the element has no recorded group.

getPhysicalNamesForPlate(tag)

Return the physical group names associated with a mesh plate element.

Parameters:

Name Type Description Default
tag myInt64

Mesh plate element tag.

 required

Returns:

Type Description
List[str] | None

List of physical group name strings the element belongs to,
List[str] | None

or None if the element has no recorded group.

renumberArrange(oldMacroTags, newMacroTags) staticmethod

Apply an element renumbering to the GMSH mesh.

Flattens oldMacroTags and newMacroTags into compact lists and calls gmsh.model.mesh.renumberElements to reassign element ids.

Parameters:

Name Type Description Default
oldMacroTags List[List[int]]

List of lists of current (old) mesh element tags, one inner list per macro-element group.

 required
newMacroTags List[List[int]]

List of lists of desired (new) mesh element tags, in the same structure as oldMacroTags.

 required

renumberFramesByNodeCoords(macroTags, dirRule) staticmethod

Sort mesh frame tags by their midpoint coordinate along a given axis.

Produces the old and new tag ordering needed by :meth:renumberArrange to physically renumber elements in GMSH.

Parameters:

Name Type Description Default
macroTags List[myInt64]

List of macro-element tags whose mesh frames are sorted.

 required
dirRule Literal['+X', '+Y', '+Z', '-X', '-Y', '-Z']

Sorting axis and direction. The sign (+ / -) controls ascending or descending order; the letter selects the coordinate axis (X, Y, or Z).

 required

Returns:

Type Description
Any

A 2-tuple (old_frame_tags, new_frame_tags) where both are
Any

lists of mesh frame tags — old in original GMSH order and new
Tuple[Any, Any]

in the sorted order.