4.1. pyfem package

run(props: str | Path | Tuple[Any, Any]) → Any[source]

Convenience function mirroring the old run behavior used in scripts.

Creates a PyFEMAPI instance, runs the analysis to completion and returns the results dictionary.

Bases: itemList

Container for nodes and node groups.

Inherits from itemList to store nodal coordinates indexed by node ID. Maintains nodal coordinates, spatial dimensionality (rank), and named groupings read from legacy .pro files or Gmsh meshes. Provides convenience methods for retrieving coordinates and iterating group contents.

rank

Spatial dimension of the mesh (2 for 2D, 3 for 3D). Initialized to -1 and set automatically when first node is added.

Type:: int

groups

Dictionary mapping group names to lists of node IDs. Groups are typically used to define boundary conditions (e.g., ‘Left’, ‘Right’, ‘Top’, ‘Bottom’).

Type:: Dict[str, List[int]]

Notes

The NodeSet class extends itemList, inheriting methods like add(), get(), and __len__(). Node coordinates are stored internally and can be retrieved via getNodeCoords().

Examples

>>> nodes = NodeSet()
>>> nodes.add(0, [0.0, 0.0])      # Add node 0 at origin
>>> nodes.add(1, [1.0, 0.0])      # Add node 1 at (1, 0)
>>> nodes.addToGroup('Bottom', 0)
>>> nodes.addToGroup('Bottom', 1)
>>> coords = nodes.getNodeCoords('Bottom')

getNodeCoords(nodeIDs: int | List[int] | str) → array[source]

Return coordinates for one or more nodes as a NumPy array.

Parameters:: nodeIDs (Union[int, List[int], str]) – Single node ID (int), list of node IDs (list), or node group name (str). When a string is provided, it references a node group defined in the model.
Returns:: Array containing nodal coordinates. For a single node, returns a 1D array of shape (rank,). For multiple nodes, returns a 2D array of shape (n, rank) where n is the number of nodes and rank is the spatial dimension.
Return type:: numpy.array

Examples

>>> nodes.getNodeCoords(5)           # Single node
array([1.0, 2.0, 0.0])

>>> nodes.getNodeCoords([1, 2, 3])   # Multiple nodes
array([[0.0, 0.0, 0.0],
       [1.0, 0.0, 0.0],
       [2.0, 0.0, 0.0]])

>>> nodes.getNodeCoords('Left')      # Node group
array([[0.0, 0.0, 0.0],
       [0.0, 1.0, 0.0]])

getNodeIDs(groupName: str) → List[int][source]

Return list of node IDs in the specified group.

Parameters:: groupName (str) – Name of the node group.
Returns:: List of node IDs in the specified group.
Return type:: List[int]

Examples

>>> nodes.getNodeIDs('Left')
[0, 1, 2]

readFromFile(fname: str) → None[source]

Read nodes and groups from legacy .pro file format.

Parses the input file twice: first pass reads nodal coordinates from <Nodes> blocks or references external Gmsh files; second pass reads <NodeGroup> definitions. Duplicate nodes in groups are automatically removed.

Parameters:: fname (str) – Path to input file (.pro format or referencing a Gmsh file).

Notes

Supported file formats: 1. Native .pro format with <Nodes> and <NodeGroup> blocks 2. Gmsh reference: line containing ‘gmsh = “filename.msh”’

The file is parsed line by line. Comments and whitespace are handled. Node groups are deduplicated after reading.

readGmshFile(fname: str) → None[source]

Read nodes and groups from a Gmsh mesh file.

Uses meshio to parse Gmsh format and extract nodes and physical groups. Automatically detects spatial dimension (2D/3D) based on element types. Physical groups from Gmsh become node groups in PyFEM.

Parameters:: fname (str) – Path to the Gmsh file (.msh format, versions 2 or 4).

Notes

3D element detection: - Checks for prisms, pyramids, hexahedra, wedges, and tetrahedra - Sets rank=3 if any 3D elements found, otherwise rank=2

Node groups are populated from Gmsh’s cell_sets_dict, with ‘gmsh:bounding_entities’ excluded. All nodes in elements belonging to a physical group are added to the corresponding PyFEM group.

Requires: - meshio package for reading Gmsh files

addToGroup(modelType: str, ID: int | str) → None[source]

Register a node ID to a named group.

Creates the group if it doesn’t exist, otherwise appends the node to the existing group. String node IDs are automatically converted to integers.

Parameters:

modelType (str) – Name of the node group (e.g., ‘Left’, ‘Right’, ‘Bottom’, ‘Top’).
ID (Union[int, str]) – Node identifier. String values are converted to int.

Examples

>>> nodes.addToGroup('Boundary', 5)
>>> nodes.addToGroup('Boundary', '10')  # String converted to int

logInfo() → None[source]

Log node and group information using the logger.

Outputs the same information as __repr__ but using the logger, with properly formatted output for number of nodes and groups.

Examples

>>> nodes.logInfo()
# Logs:
# Number of nodes ................. : 100
# Number of groups ................ : 4
# Group table with names and counts

readNodalCoords(fin: TextIO) → None[source]

Read nodal coordinates from an open file stream.

Parses node definitions from a <Nodes> block until </Nodes> is encountered. Each line should contain: nodeID x [y [z]] with semicolon separators. Comments starting with // or # are ignored. Spatial dimension (rank) is inferred from the first valid node entry.

Parameters:: fin (TextIO) – Open file handle positioned at the start of the <Nodes> block.

Notes

Format: - Multiple nodes per line separated by semicolons - Format: nodeID x y [z]; - Whitespace is normalized before parsing - Comments (// or #) are skipped - rank is set from first node (2D or 3D)

readNodegroup(fin: TextIO, key: str) → None[source]

Read a node group from an open file stream.

Parses node IDs from a <NodeGroup> block until </NodeGroup> is encountered. Node IDs are whitespace-separated integers. All valid integers found are added to the specified group.

Parameters:

fin (TextIO) – Open file handle positioned at the start of a <NodeGroup> block.
key (str) – Group name label to assign these nodes to.

Notes

Format: - <NodeGroup name=”groupname”> - nodeID1 nodeID2 nodeID3 … - </NodeGroup>

getRank() → int[source]

Return the spatial dimension (rank) of the nodes.

Returns:: Spatial dimension (rank) of the nodes.
Return type:: int

class ElementSet(nodes: Any, props: Properties)[source]

Bases: itemList

Container for finite elements and element groups.

Manages a collection of finite element objects indexed by element ID. Elements are organized into named groups based on their model type (material, element type, etc.). Provides methods for iterating over elements, reading from input files, and managing element groups.

nodes: NodeSet object containing the mesh nodes.

props: Properties object containing model and material properties.

solverStat: Solver status tracker for time stepping and iterations.

groups: Dictionary mapping group names to lists of element IDs.

Examples

>>> elements = ElementSet(nodes, props)
>>> elements.readFromFile('input.pro')
>>> for element in elements:
...     # Process each element

logInfo() → None[source]

Log element and group information using the logger.

Outputs the same information as __repr__ but using the logger, with properly formatted output for number of elements and groups.

getDofTypes() → List[str][source]

Get all unique degree of freedom (DOF) types from all elements.

Iterates through all elements and collects unique DOF types (e.g., ‘u’, ‘v’, ‘w’ for displacements, ‘temp’ for temperature, etc.).

Returns:: List of unique DOF type strings.

readFromFile(fname: str) → None[source]

Read element definitions from an input file.

Parses elements from a legacy .pro file format or references a Gmsh file. Supports <Elements> blocks with element definitions or gmsh file references.

Parameters:: fname – Path to input file (.pro format or referencing Gmsh file).

Notes

Format for <Elements> block: elemID modelName nodeID1 nodeID2 …;

Format for Gmsh reference: gmsh = “filename.msh”;

readGmshFile(fname: str) → None[source]

Read elements from a Gmsh mesh file.

Uses meshio to parse Gmsh format and extract elements. Physical groups from Gmsh become element groups in PyFEM.

Parameters:: fname – Path to the Gmsh file (.msh format).

Requires:: meshio package for reading Gmsh files.

add(ID: int, modelName: str, elementNodes: List[int]) → None[source]

Add a finite element to the element set.

Creates an element instance of the specified type with given nodes, validates node IDs, and adds the element to the appropriate group.

Parameters:

ID – Unique element identifier.
modelName – Name of the model/material (must exist in props).
elementNodes – List of node IDs that define the element connectivity.

Raises:

RuntimeError – If model is missing ‘type’ attribute or node ID invalid.
ImportError – If element module or class cannot be found.

addToGroup(modelType: str, ID: int) → None[source]

Register an element ID to a named group.

Creates the group if it doesn’t exist, otherwise appends the element ID.

Parameters:

modelType – Name of the element group.
ID – Element identifier to add to the group.

addGroup(groupName: str, groupIDs: List[int]) → None[source]

Create or replace a named group with specified element IDs.

Parameters:

groupName – Name for the element group.
groupIDs – List of element IDs to include in the group.

iterGroupNames() → Dict[str, List[int]][source]

Return the dictionary of group names and their element IDs.

Returns:: Dictionary mapping group names to lists of element IDs.

iterElementGroup(groupName: str | List[str]) → Iterator[source]

Iterate over element objects in specified group(s).

Parameters:: groupName – Name of group to iterate, ‘All’ for all elements, or list of group names to iterate multiple groups.
Returns:: Iterator over element objects in the specified group(s).

Examples

>>> for elem in elements.iterElementGroup('Material1'):
...     # Process elements in Material1 group
>>> for elem in elements.iterElementGroup(['Mat1', 'Mat2']):
...     # Process elements in both groups

elementGroupCount(groupName: str | List[str]) → int[source]

Return the number of elements in specified group(s).

Parameters:: groupName – Name of group, ‘All’ for all elements, or list of group names.
Returns:: Total count of elements in the specified group(s).

getFamilyIDs() → List[int][source]

Get family type indices for all elements.

Returns a list of integer indices representing the element family (CONTINUUM=0, INTERFACE=1, SURFACE=2, BEAM=3, SHELL=4) for each element.

Returns:: List of family indices, one per element.

commitHistory() → None[source]

Commit history variables for all elements.

Calls commitHistory() on all element objects to update internal state variables after a successful time/load step. Typically used for storing plastic strains, damage variables, etc.

4.1. pyfem package

4.1.1. Subpackages